Active Space Selection¶

Info

These methods have been developed by Tobias Clausen, Adrià Blanch and Jasen Liu under supervision by Phillip Jensen, Kristín Anardóttir, Mark Jones and Stephan Sauer. A benchmark publication for these methods is underway.

In this section, we discuss the various methods available in Cebule for selecting and optimizing active spaces for multireference quantum chemistry calculations. Active space selection is one of the most important decisions in a multireference quantum chemistry calculation. The active space defines which electrons and orbitals are treated with a correlated method (FCI, CASSCF, VQE, etc.) and which are kept frozen or inactive. A poorly chosen active space can lead to qualitatively wrong results, while a well‑chosen one can dramatically reduce computational cost without sacrificing accuracy.

Cebule provides several automated and semi‑automated methods for constructing active spaces. These methods differ in the underlying physics, the type of basis set they support, and the degree of orbital optimization they perform. The table below summarises the available options to help you choose the right one for your system.

Method Comparison

Method	Basis Set	Orbital Optimization	Active Space Definition	Typical Use Case
OVOS	Gaussian	Virtual orbitals only (MP2‑based)	Occupied + `n_ovos_orbitals` optimised virtuals	Fast generation of compact active spaces for dynamic correlation; quantum computing
COVO (plane‑wave)	Plane‑wave	None (integral extraction; virtuals are not optimized)	Occupied + user‑specified `n_virtual_orbitals`	Periodic or condensed‑phase systems; plane‑wave integrals and second‑quantized Hamiltonians for downstream correlated/quantum methods
COVO (`covo_orb`, Gaussian)	Gaussian	Virtual orbitals only (CI‑based, sequential)	Occupied + `n_covo_orbitals` optimised virtuals	Correlation‑optimised orbitals in molecular calculations; quantum computing
AVAS	Gaussian	Projection/rotation onto user-defined AOs	Active orbitals constructed by projecting occupied and virtual MOs onto target AOs. Dimension controlled by a threshold on the singular values of the MO–AO overlap matrix	Chemically intuitive active spaces; transition metals, π systems
CASSCF	Gaussian	Full (orbitals + CI coefficients)	User‑specified active spaces	Gold‑standard multireference treatment; requires orbital relaxation
DMRG‑CASSCF	Gaussian	Full (orbitals + DMRG CI)	User‑specified active space	Large active spaces beyond exact FCI limits

Choosing a Method

If you need a quick, small active space for a downstream correlated method (FCI, VQE, CC) and you are using a Gaussian basis set, OVOS or COVO (covo_orb, Gaussian) are excellent choices. OVOS is based on MP2 and tends to be faster; COVO uses a CI‑based criterion and may capture more correlation per orbital, but is slightly more expensive.
If your system requires a plane‑wave basis (e.g., periodic, solid‑state, or pseudopotential calculations), use COVO (plane‑wave). It runs a plane‑wave HF/DFT calculation to extract the MO integrals, and keeps a user‑specified number of virtual orbitals (n_virtual_orbitals). The plane‑wave variant does not further optimize those virtual orbitals; for sequential correlation‑optimized virtual orbitals, use the Gaussian‑basis covo_orb variant. The resulting integrals and second‑quantized Hamiltonian are ready for downstream FCI, CASSCF, or quantum algorithms.
If you want a chemically intuitive active space (e.g., to include all 3d orbitals of a transition metal), use AVAS. It selects orbitals based on overlap with chosen atomic orbitals, which is often the most transparent and reproducible way to define an active space.
If you need a fully optimised multireference wavefunction and your active space is small enough, CASSCF is the standard choice. It optimizes both orbitals and CI coefficients, providing the highest quality reference for subsequent perturbation theory or dynamics.
If your active space is too large for exact CASSCF but you still want orbital relaxation, use DMRG‑CASSCF. It replaces the exact CI solver with DMRG, allowing active spaces of 20, 30, or more orbitals at controlled accuracy.

Common Workflow

A typical workflow in Cebule is to first generate an active space using one of the fast, orbital‑selection methods (OVOS, COVO, AVAS), and then use that active space as input to CASSCF or DMRG‑CASSCF for orbital relaxation. The relaxed orbitals and integrals can then be used for a variety of correlated methods, including FCI, CASPT2, NEVPT2, or VQE.

For COVO (plane‑wave) specifically, the workflow is:

Run a plane‑wave HF/DFT calculation.
Extract one‑ and two‑electron integrals in the MO basis.
Choose the number of virtual orbitals to retain (n_virtual_orbitals). No further orbital optimization is performed in this plane‑wave task.
Construct the second‑quantized Hamiltonian and pass it to a separate evaluation module for FCI, CASSCF, or VQE.

Correlation Optimized Virtual Orbitals (Plane wave variant)¶

When to Use
Use the plane wave COVO task when you want to run a plane wave Hartree–Fock (or DFT) calculation and then use the resulting one‑ and two‑electron integrals for post‑Hartree–Fock methods in PySCF or SlowQuant. This is particularly useful for periodic or condensed‑phase systems, or when you want to leverage the systematic convergence of plane‑wave basis sets.

Core Idea
COVO bridges plane wave electronic structure calculations and the tools available in PySCF/SlowQuant. It runs a plane‑wave HF/DFT calculation, extracts the one- and two-electron integrals in an orthogonal molecular orbital (MO) basis, and constructs a second‑quantized Hamiltonian ready for downstream FCI, CASSCF, or VQE.

--> Note: The orbital optimization aspect of the COVO method (i.e., sequentially generating optimized virtual orbitals) is handled in the Gaussian-basis variant (covo_orb). The plane‑wave task described here focuses on extracting accurate integrals from a plane wave calculation; the user chooses the number of virtual orbitals to keep (n_virtual_orbitals), but those orbitals are not further optimized.

Key Features

Plane wave basis — integrals from pseudo-potential plane wave calculations.
Virtual orbital selection — user specifies n_virtual_orbitals.
Fermionic Hamiltonian construction — a second‑quantized Hamiltonian is built directly from the integrals, ready for quantum‑computing applications.
Periodic system extension — can be extended to periodic systems using Filon integration for exact exchange and Brillouin‑zone integration.

Benefits

Plane‑wave accuracy — systematic convergence with a single cutoff parameter, avoiding basis‑set superposition errors.
Periodic boundary conditions — ideal for surfaces, solids, liquids.
Direct use in quantum computing algorithms — orthogonal MO integrals and fermionic Hamiltonian can be fed directly to VQE or to other quantum computinng related eigensolver methods (run separately).
Reduced memory footprint — limiting the number of virtual orbitals keeps the integrals and Hamiltonian manageable.

How It Works

Input validation — Checks required keys and memory limits.
Input generation — Plane‑wave SCF with the specified cell size, cutoff, virtual count, and functional (default HF).
Run calculations — Integrals, orbital energies, and SCF energy.
Integral extraction — Spatial integrals.
Fermionic Hamiltonian — The integrals are converted into a list of coefficients and operator tuples.
Output assembly — Results are collected into a dictionary.

TaskType: covo

Required inputs:

title: str — Task name / identifier.
geometry: list[float] — Cartesian coordinates (x, y, z), Å.
symbols: list[str] — Atomic elements.
periodic: bool — Whether the system is periodic.
cutoff: float — Plane‑wave energy cutoff, Hartree.
n_virtual_orbitals: int — Number of virtual MOs to include.
charge: int — Net electric charge.
multiplicity: int — Spin multiplicity.

Optional keys:

cell_size: float — Simulation box size in Å.

Outputs:

one_electron_integrals: list[list[float]] — MO‑basis 1‑electron integrals.
two_electron_integrals: list[list[list[list[float]]]] — MO‑basis 2‑electron integrals (chemist’s notation).
hf_energy: float — Plane‑wave HF energy.
h_coefficient: list[float] — Fermionic Hamiltonian coefficients.
h_fermionic_operators: list[tuple] — Fermionic operator terms.
Metadata: task_title, cpu_time, cell_size, n_spatial_orbitals, nuclear_repulsion_energy, n_electrons, charge, multiplicity, etc.

Example

covo_input = {
    "title": "h2_covo_nwchem",
    "symbols": ["H", "H"],
    "geometry": [0.0, 0.0, 0.0, 0.0, 0.0, 0.74],
    "cell_size": 10.0,
    "periodic": True,
    "cutoff": 15.0,
    "n_virtual_orbitals": 4,
    "charge": 0,
    "multiplicity": 1,
}

Limitations and Considerations

The number of virtual orbitals (n_virtual_orbitals) is limited by the plane‑wave cutoff and the number of plane‑wave basis functions. Ensure the chosen cutoff is large enough.
If the molecule is not periodic, PSPW still requires a simulation cell large enough to avoid artificial interactions. The periodic flag is forced to True because PSPW does not support non‑periodic boundary conditions.
The plane-wave variant does not optimize or rank the virtual orbitals. n_virtual_orbitals selects how many to keep, but there is no energy-based criterion, no sequential optimization, and no re-optimization pass. You choose the count blind, or by an external criterion you compute yourself. If you need correlation-optimized virtuals, use the Gaussian-basis covo_orb variant.

Correlation Optimized Virtual Orbitals, Gaussian-basis variant (COVO_orb)¶

When to Use
This variant of COVO is intended for molecular calculations using conventional Gaussian basis sets (e.g., def2-SVP, cc-pVDZ). Choose it when you want to generate a compact set of correlation-optimized virtual orbitals without switching to a plane-wave framework. It is particularly useful for quantum computing applications or for reducing the cost of subsequent FCI, CASSCF, CASCI or VQE calculations, which are run separately on the returned active-space integrals and MO coefficients.

Core Idea
The Gaussian-basis COVO method sequentially optimizes virtual orbitals to minimize the energy of a projected configuration interaction (CI) Hamiltonian. Each new virtual orbital is tailored to capture as much electron correlation as possible, resulting in a small set of orbitals that recover a large fraction of the dynamic correlation energy.

Key Features

Sequential orbital optimization — each virtual orbital is optimized one at a time using a projected CI Hamiltonian that includes a small number of auxiliary occupied orbitals (n_aux_orbitals).
Analytic Hellmann–Feynman gradients — both the auxiliary rotation matrix U and the target virtual orbital are optimized with L-BFGS using analytic gradients (no finite differences). The gradient of the CI energy is obtained from the active-space 1- and 2-RDMs contracted with AO integrals.
A/b construction from CI perturbation theory — the target virtual update solves a Tikhonov-regularized linear system derived from the 3-state CI eigenvalue equation. The sign of the update is detected automatically by probing both orientations.
Orthogonality by construction — U is parameterized with a Cayley transform on the Stiefel manifold; the virtual orbital is rotated with expm(K) restricted to virtual–virtual rotations. Orthonormality is preserved throughout the optimization.
Robust Fréchet derivative — the derivative of expm(K) w.r.t. the rotation parameters uses scipy.linalg.expm_frechet when available, falling back to the Loinard–Lutz eigendecomposition formula, and finally to central finite differences for very small problems.
RDM sanity checks — every 1- and 2-RDM build is validated against symmetry (D = Dᵀ, Γ[p,q,r,s] = Γ[r,s,p,q]), antisymmetry (Γ[p,q,r,s] = -Γ[q,p,r,s] and r ↔ s), trace normalization (Tr(D) = 2·n_aux), and the partial-trace identity Σ_q Γ[p,q,q,s] = (N-1)·D[p,s].
Optional gradient verification — setting verify_gradients=True compares the analytic gradients of both subproblems against central finite differences and raises an AssertionError if the mismatch exceeds verify_gradients_tol (default 1e-4). Recommended for first runs on a new system, then disabled for production.
Efficient correlation capture — typically 1–8 optimized virtual orbitals already recover most of the valence correlation energy.
Frozen-core support — core orbitals can be excluded via n_frozen_orbitals.
Systematic convergence — adding more optimized virtual orbitals monotonically lowers the projected CI energy toward the full-space limit.
Gaussian basis compatibility — works with standard atomic orbital basis sets.
Quantum-computing ready — the reduced orbital count directly lowers qubit requirements for VQE and other quantum algorithms.

Benefits

Reduced computational cost — the compact active space dramatically reduces memory and time for downstream FCI, CASSCF, CASCI, or VQE.
Near-term quantum device compatibility — fewer orbitals mean fewer qubits, making COVO practical for NISQ hardware.
Versatile applications — optimized orbitals can be used with FCI, CC, MP2, VQE, and other many-body methods.
Extensivity — maintains proper size-extensivity for dissociated systems; errors decrease systematically as more COVOs are added.

How It Works

Initialization — start from a converged restricted Hartree–Fock (RHF) reference.
Choose auxiliary space — select a small number (n_aux_orbitals, typically 1 or 2) of occupied orbitals to form the auxiliary occupied space used in the projected CI Hamiltonian.
For each target virtual orbital (processed sequentially):
Initialize the auxiliary rotation matrix U using correlation strengths between the target virtual and each occupied orbital.
In a coupled loop, alternate between:
- Updating the target virtual via the A/b linear system (with the sign auto-detected on the first iteration), followed by a virtual–virtual expm(K) rotation that preserves orthogonality.
- Optimizing U (with the virtual fixed) using L-BFGS with the analytic gradient. U is parameterized via a Cayley transform on the Stiefel manifold to keep it orthonormal by construction.
The projected CI Hamiltonian contains n_aux_orbitals auxiliary occupied orbitals and the single target virtual orbital, with 2 * n_aux_orbitals electrons.
Optional re-optimization — after all virtuals are optimized, the entire set may be passed through again (n_reopt_passes) to allow earlier virtuals to adapt to the presence of later ones.
Active space definition — the final active space consists of all occupied orbitals plus the first n_covo_orbitals optimized virtual orbitals.

TaskType: covo_orb

Required inputs:

symbols: list[str] — Atomic elements (e.g., ["O", "H", "H"]) that correspond one-to-one with the coordinates in geometry. geometry: list[float] — Flat list of Cartesian coordinates (x, y, z) in Angstroms (e.g., [0.0, 0.0, 0.0, 0.0, 0.7572, -0.4692, ...]). basis_set: str — Gaussian basis set for the RHF reference (e.g., "sto-3g", "6-31G", "def2-svp", "cc-pVDZ"). charge: int — Net electric charge of the system (e.g., 0 for neutral, -1 for an anion). multiplicity: int — Spin multiplicity M = 2S + 1 (e.g., 1 for a singlet). n_covo_orbitals: int — Number of virtual orbitals to optimize sequentially and include in the active space.

Optional keys:

n_aux_orbitals: int, default = 1 — Number of auxiliary occupied orbitals in the projected CI Hamiltonian. Keep small (1–2). n_reopt_passes: int, default = 0 — Number of additional full passes over all virtual orbitals, allowing earlier virtuals to adapt to later ones. n_frozen_orbitals: int, default = 0 — Number of core occupied orbitals to freeze/exclude from the active space. Also accepted as n_core. verify_rdms: bool, default = True — If True, run RDM symmetry and normalization assertions on every 1-/2-RDM build. verify_gradients: bool, default = False — If True, compare the analytic gradients (for U and the virtual rotation) against central finite differences once per virtual. Recommended for a first run on a new system. verify_gradients_tol: float, default = 1e-4 — Tolerance for the gradient verification check.

Outputs (all energies in Hartree, lengths in Angstrom):

Task / runtime metadata

cpu_time: float — Total wall-clock time for the COVO run (seconds). geometry_units: str — Always "Angstrom".
energy_units: str — Always "Hartree".

Molecule & electronic structure basics

geometry: list[float] — Echo of the input coordinates.
symbols: list[str] — Echo of the input symbols.
charge: int — Echo of the input charge.
multiplicity: int — Echo of the input multiplicity.
n_electrons: int — Total number of electrons.
n_active_electrons: int — Electrons in the active space (2 * n_active_occ for closed-shell).

Basis set & orbital partitioning

basis_set: str — Echo of the input basis.
n_frozen_orbitals: int — Number of frozen core orbitals.
n_active_orbitals: int — Total active orbitals (occupied + optimized virtual).
n_virtual_orbitals: int — Number of active virtuals (= n_covo_orbitals).
n_active_occ: int — Active occupied orbitals.
n_active_vir: int — Active virtual orbitals.
active_orbital_indices: list[int] — Indices of active orbitals in the returned MO coefficient matrix.
frozen_orbital_indices: list[int] — Indices of frozen core orbitals in the returned MO coefficient matrix.

COVO method & CI results

method: str — Always "COVO".
n_covo_orbitals: int — Echo of the requested number of COVOs.
covo_ci_energy: float — Final projected-CI energy from the COVO optimization.
covo_ci_history: list[float] — Projected-CI energy per full pass.
covo_per_virtual_history: list[list[float]] — Projected-CI energy per virtual orbital per pass.
covo_iterations: int — Number of full passes over virtual orbitals (= 1 + n_reopt_passes).
covo_mo_coefficients: list[list[float]] — MO coefficient matrix in the COVO ordering (frozen core | active occ | active vir | remaining).
covo_mo_energies: list[float] — Diagonal Fock energies of the MOs in the COVO ordering.

Energies

nuclear_repulsion_energy: float — Nuclear repulsion energy.
hf_energy: float — RHF ground-state energy.
mp2_energy: float — HF energy plus active-space MP2 correlation energy.
active_hf_energy: float — HF energy within the active space.
active_mp2_correlation_energy: float — Active-space MP2 correlation energy.

Integrals & Hamiltonian

one_electron_integrals: list[list[float]] — Active-space 1-electron integral matrix h1 (N_act × N_act).
two_electron_integrals: list[list[list[list[float]]]] — Active-space 2-electron integral tensor eri (N_act × N_act × N_act × N_act) in physicist notation.
h_coefficient: list[float] — Coefficients of the fermionic Hamiltonian terms.
h_fermionic_operators: list[tuple] — Fermionic operators (orbital indices and creation/annihilation flags) corresponding to h_coefficient.

Example

covo_orb_input = {
    "symbols": ["O", "H", "H"],
    "geometry": [
        0.0000, 0.0000,  0.1173,
        0.0000, 0.7572, -0.4692,
        0.0000, -0.7572, -0.4692,
    ],
    "basis_set": "6-31G",
    "charge": 0,
    "multiplicity": 1,
    "n_covo_orbitals": 4,
    # optional:
    "n_aux_orbitals": 2,
    "n_reopt_passes": 1,
    "verify_rdms": True,
    "verify_gradients": False,
}

covo_orb_task = session.cebule.create_task(
    "H2O COVO_ORB Test",
    TaskType.COVO_ORB,
    json.dumps(covo_orb_input),
    max_processors=1,
)

Limitations and Considerations - This variant is not plane-wave compatible; for periodic or pseudopotential calculations, use the plane-wave COVO instead. - The optimization is based on a projected CI Hamiltonian, so it may miss some correlation effects present in a full active-space optimization (e.g., CASSCF). The occupied orbitals are fixed, so a poor HF reference will limit the quality of the result regardless of how many virtuals are optimized. - The number of auxiliary orbitals (n_aux_orbitals) must be chosen small (1–2); larger values increase cost without necessarily improving accuracy. - The method assumes a closed-shell singlet reference; open-shell systems are not supported. - verify_gradients=True raises an AssertionError on failure, it does not warn and continue. If you enable it on a new system with the default verify_gradients_tol = 1e-4 and the analytic and finite-difference gradients disagree, the job terminates. Lower the tolerance or disable verification if you want a run to complete regardless. - verify_rdms=True is the default, so every 1- and 2-RDM build runs four symmetry, antisymmetry, trace and partial-trace assertions. This is a real per-iteration cost. Once you trust the system, set verify_rdms=False for production runs. - The A/b linear system is Tikhonov-regularized, but the regularization strength is not exposed as an input key. If the projected-CI eigenvalue equation is poorly conditioned, you cannot tune the damping from the dashboard. - The Fréchet derivative of expm(K) has a three-tier fallback chain (scipy.linalg.expm_frechet → Loinard–Lutz eigendecomposition → central finite differences). For very small problems the last fallback is used, so the "analytic gradient" guarantee does not strictly hold in that regime. The fallback is silent. - Cost scales as n_covo_orbitals × (1 + n_reopt_passes) sequential L-BFGS optimizations, each rebuilding the projected-CI Hamiltonian. n_reopt_passes=1 roughly doubles the runtime of the orbital-optimization phase; n_reopt_passes ≥ 2 is rarely worth the cost. - Extensivity is a property of the construction, not something the code verifies. The method is designed to be size-extensive, but no runtime check confirms this for your system.

Optimised Virtual Orbital Space (OVOS)¶

When to Use
OVOS is the fastest method to obtain a compact active space when you plan to run a subsequent correlated calculation (FCI, CASSCF, VQE, CC, etc.) and you are using a conventional Gaussian basis set. It is especially well‑suited for quantum computing applications where reducing the number of orbitals directly reduces the number of qubits.

Core Idea
OVOS rotates the virtual orbitals to maximise the amount of second‑order Møller–Plesset (MP2) correlation energy captured within a small number of orbitals. The occupied orbitals are left unchanged, only the virtual space is optimised. This gives a reduced‑dimensionality active space that recovers a large fraction of dynamic electron correlation at a fraction of the cost of full orbital optimisation.

MP2 is the objective because it is closed‑form and cheap, but its Hessian has frozen amplitudes, not true orbital Hessian, so a plain Newton step can overshoot or point uphill. OVOS therefore takes trust‑region steps, each bounded to a radius in which the quadratic model is trusted, with the radius adapted from the true‑to‑predicted reduction ratio. This makes the approximate Hessian usable and lets the inner solver be swapped out without changing convergence guarantees.

Key Features

MP2‑based orbital optimization – conceptually and computationally simpler than CI‑based methods such as COVO.
Frozen‑core support – core occupied orbitals can be excluded, essential for larger molecules.
Gaussian basis compatibility – works naturally with def2‑SVP, cc‑pVDZ, etc.
Systematic convergence – increasing the number of optimised virtual orbitals usually lowers the MP2 energy toward the full virtual-space limit.
Pluggable trust-region solver – the inner quadratic subproblem can be solved by any of several registered solvers (tcg, gltr, steihaug_toint, dogleg, subspace2d, cauchy, precond_gradient, block_diagonal_newton, rle_newton, levenberg_marquardt). The default is Steihaug–Toint.
Quantum‑computing ready – fewer orbitals mean fewer qubits for VQE and other quantum algorithms.

Benefits

Lower computational cost – the compact active space dramatically reduces memory and time for downstream FCI, CASSCF, or VQE calculations.
Good recovery of dynamic correlation – typically >90% of valence MP2 correlation with 50% of virtuals.
Easy integration – the optimised orbitals can be used with any many‑body method, including FCI, CC, MP2, VQE, and ADAPT‑VQE.
Near‑term quantum device compatibility – fewer orbitals lead to fewer qubits, making OVOS practical for NISQ hardware.

How It Works

Initialization – start from a converged restricted Hartree‑Fock (RHF) reference.
Define active space – all non-frozen occupied orbitals plus the first n_ovos_orbitals optimised virtual orbitals.
Compute MP2 energy – form MP2 amplitudes and evaluate the second‑order correlation energy within this active/inactive partitioning.
Gradient and Hessian – calculate the analytical gradient and an approximate, unrelaxed Hessian of the MP2 energy with respect to rotations between active and inactive virtual orbitals.
Trust‑region step – solve the trust‑region subproblem \(\min_p\, g^{\!\top}p + \tfrac12 p^{\!\top}Hp\) s.t. \(\|p\|\le\Delta\) using the configured solver and its keyword arguments.
Orbital rotation – apply the resulting anti‑Hermitian orbital rotation to update the virtual orbitals while preserving orthogonality.
Canonicalise – re‑diagonalise the active virtual block to maintain a well‑defined orbital set.
Iterate – repeat steps 3–7 until the energy and gradient norms fall below the convergence thresholds and a persistence window (keep_track_max, default 50) of consecutive converged iterations has elapsed.

The trust‑region solver is directly inspired by the OpenTrustRegion library [Greiner et al., 2026], which provides robust second‑order orbital optimization for quantum chemistry.
The original OVOS method was introduced in J. Chem. Phys. 86, 6314–6324 (1987).

TaskType: ovos

Inputs:

symbols: 1D array, list Atomic elements (e.g., ["H","H"]) that directly correspond to the coordinates in the geometry array. geometry: 1D array, list Cartesian coordinates (x,y,z), in angstroms, representing the 3D position of all atoms (e.g., [0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.7400]). basis_set: str Gaussian basis set used for the RHF reference (e.g., "def2-svp", "sto-3g"). charge: value (integer) The net electric charge of the system (e.g., 0 for neutral, -1 for an anion). multiplicity: value (integer) The spin multiplicity of the system, defined as M = 2S + 1 (e.g., M=1 for a singlet state with all electrons paired with S=0). Only closed‑shell singlets (M = 1) are currently supported; other values raise NotImplementedError. n_ovos_orbitals: value (integer) The number of unoccupied (virtual) molecular orbitals to optimise and include in the active space.

Optional inputs:

n_frozen_orbitals: value (integer), default = 0 Number of core occupied orbitals to freeze/exclude from the active space. Also accepted as n_core. ovos_solver: str, default = None Name of the trust-region solver to use for the inner quadratic subproblem. When None, a Steihaug–Toint solver is constructed. Recognised values: "tcg", "block_diagonal_newton", "rle_newton", "steihaug_toint", "dogleg", "subspace2d", "cauchy", "gltr", "levenberg_marquardt", "precond_gradient". ovos_solver_kwargs: dict, default = {} Keyword arguments forwarded to the chosen solver (e.g., {"max_iter": 50, "tol": 1e-6}). See the individual solver classes in misc/ovos_solvers.py for accepted keys.

Outputs:

one_electron_integrals: 2D array (float) A matrix (N x N) containing the kinetic energy and nuclear attraction terms for individual electrons within the MO basis. two_electron_integrals: 4D array (float) A tensor (N x N x N x N) representing the electron-electron repulsion interactions. hf_energy: value (float) The molecular ground-state energy [Hartree] calculated using the mean-field Hartree-Fock approximation. mp2_energy: value (float) Total energy estimate from HF plus active‑space MP2 correlation energy [Hartree]. Note: this uses active_mp2_correlation_energy, which comes from a separate helper (compute_active_mp2_corr) and may differ at the 1e-6–1e-8 Ha level from ovos_mp2_corr_energy_final (which is the objective the OVOS engine actually minimised). Do not assume the two numbers are identical. fci_energy: value (float) The exact ground-state energy (Hartree) within the chosen OVOS optimised virtual orbitals, calculated via Full Configuration Interaction. vqe_energy: value (float) The optimised energy (Hartree) computed using the Variational Quantum Eigensolver (VQE) algorithm with the chosen OVOS optimised virtual orbitals. h_coefficient: list of float Coefficients of the fermionic Hamiltonian terms. h_fermionic_operators: list of tuple Fermionic operators (orbital indices and creation/annihilation flags) corresponding to h_coefficient. ovos_*: various Metadata describing the OVOS optimisation, including:

ovos_mp2_corr_energy_final — best correlation energy found [Ha].
ovos_mp2_corr_energy_history — correlation energy per iteration.
ovos_gradient_norm_history — gradient norm per iteration.
ovos_stop_reason — one of "Convergence", "Non-converged", "Initial", "Unknown".
ovos_iterations — number of outer iterations (see caveat below).
ovos_converged — boolean.
ovos_mo_coefficients — MO coefficient matrix in the COVO-style ordering.
ovos_mo_energies — see caveat below.

Example

# OVOS input for H2 molecule
ovos_input = {
    "symbols": ["H", "H"],
    "geometry": [0.0, 0.0, 0.0, 0.0, 0.0, 0.74],
    "basis_set": "sto-3g",
    "charge": 0,
    "multiplicity": 1,
    "n_ovos_orbitals": 1,
    # optional:
    "n_frozen_orbitals": 0,
    "ovos_solver": "steihaug_toint",
    "ovos_solver_kwargs": {"max_iter": 50, "tol": 1e-6},
}

# Create the task
ovos_task = session.cebule.create_task(
    "H2 OVOS Test",
    TaskType.OVOS,
    json.dumps(ovos_input),
    max_processors=1
)

Limitations and Considerations

Closed‑shell restricted references only. OVOS.__init__ rejects unrestricted/ROHF/UKS inputs and any SCF with fractional occupations by raising NotImplementedError. There is no spin‑adaptation machinery in the engine.
The docstring H₂/STO-3G example optimises nothing. For H₂/STO-3G, 2 * n_AO - N_el = 2 virtual spin orbitals, so with n_ovos_orbitals = 1 the inactive-virtual block is empty. The engine terminates immediately with ovos_stop_reason == "Initial" and returns the RHF orbitals unchanged. To actually exercise the optimiser you need 2 * n_ovos_orbitals < 2 * n_AO - N_el.
ovos_iterations and the histories are truncated at convergence onset. The engine requires keep_track_max (default 50) consecutive converged iterations before declaring convergence, and then cuts energy_hist, gradient_norm_history and num_iterations back to the iteration where the criteria first held. The reported energy is the minimum over the truncated list, which may not be the final energy of the run. Interpret ovos_mp2_corr_energy_final as best energy found, not energy at the moment convergence was declared.
The convergence gate named "T1" is not a T1 diagnostic. _mp1_t1_amplitudes computes a two-electron contraction over the diagonal virtual block, not the MP1 singles amplitude f_ai / (ε_i − ε_a). It is used only as an additional numerical smoothness gate; do not treat it as a physical singles diagnostic.
ovos_mo_energies are not eigenvalues. They are the diagonal elements of the original RHF Fock matrix expressed in the optimized MO basis. Re‑diagonalise the Fock matrix in your optimized basis if you need true orbital energies.
**Convergence parameters are not exposed.
The Hessian is approximate and unrelaxed. There is no coupled‑perturbed MP2 (Z‑vector) response of the amplitudes. The trust‑region machinery is what makes an approximate Hessian acceptable: a poor quadratic model produces a small \(\rho\), which shrinks \(\Delta\) and forces a more conservative step.
The objective is an MP2 correlation energy. It is a single‑reference, dynamic‑correlation measure and says nothing about static correlation. For bond breaking, biradicals, or transition‑metal multiplets, use a multireference orbital optimizer (CASSCF, DMRG‑CASSCF) instead.
The integral transformation dominates cost. And can dominate runtime for a large active occupied space.

Atomic Valence Active Space (AVAS)¶

When to Use
AVAS is useful when you want to construct an active space based on chemical intuition without manually inspecting molecular orbitals. Specify target atomic orbitals (e.g., "Fe 3d", "C 2pz"). AVAS then projects the occupied and virtual MOs of a reference Hartree–Fock calculation onto those AOs and constructs rotated, orthonormal active orbitals that have the largest overlap with the target AOs. This is particularly useful for transition-metal complexes, π-conjugated systems, and other cases where the active space should reflect known atomic character. AVAS article: Elvira R. Sayfutyarova, Qiming Sun, Garnet Kin-Lic Chan, Gerald Knizia; Automated Construction of Molecular Active Spaces from Atomic Valence Orbitals. J. Chem. Theory Comput. 12 September 2017; 13 (9): 4063–4078. https://doi.org/10.1021/acs.jctc.7b00128.

Core Idea
AVAS projects the occupied and virtual molecular orbitals of a reference Hartree–Fock calculation onto a user-defined space of atomic orbitals. The threshold is applied to the singular values of the MO–AO overlap matrix; orbitals with singular values above the threshold are retained. The threshold controls how many of these rotated active orbitals are retained. The resulting active orbitals are new orthonormal combinations aligned with the target AOs, not simply original MOs selected by weight. The result is a chemically transparent and compact active space ready for subsequent correlated calculations.

Key Features

AO-based selection – the active space is defined by projecting occupied and virtual MOs onto specified AOs (e.g., "Fe 3d", "C 2pz"). The active orbitals are rotated/orthonormalized combinations, not merely selected original MOs.
Automatic active space construction – no manual orbital inspection is required; the active space dimension is controlled by the target AOs and a truncation threshold.
Frozen-core support – core occupied orbitals can be excluded via n_frozen_orbitals (also accepted as n_core).
Compatible with Gaussian bases – works with standard all-electron and pseudopotential basis sets.
Interpretable results – projection weights (avas_occ_weights and avas_vir_weights) quantify how strongly each occupied or virtual MO/rotated combination resembles the target AOs, aiding chemical interpretation.

Benefits

Chemically intuitive active spaces – constructs active orbitals based on atomic character, especially useful for transition-metal systems and π-conjugated molecules.
Reduced user effort – requires only a target AO list and a threshold; no manual orbital selection is needed.
Easy integration – resulting active space integrals can be used directly with FCI, CASSCF, MP2, VQE, or other correlated methods.
Systematic control – adjusting the threshold or target AO list allows systematic enlargement or reduction of the active space.

How It Works

Target AO definition – the user specifies one or more atomic orbital labels (e.g., "O 2p", "Fe 3d").
Projection – the occupied and virtual MOs of a reference Hartree–Fock calculation are projected onto the target AO space.
Weight calculation – the overlap/projection matrix between the MOs and target AOs is decomposed (e.g., by SVD) to obtain rotated orbitals and their projection weights/singular values.
Thresholding – the threshold determines how many rotated active orbitals are retained from the occupied and virtual spaces. It does not simply select original MOs whose weights exceed the threshold.
active space construction – the retained occupied and virtual active orbitals are orthonormalized and combined to form the active space. The remaining occupied orbitals are inactive/core; the remaining unoccupied orbitals are virtual.
Integral generation – the one- and two-electron integrals are transformed into the AVAS active space MO basis for subsequent calculations.

TaskType: avas

Inputs:

symbols: 1D array, list Atomic elements (e.g., ["H","H"]) that directly correspond to the coordinates in the geometry array. geometry: 1D array, list Cartesian coordinates (x,y,z), in angstroms, representing the 3D position of all atoms (e.g., [0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.7400]). basis_set: str Gaussian basis set used for the RHF reference (e.g., "def2-svp", "sto-3g"). charge: value (integer) The net electric charge of the system (e.g., 0 for neutral, -1 for an anion). multiplicity: value (integer) The spin multiplicity of the system, defined as M = 2S + 1 (e.g., M=1 for a singlet state with all electrons paired with S=0). aolabels: str or list of str Atomic orbital labels defining the target AO space (e.g., "H 1s", ["Fe 3d", "C 2pz"]).

Optional keys:

threshold: value (float), default = 0.2 Truncation threshold for the projection weights/singular values used to determine the number of active orbitals. n_frozen_orbitals: value (integer), default = 0 Number of core occupied orbitals to freeze/exclude from the active space. Also accepted as n_core.

Outputs:

one_electron_integrals: 2D array (float) A matrix (N x N) containing the one-electron integrals (kinetic energy and nuclear attraction) in the AVAS active space MO basis. two_electron_integrals: 4D array (float) A tensor (N x N x N x N) representing the electron–electron repulsion integrals in the AVAS active space MO basis. hf_energy: value (float) The molecular ground-state energy [Hartree] calculated using the mean-field Hartree–Fock approximation. mp2_energy: value (float) Total energy estimate from HF plus active space MP2 correlation energy [Hartree]. fci_energy: value (float) Total active space FCI energy with frozen-core correction [Hartree]. vqe_energy: value (float) Total active space VQE energy with frozen-core correction [Hartree] (if requested). h_coefficient: list of float Coefficients of the fermionic Hamiltonian terms. h_fermionic_operators: list of tuple Fermionic operators (orbital indices and creation/annihilation flags) corresponding to h_coefficient. avas_occ_weights: list of float Projection weights of the occupied orbitals onto the target AOs. avas_vir_weights: list of float Projection weights of the virtual orbitals onto the target AOs. avas_mo_coefficients: 2D array (float) MO coefficient matrix in the AVAS ordering (inactive + active + virtual). avas_mo_energies: list of float Diagonal Fock energies of the MOs in the AVAS ordering (inactive + active + virtual).

Example

# AVAS input for H2 molecule
avas_input = {
    "symbols": ["H", "H"],
    "geometry": [0.0, 0.0, 0.0, 0.0, 0.0, 0.74],
    "basis_set": "sto-3g",
    "charge": 0,
    "multiplicity": 1,
    "aolabels": ["H 1s"],
    "threshold": 0.2
}
# Create the task
avas_task = session.cebule.create_task(
    "H2 AVAS Test",
    TaskType.AVAS,
    json.dumps(avas_input),
    max_processors=1
)

Limitations and Considerations

AVAS relies on a single Hartree–Fock reference. If the HF orbitals are poor (e.g., for strongly correlated systems), the projection may not yield the most appropriate active orbitals.
The active space size depends on the chosen threshold and target AO list. A threshold that is too low may include too many orbitals; one that is too high may omit important ones. Inspect the projection weights (avas_occ_weights, avas_vir_weights) after a calculation.
AVAS constructs active orbitals based solely on overlap/projection onto target AOs; it does not directly account for dynamic correlation strength. For some systems, a more energy-based criterion (e.g., OVOS) may be more suitable.
This implementation assumes a closed-shell singlet reference; open-shell or multireference initial references are not supported.
AVAS itself does not variationally optimize the orbitals; it only constructs them by projection/rotation. The resulting active space is therefore not an orbital-optimised CASSCF solution. If orbital relaxation is needed, use the AVAS active space as input to CASSCF or DMRG-CASSCF.

Complete Active Space Self-Consistent Field (CASSCF)¶

When to Use
CASSCF is the standard method for treating strong (static) correlation in molecular systems. It simultaneously optimises the molecular orbitals and the configuration interaction coefficients within a chosen active space. Use CASSCF when you need a fully optimised multireference wavefunction and are willing to pay the higher computational cost compared to methods like OVOS or COVO.

Core Idea
CASSCF divides the orbital space into three parts: inactive (doubly occupied, not explicitly correlated in the active space CI; their average effect is included in the mean field), active (variable occupation, treated with full CI), and virtual (unoccupied). The method variationally optimises both the orbitals and the CI coefficients to minimise the total energy. This provides a balanced description of static correlation, which is essential for transition states, excited states, transition metal complexes, and bond breaking.

Key Features

Full orbital optimisation – All orbitals (inactive, active, and virtual) are rotated to minimise the energy.
Flexible active space definition – two options:
Explicit: list of orbital indices (active_orbitals) and number of active electrons.
Automatic: AVAS selection using atomic orbital labels (aolabels) and optional threshold.
Multiple solvers – choose between exact CASSCF ("exact") or DMRG ("dmrg") for the active‑space diagonalisation.
Frozen‑core support – core orbitals can be excluded to reduce cost.
Correlation metrics – provides percent_correlation_captured and approximate full‑CI energy for validation.
Downstream ready – outputs include active‑space integrals, fermionic Hamiltonian, and optimised MO coefficients.

Benefits

Gold‑standard for static correlation – yields qualitatively correct wavefunctions for many challenging systems.
Orbital relaxation – unlike fixed‑orbital methods, the orbitals adapt to the correlated wavefunction.
Versatile active‑space choices – manual control or automated AVAS selection.
Multiple solver options – for larger active spaces, DMRG or SHCI can be used instead of exact CASCI.
Easy integration – CASSCF orbitals can be used as reference for perturbation theory (CASPT2, NEVPT2), pair‑density functional theory, or quantum algorithms (VQE).

How It Works

Initialisation – start from a converged Hartree–Fock (RHF) reference and project to an initial set of molecular orbitals.
Define active space – either:
Explicit: use active_orbitals (list of MO indices) and n_active_electrons.
AVAS: use aolabels (e.g., "Fe 3d") and optional threshold to automatically select orbitals that overlap strongly with chosen atomic orbitals.
CASSCF iterations – alternate between:
CI step: solve the full CI problem in the active space (using the chosen solver).
Orbital step: compute the orbital gradient and Hessian, then rotate orbitals to lower the energy.
Convergence check – stop when energy and orbital gradients fall below a threshold.
Post‑processing – compute one‑ and two‑electron integrals in the final CASSCF MO basis, build fermionic Hamiltonian, and evaluate correlation metrics.

TaskType: casscf

Inputs:

symbols: 1D array, list Atomic elements (e.g., ["O","H","H"]) that directly correspond to the coordinates in the geometry array. geometry: 1D array, list Cartesian coordinates (x,y,z), in angstroms, representing the 3D position of all atoms (e.g., [0.0000, 0.0000, 0.0000, 0.0000, 0.7570, 0.5860, 0.0000, -0.7570, 0.5860]). basis_set: str Gaussian basis set used for the RHF reference (e.g., "def2-svp", "sto-3g"). charge: value (integer) The net electric charge of the system (e.g., 0 for neutral, -1 for an anion). multiplicity: value (integer) The spin multiplicity of the system, defined as M = 2S + 1 (e.g., M=1 for a singlet state with all electrons paired with S=0).

Active space definition – one of the following is required:

active_orbitals: list of int Explicit indices of the active molecular orbitals (0‑based). n_active_electrons: int Number of active electrons (required if active_orbitals is given). aolabels: str or list of str Atomic orbital labels for AVAS selection (e.g., "Fe 3d"). threshold: value (float), default = 0.2 AVAS truncation threshold (only used with aolabels).

Optional keys:

n_frozen_orbitals: value (integer), default = 0 Number of core occupied orbitals to freeze/exclude from the active space. Also accepted as n_core. casscf_solver: str, default = "auto" Solver for the CASSCF diagonalisation. Options: "auto", "exact", "dmrg", "shci". dmrg_bond_dim: value (integer), default = 1000 Bond dimension for the DMRG solver (only relevant when casscf_solver="dmrg"). skip_fci: bool, default = False Skip the full‑CI reference computation (useful for large active spaces where FCI is impossible). base_dir: str, default = "data" Directory for caching full‑CI results.

Outputs:

one_electron_integrals: 2D array (float) A matrix (N x N) containing the kinetic energy and nuclear attraction terms for individual electrons within the active space in the final CASSCF MO basis. two_electron_integrals: 4D array (float) A tensor (N x N x N x N) representing the electron-electron repulsion interactions in the active space. hf_energy: value (float) The molecular ground-state energy [Hartree] calculated using the mean-field Hartree-Fock approximation. casscf_energy: value (float) Total CASSCF energy [Hartree]. mp2_energy: value (float) HF + active‑space MP2 correlation energy computed with CASSCF orbitals [Hartree]. fci_energy: value (float) Total active‑space FCI energy with frozen‑core correction [Hartree]. vqe_energy: value (float or None) Total active‑space VQE energy (if run_vqe is True), otherwise None. h_coefficient: list of float Coefficients of the fermionic Hamiltonian terms. h_fermionic_operators: list of tuple Fermionic operators (orbital indices and creation/annihilation flags) corresponding to h_coefficient. casscf_mo_coefficients: 2D array (float) Final CASSCF MO coefficient matrix (inactive + active + virtual ordering). casscf_mo_energies: list of float Diagonal Fock energies of the CASSCF orbitals (orbital energies). active_orbital_indices: list of int Indices of the active orbitals in the final MO ordering. full_fci_energy: value (float or None) Exact full‑CI total energy (if computed). percent_correlation_captured: value (float or None) Percentage of full correlation energy captured by the active space FCI.

Example

# CASSCF input for H2 molecule
casscf_input = {
    "symbols": ["H", "H"],
    "geometry": [0.0, 0.0, 0.0, 0.0, 0.0, 0.74],
    "basis_set": "sto-3g",
    "charge": 0,
    "multiplicity": 1,
    "active_orbitals": [0, 1],
    "n_active_electrons": 2
}
# Create the task
casscf_task = session.cebule.create_task(
    "H2 CASSCF Test",
    TaskType.CASSCF,
    json.dumps(casscf_input),
    max_processors=1
)

Limitations and Considerations

Active space selection is crucial – a poorly chosen active space can lead to qualitatively wrong results or convergence to undesired states. Use AVAS or chemical intuition carefully.
Local minima – CASSCF orbital optimisation is highly nonlinear and may converge to a local minimum; a good initial guess (e.g., from a previous CASSCF or a smaller calculation) is recommended.
Computational cost – exact CASCI scales combinatorially with active space size; for larger spaces, use DMRG (casscf_solver="dmrg") or SHCI.
Bond dimension – when using the DMRG solver, ensure dmrg_bond_dim is large enough; test convergence by increasing it.
State averaging – the current implementation appears state‑specific; for excited states or near‑degeneracies, state‑averaged CASSCF may be more appropriate (not currently exposed here).

Complete Active Space Self-Consistent Field with Density Matrix Renormalization Group (DMRG-CASSCF)¶

When to Use
DMRG-CASSCF is the method of choice when you need a multireference calculation but the active space is too large for traditional CASSCF (which uses exact full configuration interaction). By using DMRG as the active‑space solver, you can treat active spaces of 20, 30, or more orbitals, opening the door to transition metal clusters, extended π systems, and other strongly correlated problems.

Core Idea
CASSCF optimises both orbitals and configuration interaction coefficients within an active space. DMRG-CASSCF replaces the exact full CI solver with the Density Matrix Renormalization Group, which approximates the CI wavefunction as a matrix product state. Bond dimension is the primary accuracy knob, but sweep count and convergence settings also matter. Larger bond dimensions give more accurate results but cost more memory and time.

Key Features

Flexible active space definition – two ways to specify the active space:
Explicit list of orbital indices (active_orbitals) and number of active electrons.
Automatic selection via AVAS (using aolabels and optional threshold).
Multiple DMRG solvers – choose between "block" and "chemps2" backends.
Tunable accuracy – adjust dmrg_bond_dim and dmrg_convergence to balance cost and fidelity.
Large active spaces – routinely handles active spaces that are impossible with exact FCI.
Seamless integration – outputs are compatible with the rest of the Cebule workflow (integrals, energies, Hamiltonian).

Benefits

Access to strongly correlated systems – enables multireference treatment of molecules that were previously out of reach.
Systematic accuracy control – bond dimension provides a single knob for converging toward the FCI limit.
Two complementary active‑space strategies – use AVAS for automated, chemically intuitive spaces, or specify orbitals manually for full control.
Reuses existing Cebule infrastructure – the outputs (one‑ and two‑electron integrals, fermionic Hamiltonian) feed directly into downstream methods like VQE or FCI.

How It Works

Initialisation – start from a converged Hartree‑Fock (HF) reference and generate initial orbitals.
Define active space – either:
Explicit: use active_orbitals and n_active_electrons.
Automatic: use aolabels (and optionally threshold) to project atomic orbitals onto molecular orbitals and select those with largest overlap (AVAS).
DMRG‑CASSCF iterations – alternate between:
Orbital optimisation – update molecular orbitals to minimise the energy.
DMRG diagonalisation – solve the active‑space CI problem approximately using a matrix product state with bond dimension dmrg_bond_dim.
Convergence check – repeat until the energy and orbital gradients fall below dmrg_convergence.
Post‑processing – compute one‑ and two‑electron integrals, fermionic Hamiltonian, and correlation metrics (e.g., percent_correlation_captured).

The DMRG step is performed by the chosen solver (Block or ChemPS2). The bond dimension controls the number of kept states: larger dmrg_bond_dim yields a more accurate wavefunction but requires more memory and CPU time.

TaskType: dmrg_casscf

Inputs:

symbols: 1D array, list Atomic elements (e.g., ["O","H","H"]) that directly correspond to the coordinates in the geometry array. geometry: 1D array, list Cartesian coordinates (x,y,z), in angstroms, representing the 3D position of all atoms (e.g., [0.0000, 0.0000, 0.0000, 0.0000, 0.7570, 0.5860, 0.0000, -0.7570, 0.5860]). basis_set: str Gaussian basis set used for the RHF reference (e.g., "def2-svp", "sto-3g"). charge: value (integer) The net electric charge of the system (e.g., 0 for neutral, -1 for an anion). multiplicity: value (integer) The spin multiplicity of the system, defined as M = 2S + 1 (e.g., M=1 for a singlet state with all electrons paired with S=0).

Active space definition – one of the following is required:

active_orbitals: list of int Explicit indices of the active molecular orbitals (0-based). n_active_electrons: int Number of active electrons (required if active_orbitals is given). aolabels: str or list of str Atomic orbital labels for AVAS selection (e.g., "Fe 3d"). threshold: value (float), default = 0.2 AVAS truncation threshold (only used with aolabels).

Optional keys:

n_frozen_orbitals: value (integer), default = 0 Number of core occupied orbitals to freeze/exclude from the active space. Also accepted as n_core. dmrg_solver: str, default = "block" Solver for the DMRG active space diagonalization. Options: "block", "chemps2". dmrg_bond_dim: value (integer), default = 1000 Bond dimension (maxM) for the DMRG solver. Larger values give higher accuracy but require more memory. dmrg_convergence: value (float), default = 1e-9 Energy convergence tolerance for DMRG. skip_fci: bool, default = False Skip the full-CI reference computation (useful for large active spaces where FCI is impossible). base_dir: str, default = "data" Directory for caching full-CI results.

Outputs:

The returned dictionary contains keys similar to those returned by run_casscf:

one_electron_integrals: 2D array (float) A matrix (N x N) containing the kinetic energy and nuclear attraction terms for individual electrons within the MO basis. two_electron_integrals: 4D array (float) A tensor (N x N x N x N) representing the electron-electron repulsion interactions. hf_energy: value (float) The molecular ground-state energy [Hartree] calculated using the mean-field Hartree-Fock approximation. casscf_energy: value (float) Total DMRG-CASSCF energy [Hartree]. mp2_energy: value (float) Total energy estimate from HF plus active‑space MP2 correlation energy [Hartree] (if computed). fci_energy: value (float) Exact full‑CI energy in the active space [Hartree] (if skip_fci is False). vqe_energy: value (float) The optimised energy (Hartree) computed using the Variational Quantum Eigensolver (VQE) algorithm with the chosen orbitals (if requested). h_coefficient: list of float Coefficients of the fermionic Hamiltonian terms. h_fermionic_operators: list of tuple Fermionic operators (orbital indices and creation/annihilation flags) corresponding to h_coefficient. casscf_mo_coefficients: 2D array (float) optimised molecular orbital coefficients. casscf_mo_energies: list of float Molecular orbital energies. active_orbital_indices: list of int Indices of the active orbitals in the full orbital set. full_fci_energy: value (float) Exact full‑CI energy (if computed). percent_correlation_captured: value (float) Percentage of active‑space correlation energy captured by DMRG relative to FCI.

Example

# H2 DMRG-CASSCF input
dmrg_casscf_input = {
    "symbols": ["H", "H"],
    "geometry": [0.0, 0.0, 0.0, 0.0, 0.0, 0.74],
    "basis_set": "sto-3g",
    "charge": 0,
    "multiplicity": 1,
    "active_orbitals": [0, 1],
    "n_active_electrons": 2,
    "dmrg_solver": "block",
    "dmrg_bond_dim": 100,
}

# Create the task
dmrg_casscf_task = session.cebule.create_task(
    "H2 DMRG-CASSCF Test",
    TaskType.DMRG_CASSCF,
    json.dumps(dmrg_casscf_input),
    max_processors=1
)

Limitations and Considerations

Bond dimension choice matters – too small a bond dimension can lead to qualitative errors; too large may be prohibitively expensive. Always test convergence by increasing dmrg_bond_dim.
Active space selection still crucial – DMRG‑CASSCF cannot fix a poorly chosen active space. Use AVAS or chemical intuition to select relevant orbitals.
Memory scaling – DMRG memory usage grows with bond dimension and number of orbitals.
Solvers differ – "block" and "chemps2" may give slightly different results or performance; choose the one that works best for your system.
Orbital optimisation – the DMRG‑CASSCF optimisation can converge to local minima. A good initial guess (e.g., from HF or a previous CASSCF) helps.