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 = None, name: str | None = None, idx: int | None = 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 = None, name: str | None = 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.disable_thumbs_up()[source]#

Permanently disable thumbs up. This will write a file into your home directory called ‘.sire_no_thumbs_up.txt’. If this file exists, then thumbs up are denied and no data will be sent to sire.openbiosim.org.

The only way to re-enable thumbs up is to remove the $HOME/.sire_no_thumbs_up.txt file.

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_thumbs_up_info()[source]#

Return the info that will be sent to sire.openbiosim.org if you call the thumbs_up() function. This will return nothing if you have disabled thumbs up using the ‘disable_thumbs_up()’ function.

sire.load(path: str | List[str], *args, show_warnings=True, **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.

  • log (dict) – Optional dictionary that you can pass in that will be populated with any error messages or warnings from the parsers as they attempt to load in the molecular data. This can be helpful in diagnosing why your file wasn’t loaded.

  • 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.

  • directory (str) – Optional directory which will be used when creating any files (e.g. as a download from a URL or which unzipping files)

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")

>>> log = []
>>> mols = load("caffeine.pdb", log=log)
Exception
(look at 'log' to find out what went wrong in detail)
sire.load_test_files(files: List[str] | str, *args)[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.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.molid(num: int | None = None, name: str | None = None, idx: int | None = 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 = None, log={}, map=None) → 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.

  • log (dict) – Optional dictionary that you can pass in that will be populated with any error messages or warnings from the parsers as they attempt to write the molecular data. This can be helpful in diagnosing why your file wasn’t saved.

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"]

>>> log = {}
>>> save(mols, "broken.top", log=log)
Exception
(look at `log` to find in detail what went wrong)
sire.save_to_string(molecules, format: str, log={}, map=None) → 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 = None, name: str | None = 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.smiles(smiles: str, label: str | None = None, labels: str | None = None, smiles_column: str = 'smiles', labels_column: str = 'labels', add_hydrogens: bool = True, generate_coordinates: 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.

  • map – Property map if you want to put the molecule properties into different places

Returns: sire.mol.Molecule

The actual molecule

sire.supported_formats()[source]#

Return a string that describes all of the molecular file formats that are supported by Sire

sire.thumbs_up()[source]#

Give Sire a thumbs up! This will send a small amount of data to sire.openbiosim.org to let us know that you like Sire, and what operating system and version of Sire you are using.

(you can see all of the information that would be sent

by calling “get_thumbs_up_info()”)

You can get more information about what is sent and why this is useful to us by visiting https://sire.openbiosim.org/thumbs_up

You can permanently disable thumbs_up() on your computer by calling “disable_thumbs_up()”. This will write a small file to your home directory that will tell Sire to not allow any more thumbs_up data to be sent.

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()[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.

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.tutorial_url = https://sire.openbiosim.org/m#

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

View Module Index