Carcará
Carcará is a Python framework for fermionic quantum simulation with variational quantum algorithms. From an ASE geometry it builds a real-space Hamiltonian — with all-electron basis sets or NCPP / ONCVPSP / PAW pseudopotentials — maps it to qubits, and solves it with VQE or ADAPT-VQE on a state-vector simulator or on quantum hardware (IBM Quantum, Amazon Braket). Energies are reported in eV and distances in Å.
Latest updates
- Forces with PAW + DZP. Hellmann–Feynman and Pulay forces for
basis={"name": "PAW", "size": "DZP"}— the augmented overlap, the projectors and the compensation charges are all differentiated — throughatoms.get_forces(). - Particle-number sectors. 20-qubit problems such as LiH in PAW-DZP are solved exactly in their (nα, nβ) sector: 100 states instead of 220.
- Real molecular orbitals. Orbitals with l > 0 are rotated to real form, so the operator pools reach the exact ground state.
- Wavefunction checkpoints.
Carcara(..., checkpoint="state.json")writes the reference, the generators, the angles and the Hamiltonian after every accepted operator;resume="state.json"continues an interrupted or unconverged run where it stopped. - Virtual orbitals for the FAO basis.
basis={"name": "FAO", "virtual_orbitals": 1}appends the lowest unoccupied atomic levels (H gains 2s, C gains 3s), giving a correlated method room above the occupied orbitals; the default0is the minimal basis as before. - Quantum phase estimation.
QuantumPhaseEstimation(n_evaluation_qubits=10).run("state.json")reads the exact eigenvalue off the checkpointed state, with a memory estimate checked before the 2n+t state vector is allocated.
Installation
pip install carcara
# PAW datasets (kept in a separate repository because of their size)
git clone https://github.com/seixas-research/carcara-paw.git
carcara --link-paw carcara-paw
LiH with ASE
from ase import Atoms
from carcara import Carcara
atoms = Atoms("LiH", positions=[[0.0, 0.0, 0.0], [0.0, 0.0, 1.6]], cell=[10.0, 10.0, 10.0])
atoms.center() # the cell is the real-space box
atoms.calc = Carcara(method="adapt-vqe", # "vqe", "subspace-vqe", "subspace-adapt-vqe"
basis={"name": "PAW", "size": "DZP"}, # pseudopotential family + valence basis
h=0.25, # grid spacing (Å)
pool="fermionic", # "qubit", "qeb", "ceo"
mapping="jordan_wigner", # "parity", "bravyi_kitaev"
optimizer="L-BFGS-B", # "COBYLA", "SLSQP", "Nelder-Mead", "SPSA", "Adam"
max_iterations=80, # at most 80 operators
gradient_tolerance=1e-5, # stop when every pool gradient is smaller
device="AER_simulator", # or an IBM Quantum / Amazon Braket device
shots=0, # 0 = exact expectation values
verbose_operators=False, # True -> the pool to pool.json
verbose_hamiltonian=False) # True -> the Hamiltonian to hamiltonian.json
forces = atoms.get_forces() # eV/Å, runs the simulation
energy = atoms.get_potential_energy() # eV, from the same run
result = atoms.calc.result
print(f"E = {energy:.4f} eV with {result.num_operators} operators")
print(f"F(Li) = {forces[0, 2]:+.3f} eV/Å along the bond")
Potential energy surface
import matplotlib.pyplot as plt
import numpy as np
from ase import Atoms
from carcara import Carcara
distances = np.linspace(1.2, 3.0, 10) # Å
energies = []
for d in distances:
atoms = Atoms("LiH", positions=[[0.0, 0.0, 0.0], [0.0, 0.0, d]], cell=[10.0, 10.0, 10.0])
atoms.center()
atoms.calc = Carcara(method="adapt-vqe",
basis={"name": "PAW", "size": "DZP"},
h=0.25,
pool="fermionic",
optimizer="L-BFGS-B")
energies.append(atoms.get_potential_energy())
plt.plot(distances, energies, "o-")
plt.xlabel("Li–H distance (Å)")
plt.ylabel("Energy (eV)")
plt.savefig("lih_pes.png", dpi=150)
Theory
VQE. The variational quantum eigensolver prepares a parameterized state |ψ(θ)⟩ = U(θ)|ΦHF⟩ on a quantum processor, measures the energy ⟨ψ(θ)|H|ψ(θ)⟩, and lets a classical optimizer update θ to minimize it. By the variational principle the minimum is an upper bound to the ground-state energy, reached exactly when the ansatz can represent the ground state. Carcará starts from the Hartree–Fock determinant in the molecular-orbital basis; the fixed ansatz of method="vqe" is UCCSD.
ADAPT-VQE. ADAPT-VQE builds the ansatz during the calculation instead of fixing it in advance. At each iteration it evaluates the energy gradient ⟨ψ|[H, Ak]|ψ⟩ of every generator Ak in an operator pool, appends exp(θkAk) for the largest one, and re-optimizes all parameters. It stops when every gradient falls below gradient_tolerance, producing compact circuits tailored to the molecule.
Operator pools. The pool is the set of anti-Hermitian generators ADAPT-VQE chooses from, and it sets the trade-off between circuit depth and the number of iterations. fermionic holds spin-adapted single and double excitations; qubit splits them into individual Pauli strings (the shallowest gates, more iterations); qeb uses qubit excitations — the same occupation moves without the fermionic sign; ceo groups QEB generators that share a qubit support. Every pool is built in the encoding you ask for (Jordan–Wigner, parity or Bravyi–Kitaev) and reaches the same ground state. The fermionic and qubit-excitation pools conserve the particle number; the individual Pauli strings of qubit do not, by design.
Classical optimization. The parameters are updated by the optimizer named in optimizer=. COBYLA (the default) and Nelder–Mead are gradient-free and robust; L-BFGS-B and SLSQP use gradients and converge quickly on exact simulators; SPSA (two energy evaluations per step, whatever the number of parameters) and Adam tolerate the statistical noise of shot-based hardware.
License
Carcará is released under the MIT License. Developer: Leandro Seixas Rocha (leandro.rocha@ilum.cnpem.br). Documentation: carcara.readthedocs.io.
We thank financial support from INCT Materials Informatics (Grant No. 406447/2022-5).
1 maintainer
Metadata
1 maintainer
Release files for carcara 26.9.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| carcara-26.9.28.tar.gz | 16.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| carcara-26.9.28-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 27.9 MB
Release files / carcara-26.9.28.tar.gz
| Download URL | carcara-26.9.28.tar.gz |
|---|---|
| Size | 16.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7be64d7b7af957785b6a642f5dfa1c13214b1fa2672563e77baa415e66507f4b
|
|
BLAKE2b-256 checksum How to use checksums |
557946aa3be70609575ca41101f9de6ddf4fb44513b2e4e9cf1765ea9ca49c6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / carcara-26.9.28-py3-none-any.whl
| Download URL | carcara-26.9.28-py3-none-any.whl |
|---|---|
| Size | 11.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9250d53bc9b69cdec5215e874e50a657cb770efd64217169c28d92c66f67781
|
|
BLAKE2b-256 checksum How to use checksums |
15ac5748d884b44447013161076abd4e298ae1bc8d1c24a2cdbc7c5f65b88cff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
