OpenQP Python API

Version 1.2.1 · generated from main@740611d

The OpenQP Python layer is both a fluent calculation builder and the runtime orchestrator for the native OpenQP library. It covers molecular input, electronic-structure model selection, excited-state and dynamics workflows, analysis, interchange formats, and direct access to lower-level execution objects.

Note

This site is the source-level API reference. For installation, scientific background, supported methods, and every input keyword, use the OpenQP manual.

Quick start

The high-level oqp.openqp builder converts readable chained calls into a validated OpenQP input and runs it through the native engine.

from oqp.openqp import OpenQP

job = (
    OpenQP(project="water_pbe")
    .molecule(geometry="water", basis="6-31g*", charge=0)
    .dft("pbe", reference="rhf", runtype="grad", conv=1.0e-7)
)

input_sections = job.to_input_dict()  # inspect before execution
molecule = job.run()                  # native OpenQP Molecule result

OpenQP also exposes theory and workflow namespaces for more involved jobs:

from oqp.openqp import OpenQP

job = (
    OpenQP(project="mrsf_crossing")
    .molecule(geometry="water", charge=0)
    .theory(
        "mrsf-tddft",
        functional="bhhlyp",
        basis="6-31g*",
        nstate=5,
    )
)
job.workflow.meci(lib="oqp", istate=1, jstate=2)
result = job.run()

API map

Choose the right entry point
Area	Start here	What it provides
High-level calculations	oqp.openqp	`OpenQP` builder, molecule setup, HF/DFT/MP2/MRSF/DFTB theories, workflow namespaces, section proxies, validation, and execution.
CLI and runner	oqp.pyoqp	`Runner`, command-line dispatch, example validation, feature-coverage checks, reference generation, and regression execution.
Semantic input	oqp.utils.oqp_input	Parsing and lowering of concise `.oqp` requests, state references, natural-language-style routes, canonical rendering, and diagnostics.
Molecule and results	oqp.molecule	Molecular geometry, configuration, energies, orbitals, gradients, Hessians, state data, JSON loading, and native data access.
Electronic workflows	oqp.library	Single points, gradients, optimization/IRC/NEB, frequencies, guesses, basis projection, symmetry, solvent, and engine adapters.
Dynamics and QM/MM	oqp.library.namd	FSSH NAMD, SOC dynamics, MCH propagation, QM/MM dynamics, hopping, decoherence, restart, and trajectory state management.
Analysis	oqp.analysis	NTOs, attachment/detachment densities, transition densities, AO grids, charge-transfer descriptors, and excited-state analysis.
Quantum data	oqp.quantum	One- and two-body integrals, AO-to-MO transformations, molecular Hamiltonians, and FCIDUMP reading/writing.
Export and interchange	oqp.export	Cube generation, QCSchema conversion/validation, FCIDUMP export, and comparison/parsing helpers in oqp.interop.
Utilities	oqp.utils	MPI helpers, matrices, geometry, file handling, performance presets, structured DFTB traces, input checks, and regression tooling.

High-level calculation models

The OpenQP builder keeps theory selection separate from the requested workflow. This makes it possible to reuse the same molecular definition and switch between energy, gradient, optimization, crossing, SOC, or dynamics workflows while keeping the generated input inspectable.

Public model helpers
Model family	Representative calls	Supported role in the builder
HF and DFT	`.hf()`, `.dft(...)`, `.theory.dft(...)`	Restricted/open-shell references, functionals, SCF convergence, energies, gradients, properties, and downstream workflows.
MP2	`.mp2(...)`, `.theory.mp2(...)`	MP2, SCS-MP2, SOS-MP2, and custom same-/opposite-spin scaling for energy calculations.
Excited states	`.theory("tdhf")`, `.theory.tddft(...)`, `.mrsf(...)`	TDHF/TDDFT, SF-TDDFT, and MRSF-TDDFT state spaces and response options.
DFTB	`.dftb()`, `.mrsf_tddftb(...)`	Ground-state, TD-DFTB, SF/MRSF response, SOC, and dynamics configuration.
Embedded systems	`.qmmm(...)`	PDB/QM-region setup, electrostatic embedding, force fields, PME/cutoff settings, frontier-charge redistribution, and OpenMM coupling.

Workflow-oriented example

The same public API can express SOC-enabled QM/MM nonadiabatic dynamics:

from oqp.openqp import OpenQP

job = (
    OpenQP(project="soc_namd_qmmm")
    .molecule("chromophore.pdb 0-4", basis="6-31g*")
    .theory("mrsf-tddft", functional="bhhlyp", nstate=3)
    .qmmm(cutoff="PME")
)
job.workflow.namd(
    soc=True,
    soc_basis="mch",
    nstep=200,
    dt=0.5,
    init_state="S1",
)
trajectory = job.run()

How the Python layer is organized

oqp.openqp: User-facing fluent builder and schema-backed section proxies.
oqp.pyoqp and oqp.runtime: Native-library discovery, runner lifecycle, CLI behavior, and calculation dispatch.
oqp.library: Scientific workflow implementations and adapters around the native core.
oqp.molecule: Main state/result container and typed input data structures.
oqp.analysis, oqp.quantum, oqp.export, oqp.interop: Post-processing and portable data interfaces that can be used independently of the fluent builder where appropriate.