System Builder

class bindflow.preparation.system_builder.CRYST1(line: str | None = None)

https://www.wwpdb.org/documentation/file-format-content/format33/sect8.html#CRYST1

__init__(line: str | None = None)

The constructor

Parameters:

line (str, optional) – a line to process, by default None

from_pdb(file: PathLike | str | bytes)

Initialize the class from a pdb file

Parameters:

file (PathLike) – The PDB file

class bindflow.preparation.system_builder.MakeInputs(protein: dict | None = None, host_name: str = 'Protein', membrane: dict | None = None, cofactor: dict | None = None, cofactor_selection: str = 'resname COF', cofactor_on_protein: bool = True, water_model: str = 'amber/tip3p', custom_ff_path: None | PathLike | str | bytes = None, hmr_factor: float | None = None, fix_protein: bool = True, solv_d: float = 1.5, solv_bt: str = 'dodecahedron', solv_rmin: float = 1, solv_ion_conc: float = 0.15, builder_dir: PathLike | str | bytes = 'builder', load_dependencies: List[str] | None = None)

This class is used for building the systems for a BindFlow calculation. It will create the necessary topology and configuration files, as well the correct directory trees.

__call__(ligand_definition: dict | PathLike | str | bytes, out_dir: str = 'fep')

The call implementation. It identify if it is needed to build all the components of the systems, In case that the class was already called, it will assume that all the components of the system, with the exception of the ligand, were already builded. This is useful to call the class on several ligands that share the same components: protein, membrane and cofactor

Parameters:

• ligand_definition (Union[dict, PathLike]) –

  In case of dictionary, it should have:

  • conf -> The path of the small molecule MOL/SDF file [mandatory]. In case that top is provided,

  this must be a .gro, a ValueError will be raised if it is not the case the molecule will not get its parameters.

  • top -> GROMACS topology [optional]. Must be a single file topology with all the force field

  information and without the position restraint included, by default None

  • ff:

    • type -> openff, gaff or espaloma

    • code -> force field code [optional], by default depending on type

      • openff -> openff_unconstrained-2.0.0.offxml

      • gaff -> gaff-2.11

      • espaloma -> espaloma-0.3.1

    With this parameter you can access different small molecule force fields

  In case of PathLike:

  • The path of the small MOL/SDF molecule file

• out_dir (str, optional) – Where you would like to export the generated files, by default ‘fep’

__init__(protein: dict | None = None, host_name: str = 'Protein', membrane: dict | None = None, cofactor: dict | None = None, cofactor_selection: str = 'resname COF', cofactor_on_protein: bool = True, water_model: str = 'amber/tip3p', custom_ff_path: None | PathLike | str | bytes = None, hmr_factor: float | None = None, fix_protein: bool = True, solv_d: float = 1.5, solv_bt: str = 'dodecahedron', solv_rmin: float = 1, solv_ion_conc: float = 0.15, builder_dir: PathLike | str | bytes = 'builder', load_dependencies: List[str] | None = None)

Constructor

Parameters:

• protein (dict, optional) –

  This is a dictionary with the following information for the protein:

  • conf -> The path of the protein PDB/GRO file [mandatory]

  • top -> GROMACS topology [optional], by default None.

  Should be a single file topology with all the force field information and without the position restraint included. However, in case, you need to use an include statement such as:

  include “./charmm36-jul2022.ff/forcefield.itp”

  You must change the statement to the absolute path:

  include “{prefix of the absolute path}/charmm36-jul2022.ff/forcefield.itp”

  And copy the charmm36-jul2022.ff to custom_ff_path and set this parameter accordingly. If not you may get some errors about files not founded. The force field directory must end with the suffix “.ff”.

  • ff

    • code -> GMX force field code [optional], by default amber99sb-ildn

    You can use your custom force field, but custom_ff_path must be provided

• host_name (str) – The group name for the host in the configuration file, by default “Protein”

• membrane (dict, optional) –

  This is a dictionary with the following information for the membrane:

  • conf -> The path of the membrane PDB file [mandatory]. If provided, the PDB must have a

  correct definition of the CRYST1. This information will be used for the solvation step. The membrane must be already correctly placed around the protein. Servers like CHARM-GUI can be used on this step.

  • top -> GROMACS topology [optional], by default None.

  Should be a single file topology with all the force field information and without the position restraint included. However, in case, you need to use an include statement such as:

  include “./amber-lipids14.ff/forcefield.itp”

  You must change the statement to the absolute path:

  include “{prefix of the absolute path}/amber-lipids14.ff/forcefield.itp”

  And copy theamber-lipids14.ff to custom_ff_path and set this parameter accordingly. If not You may get some errors about files not founded. The force field directory must end with the suffix “.ff”.

  • ff

    • code -> GMX force field code [optional], by default Slipids_2020

    You can use yoru custom force field, but custom_ff_path must be provided

• cofactor (dict, optional) –

  This is a dictionary with the following information for the cofactor:

  • conf -> The path of the small molecule file [mandatory]

  • top -> GROMACS topology [optional]. Must be a single file topology with all the

  force field information and without the position restraint included, by default None

  • ff:

    • type -> openff, gaff or espaloma

    • code -> force field code [optional], by default depending on type

      • openff -> openff_unconstrained-2.0.0.offxml

      • gaff -> gaff-2.11

      • espaloma -> espaloma-0.3.1

    With this parameter you can access different small molecule force fields

  • is_water -> If presents and set to True; it is assumed that this is a water system

  and that will change the settles section (if any) to tip3p-like triangular constraints. This is needed for compatibility with GROMACS. Check here: https://gromacs.bioexcel.eu/t/how-to-treat-specific-water-molecules-as-ligand/3470/9

• cofactor_on_protein (bool) – It is used during the index generation for membrane systems. It only works if cofactor_mol is provided. If True, the cofactor will be part of the protein and the ligand if False will be part of the solvent and ions. This is used mainly for the thermostat. By default True

• cofactor_selection (str, optional) – GMX selection. This is useful when a complex topology is provided via .top/.gro files. For example, when two molecules are cofactors: “resname GDP or resname GTP or resname MG”. If the cofactor is provided as a .mol file, internally a new residue “COF” will be generated By default “resname COF”.

• hmr_factor (float, optional) –

  The Hydrogen Mass Factor to use, by default None

  Warning

  For provided topologies if hmr_factor is set, it will pass any way. So for topology files with already HMR, this should be None. And all the topologies should be provided protein, cofactors, membrane, ligands with the HMR already done

• water_model (str, optional) – The water force field to use, by default amber/tip3p. if you would likle to use the flexible definition of the CHARMM TIP3P you must define FLEXIBLE and CHARMM_TIP3P in the define statement of the mdp file

• custom_ff_path (Union[None, PathLike], optional) –

  All the custom force field must be in this directory. The class will set:

  os.environ[“GMXLIB”] = os.path.abspath(custom_ff_path)

• fix_protein (bool, optional) – If True, pdbfixer will be applied with flags –add-atoms=all –replace-nonstandard and gmx editconf will the -ignh flag. This is needed to avoid possible issues when processing the structure through GROMACS. To kept an specific protonation state is advised to input the full definition of the protein (.top, .gro) or a PDB with the atom-naming (mainly H-naming) consistent with your selected force field. This should be used for protein mainly, by default True

• solv_d (float, optional) – This is the d flag of gmx editconf, it is used during solvation of soluble complex and ligands. Membrane protein-ligand complex are not affected by this keyword, by default 1.5

• solv_bt (str, optional) – This is the bt flag of gmx editconf, it is used during solvation of soluble complex and ligands. Membrane protein-ligand complex are not affected by this keyword, by default “dodecahedron”. bindflow <= 0.15.1 used “octahedron” internally.

• solv_rmin (float, optional) – This is the rmin flag of gmx genion, it is used during solvation. If the number id too small ions might get trap in the protein, by default 1.

• solv_ion_conc (float, optional) – This is the conc flag of gmx genion, it is used during solvation. If 0, only counter ions are added, by default 150E-3 (physiological concentration).

• builder_dir (PathLike, optional) – Where all the building files. After completion you can safely remove calling the method clean, by default builder

• load_dependencies (List[str], optional) – It is used in case some previous loading steps are needed for GROMACS commands; e.g: [‘source /groups/CBG/opt/spack-0.18.1/shared.bash’, ‘module load sandybridge/gromacs/2025.4’], by default None

clean()

Small cleaner, the intermediate steps saved on builder_dir will be deleted

gmx_process(mol_definition: dict, is_membrane: bool = False) → parmed.structure.Structure

Used to process the compatibles biomolecules. By default it will use amber99sb-ildn (protein, DNA, ..) Slipids_2020 (membrane). However, these setups are overwritten by the definitions on mol_definition

Parameters:

• mol_definition (dict) – This dictionary with the self.protein or self.membrane. See the constructor-method’s documentation for more information in its definition.

• is_membrane (bool, optional) – If True, Slipids_2020 will be set as internal default instead of amber99sb-ildn, by default False

Returns:

A parameterize Structure object

Return type:

Structure

make_system(ligand_definition: dict)

Create self.sys_ligand, self.sys_cofactor, self.sys_protein, self.sys_membrane and self.md_system (the combination of the available components). In case that the class was already called, it will be assumed that self.sys_cofactor, self.sys_protein, self.sys_membrane ere already calculated, only self.sys_ligand will be updated as well self.md_system

Parameters:

ligand_definition (dict) – This is a dictionary with. Its definition is the same as mol_definition of the methods self.small_mol_process.

small_mol_process(mol_definition: dict, name: str = 'MOL', safe_naming_prefix: str | None = None)

Get parameters for small molecules: ligands, cofactors, …

Parameters:

mol_definition (dict) –

This is a dictionary with:

• conf -> The path of the small molecule MOL/SDF file [mandatory]. In case that top is provided,

this must be a .gro, a ValueError will be raised if it is not the case the molecule will not get its parameters.

• top -> GROMACS topology [optional]. Must be a single file topology with all the force field

information and without the position restraint included, by default None

• ff:

  • type -> openff, gaff or espaloma

  • code -> force field code [optional], by default depending on type

    • openff -> openff_unconstrained-2.0.0.offxml

    • gaff -> gaff-2.11

    • espaloma -> espaloma-0.3.1

namestr, optional

Name to give, by default “MOL”

safe_naming_prefixstr, optional

This is used to be sure that there will not happen any naming conflict in hte topologies, by default None

name and safe_naming_prefix will only be used if top is not provided in mol_definition.

Returns:

The BioSimSpace system

Return type:

object

bindflow.preparation.system_builder.get_gmx_ff(ff_code: str, out_dir: PathLike | str | bytes = '.') → PathLike | str | bytes

Get GROMACS Force Field

Parameters:

• ff_code (PathLike) – The identification of the gromacs force field. For now only: Slipids_2020 and amber99sb-star-ildn are supported.

• out_dir (PathLike, optional) – Where the file will be decompress, by default ‘.’

bindflow.preparation.system_builder.make_bindflow_dir(out_dir: PathLike | str | bytes, ligand_dir: PathLike | str | bytes, sys_dir: PathLike | str | bytes)

A copy and paste function to create the structure of the BindFlow directory

Parameters:

• out_dir (PathLike) – Where the complex and the ligand systems will be created

• ligand_dir (PathLike) – Origin of the ligand inputs configuration and topologies files

• sys_dir (PathLike) – Origin of the complex inputs configuration and topologies files

bindflow.preparation.system_builder.system_combiner(**md_elements)

This function simply sum up all the elements provided as keyword arguments.

Returns:

any Python object with the method sum implemented. In case elements that evaluate as False in Python will not be taken into account: E.g. False, 0, ‘’, None

Return type:

object

Raises:

RuntimeError – In case all the elements evaluate as False