# API¶

The complete set of object models and relations implemented by QCPortal. Every class shown here is its own model and the attributes shown are valid kwargs and values which can be fed into the construction.

class qcportal.models.KeywordSet(**data)[source]

A key:value storage object for Keywords.

Parameters
• id (ObjectId, Optional) – The Id of this object, will be automatically assigned when added to the database.

• hash_index (str) – The hash of this keyword set to store and check for collisions. This string is automatically computed.

• values (Dict[str, Any]) – The key-value pairs which make up this KeywordSet. There is no direct relation between this dictionary and applicable program/spec it can be used on.

• lowercase (bool, Default: True) – String keys are in the values dict are normalized to lowercase if this is True. Assists in matching against other KeywordSet objects in the database.

• exact_floats (bool, Default: False) – All floating point numbers are rounded to 1.e-10 if this is False.Assists in matching against other KeywordSet objects in the database.

• comments (str, Optional) – Additional comments for this KeywordSet. Intended for pure human/user consumption and clarity.

class qcportal.models.Molecule(orient=False, validate=None, **kwargs)[source]

The fundamental representation of a Molecule inside the QCArchive Ecosystem. This model contains data for atomic elements, coordinates, connectivity, charges, fragmentation, etc. The model also supports orientation and measurement utilities.

All Molecule objects are oriented via inertia tensor with the center-of-mass at (0,0,0) unless explicitly blocked.

All Molecule objects have coordinates truncated to 8 (GEOMETRY_NOISE) decimal places and mass and charge truncated to 6 (MASS_NOISE) and 4 (CHARGE_NOISE), respectively, unless explicitly blocked.

Parameters
• schema_name (ConstrainedStrValue, Default: qcschema_molecule) – The QCSchema specification this model conforms to. Explicitly fixed as qcschema_molecule.

• schema_version (int, Default: 2) – The version number of schema_name that this Molecule model conforms to.

• validated (bool, Default: False) – A boolean indicator (for speed purposes) that the input Molecule data has been previously checked for schema (data layout and type) and physics (e.g., non-overlapping atoms, feasible multiplicity) compliance. This should be False in most cases. A True setting should only ever be set by the constructor for this class itself or other trusted sources such as a Fractal Server or previously serialized Molecules.

• symbols (Array) – An ordered (nat,) array-like object of atomic elemental symbols of shape (nat,). The index of this attribute sets atomic order for all other per-atom setting like real and the first dimension of geometry. Ghost/Virtual atoms must have an entry in this array-like and are indicated by the matching the 0-indexed indices in real field.

• geometry (Array) – An ordered (nat,3) array-like for XYZ atomic coordinates [a0]. Atom ordering is fixed; that is, a consumer who shuffles atoms must not reattach the input (pre-shuffling) molecule schema instance to any output (post-shuffling) per-atom results (e.g., gradient). Index of the first dimension matches the 0-indexed indices of all other per-atom settings like symbols and real. Can also accept array-likes which can be mapped to (nat,3) such as a 1-D list of length 3*nat, or the serialized version of the array in (3*nat,) shape; all forms will be reshaped to (nat,3) for this attribute.

• name (str, Optional) – A common or human-readable name to assign to this molecule. Can be arbitrary.

• identifiers (Identifiers, Optional) – An optional dictionary of additional identifiers by which this Molecule can be referenced, such as INCHI, canonical SMILES, etc. See the :class:Identifiers model for more details.

• comment (str, Optional) – Additional comments for this Molecule. Intended for pure human/user consumption and clarity.

• molecular_charge (float, Default: 0.0) – The net electrostatic charge of this Molecule.

• molecular_multiplicity (int, Default: 1) – The total multiplicity of this Molecule.

• masses (Array, Optional) – An ordered 1-D array-like object of atomic masses [u] of shape (nat,). Index order matches the 0-indexed indices of all other per-atom settings like symbols and real. If this is not provided, the mass of each atom is inferred from their most common isotope. If this is provided, it must be the same length as symbols but can accept None entries for standard masses to infer from the same index in the symbols field.

• real (Array, Optional) – An ordered 1-D array-like object of shape (nat,) indicating if each atom is real (True) or ghost/virtual (False). Index matches the 0-indexed indices of all other per-atom settings like symbols and the first dimension of geometry. If this is not provided, all atoms are assumed to be real (True).If this is provided, the reality or ghostality of every atom must be specified.

• atom_labels (Array, Optional) – Additional per-atom labels as a 1-D array-like of of strings of shape (nat,). Typical use is in model conversions, such as Elemental <-> Molpro and not typically something which should be user assigned. See the comments field for general human-consumable text to affix to the Molecule.

• atomic_numbers (Array, Optional) – An optional ordered 1-D array-like object of atomic numbers of shape (nat,). Index matches the 0-indexed indices of all other per-atom settings like symbols and real. Values are inferred from the symbols list if not explicitly set.

• mass_numbers (Array, Optional) – An optional ordered 1-D array-like object of atomic mass numbers of shape (nat). Index matches the 0-indexed indices of all other per-atom settings like symbols and real. Values are inferred from the most common isotopes of the symbols list if not explicitly set.

• connectivity (List[Tuple[int, int, float]], Optional) – The connectivity information between each atom in the symbols array. Each entry in this list is a Tuple of (atom_index_A, atom_index_B, bond_order) where the atom_index matches the 0-indexed indices of all other per-atom settings like symbols and real.

• fragments (List[Array], Optional) – An indication of which sets of atoms are fragments within the Molecule. This is a list of shape (nfr) of 1-D array-like objects of arbitrary length. Each entry in the list indicates a new fragment. The index of the list matches the 0-indexed indices of fragment_charges and fragment_multiplicities. The 1-D array-like objects are sets of atom indices indicating the atoms which compose the fragment. The atom indices match the 0-indexed indices of all other per-atom settings like symbols and real.

• fragment_charges (List[float], Optional) – The total charge of each fragment in the fragments list of shape (nfr,). The index of this list matches the 0-index indices of fragment list. Will be filled in based on a set of rules if not provided (and fragments are specified).

• fragment_multiplicities (List[int], Optional) – The multiplicity of each fragment in the fragments list of shape (nfr,). The index of this list matches the 0-index indices of fragment list. Will be filled in based on a set of rules if not provided (and fragments are specified).

• fix_com (bool, Default: False) – An indicator which prevents pre-processing the Molecule object to translate the Center-of-Mass to (0,0,0) in euclidean coordinate space. Will result in a different geometry than the one provided if False.

• fix_orientation (bool, Default: False) – An indicator which prevents pre-processes the Molecule object to orient via the inertia tensor.Will result in a different geometry than the one provided if False.

• fix_symmetry (str, Optional) – Maximal point group symmetry which geometry should be treated. Lowercase.

• provenance (Provenance, Default: {‘creator’: ‘QCElemental’, ‘version’: ‘v0.6.1’, ‘routine’: ‘qcelemental.models.molecule’}) – The provenance information about how this Molecule (and its attributes) were generated, provided, and manipulated.

• id (Any, Optional) – A unique identifier for this Molecule object. This field exists primarily for Databases (e.g. Fractal’s Server) to track and lookup this specific object and should virtually never need to be manually set.

• extras (Dict[str, Any], Optional) – Extra information to associate with this Molecule.

class qcportal.models.ResultRecord(**data)[source]
Parameters
• client (Any, Optional) – The client object which the records are fetched from.

• cache (Dict[str, Any], Default: {}) – Object cache from expensive queries. It should be very rare that this needs to be set manually by the user.

• id (ObjectId, Optional) – Id of the object on the database. This is assigned automatically by the database.

• hash_index (str, Optional) – Hash of this object used to detect duplication and collisions in the database.

• procedure (ConstrainedStrValue, Default: single) – Procedure is fixed as “single” because this is single quantum chemistry result.

• program (str) – The quantum chemistry program which carries out the individual quantum chemistry calculations.

• version (int, Default: 1) – Version of the ResultRecord Model which this data was created with.

• extras (Dict[str, Any], Default: {}) – Extra information to associate with this record.

• stdout (ObjectId, Optional) – The Id of the stdout data stored in the database which was used to generate this record from the various programs which were called in the process.

• stderr (ObjectId, Optional) – The Id of the stderr data stored in the database which was used to generate this record from the various programs which were called in the process.

• error (ObjectId, Optional) – The Id of the error data stored in the database in the event that an error was generated in the process of carrying out the process this record targets. If no errors were raised, this field will be empty.

• manager_name (str, Optional) – Name of the Queue Manager which generated this record.

• status ({COMPLETE,INCOMPLETE,RUNNING,ERROR}, Default: INCOMPLETE) – The state of a record object. The states which are available are a finite set.

• modified_on (datetime, Optional) – Last time the data this record points to was modified.

• created_on (datetime, Optional) – Time the data this record points to was first created.

• provenance (Provenance, Optional) – Provenance information tied to the creation of this record. This includes things such as every program which was involved in generating the data for this record.

• driver ({energy,gradient,hessian,properties}) – The type of calculation that is being performed (e.g., energy, gradient, Hessian, …).

• method (str) – The quantum chemistry method the driver runs with.

• molecule (ObjectId) – The Id of the molecule in the Database which the result is computed on.

• basis (str, Optional) – The quantum chemistry basis set to evaluate (e.g., 6-31g, cc-pVDZ, …). Can be None for methods without basis sets.

• keywords (ObjectId, Optional) – The Id of the KeywordSet which was passed into the quantum chemistry program that performed this calculation.

• return_result (Union[float, Array, Dict[str, Any]], Optional) – The primary result of the calculation, output is a function of the specified driver.

• properties (ResultProperties, Optional) – Additional data and results computed as part of the return_result.

class qcportal.models.OptimizationRecord(**data)[source]

A OptimizationRecord for all optimization procedure data.

Parameters
• client (Any, Optional) – The client object which the records are fetched from.

• cache (Dict[str, Any], Default: {}) – Object cache from expensive queries. It should be very rare that this needs to be set manually by the user.

• id (ObjectId, Optional) – Id of the object on the database. This is assigned automatically by the database.

• hash_index (str, Optional) – Hash of this object used to detect duplication and collisions in the database.

• procedure (ConstrainedStrValue, Default: optimization) – A fixed string indication this is a record for an “Optimization”.

• program (str) – The quantum chemistry program which carries out the individual quantum chemistry calculations.

• version (int, Default: 1) – Version of the OptimizationRecord Model which this data was created with.

• extras (Dict[str, Any], Default: {}) – Extra information to associate with this record.

• stdout (ObjectId, Optional) – The Id of the stdout data stored in the database which was used to generate this record from the various programs which were called in the process.

• stderr (ObjectId, Optional) – The Id of the stderr data stored in the database which was used to generate this record from the various programs which were called in the process.

• error (ObjectId, Optional) – The Id of the error data stored in the database in the event that an error was generated in the process of carrying out the process this record targets. If no errors were raised, this field will be empty.

• manager_name (str, Optional) – Name of the Queue Manager which generated this record.

• status ({COMPLETE,INCOMPLETE,RUNNING,ERROR}, Default: INCOMPLETE) – The state of a record object. The states which are available are a finite set.

• modified_on (datetime, Optional) – Last time the data this record points to was modified.

• created_on (datetime, Optional) – Time the data this record points to was first created.

• provenance (Provenance, Optional) – Provenance information tied to the creation of this record. This includes things such as every program which was involved in generating the data for this record.

• schema_version (int, Default: 1) – The version number of QCSchema under which this record conforms to.

• initial_molecule (ObjectId) – The Id of the molecule which was passed in as the reference for this Optimization.

• qc_spec (QCSpecification) – The specification of the quantum chemistry calculation to run at each point.

• keywords (Dict[str, Any], Default: {}) – The keyword options which were passed into the Optimization program. Note: These are a Dict, not a KeywordSet.

• energies (List[float], Optional) – The ordered list of energies at each step of the Optimization.

• final_molecule (ObjectId, Optional) – The ObjectId of the final, optimized Molecule the Optimization procedure converged to.

• trajectory (List[ObjectId], Optional) – The list of Molecule Id’s the Optimization procedure generated at each step of the optimization.initial_molecule will be the first index, and final_molecule will be the last index.

class qcportal.models.QCSpecification[source]

The quantum chemistry metadata specification for individual computations such as energy, gradient, and Hessians.

Parameters
• driver ({energy,gradient,hessian,properties}) – The type of calculation that is being performed (e.g., energy, gradient, Hessian, …).

• method (str) – The quantum chemistry method to evaluate (e.g., B3LYP, PBE, …).

• basis (str, Optional) – The quantum chemistry basis set to evaluate (e.g., 6-31g, cc-pVDZ, …). Can be None for methods without basis sets.

• keywords (ObjectId, Optional) – The Id of the KeywordSet registered in the database to run this calculation with. This Id must exist in the database.

• program (str) – The quantum chemistry program to evaluate the computation with. Not all quantum chemistry programs support all combinations of driver/method/basis.

class qcportal.models.GridOptimizationInput[source]

The input to create a GridOptimization Service with.

Parameters
• program (ConstrainedStrValue, Default: qcfractal) – The name of the source program which initializes the Grid Optimization. This is a constant and is used for provenance information.

• procedure (ConstrainedStrValue, Default: gridoptimization) – The name of the procedure being run. This is a constant and is used for provenance information.

• initial_molecule (Union[ObjectId, Molecule]) – The Molecule to begin the Grid Optimization with. This can either be an existing Molecule in the database (through its ObjectId) or a fully specified Molecule model.

• keywords (GOKeywords) – The keyword options to run the Grid Optimization.

• optimization_spec (OptimizationSpecification) – The specification to run the underlying optimization through at each grid point.

• qc_spec (QCSpecification) – The specification for each of the quantum chemistry calculations run in each geometry optimization.

class qcportal.models.GridOptimizationRecord(**data)[source]

The record of a GridOptimization service result.

A GridOptimization is a type of constrained optimization in which a set of dimension are scanned over. An is to compute the

Parameters
• client (Any, Optional) – The client object which the records are fetched from.

• cache (Dict[str, Any], Default: {}) – Object cache from expensive queries. It should be very rare that this needs to be set manually by the user.

• id (ObjectId, Optional) – Id of the object on the database. This is assigned automatically by the database.

• hash_index (str, Optional) – Hash of this object used to detect duplication and collisions in the database.

• procedure (ConstrainedStrValue, Default: gridoptimization) – The name of the procedure being run, which is Grid Optimization. This is a constant and is used for provenance information.

• program (ConstrainedStrValue, Default: qcfractal) – The name of the source program which initializes the Grid Optimization. This is a constant and is used for provenance information.

• version (int, Default: 1) – The version number of the Record.

• extras (Dict[str, Any], Default: {}) – Extra information to associate with this record.

• stdout (ObjectId, Optional) – The Id of the stdout data stored in the database which was used to generate this record from the various programs which were called in the process.

• stderr (ObjectId, Optional) – The Id of the stderr data stored in the database which was used to generate this record from the various programs which were called in the process.

• error (ObjectId, Optional) – The Id of the error data stored in the database in the event that an error was generated in the process of carrying out the process this record targets. If no errors were raised, this field will be empty.

• manager_name (str, Optional) – Name of the Queue Manager which generated this record.

• status ({COMPLETE,INCOMPLETE,RUNNING,ERROR}, Default: INCOMPLETE) – The state of a record object. The states which are available are a finite set.

• modified_on (datetime, Optional) – Last time the data this record points to was modified.

• created_on (datetime, Optional) – Time the data this record points to was first created.

• provenance (Provenance, Optional) – Provenance information tied to the creation of this record. This includes things such as every program which was involved in generating the data for this record.

• initial_molecule (ObjectId) – Id of the initial molecule in the database.

• keywords (GOKeywords) – The keywords for this Grid Optimization.

• optimization_spec (OptimizationSpecification) – The specification of each geometry optimization.

• qc_spec (QCSpecification) – The specification for each of the quantum chemistry computations used by the geometry optimizations.

• starting_molecule (ObjectId) – Id of the molecule in the database begins the grid optimization. This will differ from the initial_molecule if preoptimization is True.

• final_energy_dict (final_energy_dict type=float required) – Map of the final energy from the grid optimization at each grid point.

• grid_optimizations (grid_optimizations type=ObjectId required) – The Id of each optimization at each grid point.

• starting_grid (tuple) – Initial grid point from which the Grid Optimization started. This grid point is the closest in structure to the starting_molecule.

class qcportal.models.OptimizationRecord(**data)[source]

A OptimizationRecord for all optimization procedure data.

Parameters
• client (Any, Optional) – The client object which the records are fetched from.

• cache (Dict[str, Any], Default: {}) – Object cache from expensive queries. It should be very rare that this needs to be set manually by the user.

• id (ObjectId, Optional) – Id of the object on the database. This is assigned automatically by the database.

• hash_index (str, Optional) – Hash of this object used to detect duplication and collisions in the database.

• procedure (ConstrainedStrValue, Default: optimization) – A fixed string indication this is a record for an “Optimization”.

• program (str) – The quantum chemistry program which carries out the individual quantum chemistry calculations.

• version (int, Default: 1) – Version of the OptimizationRecord Model which this data was created with.

• extras (Dict[str, Any], Default: {}) – Extra information to associate with this record.

• stdout (ObjectId, Optional) – The Id of the stdout data stored in the database which was used to generate this record from the various programs which were called in the process.

• stderr (ObjectId, Optional) – The Id of the stderr data stored in the database which was used to generate this record from the various programs which were called in the process.

• error (ObjectId, Optional) – The Id of the error data stored in the database in the event that an error was generated in the process of carrying out the process this record targets. If no errors were raised, this field will be empty.

• manager_name (str, Optional) – Name of the Queue Manager which generated this record.

• status ({COMPLETE,INCOMPLETE,RUNNING,ERROR}, Default: INCOMPLETE) – The state of a record object. The states which are available are a finite set.

• modified_on (datetime, Optional) – Last time the data this record points to was modified.

• created_on (datetime, Optional) – Time the data this record points to was first created.

• provenance (Provenance, Optional) – Provenance information tied to the creation of this record. This includes things such as every program which was involved in generating the data for this record.

• schema_version (int, Default: 1) – The version number of QCSchema under which this record conforms to.

• initial_molecule (ObjectId) – The Id of the molecule which was passed in as the reference for this Optimization.

• qc_spec (QCSpecification) – The specification of the quantum chemistry calculation to run at each point.

• keywords (Dict[str, Any], Default: {}) – The keyword options which were passed into the Optimization program. Note: These are a Dict, not a KeywordSet.

• energies (List[float], Optional) – The ordered list of energies at each step of the Optimization.

• final_molecule (ObjectId, Optional) – The ObjectId of the final, optimized Molecule the Optimization procedure converged to.

• trajectory (List[ObjectId], Optional) – The list of Molecule Id’s the Optimization procedure generated at each step of the optimization.initial_molecule will be the first index, and final_molecule will be the last index.

class qcportal.models.TorsionDriveInput[source]

A TorsionDriveRecord Input base class

Parameters
• program (ConstrainedStrValue, Default: torsiondrive) – The name of the program. Fixed to ‘torsiondrive’ since this input model is only valid for it.

• procedure (ConstrainedStrValue, Default: torsiondrive) – The name of the Procedure. Fixed to ‘torsiondrive’ since this input model is only valid for it.

• initial_molecule (List[Union[ObjectId, Molecule]]) – The Molecule(s) to begin the TorsionDrive with. This can either be an existing Molecule in the database (through its ObjectId) or a fully specified Molecule model.

• keywords (TDKeywords) – TorsionDrive-specific input arguments to pass into the TorsionDrive Procedure

• optimization_spec (OptimizationSpecification) – The settings which describe how to conduct the energy optimizations at each step of the torsion scan.

• qc_spec (QCSpecification) – The settings which describe the individual quantum chemistry calculations at each step of the optimization.

class qcportal.models.TorsionDriveRecord(**data)[source]

A interface to the raw JSON data of a TorsionDriveRecord torsion scan run.

Parameters
• client (Any, Optional) – The client object which the records are fetched from.

• cache (Dict[str, Any], Default: {}) – Object cache from expensive queries. It should be very rare that this needs to be set manually by the user.

• id (ObjectId, Optional) – Id of the object on the database. This is assigned automatically by the database.

• hash_index (str, Optional) – Hash of this object used to detect duplication and collisions in the database.

• procedure (ConstrainedStrValue, Default: torsiondrive) – The name of the procedure. Fixed to ‘torsiondrive’ since this is the Record explicit to TorsionDrive.

• program (ConstrainedStrValue, Default: torsiondrive) – The name of the program. Fixed to ‘torsiondrive’ since this is the Record explicit to TorsionDrive.

• version (int, Default: 1) – The version number of the Record.

• extras (Dict[str, Any], Default: {}) – Extra information to associate with this record.

• stdout (ObjectId, Optional) – The Id of the stdout data stored in the database which was used to generate this record from the various programs which were called in the process.

• stderr (ObjectId, Optional) – The Id of the stderr data stored in the database which was used to generate this record from the various programs which were called in the process.

• error (ObjectId, Optional) – The Id of the error data stored in the database in the event that an error was generated in the process of carrying out the process this record targets. If no errors were raised, this field will be empty.

• manager_name (str, Optional) – Name of the Queue Manager which generated this record.

• status ({COMPLETE,INCOMPLETE,RUNNING,ERROR}, Default: INCOMPLETE) – The state of a record object. The states which are available are a finite set.

• modified_on (datetime, Optional) – Last time the data this record points to was modified.

• created_on (datetime, Optional) – Time the data this record points to was first created.

• provenance (Provenance, Optional) – Provenance information tied to the creation of this record. This includes things such as every program which was involved in generating the data for this record.

• initial_molecule (List[ObjectId]) – Id(s) of the initial molecule(s) in the database.

• keywords (TDKeywords) – The TorsionDrive-specific input arguments used for this operation.

• optimization_spec (OptimizationSpecification) – The settings which describe how the energy optimizations at each step of the torsion scan used for this operation.

• qc_spec (QCSpecification) – The settings which describe how the individual quantum chemistry calculations are handled for this operation.

• final_energy_dict (final_energy_dict type=float required) – The final energy at each angle of the TorsionDrive scan.

• optimization_history (Dict[str, List[qcportal.models.common_models.ObjectId]]) – The map of each angle of the TorsionDrive scan to each optimization computations. Each value of the dict maps to a sequence of ObjectId strings which each point to a single computation in the Database.

• minimum_positions (minimum_positions type=int required) – A map of each TorsionDrive angle to the integer index of that angle’s optimization trajectory which has the minimum-energy of the trajectory.