schrodinger.application.jaguar.utils module¶

Jaguar utility functions.

class schrodinger.application.jaguar.utils.FreeEnergy(temp, gibbs, property_key)¶

Bases: NamedTuple

temp: float¶: Alias for field number 0

gibbs: float¶: Alias for field number 1

property_key: str¶: Alias for field number 2

class schrodinger.application.jaguar.utils.ChgAt(index, charge)¶

Bases: NamedTuple

index: int¶: Alias for field number 0

charge: int¶: Alias for field number 1

class schrodinger.application.jaguar.utils.LewisStructure(charges, bonds, score, unpaired)¶

Bases: NamedTuple

charges: list[schrodinger.application.jaguar.utils.ChgAt]¶: Alias for field number 0

bonds: list[tuple[int, int]]¶: Alias for field number 1

score: float¶: Alias for field number 2

unpaired: bool¶: Alias for field number 3

class schrodinger.application.jaguar.utils.ScanCoord(coord_type, atoms, initial, final, num_steps, step, const_type)¶

Bases: NamedTuple

coord_type: int¶: Alias for field number 0

atoms: list[int]¶: Alias for field number 1

initial: float¶: Alias for field number 2

final: float¶: Alias for field number 3

num_steps: int¶: Alias for field number 4

step: float¶: Alias for field number 5

const_type: int¶: Alias for field number 6

class schrodinger.application.jaguar.utils.LewisModes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: enum.IntEnum

STD = 0¶

PRINT = 1¶

RINGCHAIN = 2¶

THOROUGH = 3¶

FINDALL = 4¶

exception schrodinger.application.jaguar.utils.RingFlipError¶

Bases: ValueError

Error in when flipping rings that indicates bad or insufficient user input.

schrodinger.application.jaguar.utils.append_outfiles_to_recover_file(recover_file: str, outfiles: Iterable[str])¶

Append list of output file paths to a YAML-format .recover file.

Parameters

recover_file – .recover file name
outfiles – output file paths

schrodinger.application.jaguar.utils.get_jobname(prefix: str, str_to_hash: str) → str¶: Construct a jobname based on the given string prefix (typically the backend script name) and a string to be hashed (typically based on the cmdline being used to invoke the job.)

schrodinger.application.jaguar.utils.split_jag_ext(filename)¶

Split the extension off the filename, but account for the fact that Jaguar extensions might be .xx.mae, where xx are some digits. bob.01.mae -> bob bob.out -> bob bob.maegz -> bob, etc.

Parameters: filename (str) – The file name to split
Return type: str
Returns: The base file name without extension

schrodinger.application.jaguar.utils.restart_name(input_name: str, mae_name: Optional[str] = None) → str¶

Wrapper to extract restartname from mmjag routine

Allows for calls where mae_name is not defined or where input name is an empty string (would cause segfault in mmjag function)

schrodinger.application.jaguar.utils.basic_windows_path(dos_path: str) → str¶

Convert extended length Windows path to standard. Does nothing on other OS’s.

Parameters: dos_path – a (Windows) file path, which may have WINDOWS_EXTENDED_PATH_TAG to indicate extended path length
Returns: A file path which has not extended length tags

schrodinger.application.jaguar.utils.get_stoichiometry_string(atom_list: Iterable[str]) → str¶

Take atom_list and return stoichiometry string. For example, atom_list = [‘H’, ‘H’, ‘O’] yields stoichiometry string = ‘H2O’.

Parameters: atom_list – Iterable of element names
Returns: stoichiometry string

schrodinger.application.jaguar.utils.groupby_stoichiometry(structures: Iterable[schrodinger.structure._structure.Structure]) → dict[str, list[schrodinger.structure._structure.Structure]]¶

Group structures by stoichiometry

Parameters: structures – list of structures to group
Returns: dictionary of stoichiometry strings to list of structures

schrodinger.application.jaguar.utils.validate_stoichiometry(reactants: list['jin.JaguarInput'], products: list['jin.JaguarInput']) → Optional[str]¶

This function validates stoichiometry for a reaction defined by the list of reactants and products. If stoichiometry is not valid this function return text string explaining what was wrong. In case of valid stoichiometry returns None.

Parameters

reactants – list of JaguarInput objects for reactants
products – list of JaguarInput objects products

Returns

string with warning message or None

schrodinger.application.jaguar.utils.base_functional(func: str) → str¶

Extract basename of DFT functional

Removes a posteriori model suffixes from the functional, e.g. B3LYP-D3 -> B3LYP PBE0-d -> PBE0 b3lyp-loc-MM -> b3lyp

Parameters: func – full name of functional, case-insensitive
Returns: functional name, with corrections (e.g. dispersion, LOC) removed

schrodinger.application.jaguar.utils.get_number_electrons(st: schrodinger.structure._structure.Structure) → int¶

Count the number of electrons disregarding charges.

Parameters: st – the structure
Returns: the number of electrons

schrodinger.application.jaguar.utils.get_total_charge(structure: schrodinger.structure._structure.Structure) → int¶

Return the total charge of the structure If the property i_m_Molecular_charge is defined we use that, else we sum the formal charges

Parameters: structure – whose total charge must be calculated
Returns: total charge of structure

schrodinger.application.jaguar.utils.elmnt_mult_dict() → dict[str, int]¶

make a dictionary of element:multiplicity for all neutral elements up to Oganesson (118)

The values are from the ground state term symbol as reported by NIST at http://physics.nist.gov/PhysRefData/Elements/index.html as of 4.2014

schrodinger.application.jaguar.utils.remove_gibbs_energies(st: schrodinger.structure._structure.Structure, allowed_temps: tuple[float] = ())¶

Remove gibbs energy properties from a structure but allow some exceptions. This allows one to ‘unclutter’ the project table.

Parameters

st – structure containing gibbs energy properties
allowed_temps – temperatures that are allowed to remain as properties

schrodinger.application.jaguar.utils.parse_gibbs_energies(st: schrodinger.structure._structure.Structure, inf_sep: bool = False, std_conc: bool = False)¶

Extract the temperature, gibbs energy and property keys for free energy and store these in a dict relating temperature to FreeEnergy instances.

Parameters

st – the structure
inf_sep – True indicates infinitely separated energy
std_conc – True indicates Gibbs energy at std state concentration

Returns

a dict relating temperature to a FreeEnergy instance with attributes storing these data

schrodinger.application.jaguar.utils.gibbs_energy_property_string(temp: float, inf_sep: bool = False, std_conc: bool = False) → str¶

Construct the property key string for Gibbs energy at a particular temperature

Parameters

temp – temperature in Kelvin
inf_sep – True indicates infinitely separated energy
std_conc – True indicates Gibbs energy at std state concentration

Returns

a property key string

schrodinger.application.jaguar.utils.convert_gibbs_energy_to_std_conc(st: schrodinger.structure._structure.Structure) → dict¶

Convert std state (1 atm) Gibbs energies to a std state of 1 Molar concentration. The energies are returned as a dict relating temperature to FreeEnergy instances. The energies are also stored as structure level properties. This is intended to be used with AutoTS for rate calculations and we assume the free energies were computed at 1 atm of pressure.

Parameters: st – the structure
Returns: a dict relating temperature to a FreeEnergy instance with attributes storing these data

schrodinger.application.jaguar.utils.compute_std_conc_gibbs_energy(gibbs: float, temp: float, press: float, con: float) → float¶

Convert Gibbs energy which was computed at a pressure of press to a concentration of con using the formula G = G_0 + kT log(CRT/P_0) where we’ve used the ideal gas law to relate P = CRT

Parameters

gibbs – Gibbs free energy in a.u. evaluated at a pressure of press
press – Pressure at which the Gibbs energy was evaluated in atm
temp – Temperature at which the Gibbs energy was evaluated in Kelvin
con – Concentration which defines the standard state in moles/Liter

schrodinger.application.jaguar.utils.group_with_comparison(st_list: list[schrodinger.structure._structure.Structure], comp: Callable, **kwargs) → list[list[schrodinger.structure._structure.Structure]]¶

Group list of structures using a comparator function. Generally used with schrodinger.comparison functions.

In the worst case (where all structures in list are inequivalent by the comparison function), the number of comparisons goes as O(N^2). Keep this in mind if working with long lists.

Parameters

st_list – list of structures to be grouped
comp – a comparison function
kwargs – keyword arguments to be passed to the comparison function

Returns

list of lists of structures which are equivalent according to supplied function

schrodinger.application.jaguar.utils.beta_au(temp: float) → float¶: Beta = 1/kT in a.u.

schrodinger.application.jaguar.utils.beta_kcalmol(temp: float) → float¶: Beta = 1/kT in kcal/mol

schrodinger.application.jaguar.utils.copy_structure_bonding(ref_st: schrodinger.structure._structure.Structure, updated_st: schrodinger.structure._structure.Structure, check_xyz: bool = True)¶

Copy all bonding and formal charges from reference structure onto a structure instance we want to update. Also update FF atom-typing. Assumes number of atoms and atom numbering is the same in both structures.

Parameters

ref_st – structure to copy bonding from
updated_st – structure to copy bonding to
check_xyz – optionally check the XYZs of both structures are almost identical

schrodinger.application.jaguar.utils.sync_dummy_atoms(ref_st: schrodinger.structure._structure.Structure, st: schrodinger.structure._structure.Structure)¶

Sync dummy atoms in ref_st and st. This is useful after calling mmjag_connect to reset bonding. We check atomic number and XYZ coordinates to classify which atoms are the “same” or “different”. But note for dummy atoms, we do not require XYZ to be the same.

We then try to sync the two structures by handling two possibilities:

Existence of new dummy atoms at the end of the atom list in ref_st compared to st; they will be added to the end of st.
Non-existence of dummy atoms at any location in ref_st compared to st; they will be deleted from st.

Parameters

ref_st – structure to copy atoms from
st – structure to copy atoms to

Raises

AssertionError – Fails to sync

schrodinger.application.jaguar.utils.mmjag_reset_connectivity(st: schrodinger.structure._structure.Structure)¶

Reset connectivity and Lewis structure using mmjag algorithm. i.e input st is modified to have new bonds, bond orders and formal charges. All other properties should be preserved.

Parameters: st – structure to clean up

schrodinger.application.jaguar.utils.mmjag_update_lewis(st: schrodinger.structure._structure.Structure, mode: schrodinger.application.jaguar.utils.LewisModes = LewisModes.STD) → list[schrodinger.application.jaguar.utils.LewisStructure]¶

Update Lewis structure for a given connectivity using mmjag algorithm. This can be used instead of, or to complement, e.g. the mmlewis code. Unlike mmjag_reset_connectivity, the connectivity will be preserved.

If mode is LewisModes.PRINT, the lewis structure determination information will be returned

If mode is LewisModes.RINGCHAIN, special Lewis structure scoring for ring-chain tautomers will be used (and lewis structure information will be returned)

If mode is LewisModes.THOROUGH, the lewis structure search will be lengthened

If mode is LewisModes.FINDALL, the lewis structure search will be lengthened and suboptimal results will be included in the output data (which is sorted to have the best first).

If the mmjag Lewis code fails to update the bonding, the original bonding will be preserved.

Parameters

st – structure to clean up
mode – specifies if std or ring-chain scoring should be used and whether the data is returned from lewis.cpp. Only STD, PRINT, RINGCHAIN, THOROUGH, and FINDALL are acceptable values

Returns

If mode is PRINT, RINGCHAIN, THOROUGH, or FINDALL, parsed lewis structure data is returned as namedtuple; an empty list is returned if mode is STD.

schrodinger.application.jaguar.utils.parse_lewis_data(lewis_data: list[str]) → list[schrodinger.application.jaguar.utils.LewisStructure]¶

Parse the string-formatted Lewis data from mmjag into a data structure for easy use.

Parameters: lewis_data – the line-by-line output of mmjag/lewis.cpp run on a structure
Returns: NamedTuples containing charge, multiple bond, and score

schrodinger.application.jaguar.utils.get_charges(lewis_output: list[str]) → tuple[list[list[schrodinger.application.jaguar.utils.ChgAt]], list[bool]]¶

Parse charges from lewis code string output

Parameters: lewis_output – the line-by-line output of mmjag/lewis.cpp run on a structure
Returns: For each structure in the lewis_output (the length of the list), list of the charged atom and their charges, whether structure contains unpaired spins

schrodinger.application.jaguar.utils.get_bonds(lewis_output: list[str]) → list[list[tuple[int, int]]]¶

Parse bonds from lewis code string output

Parameters: lewis_output – the line-by-line output of mmjag/lewis.cpp run on a structure
Returns: For each structure in the lewis_output (the length of the list), list of the multiple bonds in the structure (NB: a triple bond is noted by being present in the list twice)

schrodinger.application.jaguar.utils.get_scores(lewis_output: list[str]) → list[float]¶

Parse scores from lewis code string output

Parameters: lewis_output (list of strings) – the line-by-line output of mmjag/lewis.cpp run on a structure
Return type: list of floats
Returns: For each structure in the lewis_output (the length of the list), that structures score according to the mmjag/lewis.cpp code (see there for more details)

schrodinger.application.jaguar.utils.apply_lewis(st: schrodinger.structure._structure.Structure, lewis_st: schrodinger.application.jaguar.utils.LewisStructure) → schrodinger.structure._structure.Structure¶

Return a copy of a structure with a Lewis structure as described by the LewisStructure given.

Parameters

st – structure on which to apply Lewis structure
lewis_st – Namedtuple containing charge, multiple bond, and score

Returns

a structure with the desired Lewis structure applied

class schrodinger.application.jaguar.utils.GenOptions(kwdict=None)¶

Bases: object

A class to convert keyword value pairs defined in a single string into a data structure, and allow them to be converted back into a string.

Here are some example strings:

'igeopt=1 mp2=3'
'igeopt=1 maxitg=1 iacc=1'

eq_re = re.compile('\\s*=\\s*')¶

key_val_re = re.compile('(?P<key>[^= ]+)=(?P<value>[^= \\n]+(\\s+\\d+)?)\\s*')¶

OK = 0¶

PARTIAL = 1¶

ERROR = 2¶

__init__(kwdict=None)¶

static fromString(string)¶: Create a GenOptions instance from the provided string.

static testString(string, gen_options=None)¶

Test the state of the provided string. If gen_options is provided, set its values based on the keyword value pairs in the string.

Parameters

string (str): Input string to read for settings.
gen_options (GenOptions): A gen_options instance to modify according to the values in ‘string’.

toString()¶

commandLineOptions()¶

isEquivalent(other)¶

schrodinger.application.jaguar.utils.is_spiro_junction(rings: list[list[int]], at_idx: int) → bool¶

Check if a given atom is a simple spiro junction between rings

If an atom is both part of a fused ring system and is a spiro junction, we will return False.

Parameters

rings – ordered list of atom indexes proceeding around around a ring (as generated by st.find_rings())
at_idx – index of atom to check if it is a spiro junction, i.e. an atom which is the only atom shared between two rings.

Returns

True if at_idx is a spiro junction

schrodinger.application.jaguar.utils.flip_ring_conformation(st: schrodinger.structure._structure.Structure, at1_idx: int, at2_idx: Optional[int] = None) → schrodinger.structure._structure.Structure¶

Flip a ring conformation (i.e. boat-like) to a good (chair-like) one. Only applies to 4-membered rings or greater.

We fix the ring conformation by rotating the two torsions of the substituents on either side of at1 (the atom of the ring on the “wrong” side). This keeps their substituents pointed in good places. Specifically, at1 is moved to the unique position (other than where it starts) with the same bond distances to its nearest neighbors in the ring and where all angles involving at1 and one side of the ring are preserved. We have to rotate one of the substituent-at1 torsions back to fix the at1 non-ring substituents.

Parameters

st – structure to fix the conformation of
at1_idx – atom index of the atom that needs to be flipped to the opposite side of the ring
at2_idx – atom index adjacent to at1_idx in the ring to be flipped, used to disambiguate in spiro compounds when at1_idx is the junction

Returns

structure with corrected ring conformation

schrodinger.application.jaguar.utils.get_signed_angles_for_ring_flip_torsions(b_at3_xyz: numpy.array, b_at2_xyz: numpy.array, at1_xyz: numpy.array, f_at2_xyz: numpy.array, f_at3_xyz: numpy.array) → tuple[float, float]¶

Get the angles to rotate the torsions adjacent to the moving atom in a ring flip.

We rotate the two torsions on either side of at1 (the atom of the ring that needs to move to the other side of the ring in the ring-flip) so that the substituents of those neighboring ring atoms (i.e. b_at2 and f_at2) are pointing in sensible directions. How the angle to rotate these torsions is calculated is a bit complicated.

After some experimentation, the most reliable choice is to find the angle such that when rotating about the b_at3-b_at2 axis, the distance from at1 to f_at2 is held constant. This corresponds to finding the intersection of the circle swept out by at1 when rotating about the b_at3-b_at2 axis with the sphere of radius length(f_at2-at1). This intersection occurs at two points and at1 is currently at one of those points. We therefore need to find the angle about each torsion to rotate that moves at1 to the other point.

Note, this should make round-trips a no-op. Note also that the exact angles between substituents around b_at2 will be held constant but this is not the case for f_at2. In general, the angles to at1 of other f_at2 substituents can change, though the degree is usually small and especially so when the b_at3-b_at2 and f_at3-f_at2 axes are parallel which is often the case for 6-membered rings.

Parameters

b_at3_xyz – xyz coordinates of the atom 2 positions “behind” the atom being flipped
b_at2_xyz – xyz coordinates of the atom 1 position “behind” the atom being flipped
at1_xyz – xyz coordinates of the atom being flipped
f_at2_xyz – xyz coordinates of the atom 1 position “ahead” the atom being flipped
f_at3_xyz – xyz coordinates of the atom 2 positions “ahead” the atom being flipped

schrodinger.application.jaguar.utils.get_3point_normal(center: numpy.array, sub1: numpy.array, sub2: numpy.array, sub3: numpy.array) → numpy.array¶

Get the hypothetical location of a 4th tetrahedral substituent from center atom and three substituents, 1A from center.

Parameters

center – xyz coordinates of central atom assumed to be a tetrahedron
sub1 – xyz coordinates of first substituent of center
sub2 – xyz coordinates of second substituent of center
sub3 – xyz coordinates of third substituent of center

Returns

xyz coordinates of 4th substituent, at unit distance from center

schrodinger.application.jaguar.utils.get_plane_alignment_angle(at1: numpy.array, at2: numpy.array, at3: numpy.array, at4: numpy.array, at5: numpy.array, at6: numpy.array, rot_axis: numpy.array) → float¶

Determine the angle about rot_axis to rotate the plane defined by at4, at5, and at6 such that it is aligned with the plane defined by at1, at2, and at3.

That is, define a plane P1 by points at1, at2, and at3 and a plane P2 by at4, at5, and at6. Suppose we can rotate the points at4, at5, and at6 about an axis defined by rot_axis. The function returns the angle that makes the angle between P1 and P2 0 (degrees).

Parameters

at1 – xyz-coordinate of point1 in P1
at2 – xyz-coordinate of point2 in P1
at3 – xyz-coordinate of point3 in P1
at4 – xyz-coordinate of point1 in P2
at5 – xyz-coordinate of point2 in P2
at6 – xyz-coordinate of point3 in P2
rot_axis – vector defining rotation axis

Returns

angle which aligns P1 and P2 when P2 is rotated about rot_axis

schrodinger.application.jaguar.utils.project_vec_onto_plane(vec, plane_normal)¶: Project a vector onto a plane defined by a vector normal to the plane

schrodinger.application.jaguar.utils.format_time(time: float, precision: int = 2) → str¶

Given a time in seconds return a string returning the time in the form “<float> unit”. The number of printed decimals of the <float> value is set by the “precision” argument and unit can be centuries, years, months, days, hours, seconds,milliseconds, microseconds or nanoseconds. Whichever is most appropriate.

Parameters

time – the time in seconds
precision – the precision (number of decimal places) to use when printing the time value

Returns

a string representing the time

schrodinger.application.jaguar.utils.delete_ghosts(st: schrodinger.structure._structure.Structure) → schrodinger.structure._structure.Structure¶

Delete ghost/dummy atoms from the structure and return the modified structure.

Ghosts/dummys are identified using msutils.is_dummy_atom. The original structure is unmodified.

Parameters: st – the structure with the ghost atoms
Returns: the structure without the ghost atoms