Single Compute¶

QCEngine’s primary purpose is to consume the MolSSI QCSchema and produce QCSchema results for a variety of quantum chemistry, semiempirical, and molecular mechanics programs. Single QCSchema representation comprises of a single energy, gradient, hessian, or properties evaluation.

Input Description¶

An input description has the following fields:

molecule - A QCSchema compliant dictionary or Molecule model.
driver - The energy, gradient, hessian, or properties option.
model - A description of the evaluation model. For quantum chemistry this is typically method and basis. However, non-quantum chemistry models are often a simple method as in method = 'UFF' for forcefield evaluation.
keywords - a dictionary of keywords to pass to the underlying program. These are program-specific keywords.

An example input is as follows:

>>> import qcengine as qcng
>>> import qcelemental as qcel

>>> mol = qcel.models.Molecule.from_data("""
>>>     O  0.0  0.000  -0.129
>>>     H  0.0 -1.494  1.027
>>>     H  0.0  1.494  1.027
>>> """)

>>> inp = qcel.models.AtomicInput(
>>>     molecule=mol,
>>>     driver="energy",
>>>     model={"method": "SCF", "basis": "sto-3g"},
>>>     keywords={"scf_type": "df"}
>>> )

Computation¶

A single computation can be evaluated with the compute function as follows:

>>> ret = qcng.compute(inp, "psi4")

By default the job is given resources relating to the compute environment it is in; however, these variables can be overridden:

>>> ret = qcng.compute(inp, "psi4", local_options={"memory": 2, "ncores": 3})

Results¶

The results contain a complete record of the computation:

>>> ret.return_result
-74.45994963230625

>>> ret.properties.scf_dipole_moment
[0.0, 0.0, 0.6635967188869244]

>>> ret.provenance.cpu
Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz

Input Fields¶

class qcelemental.models.AtomicInput(*, id: str = None, schema_name: qcelemental.models.results.ConstrainedStrValue = 'qcschema_input', schema_version: int = 1, molecule: qcelemental.models.molecule.Molecule, driver: qcelemental.models.common_models.DriverEnum, model: qcelemental.models.common_models.Model, keywords: Dict[str, Any] = {}, protocols: qcelemental.models.results.AtomicResultProtocols = AtomicResultProtocols(wavefunction=<WavefunctionProtocolEnum.none: 'none'>, stdout=True, error_correction=ErrorCorrectionProtocol(default_policy=True, policies=None), native_files=<NativeFilesProtocolEnum.none: 'none'>), extras: Dict[str, Any] = {}, provenance: qcelemental.models.common_models.Provenance = None)[source]¶

The MolSSI Quantum Chemistry Schema

Parameters

id (str, Optional) – The optional ID for the computation.
schema_name (ConstrainedStrValue, Default: qcschema_input) – The QCSchema specification this model conforms to. Explicitly fixed as qcschema_input.
schema_version (int, Default: 1) – The version number of schema_name to which this model conforms.
molecule (Molecule) – The molecule to use in the computation.
driver ({energy,gradient,hessian,properties}) – Allowed computation driver values.
model (Model) – The computational molecular sciences model to run.
keywords (Dict[Any], Default: {}) – The program-specific keywords to be used.
protocols (AtomicResultProtocols, Optional) – Protocols regarding the manipulation of computational result data.
extras (Dict[Any], Default: {}) – Additional information to bundle with the computation. Use for schema development and scratch space.
provenance (Provenance, Optional) – Provenance information.

Returned Fields¶

class qcelemental.models.AtomicResult(*, id: str = None, schema_name: qcelemental.models.results.ConstrainedStrValue = 'qcschema_output', schema_version: int = 1, molecule: qcelemental.models.molecule.Molecule, driver: qcelemental.models.common_models.DriverEnum, model: qcelemental.models.common_models.Model, keywords: Dict[str, Any] = {}, protocols: qcelemental.models.results.AtomicResultProtocols = AtomicResultProtocols(wavefunction=<WavefunctionProtocolEnum.none: 'none'>, stdout=True, error_correction=ErrorCorrectionProtocol(default_policy=True, policies=None), native_files=<NativeFilesProtocolEnum.none: 'none'>), extras: Dict[str, Any] = {}, provenance: qcelemental.models.common_models.Provenance, properties: qcelemental.models.results.AtomicResultProperties, wavefunction: qcelemental.models.results.WavefunctionProperties = None, return_result: Union[float, qcelemental.models.types.Array, Dict[str, Any]], stdout: str = None, stderr: str = None, native_files: Dict[str, Any] = None, success: bool, error: qcelemental.models.common_models.ComputeError = None)[source]¶

Results from a CMS program execution.

Parameters

id (str, Optional) – The optional ID for the computation.
schema_name (ConstrainedStrValue, Default: qcschema_output) – The QCSchema specification this model conforms to. Explicitly fixed as qcschema_output.
schema_version (int, Default: 1) – The version number of schema_name to which this model conforms.
molecule (Molecule) – The molecule to use in the computation.
driver ({energy,gradient,hessian,properties}) – Allowed computation driver values.
model (Model) – The computational molecular sciences model to run.
keywords (Dict[Any], Default: {}) – The program-specific keywords to be used.
protocols (AtomicResultProtocols, Optional) – Protocols regarding the manipulation of computational result data.
extras (Dict[Any], Default: {}) – Additional information to bundle with the computation. Use for schema development and scratch space.
provenance (Provenance) – Provenance information.
properties (AtomicResultProperties) –

Named properties of quantum chemistry computations following the MolSSI QCSchema.
All arrays are stored flat but must be reshapable into the dimensions in attribute shape, with abbreviations as follows:
nao: number of atomic orbitals = calcinfo_nbasis

nmo: number of molecular orbitals
wavefunction (WavefunctionProperties, Optional) – Wavefunction properties resulting from a computation. Matrix quantities are stored in column-major order. Presence and contents configurable by protocol.
return_result (Union[float, Array, Dict[Any]]) – The primary return specified by the driver field. Scalar if energy; array if gradient or hessian; dictionary with property keys if properties.
stdout (str, Optional) – The primary logging output of the program, whether natively standard output or a file. Presence vs. absence (or null-ness?) configurable by protocol.
stderr (str, Optional) – The standard error of the program execution.
native_files (Dict[Any], Optional) – DSL files.
success (bool) – The success of program execution. If False, other fields may be blank.
error (ComputeError, Optional) – Complete description of the error from an unsuccessful program execution.

FAQ¶

Where is scratch so I can access the CMS code’s files?

The QCArchive philosophy is that you shouldn’t go looking in scratch for CMS-code-written files since the scratch directory is deleted automatically by QCEngine and even if preserved may be subject to autodeletion if run from a cluster. Instead, QCEngine brings back the primary input and output and any ancillary files from which it can harvest results. Whether these are returned to the user in AtomicResult can be controlled through protocols in the input like atomicinput.protocols.stdout = True and eventually (https://github.com/MolSSI/QCElemental/pull/275) atomicinput.protocols.native_files = "all".

Nevertheless, you can, of course, access the scratch directory and CMS-code-written files. Pass an existing directory to the compute command (this directory will be parent) and tell it to not delete after the run: qcng.compute(..., local_options={"scratch_directory": "/existing/parent/dir", "scratch_messy": True}).
sdfs