schrodinger.application.matsci.msutils module

Utility functions and classes for MatSci workflows.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.msutils.Forcefield(version, name)

Bases: tuple

__contains__(key, /)

Return key in self.

__len__()

Return len(self).

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 1

version

Alias for field number 0

schrodinger.application.matsci.msutils.get_default_forcefield()

Returns information for S-OPLS if license is found. If no license is found, returns information for OLPS2005, which requires no license.

Returns namedtuple forcefield

Named 2-tuple containing the version and name of the default forcefield, respectively

schrodinger.application.matsci.msutils.remove_properties(struct, props=None, matches=None, atom_props=None, atom_matches=None)

Remove all the matching structure and atom properties. No error is thrown if the given properties do not actually exist on the structure.

Parameters

• struct (structure.Structure or cms.Cms) – The structure to remove properties from

• props (list) – A list of structure properties to delete

• matches (list) – Remove all structure properties whose name contains any of these strings

• atom_props (list) – A list of atom properties to delete

• atom_matches (list) – Remove all atom properties whose name contains any of these strings

schrodinger.application.matsci.msutils.remove_atom_property(struct, prop)

Delete atom property from all atoms in a structure (structure will be modified).

Parameters

• struct (structure.Structure or cms.Cms) – Structure object to be modified

• prop (str) – Atom property to be removed

schrodinger.application.matsci.msutils.remove_cms_property(cms_model, propname)

Delete a property from a cms model

Parameters

• cms_model (cms.Cms) – cms model

• propname (str) – property name

schrodinger.application.matsci.msutils.remove_cms_atom_property(cms_model, propname)

Delete an atom property from a cms model

Parameters

• cms_model (cms.Cms) – cms model

• propname (str) – property name

schrodinger.application.matsci.msutils.has_atom_property(struct, prop)

Check if structure has any atom with the property set.

Parameters

• structure.Structure – Input structure

• str – Property name

Raises

• KeyError – If property name doesn’t start with: s_, r_, i_, b_

• mm.MmException – If unexpected error occurred

Return bool

True of property is present, False otherwise

schrodinger.application.matsci.msutils.getstr(ret)

Convert binary string (or other data) to str.

Parameters

ret (binary_type or any other type convertable to str) – Value to be converted to str

Return type

str

Returns

Value converted to str

schrodinger.application.matsci.msutils.get_project_group_hierarchy(st=None, row=None)

Return the project group hierarchy for the given structure or row.

Parameters

• st (schrodinger.structure.Structure) – the structure

• row (schrodinger.project.ProjectRow) – the project row

Raises

ValueError – if there is an issue

Return type

list

Returns

the hierarchy (outermost to innermost)

schrodinger.application.matsci.msutils.set_project_group_hierarchy(st, hierarchy, collapsed=False)

Set the project group hierarchy for the given structure.

Parameters

• st (schrodinger.structure.Structure) – the structure

• hierarchy (list) – the hierarchy (outermost to innermost)

• collapsed (bool) – Whether the group should initially be collapsed

schrodinger.application.matsci.msutils.get_matsci_user_data_dir()

Get the absolute path to the user’s local MatSci data directory for storing custom templates, protocols, etc. Directory is created if it doesn’t exist.

Return type

str

Returns

The absolute path the Materials Science data parent directory

schrodinger.application.matsci.msutils.structure_reader(filename, log=None, do_raise=False)

Read structures from a file until the end or the first structure with an error.

Parameters

• filename (str) – filename

• log (function) – Log function, if None, nothing is called

• do_raise (bool) – Whether to raise on an exception

Yield schrodinger.structure.Structure

Next structure in the file

schrodinger.application.matsci.msutils.is_dummy_atom(atom)

Return True if the given atom is a dummy atom.

Parameters

atom (schrodinger.structure._StructureAtom) – the atom

Return type

bool

Returns

return True if the given atom is a dummy atom

schrodinger.application.matsci.msutils.validate_no_dummy_atoms(structs)

Validate that the passed structures don’t have dummy atoms

Parameters

structs (iterable) – Structures to check

Return type

bool or (bool, str)

Return type

True if no structures has dummy atoms, False and error message if at least one structure does

schrodinger.application.matsci.msutils.add_or_update_bond_order(ct, atom1, atom2, bond_order)

Create a new bond, or update the existing bond order of this bond.

Return type

schrodinger.structure._Bond

schrodinger.application.matsci.msutils.add_or_update_bond_type(ct, atom1, atom2, bond_type)

Create a new bond, or update the existing bond type of this bond.

Return type

schrodinger.structure._Bond

schrodinger.application.matsci.msutils.trim_str(text, max_len, suffix='...')

Trim the string to approximately max_len. Add a suffix if the string is longer than max_len.

Parameters

• text – String to trim

• max_len (int) – Max length of the string

• suffix (str) – Suffix to add if the string is to be trimmed

Return str

Trimmed string

schrodinger.application.matsci.msutils.mmlewis_apply(quiet=True)

Context manager that initializes mm and returns mm.mmlews_apply method.

Example usage:

with msutils.mmlewis_apply() as lewis_apply:

assert lewis_apply(struct) is None

Yield

mm.mmlewis_apply method.

Raises

mm.MmException – On mmlewis_apply failure

schrodinger.application.matsci.msutils.get_atom_ffio_velocity(atom)

Get FFIO atom velocities.

Parameters

atom (structure._StructureAtom) – Input atom

Return numpy.array

Array of velocities

schrodinger.application.matsci.msutils.set_atom_ffio_velocity(atom, velocity)

Set FFIO atom velocities.

Parameters

• atom (structure._StructureAtom) – Atom to modify

• velocity (list) – List of velocities (x, y, z components)

schrodinger.application.matsci.msutils.get_unique_name(new_name, existing_names)

Add a suffix to new_name to make a unique name if it already exists in existing_names.

Parameters

• new_name (str) – The new name

• existing_names (list) – Existing names

Return type

str

Returns

The unique version of new_name

schrodinger.application.matsci.msutils.get_next_name(name)

Get the next customer facing name. For example, ‘xx’ gives ‘xx (1)’ and ‘xx (n)’ gives ‘xx (n + 1)’

Parameters

name (str) – The name based on which the next is generated

Return type

str

Returns

The unique version of new_name

schrodinger.application.matsci.msutils.setting_to_bool(string, empty_is_false=True)

Convert a yes/no/true/false/1/0/on/off type string to a Python boolean

Parameters

• string (str) – The string to convert

• empty_is_false – If the string is empty or None, return False

Return type

bool

Returns

True if the string is a “true”-y word (TRUE, true, t, yes, on, 1, etc), False if it is a “false”-y word (FALSE, false, f, no, off, 0).

Raises

• ValueError – If the string cannot be interpreted in a True/False manner

• AttributeError – If something other than a string is passed in

schrodinger.application.matsci.msutils.flatten(alist, afunc=None)

Flatten the given list into a set.

Parameters

• alist (list) – elements contain iterable data

• afunc (function or None) – function used to extract iterable data from the given list elements or None if there isn’t one

Return type

set

Returns

a flattened set of data from the given list

schrodinger.application.matsci.msutils.get_unique_ordered_list(l_values)

Remove the duplicates from the list while maintaining the order. If there are duplicates then the value with lower index is kept

Parameters

l_values (list) – The list of values to make unique

Returns

The unique ordered list.

Return type

list

schrodinger.application.matsci.msutils.get_atomic_element(atomic_number)

Given atomic number return chemical element.

Parameters

atomic_number (int) – Atomic number

Return type

str

Returns

Chemical element

schrodinger.application.matsci.msutils.ignore_ssl_warnings()

Context manager to temporarily ignore InsecureRequestWarning warning.

schrodinger.application.matsci.msutils.get_index_from_default_name(atom_name)

Find the atom index from string of element name and atom index

Parameters

atom_name (str) – concatenated string of element symbol with the atom index

Rtype index

int or None

Para atom_index

Atom index

schrodinger.application.matsci.msutils.title_case(original, exceptions=('an', 'of', 'the', 'for'), skip_single_letters=True)

Convert the string to title case, optionally ignoring articles and single letters

Examples with default kwargs: “Number of molecules”: “Number of Molecules” “axis b”: “Axis b”

Parameters

• original (str) – The string to make title case

• exceptions (tuple) – The words to not capitalize

• skip_single_letters (bool) – Whether single letters should not be capitalized

Return type

str

Returns

The string in title case

schrodinger.application.matsci.msutils.generate_smiles(struct)

Return a SMILES string for st.

For more options, see the schrodinger.structutils.smiles.SmilesGenerator class.

Parameters

struct (Structure) – Structure for which SMILES string is desired.

Return type

str

Returns

SMILES string representing st.

schrodinger.application.matsci.msutils.get_common_property_names(sts)

Return the property names that all of the given structures have in common.

Parameters

sts (list[schrodinger.structure.Structure]) – the structures to search

Return type

set[str]

Returns

the common property names

schrodinger.application.matsci.msutils.get_common_float_property_names(sts)

Return the float property names that all of the given structures have in common.

Parameters

sts (list[schrodinger.structure.Structure]) – the structures to search

Return type

set[str]

Returns

the common float property names

schrodinger.application.matsci.msutils.get_common_atom_property_names(sts)

Return the property names that all atoms of the given structures have in common.

Parameters

sts (list[schrodinger.structure.Structure]) – the structures to search

Return type

set[str]

Returns

the common atom property names

schrodinger.application.matsci.msutils.get_common_float_atom_property_names(sts)

Return the float atom property names that all of the given structures have in common.

Parameters

sts (list[schrodinger.structure.Structure]) – the structures to search

Return type

set[str]

Returns

the common float atom property names

schrodinger.application.matsci.msutils.is_coarse_grain(struct, by_atom=False)

Check if struct is a coarse grain structure

Parameters

• struct (schrodinger.structure.Structure) – The structure to check

• by_atom (bool) – If True, check each atom to see if it is coarse grain and return True if any atom is coarse grin. If False, check only for the coarse grain structure property. True is useful when the structure has been obtained via maestro.workspace_get, which removes structure-level properties, or if the structure may be a mixed atomistic/coarse-grained structure.

Return type

bool

Returns

True if it is a coarse grain structure, False if not

schrodinger.application.matsci.msutils.structure_reader_to_3d(file_path, require_stereo=False, out_rep=None, debug=False)

Read structures from a file and return 3D representations.

Parameters

• file_path (str) – the file, can be of any format supported by schrodinger.structure.StructureReader or schrodinger.structure.SmilesReader

• require_stereo (bool) – see schrodinger.structure.Structure.generate3dConformation

• out_rep (str or None) – For eta-bound transition metal complexes, if None then the conversion is to the opposite of the given representation, eta to centroid or centroid to eta, if a string then must be either module constant parserutils.CENTROID or parserutils.ETA in which case the conversion will always provide an output representation of the given type

• debug (bool) – If debug is True it prints output else it doesn’t

Return type

list[schrodinger.structure.Structure]

Returns

3D structures

schrodinger.application.matsci.msutils.keyword_string_to_dict(keystring)

Return a dictionary whose keys are keywords and values are keyword values

Parameters

keystring (str) – The keywords are taken from this string - keywords must be in the keyword=value format and whitespace delimited.

Return type

dict

Returns

Dictionary of keyword/value pairs

Raises

ValueError – if any tokens do not match the keyword=value format

schrodinger.application.matsci.msutils.keyword_dict_to_string(keydict)

Return a string of keywords specified by keydict.

Parameters

keydict (dict) – Dictionary - keys are Jaguar keywords, values are keyword values of str type

Return type

str

Returns

A string of space-separated keyword=value pairs

schrodinger.application.matsci.msutils.is_equal_formula(sts1, sts2)

Whether lists of structures have the same total chemical formula (mass conservation).

Parameters

• sts1 (list[structure.Structure]) – List of structures

• sts2 (list[structure.Structure]) – Other list of structures

Return type

bool

Returns

Whether structures have same total chemical formula

schrodinger.application.matsci.msutils.get_st_rdkit_mappers(rd_mol)

Gets mapper dictionaries for converting between schrodinger structure atom index and rdkit molecule atom index

Parameters

rd_mol (rdkit.Chem.rdchem.Mol) – RDMol structure derived from schrodinger structure

Returns

The two dictionaries first one has key as schrodinger structure atom id and value is the rdkit molecule atom id. The second dictionary has key as rdkit molecule atom id and value as schrodinger structure atom id

Return type

dict, dict

class schrodinger.application.matsci.msutils.DictCache(maxcount=10000)

Bases: collections.OrderedDict

A first in first out dictionary cache which caches the key and associated value.

__init__(maxcount=10000)

Constructs a new lru cache.

Parameters

maxcount (int) – The maximum number of data that the cache can hold

__contains__(key, /)

True if the dictionary has the specified key, else False.

__len__()

Return len(self).

clear() → None.  Remove all items from od.

copy() → a shallow copy of od

fromkeys(value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D’s items

keys() → a set-like object providing a view on D’s keys

move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) → v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D’s values

class schrodinger.application.matsci.msutils.RdkitAdapter(struct)

Bases: object

A class to calculate calculate SMARTS and SMILES pattern for a structure multiple times. The class can be memory intensive to allow for increased speed.

PROTECTED_PATTERN_BIT = ['D', 'R', 'r', 'v', 'x', 'X', 'H']

__init__(struct)

Initiate PatternEvaluator class

Parameters

struct (schrodinger.structure.Structure) – Structure for which patterns need to be selected

toRdIndices(atom_indices)

Convert list of Schrodinger structure atom indices to RDMol atom indices

Parameters

atom_indices (list) – list of Schrodinger structure atom indices

Return type

list

Returns

list of RDMol atom indices

toStIndices(atom_indices)

Convert list of RDMol atom indices to Schrodinger structure atom indices

Parameters

atom_indices (list) – list of RDMol atom indices

Return type

list

Returns

list of Schrodinger structure atom indices

elementToAtomName(s_pattern)

If the structure is a coarse grain structure convert the SMARTS/SMILES pattern of elements to coarse grain atom name. Does nothing for all atom structures

Parameters

smarts (str) – The SMARTS/SMILES pattern

Returns

The translated SMARTS/SMILES pattern

Return type

str

atomNameToElement(s_pattern)

If the structure is a coarse grain structure convert the SMARTS/SMILES pattern of coarse grain atom name to mapped elements. Does nothing for all atom structures

Parameters

s_pattern (str) – The SMARTS/SMILES pattern

Returns

The translated SMARTS/SMILES pattern

Return type

str

property smiles

Get the SMILES for the passed structure

Returns

SMILES pattern for the passed structure

Return type

str

property smarts

Get the SMARTS for the passed structure

Returns

SMARTS pattern for the passed structure

Return type

str

toSmiles(atom_ids=None)

Get SMILES for subset of atom ids

Parameters

atom_ids (list) – list of atom indices

Return type

str

Returns

SMILES pattern for the atom ids provided

toSmarts(atom_ids=None)

Get SMARTS for subset of atom ids

Parameters

atom_ids (list) – list of atom indices

Return type

str

Returns

SMARTS pattern for the atom ids provided

getChemFormula(atom_ids=None)

Gets the chemical formula for passed atoms.

Parameters

atom_ids (list) – list of atom indices

Return type

str

Returns

Chemical formula for the passed atom indices

getSMILESMatches(smiles)

Get the list of matches for the passed SMILES pattern in the reference structure

Parameters

smiles (str) – SMILES pattern to find

Return type

list or None

Returns

list of list atom indices with matching SMILES.

getSMARTSMatches(smarts)

Get the list of matches for the passed SMARTS pattern in the reference structure

Parameters

smarts (str) – SMARTS pattern to find

Return type

list or None

Returns

list of list atom indices with matching SMARTS.

getMoleculeSmiles()

Get SMILES for each molecule in the structure

Returns

The dictionary where the key is the molecule number and the value is the corresponding SMILES pattern

Return type

dict

getMoleculeSmarts()

Get SMARTS for each molecule in the structure

Returns

The dictionary where the key is the molecule number and the value is the corresponding SMARTS pattern

Return type

dict

getUniqueMolNums(use_smarts=False)

Get the unique representative molecules in the structure

Parameters

use_smarts (bool) – If true the unique molecules will share the same SMARTS pattern. If false the unique molecules will share the same SMILES pattern.

Return type

list

Returns

list of molecule numbers that are unique

schrodinger.application.matsci.msutils.deep_update_dict(source, overrides)

Override/append source dict values using overrides dict, return a new dict. Everything is deepcopied to prevent unexpected changes.

Parameters

• source (dict) – Source dictionary

• overrides (dict) – Dictionary to override with

Return type

dict

Returns

Updated dictionary

schrodinger.application.matsci.msutils.get_interface_normal(struct)

Define normal interface vector in c direction.

Parameters

struct (schrodinger.structure.Structure) – structure

schrodinger.application.matsci.msutils.get_val_from_cmdline(args, var, default=None)

Get value from the command line given variable name.

Parameters

• args (list or str) – Arguments. If string it will be split into a list

• var (str) – Variable name

• default (Any) – Default value if var is not found

schrodinger.application.matsci.msutils.count_waters(filename=None, struct=None)

Count the number of waters in the first structure in the given file

Parameters

• filename (str) – The path to a structure file

• filename – A structure object. Either filename or struct must be given

Return type

schrodinger.structure.Structure, int

Returns

The first structure in the file and the number of waters in it

schrodinger.application.matsci.msutils.force_rmtree_resist_nfs(removal_dir, logger=None, failed_dir='rmtree_failed')

Force remove a directory tree or if it contains stale NFS handles then move it to the specified failure repository.

Parameters

• removal_dir (str) – The directory tree to be removed

• logger (logging.Logger) – The logging object you want to throw an error to if we need to move the folder rather than delete it.

• failed_dir (str) – The name of a failure repository/directory to put the removed directory into

schrodinger.application.matsci.msutils.dedent(msg, rm_breaks=True)

Light wrapper for the textwrapper.dedent function, but run with with a strip() afterwards too. Can also remove mid-string line breaks. Useful when paired with a pattern such as:

msg = (“””

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. “””)

This function will remove the leading & trailing linebreaks, and it will also fix the indentations at the beginning of each new line.

Parameters

• msg (str) – The message string that you want to dedent.

• rm_breaks (bool) – Whether or not you want to replace all linebreaks with spaces. Typically more useful to turn off when making tooltips.

schrodinger.application.matsci.msutils.write_csv_from_dicts(filename, rows)

Write a csv file from a list of dicts. Column headers will be the superset of all keys in the dictionaries in the rows list.

Parameters

• filename (str) – The name of the file to write to

• rows (list) – A list of dicts, one for each row in the csv. Keys are property names (column headers), values are row values for that column. Each dictionary need not have key/value pairs for all columns.