Species model

TCKDB backend app models species module

class tckdb.backend.app.models.species.Species(**kwargs)[source]

A class for representing a TCKDB Species item.

Note

All atom indices in these arguments are 1-indexed unless explicitly stated otherwise.

Note

Arguments use SI units as much as possible. Parameters must be provided in the requested units, necessary unit conversions must be done by the user prior to uploading data. The requested units are noted for each parameter where relevant.

Example:

Species(label='formaldehyde',
        statmech_software='Arkane (RMG) v3.0.0',
        smiles='C=O',
        charge=0,
        multiplicity=1,
        electronic_state='X',
        coordinates={'symbols': ('C', 'O', 'H', 'H'),
                     'isotopes': (12, 16, 1, 1),
                     'coords': ((-0.0122240982, 0.0001804054, -0.00162116),
                                (1.2016481968, -0.0177341701, 0.1593624097),
                                (-0.5971643978, 0.9327281670, 0.0424401022),
                                (-0.5922597008, -0.9151744023, -0.2001813507))},
        external_symmetry=2,
        point_group='C2v',
        conformation_method='ARC',
        is_well=True,
        is_global_min=True,
        is_ts=False,
        electronic_energy=-325.6458956547,
        E0=123.54842,
        frequencies=[132.2, 548.5, 1032.5, 2015.22, 2018.12, 3005.22],
        scaled_projected_frequencies=[130.217, 540.2725, 1017.013,
                                      1984.992, 1987.848, 2960.142],
        normal_displacement_modes=[[0.125, 0.89, 0.35],
                                   [-0.25, 0.25, -0.89],
                                   [0.56, 0.98, -0.65],
                                   [0.022, -0.005, 0.5],
                                   [-0.98, -0.002, 0.65],
                                   [0.05, 0.0025, -0.722]],
        freq_id=11,
        rigid_rotor='asymmetric top',
        statmech_treatment='RRHO',
        rotational_constants=[1.25, 8.56, 9.55],
        H298=-109.4534,
        S298=218.237,
        Cp_values=[35.313, 39.037, 43.4299, 47.7813, 55.438, 61.463, 70.71],
        Cp_T_list=[300, 400, 500, 600, 800, 1000, 1500],
        heat_capacity_model={'model': 'NASA',
                             'T min': 100,
                             'T max': 5000,
                             'coefficients': {'low': [4.13878818E+00, -4.69514383E-03,
                                                      2.25730249E-05, -2.09849937E-08,
                                                      6.36123283E-12, -1.43493283E+04,
                                                      3.23827482E+00],
                                              'high': [2.36095410E+00, 7.66804276E-03,
                                                       -3.19770442E-06, 6.04724833E-10,
                                                       -4.27517878E-14, -1.42794809E+04,
                                                       1.04457152E+01],
                                              'T int': 1041.96}},
        encorr_id=33,
        opt_path='path_opt',
        freq_path='path_freq',
        sp_path='path_sp')
id

The primary key (not a user input).

Type

int

label

A free user label for the species (maximum 255 characters).

Type

Optional[str]

# provenance
statmech_software

The statistical mechanics software and version used for the statistical mechanics and thermodynamic property computations. Should include the version. Example:

'Arkane (RMG) v3.0.0'
Type

Optional[str]

timestamp

The UTC timestamp of uploading the data to TCKDB (not a user input).

Type

float

retracted

A reason for retracting this object. Default: None (not a user input).

Type

str

# review
reviewed

Whether this entry was reviewed (not a user input).

Type

bool

approved

If reviewed, whether it was approved (not a user input).

Type

bool

reviewer_flags

Backend flags to assist the review process (automatically determined, but users may add notes to flag items for the reviewer).

Example:

{'general': 'This species has a shallow (1.5 kJ/mol) well along the 4-8-7-10 torsional mode.'}
Type

Dict[str, str]

# chemical identifiers
smiles

The canonical SMILES descriptor with chirality information.

Note

Either smiles, inchi, or graph must be specified.

Type

Optional[str]

inchi

The InChI descriptor with an explicit H layer and chirality information.

Note

Either smiles, inchi, or graph must be specified.

Type

Optional[str]

inchi_key

The InChI key descriptor. Automatically assigned if not given by the user.

Type

Optional[str]

charge

The net molecular charge.

Type

int

multiplicity

The spin multiplicity.

Type

int

electronic_state

The species electronic state at CIS level. Default: 'X' (denoting ground state).

Type

Optional[str]

# geometry and connectivity
coordinates

Cartesian coordinates in standard orientation. Keys (values) are:

  • ‘symbols’ (Tuple[str])

    Chemical element symbols

  • ‘isotopes’ (Tuple[int])

    The respective isotopes

  • ‘coords’ (Tuple[Tuple[float]])

    The respective coordinates

Example for methane:

{'symbols': ('C', 'H', 'H', 'H', 'H'),
 'isotopes': (12, 1, 1, 1, 1),
 'coords': ((0.0, 0.0, 0.0),
            (0.6300326, 0.6300326, 0.6300326),
            (-0.6300326, -0.6300326, 0.6300326),
            (-0.6300326, 0.6300326, -0.6300326),
            (0.6300326, -0.6300326, -0.6300326))}
Type

Dict[str, Union[Tuple[Tuple[float, float, float], …], Tuple[int, …], Tuple[str, …]]]

graph

A 2D connectivity graph in an RMG adjacency list format. Note that this graph represents a single Lewis structure (resonance structure). These graphs can be generated using RMG’s API or online at https://rmg.mit.edu/molecule_search.

Note

Either smiles, inchi, or graph must be specified.

Example for methane:

multiplicity 1
1 C u0 p0 c0 {2,S} {3,S} {4,S} {5,S}
2 H u0 p0 c0 {1,S}
3 H u0 p0 c0 {1,S}
4 H u0 p0 c0 {1,S}
5 H u0 p0 c0 {1,S}
Type

Optional[str]

fragments

Fragments represented by this species, e.g., VdW wells. Entries are atom index lists of all atoms in a fragment. Default: None (denoting there’s only one fragment).

Type

Optional[List[List[int]]]

fragment_orientation

Relative orientation of fragments, starting from the heaviest one. All fragments must be in standard Cartesian orientation prior to determining the following parameters. Entries are dictionaries with the following keys (values):

  • ‘cm’ (List[float])

    A vector pointing from a fragment’s center to the center of mass of the next fragment.

    Units:

    Angstrom

  • ‘x’ (float)

    The X axis rotational angle in degrees.

  • ‘y’ (float)

    The Y axis rotational angle in degrees.

  • ‘z’ (float)

    The Z axis rotational angle in degrees.

Type

Optional[List[Dict[str, Union[float, List[float]]]]]

external_symmetry

The species external symmetry (excluding internal torsions)

Type

int

point_group

The symmetry point group (use “inf” for infinity, don’t add spaces or underscores). Examples: 'C1', 'Cinfv', 'C2h', 'D4', 'Dinfh', 'S4', 'T', 'Th', 'Td', 'O', 'Oh', 'I', 'Ih'.

Type

str

chirality

The species’ chiral centers, following the Cahn–Ingold–Prelog (CIP) notation ('R' or 'S' for atom centers, 'E' or 'Z' for double bond centers). Keys are tuples of atom indices of a chiral center, values are string representations of the respective chiral center.

Note: Non-radical valance 3 nitrogen atoms are also considered chiral if connected to three different groups (considering the lone pair to always be a unique fourth group). In such cases, use a 'NR' or 'NS' notation.

Example

A double bond with chirality 'E' between atoms 1-2, an 'S' chiral center on atom 3, and an 'S' chiral center on atom 6 which is a nitrogen are represented as:

{(1, 2): 'E', (3,): 'S', (6,): 'NS'})
Type

Optional[Dict[Tuple[int], str]]

conformation_method

The method used to determine the lowest energy conformer. Required if the species has 4 or more atoms.

Type

Optional[str]

is_well

Whether this conformer represents a local well (at the opt level used).

Type

bool

is_global_min

If this conformer is a well, whether it is meant to represents the global minimum energy well.

Type

bool

global_min_geometry

If this species does not represent the global minimum well, this argument must contain the coordinates of the global minimum energy conformer at the same opt level.

Type

Optional[Dict[str, tuple]]

# TS
is_ts

Whether this species represents a transition state. Default: False.

Type

bool

irc_trajectories

The two IRC trajectories. Each trajectory is a list of coordinates dictionaries. Required if the species is a transition state. Cannot be specified for non-TS species.

Type

Optional[List[List[Dict[str, tuple]]]]

# energy
electronic_energy

The species single point electronic energy as calculated by the electronic structure software (without zero-point energy correction).

Units:

Hartree.

Type

float

E0

The zero kelvin enthalpy (electronic energy + zero-point energy correction) after applying energy corrections.

Units:

kJ/mol

Type

float

active_space

The active space used for a multireference calculation. Keys (values) are:

  • ‘electrons’ (int)

    The number of electrons in the active space,

  • ‘orbitals’ (int)

    The number of orbitals in the active space.

Type

Optional[Dict[str, int]]

# Hessian
hessian

The computed Hessian matrix (lower triangle). Required for polyatomic species (with 2 or more atoms).

Units:

Hartree / Bohr 2

Type

Optional[List[List[float]]]

# vibrational modes
frequencies

Unscaled, unprojected frequencies. Complex roots are represented by a negative number. Required for polyatomic species (with 2 or more atoms).

Units:

cm -1

Type

Optional[List[float]]

scaled_projected_frequencies

Scaled, projected frequencies (user input). If no rotors are used then the projection is unnecessary. Complex roots are represented by a negative number. Required for polyatomic species (with 2 or more atoms).

Units:

cm -1

Type

Optional[List[float]]

normal_displacement_modes

The normal displacement modes. Required for polyatomic species (with 2 or more atoms). Entries of the first level list are normal displacement modes per frequency. Entries of the second level list are normal displacement modes per frequency per atom. Entries of the third level list are normal displacement modes per frequency per atom per axis (X, Y, Z).

Units:

Angstrom

Type

Optional[List[List[List[float]]]]

freq_id

The frequency scaling factor key for the Freq table. Required for polyatomic species (with 2 or more atoms).

Note

This argument is facilitated by querying the Freq table.

Type

Optional[int]

# rotational modes
rigid_rotor

The rigid rotor treatment type. Allowed values: 'atom', 'linear', 'spherical top', 'symmetric top', or 'asymmetric top'.

Type

str

statmech_treatment

The statistical mechanics treatment of the species. Required for polyatomic species (with 3 or more atoms).

Examples:

  • ‘RRHO’ (rigid rotor harmonic oscillator)

  • ‘RRHO-1D’ (rigid rotor harmonic oscillator with 1D torsions)

  • ‘RRHO-1D-ND’ (rigid rotor harmonic oscillator with mixed 1D torsions and ND torsions)

  • ‘RRHO-ND’ (rigid rotor harmonic oscillator with ND torsions)

  • ‘RRHO-AD’ (rigid rotor harmonic oscillator with ND torsions, D is the overall number of torsions, D > 1)

  • ‘RRAO’ (rigid rotor anharmonic oscillator)

Type

Optional[str]

rotational_constants

Rotational constants. None for monoatomic species. One entry for linear molecules, three entries for non-linear polyatomic molecules. Computed from the geometry if not provided by the user.

Units:

amu * Angstrom 2

Type

Optional[List[float]]

# torsional modes
torsions

The torsional modes. Entries are dictionaries with keys (values):

  • ‘computation_type’ (str, optional)

    The torsional mode computation type. Allowed values: 'single point', 'constrained optimization', or 'continuous constrained optimization'. Default: 'continuous constrained optimization'.

  • ‘dimension’ (int, optional)

    The torsional dimension treated by this mode. Default: 1.

  • ‘constraints’ (Dict[Tuple[int, …], float], optional)

    Any constraints (bond distances, angles, and dihedral angles) used in the optimization other than the primary torsion modes. Keys (values) are:

    • Tuple[int, …] (float)

      A key is a tuple of atom indices representing an internal geometrical parameter (bond, angle, or dihedral angle). This parameter type is identified by the length of the tuple key (two, three, and four atom indices represent bond, angle and dihedral angle, respectively. Values are corresponding parameters in either degrees or Angstrom.

  • ‘symmetry’ (int)

    The internal rotation symmetry

  • ‘treatment’ (str)

    The torsion treatment method. Allowed values are 'hindered rotor', 'free rotor' 'rigid top', or 'hindered rotor density of states'.

  • ‘torsions’ (Union[List[List[int]], Iterable[int]])

    The atom indices describing the torsional mode. Entries are 4-length lists/tuples of atom indices, the number of entries is the torsion dimension.

  • ‘top’ (List[int])

    Atom indices of all atoms on one side of the internal rotor, starting from its center. For a 1D rotor (“R1-A-B-C-D-R2”), this means listing all atoms starting from one of the pivotal atoms (“C-D-R2”). For an adjacent 2D rotor (“R1-A-B-C-D-E-R2”), this means starting from the middle atom which is a pivotal atom in both modes (“C-D-E-R2”).

  • ‘energies’ (list)

    The scan energies. This is an ND array, axes order corresponds to the order in which the torsions are defined under torsions. For a 1D torsion, this would be of type List[float]. For a 2D torsion, this would be of type List[List[float]]. For a 3D torsion, this would be of type List[List[List[float]]], and so on.

    Units:

    kJ / mol

  • ‘resolution’ (Union[float, List[float]])

    The dihedral angle increment resolutions.

    Units:

    degrees

  • ‘trajectory’ (list)

    Entries are Cartesian coordinates of respective points in the scan. This is an ND array. Axes order corresponds to the order in which the torsions are defined under torsions. The structure of this argument is similar to the structure of the ‘energies’ argument.

  • ‘invalidated’ (str, optional)

    An invalidation reason, if this mode was invalidated. Useful for TSs where a torsion breaks the connectivity near the reactive site, and for high-barrier torsions not considered in the statmech treatment. Default: None.

Type

Optional[List[Dict[str, Union[Dict[Tuple[int], float], int, List[int], List[List[int]], str]]]]

# conformers
conformers

The species conformers used for Boltzmann averaging of accessible wells. None if torsions are used, and vice versa. Entries are dictionaries containing the same keys as the coordinates attribute, with two additional keys: 'energy' with the relative conformer energy in kJ/mol at the sp level, and 'degeneracy' with the number of repetitions per conformer (defaults to 1).

Type

Optional[List[Dict[str, Union[float, Tuple[Tuple[float]], Tuple[int], Tuple[str]]]]]

# thermochemical properties
H298

The standard (298.15 K, 1 bar) enthalpy change of formation. Required for non-TS species.

Units:

kJ/mol

Type

Optional[float]

S298

The standard (298.15 K, 1 bar) entropy change of formation. Required for non-TS species.

Units:

J / (mol * K)

Type

Optional[float]

Cp_values

The constant pressure heat capacity values. Required for non-TS species.

Units:

J / (mol * K).

Type

Optional[List[float]]

Cp_T_list

The temperatures in K corresponding to the discrete Cp values. Required for non-TS species.

Type

Optional[List[float]]

heat_capacity_model

The heat capacity extrapolation model and coefficients. Required for non-TS species. Keys (values) are:

  • ‘model’ (str)

    The heat capacity model. For example: 'NASA', 'Wilhoit'.

  • ‘T min’ (float)

    The minimum temperature range in K.

  • ‘T max’ (float)

    The maximum temperature range in K.

  • ‘P min’ (float)

    The minimum temperature range in K (irrelevant for NASA/Wilhoit).

  • ‘P max’ (float)

    The maximum temperature range in K (irrelevant for NASA/Wilhoit).

  • ‘coefficients’ (dict)

    The heat capacity coefficients. For a 'NASA' model the keys (values) are:

    • ‘low’ (List[float]): Low T range coefficients

    • ‘high’ (List[float]): High T range coefficients

    • ‘T int’ (float): Intermediate range temperature in K

    For a ‘Wilhoit’ model the keys (values) are:

    • ‘a0’ (float): The Wilhoit a0 coefficient

    • ‘a1’ (float): The Wilhoit a1 coefficient

    • ‘a2’ (float): The Wilhoit a2 coefficient

    • ‘a3’ (float): The Wilhoit a3 coefficient

    • ‘B’ (float): The Wilhoit B coefficient

    • ‘H0’ (float): The Wilhoit H0 coefficient

    • ‘S0’ (float): The Wilhoit S0 coefficient

Type

Optional[Dict[str, Union[float, Dict[str, Union[float, List[float]]], str]]]

# relationships - Many to One
encorr_id

The energy correction key from the EnCorr table.

Type

int

encorr

An attribute that establishes a bidirectional relationship in a One to Many data model with the EnCorr table, where the “reverse” side is a Many to One data model.

Type

relationship

literature_id

The literature reference from the Literature table.

Type

int

literature

An attribute that establishes a bidirectional relationship in a One to Many data model with the Literature table, where the “reverse” side is a Many to One data model.

Type

relationship

bot_id

The bot used to generate the object from the Bot table.

Type

int

bot

An attribute that establishes a bidirectional relationship in a One to Many data model with the Bot table, where the “reverse” side is a Many to One data model.

Type

relationship

opt_level

An attribute that establishes a bidirectional relationship in a One to Many data model with the Level table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

freq_level

An attribute that establishes a bidirectional relationship in a One to Many data model with the Level table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

scan_level

An attribute that establishes a bidirectional relationship in a One to Many data model with the Level table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

irc_level

An attribute that establishes a bidirectional relationship in a One to Many data model with the Level table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

sp_level

An attribute that establishes a bidirectional relationship in a One to Many data model with the Level table, where the “reverse” side is a Many to One data model. Required.

Type

relationship

opt_ess

An attribute that establishes a bidirectional relationship in a One to Many data model with the ESS table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

freq_ess

An attribute that establishes a bidirectional relationship in a One to Many data model with the ESS table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

scan_ess

An attribute that establishes a bidirectional relationship in a One to Many data model with the ESS table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

irc_ess

An attribute that establishes a bidirectional relationship in a One to Many data model with the ESS table, where the “reverse” side is a Many to One data model.

Type

Optional[relationship]

sp_ess

An attribute that establishes a bidirectional relationship in a One to Many data model with the ESS table, where the “reverse” side is a Many to One data model. Required.

Type

relationship

# relationships - Many to Many
authors

An attribute that establishes a bidirectional relationship in a Many to Many data model with the Person table representing authors of this object.

Type

relationship

reviewers

An attribute that establishes a bidirectional relationship in a Many to Many data model with the Person table representing reviewers of this object.

Type

relationship

# paths
opt_path

The path to the optimization output file. Required for polyatomic species (with 2 or more atoms).

Type

Optional[str]

freq_path

The path to the frequencies calculation output file. Required for polyatomic species (with 2 or more atoms).

Type

Optional[str]

scan_paths

Paths to the torsion scan calculation output files. Keys are tuples of tuples. The number of inner-level tuples corresponds to the torsion dimension. Entries of the inner-level tuple are torsion atom indices. Values are paths to the respective scan calculation log file.

Type

Optional[Dict[Tuple[Tuple[int, int, int, int], …], str]]

irc_paths

Entries are paths to the IRC calculation output files. Required for transition states. Either a single path to a forward+reverse IRC, or two respective paths.

Type

Optional[List[str]]

sp_path

The path to the single point energy output file.

Type

str

# unconverged jobs
unconverged_jobs

Any relevant unconverged jobs that were troubleshooted while calculating this Species. Entries are dictionaries, keys (values) are:

  • ‘job type’ (str): 'opt', 'freq', 'scan', 'irc', or 'sp'

  • ‘issue’ (str): The identified issue

  • ‘troubleshooting’ (str): Description of the troubleshooting method(s) that solved the issue

  • ‘comment’ (str): An optional comment explaining the troubleshooting approach

  • ‘path’ (str): The path to the relevant unconverged ESS log file

Type

Optional[List[Dict[str, str]]]

# misc
extras

Any additional information in the form of a dictionary.

Type

Optional[Dict[str, Any]]

tckdb.backend.app.models.species.species_as_str(class_name, id, label, smiles, inchi, inchi_key)[source]

A helper function for generating a user-friendly string representation of a Species or NonPhysicalSpecies object.