API Reference

This page documents the public modules, classes, and functions of the Carcará package.

Algorithms & Drivers

Basis Sets

Integral Engine

Fermionic Operators & Mappings

Quantum Circuits & Ansätze

Classical Optimizers

Utilities & Profiling

Utilities (structured logging, …).

class carcara.utils.AdaptOutputLogger(path: str = 'output.txt')[source]

Bases: object

Append-only writer for the ADAPT-VQE output.txt protocol.

Parameters:

path (str) – Destination file (overwritten at construction; "output.txt" by convention).

close() → None[source]
write_iteration(iteration: int, pool_operators: Sequence, gradients: Iterable[float], selected_index: int, expressivity: float | None, energy: float, num_parameters: int, energy_unit: str = 'eV', metrics: Any = None) → None[source]

Append one ADAPT iteration’s tracked metrics, in order.

The selected operator is reported in its own block, clearly separate from the full operator pool listing that follows it.

Parameters:

  • iteration (int) – 1-based macro-iteration index.

  • pool_operators (sequence of PoolOperator) – The full operator pool at this step.

  • gradients (iterable of float) – Screening gradient of each pool operator (same order as pool_operators); their magnitudes are logged.

  • selected_index (int) – Index (into pool_operators) of the operator chosen for the ansatz.

  • expressivity (float or None) – Expressivity score \(E\) of the parameterized ansatz at this iteration (None if not computed).

  • energy (float) – Energy after the inner re-optimization, in energy_unit.

  • num_parameters (int) – Number of parameters (operators) in the ansatz after this step.

  • energy_unit (str) – Unit label for energy (default "eV").

  • metrics (optional) – Object exposing cnot_count / depth / total_gates (logged if present).

write_metadata(symbols: Sequence[str] | None = None, positions=None, cell=None, units: str = 'Angstrom', title: str = 'ADAPT-VQE run', extra: dict | None = None) → None[source]

Write the initial geometry and the explicit unit-cell parameters.

Parameters:

  • symbols (sequence of str, optional) – Chemical symbols, one per atom.

  • positions ((N, 3) array_like, optional) – Cartesian coordinates in units.

  • cell ((3, 3) array_like, optional) – Lattice/cell tensor (rows are lattice vectors) in units. None (or an all-zero matrix) means a non-periodic molecule.

  • units (str) – Length unit label for the geometry and cell.

  • title (str) – Header title.

  • extra (dict, optional) – Additional KEY: value metadata lines.

write_optimizer_setup(optimizer_method: str, reference_energy: float, energy_unit: str = 'eV', gradient_tol: float | None = None, max_iterations: int | None = None, extra: dict | None = None) → None[source]

Write the classical optimizer and the pre-loop (reference) results.

The final classical ansatz optimization result leading into the VQE runtime is, before the first operator is added, the Hartree-Fock reference energy of the empty ansatz – logged here as the loop’s starting point.

write_summary(converged: bool, optimal_energy: float, num_operators: int, energy_unit: str = 'eV', reference_energy: float | None = None, correlation_energy: float | None = None, num_parameters: int | None = None, final_max_gradient: float | None = None, expressivity: float | None = None, num_evaluations: int | None = None, metrics: Any = None, optimizer: str | None = None, operator_sequence: Sequence[str] | None = None, extra: dict | None = None) → None[source]

Write the closing summary block: the final parameterization in full.

Records the converged energy, the final ansatz size (operators / parameters), its expressivity, and the compiled-circuit cost (CNOTs, single-qubit gates, total gates, depth), plus the classical-optimizer effort – everything describing the final variational state.

class carcara.utils.Timings(n_cores: int | None = None, backend: str | None = None)[source]

Bases: object

Ordered accumulator of named stage wall-times, with memory/core context.

Use time() as a context manager to time a stage (accumulating across repeated calls), or add() to fold in an externally measured duration. peak_memory_mb and n_cores capture the resource context for the summary.

add(name: str, seconds: float) → None[source]

Fold seconds into stage name and refresh the memory peak.

as_dict() → dict[source]

Serializable view: stage times plus the resource context.

format_report(indent: str = '  ', width: int = 30) → str[source]

Multi-line report of stage times, cores and peak memory.

merge(other: Timings, prefix: str = '') → None[source]

Merge another Timings’ stages (optionally name-prefixed).

property peak_memory_mb: float
time(name: str)[source]

Time the wrapped block, accumulating into stage name.

property total: float
carcara.utils.backend_cores() → int | None[source]

OpenMP thread count of the C integral backend, or None (NumPy path).

carcara.utils.parse_output(path: str) → dict[source]

Reference parser for an ADAPT output.txt (used by the tests).

Scans the file line by line and returns a dict with the metadata, the optimization setup, and a list of per-iteration records – demonstrating that the protocol is machine-parseable as it is written.

carcara.utils.peak_memory_mb() → float[source]

Process peak resident memory in MiB (a monotonic high-water mark).