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.
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
python -m carcara.pseudopotentials.link_library --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=True) # iteration table and timings
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",
verbose=False)
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.18
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.18.tar.gz | 15.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| carcara-26.9.18-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 27.5 MB
Release files / carcara-26.9.18.tar.gz
| Download URL | carcara-26.9.18.tar.gz |
|---|---|
| Size | 15.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba4f31b666db9e44d97e0d7b52e03d9ba9939e658797f662937f6a9f865084dc
|
|
BLAKE2b-256 checksum How to use checksums |
03d15f0892c5db2e26c80a6af4bf87d6fb37812ca6ddb2f2407f1111b58391f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / carcara-26.9.18-py3-none-any.whl
| Download URL | carcara-26.9.18-py3-none-any.whl |
|---|---|
| Size | 11.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d1066ab7a1afb9c62265faf22dd9858ed47cdf0424275a101cea9e55fc03831c
|
|
BLAKE2b-256 checksum How to use checksums |
6465bd425972b96dc0eb4868aa30e5c87b8aa9a8d3f0d57ecf4c5202dc805fc5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
