Public API¶

class sire.system.ForceFieldInfo(val, map=None)[source]¶

class sire.system.System(system=None)[source]¶

This class holds a complete system of molecules. This is normally created by reading in molecules from an input file.

This provides a “MoleculeView”-style interface to the molecules, acting very similarly to a sire.mol.SelectorMol object.

You can convert this to a sire.mol.SelectorMol object by calling the System.molecules() function.

add(molecules)[source]¶: Add the passed molecules to this system. This will only add molecules that don’t already exist in this system.

add_shared_property(name, value=None)[source]¶: Add the shared System property called ‘name’ to this system. If ‘value’ is supplied, then this also sets the property too.

angle(*args, **kwargs)[source]¶: Return the angle that matches the passed index/search

angles(*args, **kwargs)[source]¶: Return all angles in this System (or those that match the passed index, if supplied)

apply(*args, **kwargs)[source]¶: Apply (perform / map) the passed function (with associated arguments) on all of the molecules in this System

apply_reduce(*args, **kwargs)[source]¶: Apply (perform / map) the passed function (with associated arguments) on all of the molecules in this System, reducing the result using the passed reduction function

atom(*args, **kwargs)[source]¶: Return the atom that matches the passed index/search

atoms(*args, **kwargs)[source]¶: Return all atoms in this System (or those that match the passed index, if supplied)

bond(*args, **kwargs)[source]¶: Return the bond that matches the passed index/search

bonds(*args, **kwargs)[source]¶: Return all bonds in this System (or those that match the passed index, if supplied)

chain(*args, **kwargs)[source]¶: Return the chain that matches the passed index/search

chains(*args, **kwargs)[source]¶: Return all chains in this System (or those that match the passed index, if supplied)

charge(*args, **kwargs)[source]¶: Return the total charge of this System (or of the matching index/search subset of this System)

clear_energy_trajectory(map=None)[source]¶: Completely clear any existing energy trajectory

clone()[source]¶: Return a copy (clone) of this System

coordinates(*args, **kwargs)[source]¶: Return the center of geometry of this System (or of the matching index/search subset of this System)

count()[source]¶: Return the number of items in this System

cursor()[source]¶: Return a sire.mol.Cursor that can be used to edit the molecules in this System

delete_all_frames(map=None)[source]¶: Delete all the frames from the trajectory

delete_frame(i, map=None)[source]¶: Delete the ith frame from the trajectory

dihedral(*args, **kwargs)[source]¶: Return the dihedral that matches the passed index/search

dihedrals(*args, **kwargs)[source]¶: Return all dihedrals in this System (or those that match the passed index, if supplied)

dynamics(*args, **kwargs)[source]¶

Return a Dynamics object that can be used to perform dynamics on the molecule(s) in this System

cutoff: Length: The size of the non-bonded cutoff
cutoff_type: str: The type of cutoff to use, e.g. “PME”, “RF” etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options
timestep: time: The size of the dynamics timestep
save_frequency: time: The amount of simulation time between saving energies and frames. This can be overridden using energy_frequency or frame_frequency, or by these options in individual dynamics runs. Set this to zero if you don’t want any saves.
energy_frequency: time: The amount of time between saving energies. This overrides the value in save_frequency. Set this to zero if you don’t want to save energies during the trajectory. This can be overridden by setting energy_frequency during an individual run.
frame_frequency: time: The amount of time between saving frames. This overrides the value in save_frequency. Set this to zero if you don’t want to save frames during the trajectory. This can be overridden by setting frame_frequency during an individual run.
save_velocities: bool: Whether or not to save velocities when saving trajectory frames during the simulation. This defaults to False, as velocity trajectories aren’t often needed, and they double the amount of space that is required for a trajectory.
constraint: str: The type of constraint to use for bonds and/or angles, e.g. h-bonds, bonds etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options. This will be automatically guessed from the timestep if it isn’t set.
perturbable_constraint: str: The type of constraint to use for perturbable bonds and/or angles, e.g. h-bonds, bonds etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options. This equal the value of constraint if it isn’t set.
include_constrained_energies: bool: Whether or not to include the energies of the perturbable bonds and angles. If this is False, then the internal bond or angle energy of the perturbable degrees of freedom are not included in the total energy, and their forces are not evaluated.
schedule: sire.cas.LambdaSchedule: The schedule used to control how perturbable forcefield parameters should be morphed as a function of lambda. If this is not set then a sire.cas.LambdaSchedule.standard_morph() is used.
lambda_value: float: The value of lambda at which to run dynamics. This only impacts perturbable molecules, whose forcefield parameters will be scaled according to the lambda schedule for the specified value of lambda.
swap_end_states: bool: Whether or not to swap the end states. If this is True, then the perturbation will run from the perturbed back to the reference molecule (the perturbed molecule will be at lambda=0, while the reference molecule will be at lambda=1). This will use the coordinates of the perturbed molecule as the starting point.
ignore_perturbations: bool: Whether or not to ignore perturbations. If this is True, then the perturbation will be ignored, and the simulation will be run using the properties of the reference molecule (or the perturbed molecule if swap_end_states is True). This is useful if you just want to run standard molecular dynamics of the reference or perturbed states.
integrator: str: The type of integrator to use, e.g. langevin, verlet etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options. This will be automatically set to langevin_middle (NVT/NPT) or verlet (NVE) depending on the ensemble if this is not set (or is set to auto)
temperature: temperature: The temperature at which to run the simulation. A microcanonical (NVE) simulation will be run if you don’t specify the temperature.
pressure: pressure: The pressure at which to run the simulation. A microcanonical (NVE) or canonical (NVT) simulation will be run if the pressure is not set.
rest2_scale: float: The scaling factor to apply when running a REST2 simulation (Replica Exchange with Solute Tempering). This defaults to 1.0. This specifies the ratio of the temperature of the REST2 region to the temperature of the rest of the system.
rest2_selection: str: A selection string for atoms to include in the REST2 region in addition to any perturbable molecules. For example, “molidx 0 and residx 0,1,2” would select atoms from the first three residues of the first molecule. If None, then all atoms within perturbable molecules will be included in the REST2 region. When atoms within a perturbable molecule are also included in the selection, then only those atoms will be considered as part of the REST2 region. This allows REST2 to be applied to protein mutations.
vacuum: bool: Whether or not to run the simulation in vacuum. If this is set to True, then the simulation space automatically be replaced by a sire.vol.Cartesian space, and the simulation run in vacuum.
shift_coulomb: length: The shift_coulomb parameter that controls the electrostatic softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 1.0 A.
shift_delta: length: The shift_delta parameter that controls the electrostatic and van der Waals softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 2.0 A.
coulomb_power: int: The coulomb power parmeter that controls the electrostatic softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 0.
restraints: sire.mm.Restraints or list[sire.mm.Restraints]: A single set of restraints, or a list of sets of restraints that will be applied to the atoms during the simulation.
fixed: molecule(s) view, search string, int, list[int] etc: Anything that can be used to identify the atom or atoms that should be fixed in place during the simulation. These atoms will not be moved by dynamics.
qm_engine:: A sire.qm.QMMMEngine object to used to compute QM/MM forces and energies on a subset of the atoms in the system.
lambda_interpolate: float: The lambda value at which to interpolate the QM/MM forces and energies, which can be used to perform end-state correction simulations. A value of 1.0 is full QM, whereas a value of 0.0 is full MM. If two values are specified, then lambda will be linearly interpolated between the two values over the course of the simulation, which lambda updated at the energy_frequency.
platform: str: The name of the OpenMM platform on which to run the dynamics, e.g. “CUDA”, “OpenCL”, “Metal” etc.
device: str or int: The ID of the GPU (or accelerator) used to accelerate the simulation. This would be CUDA_DEVICE_ID or similar if CUDA was used. This can be any valid OpenMM device string
precision: str: The desired precision for the simulation (e.g. single, mixed or double)
com_reset_frequency:: Either the number of steps between center-of-mass resets, or the time between resets. If this is unset, then the center-of-mass is not reset during the simulation.
barostat_frequency:: Either the number of steps between MC moves to apply the barostat, of the time between moves. If this is unset, then the default of every 25 steps is used.
dynamic_constraints: bool: Whether or not to update the length of constraints of perturbable bonds with lambda. This defaults to True, meaning that changing lambda will change any constraint on a perturbable bond to equal to the value of r0 at that lambda value. If this is false, then the constraint is set based on the current length.
map: dict: A dictionary of additional options. Note that any options set in this dictionary that are also specified via one of the arguments above will be overridden by the argument value

energies(*args, **kwargs)[source]¶: Calculate and return the individual energies of the contents of this System (or of the matching index/search subset of this System)

energy(*args, **kwargs)[source]¶: Calculate and return the energy of this System (or of the matching index/search subset of this System)

energy_trajectory(to_pandas: bool = False, to_alchemlyb: bool = False, energy_unit: str = 'kcal/mol', map=None)[source]¶

Return the energy trajectory for this System. This is the history of energies evaluate during any dynamics runs. It could include energies calculated at different values of lambda.

Parameters:

to_pandas (bool) – Whether or not to return the energy trajectory as a pandas DataFrame.
to_alchemlyb (bool) – Whether or not to return the energy trajectory as a pandas DataFrame that is formatted to usable in alchemlyb
energy_unit (str) – Whichever of the alchemlyb energy units you want the output DataFrame to use. This is in alchemlyb format, e.g. kcal/mol, kJ/mol, or kT. This is only used if to_alchemlyb is True.

ensemble(map=None)[source]¶: Return the last ensemble that was used to simulate this system. This returns a microcanonical ensemble if None was used

evaluate(*args, **kwargs)[source]¶: Return an evaluator for this Systme (or of the matching index/search subset of this System)

find(views)[source]¶: Return the index(es) of the molecule(s) that are in views

has_metadata(key)[source]¶: Return whether or not this System has metadata associated with the requested key

has_property(*args, **kwargs)[source]¶: Return whether or not this system has the passed property

improper(*args, **kwargs)[source]¶: Return the improper that matches the passed index/search

impropers(*args, **kwargs)[source]¶: Return all impropers in this System (or those that match the passed index, if supplied)

static is_system(obj)[source]¶: Return whether the passed object is a System class (either a new or legacy System)

load_frame(i, map=None)[source]¶: Load the ith frame into this System

make_whole(center=None, map=None)[source]¶: Make all of the molecules in this system whole. This maps each molecule into the current space, such that no molecule is broken across a periodic box boundary

mass(*args, **kwargs)[source]¶: Return the total mass of this System (or of the matching index/search subset of this System)

metadata(key: str = None)[source]¶: Return the metadata associated with the passed ‘key’, or all metadata if ‘key’ is None. This returns None if there is no metadata associated with this key, or no metadata has been set

metadata_keys()[source]¶: Return the keys of all metadata set in this System This returns an empty list if no metadata has been set

minimisation(*args, **kwargs)[source]¶

Return a Minimisation object that can be used to perform minimisation of the molecule(s) in this System

cutoff: Length: The size of the non-bonded cutoff
cutoff_type: str: The type of cutoff to use, e.g. “PME”, “RF” etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options
constraint: str: The type of constraint to use for bonds and/or angles, e.g. h-bonds, bonds etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options. This will be none if it hasn’t been set.
perturbable_constraint: str: The type of constraint to use for perturbable bonds and/or angles, e.g. h-bonds, bonds etc. See https://sire.openbiosim.org/cheatsheet/openmm.html#choosing-options for the full list of options. This equal the value of constraint if it isn’t set.
include_constrained_energies: bool: Whether or not to include the energies of the perturbable bonds and angles. If this is False, then the internal bond or angle energy of the perturbable degrees of freedom are not included in the total energy, and their forces are not evaluated.
schedule: sire.cas.LambdaSchedule: The schedule used to control how perturbable forcefield parameters should be morphed as a function of lambda. If this is not set then a sire.cas.LambdaSchedule.standard_morph() is used.
lambda_value: float: The value of lambda at which to run minimisation. This only impacts perturbable molecules, whose forcefield parameters will be scaled according to the lambda schedule for the specified value of lambda.
swap_end_states: bool: Whether or not to swap the end states. If this is True, then the perturbation will run from the perturbed back to the reference molecule (the perturbed molecule will be at lambda=0, while the reference molecule will be at lambda=1). This will use the coordinates of the perturbed molecule as the starting point.
ignore_perturbations: bool: Whether or not to ignore perturbations. If this is True, then the perturbation will be ignored, and the simulation will be run using the properties of the reference molecule (or the perturbed molecule if swap_end_states is True). This is useful if you just want to run standard molecular dynamics of the reference or perturbed states.
shift_coulomb: length: The shift_coulomb parameter that controls the electrostatic softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 1.0 A.
shift_delta: length: The shift_delta parameter that controls the electrostatic and van der Waals softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 2.0 A.
coulomb_power: int: The coulomb power parmeter that controls the electrostatic softening potential that smooths the creation and deletion of ghost atoms during a potential. This defaults to 0.
vacuum: bool: Whether or not to run the simulation in vacuum. If this is set to True, then the simulation space automatically be replaced by a sire.vol.Cartesian space, and the simulation run in vacuum.
restraints: sire.mm.Restraints or list[sire.mm.Restraints]: A single set of restraints, or a list of sets of restraints that will be applied to the atoms during the simulation.
fixed: molecule(s) view, search string, int, list[int] etc: Anything that can be used to identify the atom or atoms that should be fixed in place during the simulation. These atoms will not be moved by minimisation.
platform: str: The name of the OpenMM platform on which to run the dynamics, e.g. “CUDA”, “OpenCL”, “Metal” etc.
device: str or int: The ID of the GPU (or accelerator) used to accelerate minimisation. This would be CUDA_DEVICE_ID or similar if CUDA was used. This can be any valid OpenMM device string
dynamic_constraints: bool: Whether or not to update the length of constraints of perturbable bonds with lambda. This defaults to True, meaning that changing lambda will change any constraint on a perturbable bond to equal to the value of r0 at that lambda value. If this is false, then the constraint is set based on the current length.
map: dict: A dictionary of additional options. Note that any options set in this dictionary that are also specified via one of the arguments above will be overridden by the argument value

molecule(*args, **kwargs)[source]¶: Return the molecule that matches the passed index/search

molecules(*args, **kwargs)[source]¶: Return this System converted to a sire.mol.SelectorMol. You can pass in arguments to search or index so that you limit the number of molecules returned.

names()[source]¶: Return the names of all of the molecules in this System

num_atoms()[source]¶: Return the number of atoms in this System

num_chains()[source]¶: Return the number of chains in this System

num_frames(map=None)[source]¶: Return the number of trajectory frames for this System

num_molecules()[source]¶: Return the number of molecules in this System

num_residues()[source]¶: Return the number of residues in this System

num_segments()[source]¶: Return the number of segments in this System

numbers()[source]¶: Return the numbers of all of the molecules in this System

properties()[source]¶: Return all of the System-level properties of this System

property(*args, **kwargs)[source]¶: Return the System property that matches the passed key/arguments

property_keys()[source]¶: Return the keys (IDs) of all of the System-level properties of this System

remove(molecules)[source]¶: Remove the passed molecules from this system.

remove_all_shared_properties(*args, **kwargs)[source]¶: Completely remove all shared properties, and set no properties as being shared from this system

remove_shared_property(*args, **kwargs)[source]¶: Completely remove the specified shared property, and set this as a non-shared property for the future

residue(*args, **kwargs)[source]¶: Return the residue that matches the passed index/search

residues(*args, **kwargs)[source]¶: Return all residues in this System (or those that match the passed index, if supplied)

save_frame(i=None, map=None)[source]¶: Save the current coordinates to the ith frame of this System. If i is not specfied then this adds the frame onto the end of the trajectory

segment(*args, **kwargs)[source]¶: Return the segment that matches the passed index/search

segments(*args, **kwargs)[source]¶: Return all segments in this System (or those that match the passed index, if supplied)

set_energy_trajectory(trajectory, map=None)[source]¶: Set the energy trajectory to the passed value

set_ensemble(ensemble, map=None)[source]¶: Set the ensemble that was last used to simulate this system. This is copied into the map[“ensemble”] property

set_metadata(key, value)[source]¶: Set the metadata for this System so that the metadata associated with the key ‘key’ is equal to ‘value’

set_property(*args, **kwargs)[source]¶: Set the System property according to the passed arguments

set_shared_property(name, value)[source]¶: Set the shared System property according to the passed arguments

set_space(space, map=None)[source]¶: Set the space to be used to hold all of the molecules in this system

set_time(time, map=None)[source]¶: Set the current time for the system

shared_properties()[source]¶: Return all of the System properties that are being shared (copied) to all contained molecules

size()[source]¶: Return the number of items in this System

smarts(*args, **kwargs)[source]¶: Return the molecule views in this container as smarts strings. Include hydrogens in ‘include_hydrogens’ is True. This returns a list of smarts strings, in the same order as the views in the container

smiles(*args, **kwargs)[source]¶: Return the molecule views in this container as smiles strings. Include hydrogens in ‘include_hydrogens’ is True. This returns a list of smiles strings, in the same order as the views in the container

space(map=None)[source]¶: Return the space used for this system

time(map=None)[source]¶: Return the current system time

to_molecule_group()[source]¶: Return this System converted to a sire.mol.MoleculeGroup

trajectory(*args, **kwargs)[source]¶

Return an iterator over the trajectory of frames of this view.

align:

Pass in a selection string to select atoms against which every frame will be aligned. These atoms will be moved to the center of the periodic box (if a periodic box is used). If “True” is passed, then this will attempt to align ALL of the coordinates in the view.

You can also choose to pass in a molecular container, and it will align against the atoms in that container, assuming they are contained in this view. If not, then you need to supply a mapping that maps from the atoms in the align container, to the atoms in this view.

frame:

The frame of the trajectory against which the alignment should be based. For example, frame=3 would align based on the coordinates of the aligned atoms in frame 3 of the trajectory. If this is None (the default) then the first frame will be used.

mapping: AtomMapping

An AtomMapping object that maps from atoms in the alignment container to atoms in this view. You only need to supply this if all of the alignment atoms are not contained in this view.

smooth:

Pass in the number of frames to smooth (average) the view over. If ‘True’ is passed, then the recommended number of frames will be averaged over

wrap: bool

Whether or not to wrap the coordinates into the periodic box

update(molecules)[source]¶: Update the molecules in this system so that they have the same versions and data as the new molecules contained in ‘value’

view(*args, **kwargs)[source]¶: View this System (or the matching index/search subset) via a nglview viewer. Only works in an interactive notebook session, e.g. in a Jupyter notebook

view2d(*args, **kwargs)[source]¶: Create a 2D representation of the molecules in this system. If ‘filename’ is set then this will be written to that file. Otherwise this will be returned for visualisation in a jupyter notebook.