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

name

Alias for field number 1

version

Alias for field number 0

schrodinger.application.matsci.msutils.with_global_as(glob_var, new_var)

Context manager which updates global variable with new variable and restores with old value when execution leaves context manager

Parameters:

• glob_var (Any) – The global variable which gets updated with given new variable

• new_var (Any) – The new variable with which global variable gets updated

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_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.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.get_dummy_atoms(st)

Return all dummy atoms in the given structure.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

list[schrodinger.structure._StructureAtom]

Returns:

the dummy atoms

schrodinger.application.matsci.msutils.remove_dummy_atoms(st)

Return a copy of the given structure with any dummy atoms removed.

Parameters:

st (schrodinger.structure.Structure) – the structure

Return type:

schrodinger.structure.Structure, dict

Returns:

a copy of the structure with any dummy atoms removed and the old-to-new atom index renumbering map

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.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_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.generate_smiles(struct, *args, method=SMARTS_METHOD.internal, **kwargs)

Return a SMILES string for the given structure.

Parameters:

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

• method (SMARTS_METHOD) – The method to use for SMILES generation.

Return type:

str

Returns:

SMILES string representing the structure

Raises:

NotImplementedError – If the given method is not supported.

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_any_struct_coarse_grain(structs, **kwargs)

Check if any structure is a coarse grain structure

Parameters:

structs (list) – Each item is a Structure object

Additional keyword arguments are passed to the is_coarse_grain function

Return type:

bool

Returns:

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

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

• 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.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, no_val=False)

Get value from the command line given flag name.

Parameters:

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

• var (str) – Flag name

• default (Any) – Default value if var is not found or has no argument

• no_arg (bool) – If True, the flag is not expected to have an argument. Simply return True/False based on whether var is in args.

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

schrodinger.application.matsci.msutils.is_iterable(val)

Check whether value is iterable, but not string.

Parameters:

val (Any) – Value to check

Return bool:

Whether value is iterable but not string

schrodinger.application.matsci.msutils.get_iterator(val)

Get iterator from value. If value is iterable yield from it, otherwise simply yield the value itself.

Yield Any:

Next value

schrodinger.application.matsci.msutils.get_enum_member(enum_type, var, is_value=False)

Get enum member.

Parameters:

• enum_type (enum.Enum) – Enum

• is_value (bool) – Whether var is enum member value or name

Return enum_type:

Enum member

Raises:

KeyError – If var is not a enum member

schrodinger.application.matsci.msutils.copy_st_props(src, dest, props)

Copy structure properties from the source structure to the destination structure.

Parameters:

• src (structure.Structure) – Source structure

• dest (structure.Structure) – Destination structure

• props (String or iterable of strings) – Structure property or an iterable of structure properties to copy

schrodinger.application.matsci.msutils.get_molecular_weight(struct, idxs=None, decimal=None, is_cg=None, by_mol=False)

Return the molecular weight (amu) taken over the given atom indices in the given structure.

Parameters:

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

• idxs (list[int]) – Atom indices. If None, all atoms will be used

• decimal (int) – An optional number of decimal places to which to round the weight. If None, no rounding will be performed

• is_cg (bool) – Whether structure is CG. If None, will check if structure is CG or AA

• by_mol (bool) – Whether to return molecule weight by molecule or total

Return type:

float or list[float]

Returns:

Total molecular weight (amu) or by molecule

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

Remove project table group information from the structure

Parameters:

struct (structure.Structure) – The structure

schrodinger.application.matsci.msutils.write_sea2msj(stages, fname=None, to_str=False)

Write stages to a file and/or return a string.

Parameters:

• stages (list[sea.Map]) – List of stages

• fname (str) – File name to write

• to_str (bool) – Whether to return string with all the stages

schrodinger.application.matsci.msutils.file_to_tmp_fn(file_fh)

Given a file handler copy it to a temporary file and yield its file name.

Parameters:

file_fh (FILE) – File handler

Ytype:

str

Yield:

Temporary file path where the original file has been copied

class schrodinger.application.matsci.msutils.EnumMetaWithContains(cls, bases, classdict, *, boundary=None, _simple=False, **kwds)

Bases: EnumType

Meta enum class that implements __contains__ method.

__contains__(item)

Implement in. Check if enum contains an item.

Parameters:

item (Any) – Item to check

Return type:

bool

Returns:

Whether enum contains the item

class schrodinger.application.matsci.msutils.KeywordEnum

Bases: StrEnum

Enum that has values the same as names. Names must be unique. Useful to define grammar enums.

schrodinger.application.matsci.msutils.get_ct_atoms_count(fpath)

Get the total number of atoms from MAE or CMS files.

Parameters:

fpath (str) – Path to file

Returns:

Total number of atoms in passed structure file.

Return type:

int