sire module¶

This is the primary module of sire. You import it using;

>>> import sire as sr

This gives direct access to a small public API that provides a high-level and easy (we hope!) interface to the power of the classes and functions in the other sire sub-modules.

Public API¶

View Module Index

sire.atomid(num: int = None, name: str = None, idx: int = None, case_sensitive=True)[source]¶

Construct an identifer for an Atom from the passed: name, number and index.

Parameters:

name (str, optional) – The atom name. Defaults to None.
num (int, optional) – The atom number. Defaults to None.
idx (int, optional) – The atom index. Defaults to None.
case_sensitive (bool) – Whether the name is case sensitive or not

Returns:

The returned atom identifier

Return type:

AtomID

sire.chainid(idx: int = None, name: str = None, case_sensitive: bool = True)[source]¶

Construct an identifer for a Chain from the passed: name and index.

Parameters:

name (str, optional) – The chain name. Defaults to None.
index (int, optional) – The chain index. Defaults to None.
case_sensitive (bool) – Whether or not the name is case sensitive

Returns:

The returned chain identifier

Return type:

ChainID

sire.expand(base: str, path: str | List[str], *args, **kwargs)[source]¶

Expand the set of paths with the supplied base.

Parameters:

base (str) – The base to be prepended to all paths
path (str or list[str]) – The filename (or names) that will be prepended with the base.
suffix (str) – A suffix to attach to all files, e.g. “.bz2”
Returns – list[str]: The list of expanded filenames or URLs

Examples –

>>> expand("https://sire.openbiosim.org/m", "urea.gro", "urea.top")
["https://sire.openbiosim.org/m/urea.gro",
 "https://sire.openbiosim.org/n/urea.top"]

>>> expand("input", ["ala.top", "ala.crd"])
["input/ala.top", "input/ala.crd"]

sire.get_max_num_threads()[source]¶: Return the maximum number of C++ threads that will be allowed for computation. Note that this is the maximum number of compute threads managed via Intel’s Threading Building blocks. Sire additionally uses a small number of lightweight background threads for management, which are unaffected by this setting.

sire.load(path: str | List[str], *args, show_warnings=True, silent: bool = False, directory: str = '.', ignore_topology_frame: bool = False, gromacs_path: str = None, parallel: bool = True, map=None, **kwargs)[source]¶

Load the molecular system at ‘path’. This can be a filename of a URL. If it is a URL, then the file will be downloaded to the current directory and loaded from there.

Parameters:

path (str or list[str]) – The filename (or names) or the URL or URLS of the molecular system to load. This allows multiple paths to be input as some molecular file formats split molecular information across multiple files. Multiple paths can also be passed as multiple arguments to this function.
show_warnings (bool) – Whether or not to print out any warnings that are encountered when loading your file(s). This is default True, and may lead to noisy output. Set show_warnings=False to silence this output.
silent (bool) – Whether or not to silence all output (including any warnings)
directory (str) – Optional directory which will be used when creating any files (e.g. as a download from a URL or when unzipping files)
ignore_topology_frame (bool) – Ignore any coordinate / frame data coming from the topology file. By default, frame data from topology files will be included. Setting this to True will ignore that data, meaning that frame data will only come from the trajectory files that are loaded.
gromacs_path (str) – Path to the directory containing gromacs parameters. If this is not set then the gromacs parameters installed with sire will be used.
parallel (bool) – Whether or not to load files in parallel (using multiple cores). You normally do want to do this. Only switch this to False if debugging or if you don’t want to use all the cores in your computer.

Returns:

The molecules that have been loaded are returned as a sire.system.System

Return type:

sire.system.System

Examples

>>> mols = load("caffeine.pdb")

>>> mols = load(["ala.crd", "ala.top"])

>>> mols = load("ala.crd", "ala.top")

>>> mols = load("https://something")

sire.load_test_files(files: List[str] | str, *args, map=None)[source]¶

Load the passed files that are part of the unit testing and return the resulting molecules. This will cache the files into a directory called “../cache” so that downloads can be shared between tests. You should only need this function if you are writing unit tests.

Parameters:

files (str or list[str]) – The list of files to load from the tutorial website. This will automatically add on the tutorial URL and compression suffix

Returns:

sire.system.System: The loaded molecules

sire.match_atoms(mol0, mol1, match=None, prematch=None, match_light_atoms=False, map0=None, map1=None)[source]¶

Perform a simple match that tries to identify the mapping from atoms in ‘mol0’ to the atoms in ‘mol1’. This uses the AtomMCSMatcher to match the atoms, using the passed prematch argument.

However, if the match argument is provided, this will be used as the atom mapping directly (it can either be a dictionary mapping atom identifiers, or an AtomMatcher object).

Parameters:

mol0 (Molecule view) – The reference state molecule (or part of molecule)
mol1 (Molecule view) – The perturbed state molecule (or part of molecule)
match (dict, AtomMatcher, optional) – The atom matcher to use to match atoms. If this is a dictionary of atom identifiers, then this will be passed to a AtomIDMatcher object. If this is an AtomMatcher object, then this will be used directly.
prematch (dict, AtomMatcher, optional) – The atom matcher to use to prematch atoms. If match is not supplied, then this will be used as the prematch argument to the AtomMCSMatcher used to find the maximum common subgraph match.
match_light_atoms (bool, optional) – Whether to match light atoms (i.e. hydrogen atoms) if using the default AtomMCSMatcher. Default is False.
map0 (dict, optional) – Property map to find properties in mol0
map1 (dict, optional) – Property map to find properties in mol1

Returns:

The atom mapping between the two molecules (or parts of molecules)

Return type:

AtomMapping

sire.measure(item0, item1=None, item2=None, item3=None, improper_angle: bool = False, ignore_space: bool = False, map=None)[source]¶

Measure and return the distance, angle, torsion angle or improper angle for the passed items. The items can be points in space, atoms, residues or any molecule view.

If one item is passed, then it should be Bond, Angle, Dihedral or Improper. In this case, the measure() function of that item will be returned.

If two items are passed, then the distance between them is returned.

If three items are passed, then the angle between then is returned.

If four items are passed, then the torsion angle between them is returned if improper_angle is False (the default). If improper_angle is True, then the improper angle is returned.

Note that this will take into account any periodic boundary conditions. The first-found space will be used to map all points into a minimum-image-convention box, and the measurements will be made from these. Set ‘ignore_space=True’ if you want to ignore the space and perform measurements without periodic boundary conditions.

Parameters:

item0 – Any sire object that be converted to coordinates. This is either sire.maths.Vector, or if this is a molecule view, then it is the result of calling view.coordinates()
item1 – Any sire object that be converted to coordinates. This is either sire.maths.Vector, or if this is a molecule view, then it is the result of calling view.coordinates()
item2 – Any sire object that be converted to coordinates. This is either sire.maths.Vector, or if this is a molecule view, then it is the result of calling view.coordinates()
item3 – Any sire object that be converted to coordinates. This is either sire.maths.Vector, or if this is a molecule view, then it is the result of calling view.coordinates()
improper_angle – bool. Whether or not the improper angle should be returned (default False, as the torsion angle is calculated by default between four items)
ignore_space –

bool. Whether or not to ignore any space found
in the passed sire objects that instead to perform the measurements in an infinite cartesian space.

Returns:

measurementEither a distance or an angle depending on the
number of items passed.

sire.minimum_distance(mol0, mol1, space=None, map=None)[source]¶

Return the minimum distance between the atoms of the two passed molecules.

If ‘space’ is passed, then that will be used to apply periodic boundary conditions.

sire.molid(num: int = None, name: str = None, idx: int = None, case_sensitive: bool = True)[source]¶

Construct an identifer for a Molecule from the passed: name, number and index.

Parameters:

name (str, optional) – The molecule name. Defaults to None.
num (int, optional) – The molecule number. Defaults to None.
idx (int, optional) – The molecule index. Defaults to None.
case_sensitive (bool) – Whether or not the name is case sensitive

Returns:

The returned molecule identifier

Return type:

MolID

sire.save(molecules, filename: str, format: str | List[str] = None, show_warnings=True, silent: bool = False, directory: str = '.', parallel: bool = True, map=None, **kwargs) → List[str][source]¶

Save the passed molecules to a file called ‘filename’. If the format is not specified, then the format will be guessed from the filename. If the format is specified, and is a list, then multiple files will be written, one for each specified format.

:param molecules sire.system.System: sire.mol.Molecule,: List[sire.mol.Molecule] etc.)

The molecule (or molecules) that should be written to the file. This can be anything that can be converted to a sire.system.System, i.e. a single Molecule (or MoleculeView), or a list of Molecules (or MoleculeViews)
:paramsire.mol.Molecule,: List[sire.mol.Molecule] etc.)

The molecule (or molecules) that should be written to the file. This can be anything that can be converted to a sire.system.System, i.e. a single Molecule (or MoleculeView), or a list of Molecules (or MoleculeViews)

Parameters:

filename (str) – The name of the file to which to write the file. Extensions will be automatically added if they are needed to match the formats of the file (or files) that are written.
format (str or list(str)) –

The format (or formats) that should be used to write the
file (or files). If the format isn’t specified, then it will be guessed from the extension used for filename. If this doesn’t have an extension, then it will be guessed based on the formats used to load the molecule originally. If it still isn’t available, then PDB will be used.

show_warnings (bool):
Whether or not to write out any warnings that occur during save

silent (bool):
Whether or not to silence all output during the save

directory (str):
If supplied, the directory in which to save the files.

parallel (bool):
Whether or not to save in parallel (using multiple cores). You normally want this switched on, unless you are debugging or want to restrict sire to a single core.

Returns:

The absolute paths/name(s) of the files that have been written.

Return type:

list[str]

Examples

>>> save(molecules, "molecules.pdb")
["/path/to/molecules.pdb"]

>>> save([mol1, mol2, mol3], "molecules.sdf")
["/path/to/molecules.sdf"]

>>> save(mols, "ala", format=["top", "crd"])
["/path/to/ala.top", "/path/to/ala.crd"]

sire.save_to_string(molecules, format: str, show_warnings=True, silent: bool = False, parallel: bool = True, map=None, **kwargs) → List[str][source]¶

Save the passed molecules to an in-memory list of lines. This will write the molecule(s) in the format specified to memory, thereby avoiding writing any data to a text file

Note that you must pass in the format, and only a single “file” can be written at a time.

sire.segid(idx: int = None, name: str = None, case_sensitive: bool = True)[source]¶

Construct an identifer for a Segment from the passed: name and index.

Parameters:

name (str, optional) – The segment name. Defaults to None.
index (int, optional) – The segment index. Defaults to None.
case_sensitive (bool) – Whether or not the name is case sensitive

Returns:

The returned chain identifier

Return type:

SegID

sire.set_default_num_threads()[source]¶: Set a reasonable default number of C++ threads that will be allowed for computation. Note that this is the maximum number of compute threads managed via Intel’s Threading Building blocks. Sire additionally uses a small number of lightweight background threads for management, which are unaffected by this setting.

sire.set_max_num_threads(n: int)[source]¶: Set the maximum number of C++ threads that will be allowed for computation. Note that this is the maximum number of compute threads managed via Intel’s Threading Building blocks. Sire additionally uses a small number of lightweight background threads for management, which are unaffected by this setting.

sire.smarts(smarts: str, label: str = None, labels: str = None, smarts_column: str = 'smarts', labels_column: str = 'labels', map=None)[source]¶

Return a molecule that has been generated using the passed smiles string. This uses rdkit to create the molecule, so it must be installed.

Parameters:

smiles – str or list[str] or pandas.Dataframe The smiles string to interpret. This can be a single smiles string, a list of smiles strings, or a pandas Dataframe containing a smiles column and a label column (either called this, or use options below to name them yourself)
label – str The label for the molecule being created. This can only be a single string. If it is set, then labels will be ignored.
labels – str or list[str] The label (name) for the molecule that will be created. This should be a single string or a list of strings depending on ‘smiles’. Note that this will be ignored if a Dataframe is passed in. Note that if this is not passed in then the label will be taken from the smiles string
smiles_column – str The name of the smiles column in the Dataframe (default ‘smiles’)
labels_column – str The name of the labels column in the Dataframe (default ‘labels’)
map – Property map if you want to put the molecule properties into different places

Returns: sire.mol.Molecule: The actual molecule

sire.smiles(smiles: str, label: str = None, labels: str = None, smiles_column: str = 'smiles', labels_column: str = 'labels', add_hydrogens: bool = True, generate_coordinates: bool = True, must_sanitize: bool = True, map=None)[source]¶

Return a molecule that has been generated using the passed smiles string. This uses rdkit to create the molecule, so it must be installed.

Parameters:

smiles – str or list[str] or pandas.Dataframe The smiles string to interpret. This can be a single smiles string, a list of smiles strings, or a pandas Dataframe containing a smiles column and a label column (either called this, or use options below to name them yourself)
label – str The label for the molecule being created. This can only be a single string. If it is set, then labels will be ignored.
labels – str or list[str] The label (name) for the molecule that will be created. This should be a single string or a list of strings depending on ‘smiles’. Note that this will be ignored if a Dataframe is passed in. Note that if this is not passed in then the label will be taken from the smiles string
smiles_column – str The name of the smiles column in the Dataframe (default ‘smiles’)
labels_column – str The name of the labels column in the Dataframe (default ‘labels’)
add_hydrogens – bool (default True) Whether or not to automatically add hydrogens. Note that not adding hydrogens will automatically disable the generation of coordinates.
generate_coordinates – bool (default True) Whether or not to automatically generate 3D coordinates. Note that generating coordinates requires that hydrogens are automatically added.
must_sanitize – bool (default True) Whether or not all sanity checks must pass when creating the molecule. This will ensure that all sanity checks pass, and if they don’t, then an exception will be raised. If this is not True, then sanity checks that failed are skipped and silently ignored. It is possible, in this case, that a null or malformed molecule may be returned.
map – Property map if you want to put the molecule properties into different places

Returns: sire.mol.Molecule: The actual molecule

sire.sqrt(x)[source]¶: Return the square root of the passed value

sire.supported_formats()[source]¶: Return a string that describes all of the molecular file formats that are supported by Sire

sire.u(unit)[source]¶: Return a sire unit created from the passed expression. If this is a sire.units.GeneralUnit then it will be returned. If this is a string, then it will be parseed and returned as a sire.units.GeneralUnit.

sire.use_mixed_api(support_old_module_names: bool = False)[source]¶

Load Sire using both the new (python-style) and old APIs. This is useful for migrating old scripts as a temporary porting option. You can start writing functions using the new API, safe in the knowledge that the old API functions will still work.

Do aim to finish your port though, else you will forever have a duplicated API (e.g. have both X.nAtoms() and X.num_atoms() etc.)

sire.use_new_api(is_base: bool = False)[source]¶

Load Sire using the new (python-style) API. This will be called automatically when you load any of the new Python modules, so you shouldn’t need to call this yourself.

Parameters:: is_base (bool (defaults to False)) – Whether or not this is being called by the sire.base module. This triggers a special case where we only load sire.base, and thus avoid circular imports

sire.use_old_api()[source]¶: Load Sire using the old (C++-style) API. This is for compatibility reasons for old code only. This should not be used with new code

sire.v(x, y=None, z=None, units=None)[source]¶

Return a sire vector from the passed expression. If this is a set of numbers or lengths (or a combination) then a sire.maths.Vector will be returned. If this is a value with velocity or force units then a Velocity3D or Force3D will be returned. If there is no vector type for data of this value then a simple python vector object will be returned.

Parameters:

x – The x-value, or something containing 3 values
y – The y-value (cannot be specified if x has more than 1 value)
z – The z-value (cannot be specified if x has more than 1 value)
units – The units of the passed values (optional - will be guessed if not specified). You should not pass this if x, y or z already have values.

sire.tutorial_url = https://sire.openbiosim.org/m¶

The base URL for all molecule files used in the tutorial.

View Module Index