mofbuilder.md.SolvationBuilder#

class mofbuilder.md.SolvationBuilder(comm=None, ostream=None)[source]#

Bases: object

Builder for the creation of solvated molecular structures in a periodic box.

This class provides methods to pack solvent molecules around a solute inside a simulation box, avoiding atomistic overlaps and managing multi-solvent systems.

Parameters:

  • comm (Any | None)

  • ostream (veloxchem.outputstream.OutputStream | None)

comm#

MPI Communicator used for parallel operations.

Type:

MPI.Comm

rank#

Rank of the current process in the communicator.

Type:

int

nodes#

Number of processes in the communicator.

Type:

int

ostream#

Output stream for logging.

Type:

OutputStream

buffer#

Minimum distance between atoms of different residues (Å).

Type:

float

box_size#

Simulation box size (Å).

Type:

np.ndarray|list|None

trial_rounds#

Number of solvation trials to attempt.

Type:

int

max_fill_rounds#

Maximum number of cavity-filling iterations per trial.

Type:

int

scalar#

Factor to alter number of random solvent candidates per round.

Type:

float

solute_file#

Filename of solute structure (xyz).

Type:

str|None

solute_data#

Pre-loaded solute data array.

Type:

np.ndarray|None

solvents_names#

List of solvent names.

Type:

List[str]

solvents_files#

List of solvent structure xyz filenames.

Type:

List[str]

solvents_proportions#

List of solvent proportions (sum to 1).

Type:

List[float]

solvents_quantities#

List of solvent molecule counts.

Type:

List[int]

best_solvents_dict#

Holds best-performing solvent data after solvation.

Type:

dict|None

custom_solvent_data#

Data for user-supplied solvents.

Type:

dict

preferred_region_box#

Sub-box coordinates for focused packing.

Type:

list|None

target_directory#

Directory for output files.

Type:

str|Path|None

_debug#

Toggle debug logging.

Type:

bool

original_solvents_dict#

Holds original solvents input dict (set in solvate()).

Type:

Optional[dict]

solute_dict#

Solute information (labels/coords/n_atoms).

Type:

Optional[dict]

rc_solute_coords#

Solute coords recentered inside box.

Type:

Optional[np.ndarray]

safe_box#

Internal safe box definition used during packing.

Type:

Optional[list]

solvents_datalines#

Data lines for solvents in output.

Type:

Optional[np.ndarray]

system_datalines#

Solute+solvent combined output datalines.

Type:

Optional[np.ndarray]

remove_overlaps_kdtree(existing_coords, candidate_coords, candidate_residues)[source]#

Check for overlaps between candidate atoms and existing atoms/residues.

Parameters:

  • existing_coords (np.ndarray) – Atomic coordinates (existing).

  • candidate_coords (np.ndarray) – Atomic coordinates (candidates).

  • candidate_residues (np.ndarray) – Residue indices (candidates).

Returns:

(keep_mask, drop_mask), Booleans for keeping/dropping atoms.

Return type:

Tuple[np.ndarray, np.ndarray]

add_custom_solvent(solvent_file, density, molar_mass)[source]#

Add custom solvent definition.

Parameters:

  • solvent_file (str or List[str]) – File name(s) of the solvent xyz structure(s).

  • density (float or List[float]) – Density/densities in g/cm³.

  • molar_mass (float or List[float]) – Molecular mass(es) in g/mol.

Return type:

None

molecule_radii(coords)[source]#

Estimate molecule radius by half-max distance from origin.

Parameters:

coords (np.ndarray) – Coordinates relative to center.

Returns:

Estimated radius (Å).

Return type:

float

mols_radii(solvents_dict)[source]#

Return representative max radius from all solvents above 0.1 proportion.

Parameters:

solvents_dict (dict) – Solvent info dictionary.

Returns:

Maximum solvent molecular radius (Å).

Return type:

float

load_solute_info(solute_file=None, solute_data=None)[source]#

Load solute label/coord data from xyz file or pre-loaded array.

Parameters:

  • solute_file (str, optional) – File path of solute xyz.

  • solute_data (np.ndarray, optional) – Pre-provided solute data.

Returns:

Dict with keys ‘labels’, ‘coords’, and ‘n_atoms’.

Return type:

dict

grid_points_template(solvents_dict, box_size, grid_spacing=None)[source]#

Generate a cubic lattice of grid points within the simulation box for use as candidate centers.

Parameters:

  • solvents_dict (dict) – Dictionary of solvent properties.

  • box_size (np.ndarray | list) – Box size (length 3).

  • grid_spacing (float, optional) – Grid spacing (Å).

Returns:

Grid points shape (N, 3).

Return type:

np.ndarray

solvate()[source]#

Perform the primary packing/solvation operation.

Places all solvent molecules into the simulation box around the solute, avoiding overlaps and preserving the desired ratios/densities.

Returns:

best_solvents_dict, with info on final solvent placements/atoms/etc.

Return type:

dict or None

write_output(output_file='solvated_structure', format=[])[source]#

Write the solvated system to file(s) in various formats.

Parameters:

  • output_file (str, optional) – Base target name (suffix added per format).

  • format (str | list of str, optional) – Output format(s): xyz, pdb, gro.

Return type:

None