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
, orgraph
must be specified.- Type
Optional[str]
- inchi¶
The InChI descriptor with an explicit H layer and chirality information.
Note
Either
smiles
,inchi
, orgraph
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
, orgraph
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
iftorsions
are used, and vice versa. Entries are dictionaries containing the same keys as thecoordinates
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¶
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]]