molsysmt.build package#
Submodules#
molsysmt.build.add_bonds module#
- molsysmt.build.add_bonds.add_bonds(molecular_system, bonded_atom_pairs, in_place=True, skip_digestion=False)[source]#
Adding covalent bonds between atom pairs in a molecular system.
This function adds new covalent bonds between pairs of atoms in a molecular system. The new bonds are defined by a list of atom index pairs. The function modifies the input molecular system in place unless otherwise specified.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to which new bonds will be added.
bonded_atom_pairs (list, tuple, or numpy.ndarray of shape (n_bonds, 2)) – List or array of atom index pairs (0-based integers), where each pair defines a bond to be added.
in_place (bool, default True) – Whether to modify the input molecular system in place. If set to False, a copy of the molecular system is returned with the new bonds added.
skip_digestion (bool, default False) – If True, skips the initial validation and normalization of the input arguments. Mainly used internally.
- Returns:
If in_place=True, the function modifies the input system and returns None. If in_place=False, a new molecular system is returned with the added bonds.
- Return type:
molecular system or None
- Raises:
NotSupportedFormError – Raised if the molecular system has a format that does not support topology editing.
ArgumentError – Raised if the input atom indices are invalid or improperly formatted.
Notes
This function only updates the topological attribute bonded_atoms.
No bond orders or bond types are inferred or assigned.
Atom indices must be valid and within the range of the molecular system’s atoms.
See also
molsysmt.build.remove_bonds()Remove specific bonds from a molecular system.
molsysmt.build.add_missing_bonds()Add bonds based on distance criteria and atomic types.
Examples
>>> import molsysmt as msm >>> system = msm.convert('181L') >>> new_bonds = [(0, 4), (5, 10)] >>> msm.build.add_bonds(system, new_bonds) >>> msm.get(system, bonded_atoms=True)[:5] array([[0, 1], [1, 2], [2, 3], [3, 4], [0, 4]])
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add bonds.
Added in version 1.0.0.
molsysmt.build.add_missing_bonds module#
- molsysmt.build.add_missing_bonds.add_missing_bonds(molecular_system, max_bond_length='2 angstroms', selection='all', structure_index=0, syntax='MolSysMT', engine='MolSysMT', in_place=True, skip_digestion=False)[source]#
Adding missing covalent bonds based on atomic distances and types.
This function analyzes the atomic coordinates and element types in a molecular system to infer and add covalent bonds between atoms that are close enough based on standard bonding distances. The new bonds are added to the bonded_atoms attribute. No bond types or orders are assigned. The procedure can be applied in-place or return a modified copy.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to which new covalent bonds will be added.
max_bond_length (str or float with unit, default '2 angstroms') – Maximum distance between two atoms for a bond to be considered. Atoms further than this value will not be bonded. If a string is passed, it must include units (e.g., ‘0.19 nm’).
selection (tuple, list, numpy.ndarray or str, default 'all') – Selection of atoms to which the method applies. The selection can be given by a list, tuple or numpy array of atom indices (0-based integers), or by a query string following any of the selection syntaxes parsable by MolSysMT.
structure_index (int, default 0) – Structure index (0-based) to use when the molecular system contains multiple structures. The bond detection is based on the atomic positions at this structure.
syntax (str, default 'MolSysMT') – Supported syntax used in the selection argument (in case it is a string).
engine ({'MolSysMT'}, default 'MolSysMT') – Engine used to infer bonds. Currently only the native ‘MolSysMT’ engine is supported.
in_place (bool, default True) – If True, the input molecular system is modified directly. If False, a new system with the added bonds is returned.
skip_digestion (bool, default False) – If True, skips initial validation of input arguments. Used internally.
- Returns:
If in_place=True, the function returns None and modifies the input molecular system. If in_place=False, a new molecular system is returned with inferred bonds added.
- Return type:
molecular system or None
- Raises:
NotSupportedFormError – Raised if the input molecular system is in a form that cannot be edited.
ArgumentError – Raised if any of the input arguments are invalid or inconsistent.
Notes
This method updates only the bonded_atoms attribute of the system. No bond types or orders are assigned.
This function is useful when working with coordinate files that lack bond information (e.g., .xyz, .pdb, or trajectory frames).
The list of supported molecular systems’ forms is detailed in the documentation section: User Guide > Introduction > Molecular systems > Forms
The list of supported selection syntaxes can be found here: User Guide > Introduction > Selection syntaxes
See also
molsysmt.build.add_bonds()Manually add specific bonds to a molecular system.
molsysmt.build.remove_bonds()Remove covalent bonds from a molecular system.
molsysmt.basic.get()Access attributes like bonded_atoms.
molsysmt.basic.convert()Convert the system into a supported editable form.
Examples
>>> import molsysmt as msm >>> molsys = msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm'] >>> system = msm.convert(molsys) >>> msm.build.remove_bonds(system) >>> msm.build.add_missing_bonds(system) >>> msm.get(system, bonded_atoms=True)[:3] array([[0, 1], [1, 2], [2, 3]])
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add missing bonds.
Added in version 1.0.0.
molsysmt.build.add_missing_heavy_atoms module#
- molsysmt.build.add_missing_heavy_atoms.add_missing_heavy_atoms(molecular_system, selection='all', syntax='MolSysMT', engine='PDBFixer', skip_digestion=False)[source]#
Adding missing non-hydrogen atoms to a molecular system.
This function checks for missing heavy atoms (non-hydrogens) in a molecular system and adds them when possible. The missing atoms are identified based on known residue templates and inferred topological context. The coordinates of new atoms are estimated using internal geometry rules or external reconstruction engines such as PDBFixer.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to which missing heavy atoms will be added.
selection (tuple, list, numpy.ndarray or str, default 'all') – Selection of atoms that define the residues or molecules to analyze. Can be provided as indices (list, tuple, array of 0-based integers) or as a string using any of the supported selection syntaxes.
syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string.
engine ({'MolSysMT', 'PDBFixer'}, default 'PDBFixer') – Engine used to rebuild the missing atoms. If ‘MolSysMT’ is chosen, internal geometry templates are used. If ‘PDBFixer’ is selected, the external PDBFixer engine is called.
- Returns:
A molecular system with the missing heavy atoms added, in the same form as the input system.
- Return type:
molecular system
- Raises:
NotSupportedFormError – Raised if the input molecular system is in an unsupported format.
ArgumentError – Raised if one or more input arguments are invalid.
EngineError – Raised if the specified engine fails to rebuild the atoms.
Notes
This function adds only non-hydrogen atoms (heavy atoms) that are missing from standard residues. Hydrogen atoms can be added using other tools or methods.
The list of supported molecular systems’ forms is detailed in: User Guide > Introduction > Molecular systems > Forms
The list of supported selection syntaxes is available at: User Guide > Introduction > Selection syntaxes
See also
molsysmt.build.get_missing_heavy_atoms()Identify heavy atoms that are missing based on residue templates.
molsysmt.basic.remove()Remove atoms from a molecular system.
molsysmt.basic.contains()Check whether specific elements are present in a molecular system.
molsysmt.build.build_peptide()Build capped peptide structures from amino acid sequences.
Examples
>>> import molsysmt as msm >>> molsys = msm.build.build_peptide('AAA') >>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True) 3 >>> molsys = msm.build.remove(molsys, selection='atom_name=="CB"') >>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True) 0 >>> molsys = msm.build.add_missing_heavy_atoms(molsys) >>> msm.get(molsys, selection='atom_name=="CB"', n_atoms=True) 3
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add missing heavy atoms.
Added in version 1.0.0.
molsysmt.build.add_missing_hydrogens module#
- molsysmt.build.add_missing_hydrogens.add_missing_hydrogens(molecular_system, pH=7.4, engine='OpenMM', skip_digestion=False)[source]#
Adding missing hydrogen atoms to a molecular system.
This function adds hydrogen atoms that are missing from a molecular system, based on its topology, standard chemical templates, and a selected pH. The added atoms are positioned using predefined rules for protonation states and geometry constraints.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to which hydrogens will be added.
pH (float, default 7.4) – Approximate pH used to determine the protonation state of ionizable groups.
engine ({'MolSysMT', 'OpenMM', 'PDBFixer'}, default 'OpenMM') – The engine used to perform hydrogen placement. The engine determines residue protonation states and adds atoms accordingly.
- Returns:
A new molecular system with hydrogens added, returned in the same form as the input.
- Return type:
molecular system
- Raises:
NotSupportedFormError – Raised if the input molecular system is not in a supported form.
ArgumentError – Raised if an input argument does not meet the expected format or conditions.
EngineError – Raised if the selected engine fails to perform hydrogen addition.
Notes
Hydrogen atoms are added based on standard residue templates and general rules for protonation. Ionizable side chains (e.g., ASP, GLU, HIS) are adjusted according to the provided pH.
The list of supported molecular systems’ forms is available at: User Guide > Introduction > Molecular systems > Forms
See also
molsysmt.build.has_hydrogens()Check whether a molecular system contains hydrogen atoms.
molsysmt.build.add_missing_heavy_atoms()Add missing non-hydrogen atoms to a molecular system.
molsysmt.basic.contains()Check for the presence of specific atoms or molecules.
Examples
The following example illustrates the use of the function:
>>> import molsysmt as msm >>> molsys = msm.convert('181L', selection='molecule_type=="protein"') >>> msm.build.has_hydrogens(molecular_system) False >>> molsys = msm.build.add_missing_hydrogens(molsys, pH=7.4) >>> msm.build.has_hydrogens(molsys) True
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add missing hydrogens
Added in version 1.0.0.
molsysmt.build.add_missing_terminal_cappings module#
- molsysmt.build.add_missing_terminal_cappings.add_missing_terminal_cappings(molecular_system, N_terminal=None, C_terminal=None, pH=7.4, keep_ids=False, selection='all', syntax='MolSysMT', engine='PDBFixer', skip_digestion=False)[source]#
Adding terminal cappings to peptides and proteins.
This function adds chemical groups to the N- and/or C-termini of protein or peptide chains. These terminal groups can either neutralize terminal charges or simply complete missing atoms for a standard terminal residue. The resulting cappings are consistent with typical protonation states at the specified pH.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to which terminal cappings will be added.
N_terminal (str or None, default None) – Residue name to cap the N-terminus. If None, the missing atoms are added to the native terminal residue without introducing a separate cap. Use ‘ACE’ to cap with an acetyl group, or other recognized residue names.
C_terminal (str or None, default None) – Residue name to cap the C-terminus. If None, the missing atoms are added to the native terminal residue without introducing a separate cap. Use ‘NME’ to cap with a N-methyl amide group, or other recognized residue names.
pH (float, default 7.4) – Approximate pH used to determine the protonation states of terminal groups and nearby residues.
keep_ids (bool, default False) – If True, preserves the original atom and group ids. Otherwise, new IDs may be reassigned.
selection (str, list, tuple, or numpy.ndarray, default 'all') – Selection of atoms or residues to which this operation applies. Can be a list of indices or a query string following MolSysMT selection syntax.
syntax (str, default 'MolSysMT') – Syntax used to parse the selection argument, if it is a string.
engine ({'PDBFixer'}, default 'PDBFixer') – Engine used to perform capping. Determines atom placement and protonation based on templates.
- Returns:
A new molecular system with modified termini, in the same form as the input system.
- Return type:
molecular system
- Raises:
NotSupportedFormError – Raised if the input molecular system is in a non-supported form.
ArgumentError – Raised if an input argument value is invalid.
Notes
- Common capping groups:
‘ACE’ for acetyl (N-terminal)
‘NME’ for N-methyl amide (C-terminal)
If no capping residues are provided, the function only completes missing terminal atoms in the native residues (which are often charged).
The list of supported molecular system forms is detailed in: User Guide > Introduction > Molecular systems > Forms
See also
molsysmt.build.build_peptide()Construct a peptide sequence with optional terminal cappings.
molsysmt.build.add_missing_heavy_atoms()Add missing non-hydrogen atoms to standard residues.
molsysmt.basic.info()Inspect the content and composition of a molecular system.
molsysmt.physchem.get_charge()Calculate the total or partial charge of a system.
Examples
>>> import molsysmt as msm >>> molsys = msm.build.build_peptide('AlaValPro') >>> molsys = msm.build.add_missing_terminal_cappings(molsys, N_terminal='ACE', C_terminal='NME') >>> msm.physchem.get_charge(capped_system) 0.0 elementary_charge >>> msm.convert(molsys, to_form='string:amino_acids_3') 'AceAlaValProNme'
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Add missing terminal cappings
Added in version 1.0.0.
molsysmt.build.build_peptide module#
- molsysmt.build.build_peptide.build_peptide(molecular_system, to_form='molsysmt.MolSys', engine='LEaP')[source]#
Building a peptide from a sequence.
This function constructs a capped or uncapped peptide from a sequence of amino acids. It generates the complete atomic topology, including bonds, angles, and coordinates for the resulting system. Optionally, terminal capping groups can be included in the input sequence.
- Parameters:
molecular_system (str or list of str) – The peptide sequence provided using either three-letter or one-letter amino acid codes. The sequence can also include optional terminal caps such as ‘ACE’ or ‘NME’.
to_form (str, default='molsysmt.MolSys') – Output form of the resulting molecular system. Must be one of the supported forms.
engine ({'LEaP'}, default 'LEaP') – Engine used to build the peptide. Currently, only the LEaP engine from AmberTools is supported.
- Returns:
A new molecular system representing the fully constructed peptide, including coordinates and all relevant topological information.
- Return type:
molecular system
- Raises:
NotImplementedError – Raised if the selected engine is not supported.
ArgumentError – Raised if the input sequence is invalid or contains unsupported codes.
NotSupportedFormError – Raised if the output form is not recognized or supported.
Notes
The sequence must contain standard amino acid codes recognized by the selected engine.
Terminal caps can be specified explicitly by using residue names such as ‘ACE’ (N-terminus) and ‘NME’ (C-terminus).
The resulting structure is built in vacuum and can be subsequently solvated using
molsysmt.build.solvate().
See also
molsysmt.build.add_missing_terminal_cappings()Add terminal groups to complete or neutralize peptide ends.
molsysmt.build.solvate()Surround a molecular system with solvent molecules.
molsysmt.structure.center()Center a molecular system in a simulation box.
molsysmt.basic.view()Visualize the resulting molecular system in a Jupyter notebook.
Examples
>>> import molsysmt as msm >>> molsys = msm.build.build_peptide('AceGlyGlyNme') >>> msm.basic.get(molsys, n_groups=True) 4
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Build peptide
Added in version 1.0.0.
molsysmt.build.define_new_chain module#
- molsysmt.build.define_new_chain.define_new_chain(molecular_system, selection='all', chain_id=None, chain_name=None, syntax='MolSysMT', skip_digestion=False)[source]#
Defining a new chain from selected atoms.
This function creates a new chain by assigning a unique chain_id and/or chain_name to a selection of atoms in a molecular system. The selected atoms are grouped into a new chain, which is appended to the existing list of chains in the system. This does not alter or remove any of the existing chains.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to be modified.
selection (index, tuple, list, numpy.ndarray or str, default 'all') – Selection of atoms to assign to the new chain. The selection can be given as a list, tuple, or NumPy array of atom indices (0-based integers), or as a string following one of the supported selection syntaxes.
chain_id (str or int, optional) – Identifier of the new chain (e.g., ‘A’, ‘B’, ‘C’, or numeric value). If not provided, a unique chain_id will be automatically generated.
chain_name (str, optional) – Descriptive name for the new chain. If not provided, the name will be left empty or automatically assigned.
syntax (str, default 'MolSysMT') – Supported syntax used in the selection argument (in case it is a string).
- Returns:
A modified molecular system with the selected atoms grouped into a newly defined chain.
- Return type:
molecular system
- Raises:
NotSupportedFormError – Raised if the molecular system has a non-supported form.
ArgumentError – Raised if any of the input values is invalid or incompatible.
Notes
This function is useful when merging multiple molecules, redefining topology, or recovering proper chain segmentation after structural edits.
Chains are identified by their chain_id (unique identifier) and chain_name (optional descriptive label).
See also
molsysmt.basic.set()Setting attribute values in a molecular system.
molsysmt.basic.info()Displaying a summary of elements and chain structure.
molsysmt.build.merge()Merging multiple molecular systems, often requiring reassignment of chains.
Examples
>>> import molsysmt as msm >>> molsys = msm.convert('1TCD') >>> msm.build.define_new_chain(molsys, selection='molecule_type=="water"', chain_name='C') >>> msm.get(molsys, element='chain', chain_name=True) ['A', 'B', 'C']
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Define new chain
Added in version 1.0.0.
molsysmt.build.get_disulfide_bonds module#
- molsysmt.build.get_disulfide_bonds.get_disulfide_bonds(molecular_system, selection='all', structure_index=0, max_bond_length=None, group_names=['CYS'], pbc=True, syntax='MolSysMT', engine='MolSysMT', sorted=True, skip_digestion=False)[source]#
Identifying disulfide bonds between sulfur atoms.
This function detects disulfide bonds in a molecular system by finding pairs of sulfur atoms that belong to specified residue types (e.g., CYS) and lie within a covalent bond distance. These S–S bridges are returned as atom index pairs.
- Parameters:
molecular_system (molecular system) – Molecular system in any of the supported forms to be analyzed.
selection (index, tuple, list, numpy.ndarray or str, default 'all') – Selection of atoms to be considered for disulfide bond detection. This can be a list, tuple, or array of atom indices (0-based), or a string parsed using the specified selection syntax.
structure_index (int, default 0) – Index of the structure (frame) in which disulfide bonds will be searched.
max_bond_length (float or str with units, optional) – Maximum distance between two sulfur atoms to be considered a disulfide bond. If not provided, a default threshold (typically 2.05 Å) will be used.
group_names (list of str, default ['CYS']) – List of residue names to be considered as potential cysteine-like residues forming disulfide bonds.
pbc (bool, default True) – Whether to apply periodic boundary conditions when computing distances.
syntax (str, default 'MolSysMT') – Supported syntax used to parse the selection argument (if string).
engine ({'MolSysMT'}, default 'MolSysMT') – Engine used to perform the analysis. Currently only ‘MolSysMT’ is supported.
sorted (bool, default True) – Whether to sort the indices in each pair (i.e., smaller index first).
- Returns:
Array of atom index pairs (each a disulfide bond) detected in the selected atoms and structure.
- Return type:
numpy.ndarray of shape (n, 2)
- Raises:
NotSupportedFormError – If the molecular system format is not supported.
ArgumentError – If input values do not meet required conditions.
Notes
Sulfur atoms are identified based on element type and filtered by group name (e.g., ‘CYS’).
This function assumes that disulfide bonds are formed between SG atoms of cysteines or equivalent residues.
Distance units are internally standardized to nanometers.
See also
molsysmt.build.add_bonds()Manually add bonds between specific atom pairs.
molsysmt.structure.get_neighbors()Find neighboring atoms within a distance or bond limit.
molsysmt.build.get_missing_bonds()Automatically infer missing covalent bonds.
Examples
>>> import molsysmt as msm >>> molsys = msm.convert('5XJH') >>> s_s_pairs = msm.build.get_disulfide_bonds(molsys, max_bond_length='2.15 angstroms') >>> s_s_pairs.shape (2, 2)
User guide
Follow this link for a tutorial on how to work with this function: User Guide > Tools > Build > Get disulfide bonds
Added in version 1.0.0.
molsysmt.build.get_missing_bonds module#
- molsysmt.build.get_missing_bonds.get_missing_bonds(molecular_system, selection='all', structure_index=0, max_bond_length='2 angstroms', disulfide_bonds=False, disulfide_group_names=['CYS'], pbc=True, syntax='MolSysMT', engine='MolSysMT', sorted=True, skip_digestion=False)[source]#
To be written soon…
molsysmt.build.get_missing_heavy_atoms module#
molsysmt.build.get_missing_residues module#
molsysmt.build.get_missing_terminal_cappings module#
molsysmt.build.get_non_standard_residues module#
molsysmt.build.has_hydrogens module#
molsysmt.build.is_solvated module#
molsysmt.build.make_bioassembly module#
molsysmt.build.make_water_box module#
molsysmt.build.mutate module#
molsysmt.build.remove_bonds module#
molsysmt.build.remove_overlapping_molecules module#
molsysmt.build.solvate module#
- molsysmt.build.solvate.solvate(molecular_system, box_shape='truncated octahedral', clearance='14.0 angstroms', anion='Cl-', n_anions='neutralize', cation='Na+', n_cations='neutralize', ionic_strength='0.0 molar', water_model='TIP3P', engine='OpenMM', to_form=None, verbose=False)[source]#
To be written soon…
Methods and wrappers to create and solvate boxes :param anion: :type anion: ‘Cl-’, ‘Br-’, ‘F-’, and ‘I-’ :param n_anions: :type n_anions: number of cations to add. integer or “neutralize” :param cation: :type cation: “NA” ‘Cs+’, ‘K+’, ‘Li+’, ‘Na+’, and ‘Rb+’ :param n_cations: :type n_cations: number of cations to add. integer or “neutralize” :param box_shape: :type box_shape: “cubic”, “truncated_octahedral” or “rhombic_dodecahedron” (Default: “truncated_octahedral”)
- Returns:
item – bla bla
- Return type:
bla bla
Examples
Notes