QCElemental

QCSchema v2 uses a custom Array type annotation to handle Numpy arrays during serialization via model_dump():

• mode="python": Returns a dictionary where Numpy arrays are preserved as actual Numpy arrays.
• mode="json": Returns a dictionary where Numpy arrays are converted to lists of floats (compatible with standard JSON).

Unlike v1, v2 serialization includes all fields by default. However, Molecule, AtomicProperties, WavefunctionProperties, OptimizationProperties, and ManyBodyProperties will still exclude None values.

# Returns dict with numpy arrays
data_py = model.model_dump(mode="python")

# Returns dict with lists (JSON compatible)
data_json = model.model_dump(mode="json")

QCElemental provides Python implementations of the MolSSI QCSchema for 'Atomic' or 'Single-Point' models. These models are used to represent calculations performed on single atoms. The implementation is structured around several key Pydantic models:

• AtomicInput: Defines the input parameters for an atomic calculation.
• AtomicResult: Defines the output data and results from an atomic calculation.
• AtomicSpecification: A sub-model used to describe the specific requirements or setup of the atomic calculation.

Each of these models includes a .convert_v() method to facilitate version conversion or data transformation within the schema.

By default, qcel.covalentradii points to the latest available data and will be updated over time. To ensure reproducibility in your workflows, you can "pin" a specific data version by creating a context object.

Currently, the only available version is ALVAREZ2008.

>>> context = qcel.CovalentRadii("ALVAREZ2008")
>>> qcel.covalentradii.get(6)
1.4361918553479494

The Torsion Drive implementation is composed of several specialized sub-models used to structure the data:

• TorsionDriveSpecification: Defines the technical specification of the torsion drive.
• TorsionDriveKeywords: Contains the keywords/parameters used in the calculation.
• TorsionDriveProtocols: Defines the protocols followed during the torsion drive.
• TorsionDriveProperties: Captures the physical or calculated properties resulting from the torsion drive.

Physical constants change as experimental precision improves. While qcel.constants defaults to the latest NIST data, you can "pin" your calculations to a specific historical version to ensure reproducibility.

Currently, only CODATA2014 is available via the qcel.PhysicalConstantsContext class.

import qcelemental as qcel

# Create a context pinned to CODATA 2014
context = qcel.PhysicalConstantsContext("CODATA2014")

# Use the context to perform conversions
factor = context.conversion_factor("hartree", "eV")

To ensure reproducibility and prevent your results from changing when the default data is updated, you can "pin" a specific version of the van der Waals radii data by creating a specific context object.

Currently, the only available context is MANTINA2009.

>>> context = qcel.VanderWaalsRadii("MANTINA2009")
>>> # Use the context object to retrieve data
>>> context.get(6)
3.212534413278308

QCElemental's periodic table API allows you to retrieve chemical properties using multiple types of aliases. You can pass an atomic number (int), a chemical symbol (str), an isotope symbol (str), or a chemical name (str) to the property functions. The API will resolve these aliases to the correct quantity.

# All these aliases resolve to the same mass
qcel.periodictable.to_mass(6)        # Atomic number
qcel.periodictable.to_mass("C")      # Symbol
qcel.periodictable.to_mass("C12")    # Isotope symbol
qcel.periodictable.to_mass("Carbon") # Name

The qcelemental/checkup_data directory contains periodic table and physical constant data sourced from Psi4 and Cfour. This data is used to validate qcelemental outputs by running comparisons via the PeriodicTable.run_comparison() method.

Note: This directory is intended for data storage and is usually not imported directly into your code.

# Example conceptual usage for running comparisons
PeriodicTable.run_comparison()

Starting with QCElemental v0.50.0, QCSchema v2 is available. It is a technical upgrade to Pydantic v2 and does not introduce new features, but it rearranges fields to make models more composable and distinguishable in dictionary form.

Timeline:

• v0.50: v2 available; v1 unchanged.
• v0.60: v2 layout finalized.
• v0.70: v2 becomes default; v1 requires specific import paths.
• v1.0: v1 dropped.

Because Pydantic does not allow nesting v1 and v2 models, you should overhaul QCSchema operations all at once.

Recommended Pattern for Library Authors: To support both versions, convert to v2 internally and handle v1/v2 at the interface level:

1. Accept a v1 or v2 object.
2. Convert it to v2 using .convert_v(2).
3. Perform all internal logic using v2 models.
4. Convert back to the requested version using .convert_v(return_version) before returning control to the caller.

Testing: Use the schema_versions pytest fixtures to parametrize your tests for both v1 and v2 simultaneously.

# Convert a v1 model to v2
v2_model = v1_model.convert_v(2)

# Convert back to v1
v1_model = v2_model.convert_v(1)