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

---

Hamiltonian Serialization

The on-disk qubit-Hamiltonian cache (Apache Parquet or JSON) that lets a run skip the integrals and the fermion-to-qubit mapping entirely. See Caching the Hamiltonian (Parquet / JSON).

---

Backends: Devices & Circuit Providers

Device Registry

Which machine a run executes on – the ideal simulator, or an Amazon Braket simulator or QPU. See Running on Amazon Braket (and real QPUs).

Execution devices for the variational loop.

Carcará computes energies on an exact state-vector backend today; this module is the small registry that lets the user name the device an ADAPTVQE should run on, so the same driver can later dispatch to a shot-based simulator or real quantum hardware without changing its public API.

Supported names

"AER_simulator"

The default: an ideal (noiseless) simulator. In the current build this is the exact state-vector backend; it is the device used by the tests and examples.

"ibm-quantum"

Real IBM Quantum hardware (via Qiskit Runtime). Reserved – the dispatch is not implemented yet; naming it is accepted so code can be written against the final API, but running raises NotImplementedError.

"braket-local"

Amazon Braket’s local state-vector simulator, driven by BraketProvider.

"braket-sv1" / "braket-dm1" / "braket-tn1"

Amazon Braket’s managed on-demand simulators, run through the AWS service. Runnable, billed to your AWS account.

"braket-ionq-aria" / "braket-ionq-forte" / "braket-iqm-garnet" / "braket-rigetti-ankaa"

Real QPUs on Amazon Braket. Runnable via BraketProvider with shots > 0 – see device_arn() and carcara.backends.measurement.

Any string starting with arn:aws:braket is also accepted verbatim, so a device that post-dates this release can still be named.

carcara.backends.hardware.AWS_ARN_PREFIX = 'arn:aws:braket'

Prefix identifying an Amazon Braket device ARN.

class carcara.backends.hardware.Device(name: str, simulator: bool, runnable: bool, provider: str | None, arn: str | None = None, description: str = '')

Bases: object

One entry of the device registry.

arn: str | None = None

description: str = ''

property is_aws: bool

name: str

provider: str | None

runnable: bool

simulator: bool

carcara.backends.hardware.available_devices() → list[str]

Canonical device names understood by normalize_device().

carcara.backends.hardware.describe_devices() → list[Device]

The full registry, for listing what a build can target.

carcara.backends.hardware.device_arn(name: str) → str | None

The Amazon Braket ARN of name, or None if it is not an AWS device.

carcara.backends.hardware.device_provider(name: str) → str | None

The circuit provider that drives name (None = the internal one).

carcara.backends.hardware.get_device(name: str) → Device

The Device record for name (synthesized for unknown ARNs).

carcara.backends.hardware.is_aws_device(name: str) → bool

True when the device runs through the Amazon Braket service.

carcara.backends.hardware.is_simulator(name: str) → bool

True when the (normalized) device is a classically simulable simulator.

carcara.backends.hardware.normalize_device(name: str) → str

Resolve a device name/alias to its canonical form.

A raw Amazon Braket ARN is returned unchanged (mapped to its registered name when it is one this build knows), so devices added by AWS after this release can still be named.

Raises:

ValueError – If name is not a known device.

carcara.backends.hardware.require_runnable(name: str) → str

Return the canonical device, or raise if it cannot be executed yet.

"ibm-quantum" is accepted as a label but not yet wired to an execution path, so attempting to run on it raises NotImplementedError.

carcara.backends.hardware.requires_shots(name: str) → bool

True when the device can only be run with shots > 0 (every QPU).

Real hardware never returns a state vector, so an energy has to be estimated from measurements – see carcara.backends.measurement.

Circuit Providers

Which SDK builds and executes the ansatz circuits – Qiskit, Amazon Braket or Cirq. See Backend Providers: Qiskit, Braket and Cirq.

Shot-Based Measurement

Estimating \(\langle H \rangle\) from measurement shots via qubit-wise commuting Pauli groups – the protocol a real QPU requires.

---

Utilities & Profiling

Utilities (structured logging, …).

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

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

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

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

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

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

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)

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

Fold seconds into stage name and refresh the memory peak.

as_dict() → dict

Serializable view: stage times plus the resource context.

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

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

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

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

property peak_memory_mb: float

time(name: str)

Time the wrapped block, accumulating into stage name.

property total: float

carcara.utils.backend_cores() → int | None

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

carcara.utils.parse_output(path: str) → dict

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

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