API Reference

Primary Workflows

These are the public entrypoints most users should start from.

vqe.run_vqe(molecule: str = 'H2', seed: int = 0, steps: int = 75, stepsize: float | None = None, plot: bool = True, ansatz_name: str = 'UCCSD', ansatz_kwargs: dict[str, Any] | None = None, optimizer_name: str = 'Adam', noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, force: bool = False, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, multiplicity: int = 1, unit: str = 'angstrom', mapping: str = 'jordan_wigner', active_electrons: int | None = None, active_orbitals: int | None = None, hamiltonian: LinearCombination | None = None, num_qubits: int | None = None, reference_state=None)

Run a ground-state VQE optimization.

The input problem can be provided in three modes:

  • registry mode with molecule="H2" or another registered name

  • explicit-geometry mode with symbols and coordinates

  • expert mode with a prebuilt hamiltonian, num_qubits, and an optional computational-basis reference_state

Parameters:

  • molecule – Molecule registry key or label used for explicit/expert-mode runs.

  • seed – Random seed used when initializing ansatz parameters.

  • steps – Number of optimizer steps. The returned energy history includes the initial energy, so len(result["energies"]) == steps + 1.

  • stepsize – Optimizer step size. When omitted, the calibrated package default for optimizer_name is used.

  • ansatz_name – Ansatz name from the VQE registry. "auto" selects a conservative ansatz from the Hamiltonian structure for supported model problems.

  • ansatz_kwargs – Extra ansatz-specific keyword arguments included in cache signatures.

  • optimizer_name – Optimizer registry key, for example "Adam".

  • noisy – Whether to use a mixed-state device and insert configured noise channels during energy evaluation.

  • depolarizing_prob

  • amplitude_damping_prob

  • phase_damping_prob

:param : :param bit_flip_prob: Per-operation noise probabilities. They are ignored unless noisy is

true, but remain part of normalized run metadata.

Parameters:

  • phase_flip_prob – Per-operation noise probabilities. They are ignored unless noisy is true, but remain part of normalized run metadata.

  • force – Recompute even when a matching cached JSON result exists.

  • symbols – Explicit molecular geometry. Use with basis, charge, multiplicity, unit, and optional active-space settings.

  • coordinates – Explicit molecular geometry. Use with basis, charge, multiplicity, unit, and optional active-space settings.

  • mapping – Fermion-to-qubit mapping passed to the shared Hamiltonian builder.

  • active_electrons – Optional active-space controls for chemistry Hamiltonians.

  • active_orbitals – Optional active-space controls for chemistry Hamiltonians.

  • hamiltonian – Expert-mode problem definition. Non-contiguous Hamiltonian wires are remapped to range(num_qubits) by the shared resolver.

  • num_qubits – Expert-mode problem definition. Non-contiguous Hamiltonian wires are remapped to range(num_qubits) by the shared resolver.

  • reference_state – Expert-mode problem definition. Non-contiguous Hamiltonian wires are remapped to range(num_qubits) by the shared resolver.

Returns:

Result dictionary containing energy, energies, steps, final_state_real, final_state_imag, num_qubits, active-space metadata, resolved ansatz, ansatz_kwargs, final_params, params_history, runtime_s, compute_runtime_s, cache_hit, and ansatz_selection when auto-selection was used.

Return type:

dict

qpe.run_qpe(molecule: str = 'H2', seed: int = 0, n_ancilla: int = 4, t: float = 1.0, trotter_steps: int = 2, shots: int | None = 1000, plot: bool = True, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, force: bool = False, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, unit: str = 'angstrom', mapping: str = 'jordan_wigner', active_electrons: int | None = None, active_orbitals: int | None = None, hamiltonian: LinearCombination | None = None, hf_state: ndarray | None = None, system_qubits: int | None = None) → Dict[str, Any]

Run a (noisy or noiseless) Quantum Phase Estimation simulation with caching.

High-level API mirrors run_vqe(): - registry mode via molecule=… - explicit geometry mode via symbols=…, coordinates=…, charge=…, basis=… - optional expert override via precomputed hamiltonian and hf_state

qite.run_qite(molecule: str = 'H2', *, seed: int = 0, steps: int = 75, dtau: float = 0.2, plot: bool = True, ansatz_name: str = 'UCCSD', ansatz_kwargs: dict[str, Any] | None = None, force: bool = False, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, show: bool = True, fd_eps: float = 0.001, reg: float = 1e-06, solver: str = 'solve', pinv_rcond: float = 1e-10, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, noise_model=None, hamiltonian: LinearCombination | None = None, num_qubits: int | None = None, reference_state=None) → Dict[str, Any]

Run VarQITE end-to-end with caching.

VarQITE uses a McLachlan linear-system update requiring a pure statevector. Noisy/mixed-state runs are intentionally not supported here.

Returns:

{

“energy”: float, “energies”: [float, …], “steps”: int, “dtau”: float, “num_qubits”: int, “final_state_real”: […], “final_state_imag”: […], “final_params”: […], “final_params_shape”: […], “varqite”: {…},

}

Return type:

dict

qite.run_qrte(molecule: str = 'H2', *, seed: int = 0, steps: int = 50, dt: float = 0.05, plot: bool = True, ansatz_name: str = 'UCCSD', ansatz_kwargs: dict[str, Any] | None = None, force: bool = False, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, show: bool = True, fd_eps: float = 0.001, reg: float = 1e-06, solver: str = 'solve', pinv_rcond: float = 1e-10, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, noise_model=None, initial_params=None, hamiltonian: LinearCombination | None = None, num_qubits: int | None = None, reference_state=None) → Dict[str, Any]

Run VarQRTE end-to-end with caching.

VarQRTE uses the real-time McLachlan projected update on a pure-state ansatz. Noisy/mixed-state optimization is intentionally not supported here.

VQE Benchmarks And Comparisons

vqe.run_vqe_optimizer_comparison(molecule: str = 'H2', ansatz_name: str = 'RY-CZ', optimizers=None, steps: int = 50, stepsize=None, noisy: bool = True, depolarizing_prob: float = 0.05, amplitude_damping_prob: float = 0.05, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, seed: int = 0, mode: str = 'convergence', noise_type: str = 'depolarizing', noise_levels=None, seeds=None, reference: str = 'per_seed_noiseless', force: bool = False, mapping: str = 'jordan_wigner', unit: str = 'angstrom', show: bool = True, plot: bool = True)

Compare classical optimizers for a fixed VQE instance.

This function supports two modes:

  1. mode=”convergence” - Runs each optimizer once (single seed, single noise point). - Returns energy trajectories vs iteration.

  2. mode=”noise_stats” (new; for Noisy_Optimizer_Comparison) - Sweeps noise_levels and averages over seeds for each optimizer. - Computes:

    ΔE = E_noisy - E_ref (reference from noiseless runs) Fidelity vs noiseless final state

    and returns mean/std vs noise level per optimizer.

Parameters:

  • stepsize (float | dict | None) – If omitted, use the calibrated default stepsize for each optimizer.

  • noise_type (str) – Built-in channel to sweep in mode=”noise_stats”. Supported values: depolarizing, amplitude_damping, phase_damping, bit_flip, phase_flip, combined.

  • reference (str) – Currently only “per_seed_noiseless” is supported: compute noiseless reference energy/state for each seed (and optimizer).

vqe.run_vqe_ansatz_comparison(molecule: str = 'H2', optimizer_name: str = 'Adam', ansatzes=None, steps: int = 50, stepsize: float | None = None, noisy: bool = True, depolarizing_prob: float = 0.05, amplitude_damping_prob: float = 0.05, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, seed: int = 0, mode: str = 'convergence', noise_type: str = 'depolarizing', noise_levels=None, seeds=None, reference: str = 'per_seed_noiseless', force: bool = False, mapping: str = 'jordan_wigner', unit: str = 'angstrom', show: bool = True, plot: bool = True)

Compare ansatz families for a fixed optimizer.

If stepsize is omitted, use the calibrated default for optimizer_name.

mode=”convergence”:

  • single run per ansatz

  • returns energy trajectories vs iteration

mode=”noise_stats”:

  • sweeps noise_levels and averages over seeds for each ansatz

  • computes ΔE (vs per-seed noiseless reference) and fidelity mean/std vs noise

  • sweeps one built-in channel selected by noise_type

vqe.run_vqe_multi_seed_noise(molecule='H2', ansatz_name='RY-CZ', optimizer_name='Adam', steps=30, stepsize=None, seeds=None, noise_type='depolarizing', depolarizing_probs=None, amplitude_damping_probs=None, force=False, mapping: str = 'jordan_wigner', unit: str = 'angstrom', show: bool = True)

Multi-seed noise statistics for a given molecule and ansatz.

vqe.run_vqe_geometry_scan(molecule='H2_BOND', param_name='bond', param_values=None, ansatz_name='UCCSD', optimizer_name='Adam', steps=30, stepsize=None, seeds=None, force=False, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, show: bool = True)

Geometry scan using run_vqe + generate_geometry, mirroring the H₂O and LiH notebooks.

Parameters:

show (bool) – Whether to display the generated plot.

Returns:

[(param_value, mean_E, std_E), …]

Return type:

list of tuples

vqe.run_vqe_low_qubit_benchmark(molecules=None, max_qubits: int = 10, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 75, stepsize=None, seeds=None, force: bool = False, mapping: str = 'jordan_wigner', unit: str = 'angstrom', skip_failures: bool = True, show: bool = True)

Benchmark noiseless VQE across supported low-qubit registry molecules.

The benchmark auto-selects molecules whose resolved qubit count is <= max_qubits unless molecules is provided explicitly. It reports mean / standard deviation for runtime and absolute error against an exact diagonalization of the same qubit Hamiltonian.

vqe.run_vqe_mapping_comparison(molecule='H2', ansatz_name='UCCSD', optimizer_name='Adam', mappings=None, steps=50, stepsize=None, noisy=False, depolarizing_prob=0.0, amplitude_damping_prob=0.0, force=False, show=True, seed=0, unit: str = 'angstrom')

Compare different fermion-to-qubit mappings by:

  • Building qubit Hamiltonians via build_hamiltonian

  • Running VQE (re-using caching) via run_vqe for each mapping

  • Plotting energy convergence curves and printing summary

Parameters:

show (bool) – Whether to display the generated plot.

Returns:

{
mapping_name: {

“final_energy”: float, “energies”: […], “num_qubits”: int, “num_terms”: int or None,

}

Return type:

dict

Excited-State Methods

vqe.run_adapt_vqe(molecule: str = 'H2', *, pool: str = 'uccsd', max_ops: int = 20, grad_tol: float = 0.001, inner_steps: int = 50, inner_stepsize: float = 0.2, optimizer_name: str = 'Adam', seed: int = 0, mapping: str = 'jordan_wigner', noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, noise_model: Callable[[list[int]], None] | None = None, plot: bool = True, force: bool = False)

Run ADAPT-VQE with a UCC excitation pool.

Returns:

{

“energy”: float, “energies”: [float], # per outer iteration (post inner-opt) “inner_energies”: [[float]], # per outer iteration “max_gradients”: [float], # per outer iteration (pre-append) “selected_operators”: [{“kind”:…, “wires”:[…]}], “final_params”: [float], “num_qubits”: int, “config”: dict,

}

Return type:

dict

vqe.run_ssvqe(molecule: str = 'H3+', *, num_states: int = 2, weights: Sequence[float] | None = None, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 100, stepsize: float = 0.4, seed: int = 0, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, noise_model: Callable[[list[int]], None] | None = None, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, unit: str = 'angstrom', mapping: str = 'jordan_wigner', reference_states: Sequence[Sequence[int]] | None = None, plot: bool = True, force: bool = False)

Subspace-Search VQE (SSVQE).

Canonical structure:

|psi_k(theta)> = U(theta) |phi_k> minimize sum_k w_k <psi_k(theta)| H |psi_k(theta)>

Implementation notes (important)

  • This implementation is ansatz-agnostic:

    reference preparation |phi_k> is done explicitly via qml.BasisState.

    This ensures SSVQE works for toy ansatzes that do not support reference_state kwargs.

  • For UCC-family ansatzes, we prevent the ansatz from re-preparing HF by calling it with prepare_reference=False (if supported). This makes the ansatz act like a “pure” U(theta).

Noise

  • Supports depolarizing/amplitude probabilities and an arbitrary noise_model(wires) callable.

  • If noisy=False, no noise is applied.

Output ordering contract (important)

  • energies_per_state[k] is ALWAYS tied to reference_states[k] (reference-index semantics).

  • To avoid “state swapping” in downstream comparisons, the result includes:

    • final_energies_by_ref (reference-index finals)

    • final_order (sorted index -> reference index)

    • final_energies_sorted (ascending finals, canonical E0/E1/…)

    Trajectories are NOT reordered (energy curves can cross).

vqe.run_vqd(molecule: str = 'H3+', *, num_states: int = 2, beta: float = 10.0, beta_start: float | None = None, beta_ramp: str = 'linear', beta_hold_fraction: float = 0.0, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 100, stepsize: float = 0.4, seed: int = 0, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, noise_model: Callable[[list[int]], None] | None = None, symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, unit: str = 'angstrom', plot: bool = True, force: bool = False, mapping: str = 'jordan_wigner')

Variational Quantum Deflation (VQD) for ground + excited states (k-state).

Sequential algorithm:

  • Solve VQE for state 0

  • For state n>0 minimize:

    E(theta_n) + beta(t) * sum_{k<n} overlap(state_k, state_n)

where overlap is:

  • noiseless: |<psi_k|psi_n>|^2

  • noisy: Tr(rho_k rho_n)

Beta schedule:

  • beta_end := beta

  • beta_start defaults to 0.0 if not provided

  • beta(t) ramps from beta_start -> beta_end over optimization steps (optionally holding at beta_start for an initial fraction).

Noise: - If noisy=True, the device is default.mixed and the state QNode returns a density matrix. - You may specify depolarizing_prob, amplitude_damping_prob, and/or noise_model(wires).

Returns:

  • energies_per_state: list[list[float]] (length num_states)

  • final_params: list[list[float]] (length num_states)

  • config: dict

Return type:

dict with keys

vqe.run_qse(molecule: str = 'H2', *, k: int = 3, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 50, stepsize: float | None = None, seed: int = 0, mapping: str = 'jordan_wigner', pool: str = 'hamiltonian_topk', max_ops: int = 24, operators: Sequence[Dict[str, Any]] | None = None, eps: float = 1e-08, force: bool = False)

Run Quantum Subspace Expansion (QSE) using a cached/noiseless VQE reference.

Notes

  • QSE is currently noiseless-only. It relies on the VQE reference statevector.

  • The reference VQE run is called with plot=False and noisy=False.

Parameters:

  • k – Number of eigenvalues to return (lowest-k).

  • pool –

    Operator pool strategy. Currently supported:

    • ”hamiltonian_topk”

  • max_ops – Maximum number of operators in the pool (including identity if used).

  • operators – Optional explicit operator list (JSON specs). If provided, it overrides pool. Each operator spec must be {“type”:”pauli_word”,”word”:”…”,”wires”:[…]}.

  • eps – Cutoff threshold on overlap matrix eigenvalues (discard small directions).

vqe.run_lr_vqe(molecule: str = 'H2', *, k: int = 3, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 50, stepsize: float | None = None, seed: int = 0, mapping: str = 'jordan_wigner', fd_eps: float = 0.001, eps: float = 1e-10, force: bool = False, plot: bool = False, show: bool = True, save: bool = False) → Dict[str, Any]

Estimate low-lying excitation energies with a linear-response VQE model.

The routine first obtains a VQE reference with the requested ansatz and optimizer settings, then builds finite-difference tangent vectors around the optimized parameters. It solves a projected generalized eigenvalue problem in that tangent space and reports excitation energies above the VQE reference.

Parameters:

  • molecule – Molecule registry key.

  • k – Maximum number of positive excitation roots to return.

  • ansatz_name – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • optimizer_name – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • steps – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • stepsize – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • seed – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • mapping – Fermion-to-qubit mapping passed to the shared Hamiltonian builder.

  • fd_eps – Finite-difference displacement used to estimate tangent vectors.

  • eps – Numerical cutoff used when conditioning the overlap matrix.

  • force – Recompute instead of reusing a matching cached result.

  • plot – Controls for the optional spectrum comparison plot.

  • show – Controls for the optional spectrum comparison plot.

  • save – Controls for the optional spectrum comparison plot.

Returns:

Result dictionary with reference_energy, excitations, eigenvalues, solver diagnostics, the cache config, and serialized tangent-space matrices S and A.

Return type:

dict

vqe.run_eom_vqe(molecule: str = 'H2', *, k: int = 3, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 50, stepsize: float | None = None, seed: int = 0, mapping: str = 'jordan_wigner', fd_eps: float = 0.001, eps: float = 1e-10, omega_eps: float = 1e-12, force: bool = False, plot: bool = False, show: bool = True, save: bool = False) → Dict[str, Any]

Estimate excitation energies with a full-response EOM-VQE approximation.

The routine computes a VQE reference, constructs finite-difference tangent vectors at the optimized parameters, and solves a symplectic response problem using tangent and conjugate-tangent coupling blocks. It is intended as a compact small-system diagnostic rather than a production chemistry implementation.

Parameters:

  • molecule – Molecule registry key.

  • k – Maximum number of positive excitation roots to return.

  • ansatz_name – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • optimizer_name – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • steps – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • stepsize – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • seed – Settings for the underlying VQE reference calculation. When stepsize is omitted, the calibrated optimizer default is used.

  • mapping – Fermion-to-qubit mapping passed to the shared Hamiltonian builder.

  • fd_eps – Finite-difference displacement used to estimate tangent vectors.

  • eps – Numerical cutoff used when conditioning the overlap matrix.

  • omega_eps – Minimum positive response frequency retained in the output.

  • force – Recompute instead of reusing a matching cached result.

  • plot – Controls for the optional spectrum comparison plot.

  • show – Controls for the optional spectrum comparison plot.

  • save – Controls for the optional spectrum comparison plot.

Returns:

Result dictionary with reference_energy, excitations, eigenvalues, solver diagnostics, the cache config, and serialized response matrices S, A, and B.

Return type:

dict

vqe.run_eom_qse(molecule: str = 'H2', *, k: int = 3, ansatz_name: str = 'UCCSD', optimizer_name: str = 'Adam', steps: int = 50, stepsize: float | None = None, seed: int = 0, mapping: str = 'jordan_wigner', pool: str = 'hamiltonian_topk', max_ops: int = 24, operators: Sequence[Dict[str, Any]] | None = None, eps: float = 1e-08, imag_tol: float = 1e-10, omega_eps: float = 1e-12, force: bool = False) → Dict[str, Any]

Run EOM-QSE (commutator EOM in an operator manifold) using a noiseless VQE reference.

Notes

  • EOM-QSE is currently noiseless-only. It relies on the VQE reference statevector.

  • The reference VQE run is called with plot=False and noisy=False.

Parameters:

  • k – Number of excitation energies to return (lowest-k positive ω).

  • pool –

    Operator pool strategy. Supported:

    • ”hamiltonian_topk”

  • max_ops – Maximum number of operators in the pool (including identity if used).

  • operators – Optional explicit operator list (JSON specs). If provided, it overrides pool. Each operator spec must be {“type”:”pauli_word”,”word”:”…”,”wires”:[…]}.

  • eps – Cutoff on overlap eigenvalues (discard small directions).

  • imag_tol – Imaginary-part tolerance for accepting an eigenvalue as “real-ish”.

  • omega_eps – Require Re(ω) > omega_eps for acceptance as a physical excitation.

Problems And Hamiltonians

Use these helpers when you need to inspect or reuse the shared molecule, geometry, active-space, and expert-mode resolution layer.

class common.ResolvedProblem(hamiltonian: LinearCombination, num_qubits: int, reference_state: ndarray | None, molecule_label: str, symbols: list[str], coordinates: ndarray, basis: str, charge: int, multiplicity: int, mapping: str, unit: str, active_electrons: int | None, active_orbitals: int | None, cacheable: bool)

Normalized problem description shared by solver entrypoints.

cacheable is true for registry and explicit-geometry chemistry inputs. Expert-mode Hamiltonian inputs are normalized by resolve_problem but callers decide how to include the Hamiltonian fingerprint in their cache signature.

common.resolve_problem(*, molecule: str = 'H2', symbols=None, coordinates=None, basis: str = 'sto-3g', charge: int = 0, multiplicity: int = 1, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, hamiltonian: LinearCombination | None = None, num_qubits: int | None = None, reference_state=None, default_reference_state: bool = False, require_reference_state: bool = False, reference_name: str = 'reference_state') → ResolvedProblem

Resolve molecule, explicit-geometry, or expert-mode inputs.

Registry mode uses molecule to look up symbols, coordinates, basis, charge, multiplicity, and active-space defaults. Explicit-geometry mode uses caller-provided symbols and coordinates with the supplied chemistry settings. Expert mode uses a prebuilt PennyLane hamiltonian and optional reference_state; Hamiltonian wires are remapped to contiguous integer wires when needed.

Parameters:

  • molecule – Registry key in chemistry modes, or a label for expert-mode runs.

  • symbols – Explicit molecular geometry. Both are required when bypassing the molecule registry.

  • coordinates – Explicit molecular geometry. Both are required when bypassing the molecule registry.

  • basis – Chemistry settings forwarded to the shared Hamiltonian builder.

  • charge – Chemistry settings forwarded to the shared Hamiltonian builder.

  • multiplicity – Chemistry settings forwarded to the shared Hamiltonian builder.

  • mapping – Chemistry settings forwarded to the shared Hamiltonian builder.

  • unit – Chemistry settings forwarded to the shared Hamiltonian builder.

  • active_electrons – Optional active-space controls.

  • active_orbitals – Optional active-space controls.

  • hamiltonian – Prebuilt qubit Hamiltonian for expert mode.

  • num_qubits – Number of system qubits in expert mode. If omitted, it is inferred from the Hamiltonian wires.

  • reference_state – Computational-basis bitstring used by solvers that need an initial state.

  • default_reference_state – In expert mode, create an all-zero reference state when no reference_state is provided.

  • require_reference_state – In expert mode, raise when no reference state is provided.

  • reference_name – Name used in validation error messages.

Returns:

Normalized Hamiltonian, qubit count, reference state, chemistry metadata, active-space metadata, and cacheability flag.

Return type:

ResolvedProblem

common.build_hamiltonian(molecule: str | None = None, coordinates: ndarray | None = None, symbols: list[str] | None = None, *, charge: int | None = None, basis: str | None = None, multiplicity: int | None = None, mapping: str = 'jordan_wigner', unit: str = 'angstrom', return_metadata: bool = False, active_electrons: int | None = None, active_orbitals: int | None = None)

Unified Hamiltonian entrypoint.

Supported call styles

  1. Registry / tag mode:

    build_hamiltonian(“H2”, mapping=”jordan_wigner”, unit=”angstrom”)

  2. Explicit molecule mode (used by tests and geometry scans):

    build_hamiltonian(symbols=[…], coordinates=array(…), charge=0, basis=”sto-3g”)

Notes

  • unit controls coordinate input/output units only (angstrom or bohr). Hamiltonian eigenvalues and solver energies remain in Hartree (Ha).

  • This function intentionally does NOT treat non-string molecule as a registry key. Tests often pass atoms/coords positionally; that is handled here by interpreting (molecule, coordinates) as (symbols, coordinates) when molecule is a sequence.

returns:

  • Default (return_metadata=False) – (H, n_qubits, hf_state)

  • With return_metadata=True – (H, n_qubits, hf_state, symbols, coordinates, basis, charge, unit_out)

vqe.build_hamiltonian(molecule: str | None = None, coordinates: ndarray | None = None, symbols: list[str] | None = None, *, charge: int | None = None, basis: str | None = None, multiplicity: int | None = None, mapping: str | None = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None) → Tuple[LinearCombination, int, ndarray, List[str], ndarray, str, int, str]

Build a chemistry Hamiltonian using the shared common implementation.

This compatibility wrapper keeps the historical vqe.build_hamiltonian import path while delegating all molecule lookup, explicit-geometry handling, active-space resolution, and mapping logic to common.build_hamiltonian.

Returns:

(hamiltonian, num_qubits, hf_state, symbols, coordinates, basis, charge, unit).

Return type:

tuple

qpe.build_hamiltonian(molecule: str | None = None, coordinates: ndarray | None = None, symbols: list[str] | None = None, *, charge: int | None = None, basis: str | None = None, multiplicity: int | None = None, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None) → Tuple[LinearCombination, int, ndarray, List[str], ndarray, str, int, str]
Return type:

(H, n_qubits, hf_state, symbols, coordinates, basis, charge, unit_out)

qite.build_hamiltonian(molecule: str | None = None, coordinates: ndarray | None = None, symbols: list[str] | None = None, *, charge: int | None = None, basis: str | None = None, multiplicity: int | None = None, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None) → Tuple[LinearCombination, int, ndarray, List[str], ndarray, str, int, str, str]

Build a chemistry Hamiltonian using the shared common implementation.

This compatibility wrapper keeps the historical qite.build_hamiltonian import path while delegating molecule lookup, explicit geometry, active-space resolution, and mapping behavior to common.build_hamiltonian.

Returns:

(hamiltonian, num_qubits, hf_state, symbols, coordinates, basis, charge, mapping, unit).

Return type:

tuple

common.generate_geometry(name: str, param: float, *, unit: str = 'angstrom')

Geometry wrapper. Supported conventions:

“H2_BOND” “H3+_BOND” (aliases: “H3PLUS_BOND”, “H3_PLUS_BOND”) “LiH_BOND” “H2O_ANGLE”

common.get_molecule_config(name: str)

Return the molecule configuration dict.

common.MOLECULES

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

Ansatzes And Optimizers

vqe.ANSATZES

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

vqe.get_ansatz(name: str)

Return ansatz function by name.

This is the entry point used by vqe.engine.build_ansatz(…).

vqe.init_params(ansatz_name: str, num_wires: int, scale: float = 0.01, requires_grad: bool = True, symbols=None, coordinates=None, basis: str = 'STO-3G', charge: int = 0, multiplicity: int = 1, active_electrons: int | None = None, active_orbitals: int | None = None, ansatz_kwargs: dict[str, Any] | None = None, seed: int = 0)

Initialise variational parameters for a given ansatz.

Design choices (kept consistent with the legacy notebooks):

  • TwoQubit-RY-CNOT / Minimal

    • 1 parameter, small random normal ~ N(0, scale²)

  • RY-CZ

    • num_wires parameters, random normal ~ N(0, scale²)

  • StronglyEntanglingLayers

    • params.shape = (1, num_wires, 3), normal with width ~ π

  • UCC family (UCCS / UCCD / UCCSD)

    • All zeros, starting from θ = 0 as in the original chemistry notebooks. The length of the vector is determined from the excitation lists.

Returns:

Parameter array with requires_grad=True

Return type:

np.ndarray

vqe.OPTIMIZERS

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

vqe.get_optimizer(name: str = 'Adam', stepsize: float | None = None)

Return a PennyLane optimizer instance by name.

Parameters:

  • name – Optimizer identifier (case-insensitive).

  • stepsize – Learning rate. If omitted, use the calibrated optimizer default.

Returns:

An instantiated optimizer.

vqe.get_optimizer_stepsize(name: str = 'Adam') → float

Return the calibrated default stepsize for an optimizer.

Parameters:

name – Optimizer identifier (case-insensitive).

Returns:

Calibrated default learning rate for the canonical optimizer.

QPE Analysis Helpers

qpe.bitstring_to_phase(bits: str, msb_first: bool = True) → float

Convert bitstring → fractional phase in [0, 1).

Parameters:

  • bits – String of “0”/”1”, e.g. “0110”.

  • msb_first – If False, interpret the string as LSB-first.

Returns:

Phase in [0, 1).

Return type:

float

qpe.phase_to_energy_unwrapped(phase: float, t: float, ref_energy: float | None = None) → float

Convert a phase in [0, 1) into an energy, unwrapped around a reference.

The base relation is:

E ≈ -2π * phase / t (mod 2π / t)

We first wrap E into (-π/t, π/t], then (if ref_energy is given) shift by ± 2π/t to choose the branch closest to ref_energy.

qpe.hartree_fock_energy(hamiltonian: LinearCombination, hf_state: ndarray) → float

Compute ⟨HF|H|HF⟩ in Hartree.

common.qpe_branch_candidates(bitstring: str, t: float, ref_energy: float) → dict[str, float]

Return MSB-first and LSB-first phase/energy interpretations for a QPE bitstring.

QPE notebooks often need to distinguish the displayed dominant bitstring from the phase-orientation branch used to convert that bitstring into an energy. Keeping this helper in common avoids duplicating that diagnostic logic.

common.analyze_qpe_result(result: dict[str, Any], exact_ground: float, *, good_enough_error_ha: float = 0.05, branch_tol_ha: float = 1e-09) → dict[str, object]

Summarize QPE result quality and identify branch/bin failure modes.

The returned dictionary is intentionally flat so benchmark notebooks can add it directly to a pandas record row.

common.qpe_calibration_plan(*, ancillas_grid, times_grid, trotter_grid, shots_grid, seeds) → list[dict[str, object]]

Build run rows for a QPE calibration grid.

Analytic runs (shots is None) are deterministic, so they are scheduled once with seed 0. Finite-shot runs are repeated over the provided seeds.

Benchmark Utilities

common.exact_ground_energy_for_problem(**problem_spec) → float

Exact ground energy from the resolved qubit Hamiltonian for a problem spec.

common.summarize_problem(**problem_spec) → dict[str, object]

Build one compact summary row for a resolved problem specification.

common.summarize_registry_coverage(*, systems: list[str] | None = None, mapping: str = 'jordan_wigner', unit: str = 'angstrom', progress: bool = False) → list[dict[str, Any]]

Build a coverage summary for registry-backed molecules.

Parameters:

  • systems – Optional subset of registry molecule names. Defaults to all registry entries.

  • mapping – Shared chemistry-pipeline options passed into build_hamiltonian(...).

  • unit – Shared chemistry-pipeline options passed into build_hamiltonian(...).

  • progress – If True, print one line per built system.

Returns:

One row per registry molecule with charge, multiplicity, electron count, qubit count, Hamiltonian term count, and exact ground-state energy.

Return type:

list[dict[str, Any]]

common.ionization_energy_panel(coverage_rows: list[dict[str, Any]], *, pairs: list[tuple[str, str]] | None = None) → list[dict[str, object]]

Build neutral/cation ionization-energy rows from registry coverage output.

The input is intentionally the flat output from summarize_registry_coverage(...) so notebooks can build expensive Hamiltonians once and reuse the same metadata table for multiple views.

common.summary_stats(xs) → dict[str, float]

Mean/std/min/max summary for a numeric sequence.

common.timed_call(fn: Callable[[...], Any], /, *, suppress_stdout: bool = False, **kwargs) → tuple[Any, float]

Call a function and return (result, elapsed_seconds).

This is intentionally lightweight so notebooks can measure API wall time without reimplementing timing boilerplate.

common.compute_fidelity(pure_state, state_or_rho) → float
Fidelity between a pure reference state |psi> and either:

  • a statevector |phi>

  • or a density matrix rho

Returns |<psi|phi>|^2 or <psi|rho|psi> respectively.

Plotting

vqe.plot_convergence(energies_noiseless, molecule: str, energies_noisy=None, optimizer: str = 'Adam', ansatz: str = 'UCCSD', dep_prob: float = 0.0, amp_prob: float = 0.0, phase_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, seed: int | None = None, show: bool = True)

Plot VQE energy convergence, optionally comparing noisy and noiseless traces.

vqe.plot_optimizer_comparison(molecule: str, results: dict, ansatz: str = 'UCCSD', seed: int | None = None, show: bool = True)

Plot convergence traces from a VQE optimizer comparison run.

vqe.plot_ansatz_comparison(molecule: str, results: dict, optimizer: str = 'Adam', seed: int | None = None, show: bool = True)

Plot convergence traces from a VQE ansatz comparison run.

vqe.plot_noise_statistics(molecule: str, noise_levels, energy_means, energy_stds, fidelity_means, fidelity_stds, optimizer_name: str = 'Adam', ansatz_name: str = 'UCCSD', noise_type: str = 'Depolarizing', show: bool = True)

Plot mean energy error and fidelity against a VQE noise-level sweep.

vqe.plot_multi_state_convergence(energies_per_state=None, ssvqe_or_vqd: str = 'SSVQE', *, molecule: str = 'molecule', ansatz: str = 'UCCSD', optimizer: str = 'Adam', optimizer_name=None, E0_list=None, E1_list=None, seed: int | None = None, show: bool = True, save: bool = True, state_labels: Sequence[str] | None = None, order: Sequence[int] | None = None)

Plot per-state convergence traces for SSVQE or VQD runs.

qpe.plot_qpe_distribution(result: Dict[str, Any], *, order: str = 'binary_asc', show: bool = True, save: bool = True) → None

Plot the measured ancilla probability distribution from a QPE result.

Parameters:

  • result – Dictionary returned by run_qpe. The plot uses probs, molecule, n_ancilla, t, and optional noise metadata.

  • order – Bar ordering. Use "binary_asc" for computational-basis order or the other internal ordering modes accepted by _sort_items.

  • show – Display the figure after plotting.

  • save – Save the figure through the shared plotting path conventions.

qpe.plot_qpe_sweep(x_values: Sequence[float], y_means: Sequence[float], y_stds: Sequence[float] | None = None, *, molecule: str = '?', sweep_label: str = 'Sweep parameter', ylabel: str = 'Energy (Ha)', title: str = 'Sweep', ref_value: float | None = None, ref_label: str = 'Reference', ancilla: int | None = None, t: float | None = None, noise_params: Dict[str, float] | None = None, show: bool = True, save: bool = True, seed: int = 0) → None

Plot a QPE sweep with optional error bars and reference line.

x_values define the swept control parameter, y_means are the values to plot, and y_stds optionally supplies matching standard deviations. Metadata such as molecule, ancilla, t, noise_params, and seed is used for labels and saved filenames.

qite.plot_convergence(energies: Sequence[float], *, molecule: str = 'molecule', method: str = 'VarQITE', ansatz: str | None = None, step_label: str = 'Iteration', ylabel: str = 'Energy (Ha)', seed: int | None = None, show: bool = True, save: bool = True, dep_prob: float = 0.0, amp_prob: float = 0.0, noise_type: str | None = None) → None

Plot energy convergence vs iteration.

Notes

VarQITE runs are noiseless by design; noise metadata is supported only for consistency with shared filename conventions (e.g. post-evaluation plots).

qite.plot_noise_statistics(noise_levels: Sequence[float], deltaE_mean: Sequence[float], deltaE_std: Sequence[float] | None = None, fidelity_mean: Sequence[float] | None = None, fidelity_std: Sequence[float] | None = None, *, molecule: str = 'molecule', method: str = 'VarQITE', ansatz: str | None = None, noise_type: str = 'depolarizing', seed: int | None = None, show: bool = True, save: bool = True) → None

Plot ΔE and (optionally) fidelity vs noise level.

Intended for post-evaluation noise studies (e.g., evaluating converged VarQITE parameters under default.mixed).

qite.plot_diagnostics(values: Sequence[float], *, molecule: str = 'molecule', title: str = 'Diagnostics', xlabel: str = 'Iteration', ylabel: str = 'Value', tag: str = 'diagnostics', ansatz: str | None = None, seed: int | None = None, show: bool = True, save: bool = True) → None

Generic single-curve diagnostic plot (e.g., residual norms, step sizes, etc.).

common.plot_molecule(symbols: Sequence[str], coords: np.ndarray, *, title: str | None = None, bonds: Sequence[Tuple[int, int]] | None = None, angles: Sequence[Tuple[int, int, int]] | None = None, atom_charges: Sequence[float] | None = None, show_bond_lengths: bool = True, show_angles: bool = True, show_atom_indices: bool = False, ax: plt.Axes | None = None, **kwargs) → plt.Axes

Minimal 2D molecule diagram: - atoms as circles - bonds as lines + length labels - angles as text labels near the central atom - optional per-atom charge labels (useful for ions)

common.infer_bonds(symbols: Sequence[str], coords: ndarray, *, scale: float = 1.2, max_dist: float = 2.4) → List[Tuple[int, int]]

Bond if d(i,j) < scale*(r_i+r_j), capped by max_dist.

common.infer_angles_from_bonds(bonds: Sequence[Tuple[int, int]]) → List[Tuple[int, int, int]]

Return angle triplets (i, j, k) where j is central and (i-j), (j-k) are bonds.

Advanced I/O And Naming

These helpers are public for notebooks and reproducibility tooling, but most users should prefer the high-level workflow functions above.

vqe.make_run_config_dict(symbols, coordinates, basis: str, ansatz_desc: str, optimizer_name: str, stepsize: float, max_iterations: int, seed: int, mapping: str, noisy: bool = False, depolarizing_prob: float = 0.0, amplitude_damping_prob: float = 0.0, phase_damping_prob: float = 0.0, bit_flip_prob: float = 0.0, phase_flip_prob: float = 0.0, molecule_label: str | None = None, charge: int = 0, unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, ansatz_kwargs: dict[str, Any] | None = None) → Dict[str, Any]

Construct a JSON-safe config dict used for hashing/caching.

Notes

  • Callers may append extra keys (e.g. beta schedules, num_states, noise_model name).

  • We round geometry floats to stabilize hashing.

vqe.run_signature(cfg: Dict[str, Any]) → str

Return the stable hash used in VQE-family cache filenames.

vqe.save_run_record(prefix: str, record: Dict[str, Any]) → str

Save run record JSON under results/vqe/<prefix>.json.

vqe.ensure_dirs() → None

Create the VQE results directory if it does not already exist.

qpe.signature_hash(*, molecule: str, symbols: list[str], geometry, basis: str, charge: int, n_ancilla: int, t: float, seed: int = 0, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, hamiltonian: Dict[str, Any] | None = None, reference_state: list[int] | None = None, shots: int | None = None, noise: Dict[str, float] | None = None, trotter_steps: int = 1) → str

Return the stable cache key for a QPE run configuration.

The key includes normalized geometry, basis, charge, mapping, unit, active-space settings, QPE controls, shot mode, noise parameters, and expert Hamiltonian/reference fingerprints when provided.

qpe.save_qpe_result(result: Dict[str, Any]) → str

Persist a QPE result as a cache JSON file.

The destination path is derived from the same normalized signature used by load_qpe_result. The input dictionary must contain the run metadata emitted by run_qpe.

qpe.load_qpe_result(*, molecule: str, symbols: list[str], geometry, basis: str, charge: int, n_ancilla: int, t: float, seed: int, shots: int | None, noise: Dict[str, float] | None, trotter_steps: int, mapping: str = 'jordan_wigner', unit: str = 'angstrom', active_electrons: int | None = None, active_orbitals: int | None = None, hamiltonian: Dict[str, Any] | None = None, reference_state: list[int] | None = None) → Dict[str, Any] | None

Load a cached QPE result matching the provided normalized configuration.

Returns None when no matching cache file exists. Callers are responsible for validating whether old cache records contain any runtime metadata they require.

qpe.apply_noise_all(wires: Iterable[int], p_dep: float = 0.0, p_amp: float = 0.0, p_phase_damp: float = 0.0, p_bit_flip: float = 0.0, p_phase_flip: float = 0.0) → None

Apply built-in single-qubit noise channels to the given wires.

This function is intended to be called inside a QNode, typically after a unitary operation or ansatz to simulate mixed noise channels.

Parameters:

  • wires (Iterable[int]) – Wires (qubit indices) on which to apply noise.

  • p_dep (float, optional) – Depolarizing probability per wire (default = 0.0).

  • p_amp (float, optional) – Amplitude damping probability per wire (default = 0.0).

Example

>>> apply_noise_all([0, 1, 2], p_dep=0.02, p_amp=0.01)
qite.make_run_config_dict(*, symbols, coordinates, basis, charge: int, unit: str, seed: int, mapping: str, noisy: bool, depolarizing_prob: float, amplitude_damping_prob: float, phase_damping_prob: float, bit_flip_prob: float, phase_flip_prob: float, dtau: float, steps: int, molecule_label: str, ansatz_name: str, noise_model_name: str | None = None, active_electrons: int | None = None, active_orbitals: int | None = None, fd_eps: float | None = None, reg: float | None = None, solver: str | None = None, pinv_rcond: float | None = None, ansatz_kwargs: dict[str, Any] | None = None)

Build a stable, JSON-serialisable config dict for caching.

Notes

  • VarQITE numerics are included when provided so they participate in caching.

qite.run_signature(cfg: Dict[str, Any]) → str

Return the stable hash used in VarQITE/VarQRTE cache filenames.

qite.save_run_record(prefix: str, record: Dict[str, Any]) → str

Save run record JSON under results/qite/<prefix>.json.

qite.make_filename_prefix(cfg: dict, *, noisy: bool, seed: int, hash_str: str, algo: str | None = None, **_ignored) → str

Build a stable filename prefix for results/images.

Notes

Accepts extra kwargs so qite.core can evolve without breaking I/O.

qite.ensure_dirs() → None

Create the QITE results directory if it does not already exist.

common.build_filename(*, topic: str, ansatz: str | None = None, optimizer: str | None = None, mapping: str | None = None, seed: int | None = None, dep: float | None = None, amp: float | None = None, noise_scan: bool = False, noise_type: str | None = None, multi_seed: bool = False, ancilla: int | None = None, t: float | None = None, tag: str | None = None) → str

Build a normalized PNG filename from run and plotting metadata.

This helper centralizes filename tokens for notebooks and plotting helpers. It does not create directories or write files.

common.save_plot(filename: str, *, kind: str, molecule: str | None = None, show: bool = True) → str

Save the current Matplotlib figure under the shared images directory.

Parameters:

  • filename – Filename to write. .png is appended when omitted.

  • kind – Top-level image category, such as "vqe", "qpe", or "qite".

  • molecule – Optional molecule subdirectory.

  • show – Display the figure after saving. When false, the figure is closed.

common.format_molecule_name(mol: str) → str

Normalize a molecule label for filenames and cache paths.

Plus signs are expanded to plus and whitespace or unsupported filename characters are replaced with underscores.

common.format_token(val: object) → str

Canonical filename-safe token.

  • ints/floats: fixed precision, trim trailing zeros, encode:

    ‘.’ -> ‘p’, ‘-’ -> ‘m’

    Example: -1.25 -> ‘m1p25’

  • strings: strip, spaces -> ‘_’, ‘+’ -> ‘plus’

Advanced QITE Engine Utilities

These functions expose the lower-level VarQITE/VarQRTE engine used by the workflow entrypoints.

qite.make_device(num_wires: int, *, noisy: bool = False, shots: int | None = None)

Create a PennyLane device.

noiseless -> default.qubit (statevector) noisy -> default.mixed (density matrix)

shots=None keeps analytic mode.

qite.make_energy_qnode(H, dev, ansatz_fn, num_wires, *, noisy=False, depolarizing_prob=0.0, amplitude_damping_prob=0.0, phase_damping_prob=0.0, bit_flip_prob=0.0, phase_flip_prob=0.0, noise_model=None, **_ignored)
Energy QNode:

  • noiseless: ⟨ψ(θ)|H|ψ(θ)⟩

  • noisy: Tr[ρ(θ) H] (noise applied after ansatz)

qite.make_state_qnode(dev, ansatz_fn, num_wires, *, noisy=False, depolarizing_prob=0.0, amplitude_damping_prob=0.0, phase_damping_prob=0.0, bit_flip_prob=0.0, phase_flip_prob=0.0, noise_model=None, **_ignored)
State QNode:

  • noiseless: returns qml.state() (statevector)

  • noisy: returns qml.density_matrix(…)

qite.build_ansatz(ansatz_name: str, num_wires: int, *, seed: int = 0, symbols=None, coordinates=None, charge: int = 0, basis: str | None = None, active_electrons: int | None = None, active_orbitals: int | None = None, requires_grad: bool = True, hf_state: ndarray | None = None, ansatz_kwargs: dict[str, Any] | None = None) → Tuple[Callable[[ndarray], None], ndarray]

Build an ansatz callable and an initial parameter array.

If vqe.ansatz.build_ansatz is available, we delegate to it (to keep ansatz definitions centralized). Otherwise we fall back to a small HEA.

The returned ansatz_fn(params) is responsible for preparing |ψ(θ)⟩, including optional HF initialization via qml.BasisState(hf_state, …).

qite.qite_step(*, params: ndarray, energy_qnode: Callable[[ndarray], Any], state_qnode: Callable[[ndarray], Any], dtau: float, num_wires: int, hamiltonian: LinearCombination, fd_eps: float = 0.001, reg: float = 1e-06, solver: str = 'solve', pinv_rcond: float = 1e-10, cache: dict | None = None) → ndarray

One McLachlan VarQITE update step:

A(θ) v = -C(θ) θ <- θ + dtau * v

where A_ij = Re(<∂i ψ|∂j ψ>) and C_i = Re(<∂i ψ|(H-E)|ψ>), with tangent-space projection applied to the derivatives.

qite.qrte_step(*, params: ndarray, energy_qnode: Callable[[ndarray], Any], state_qnode: Callable[[ndarray], Any], dt: float, num_wires: int, hamiltonian: LinearCombination, fd_eps: float = 0.001, reg: float = 1e-06, solver: str = 'solve', pinv_rcond: float = 1e-10, cache: dict | None = None) → ndarray

One McLachlan VarQRTE update step:

A(θ) v = C(θ) θ <- θ + dt * v

where A_ij = Re(<∂i ψ|∂j ψ>) and

C_i = Im(<∂i ψ|(H-E)|ψ>),

with tangent-space projection applied to the derivatives.