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
andname
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
orcms.Cms
) – The structure to remove properties fromprops (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
orcms.Cms
) – Structure object to be modifiedprop (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 modelpropname (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 structurerow (
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 structurehierarchy (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
- 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 checkby_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
orschrodinger.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
- 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
- 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:
enum.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(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
Bases:
schrodinger.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