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 without the Jordan–Wigner Z strings, and ceo couples qubit excitations that share an entangling structure for the best accuracy per CNOT. Every pool conserves the particle number, so the search stays in the physical sector.
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.17
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.17.tar.gz | 15.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| carcara-26.9.17-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 27.4 MB
Release files / carcara-26.9.17.tar.gz
| Download URL | carcara-26.9.17.tar.gz |
|---|---|
| Size | 15.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1f6bec10a9366495980ab566f2537107abc7be78dcb87402b11a3d30654a0fd
|
|
BLAKE2b-256 checksum How to use checksums |
32ff402438567d1d13ffeb296a57515ee651e21bff3a82c4b1006750fdc36dfd
|
| 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.17-py3-none-any.whl
| Download URL | carcara-26.9.17-py3-none-any.whl |
|---|---|
| Size | 11.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2b7bb8665935449c6a3c94dd20bc7ecfc37942cbbb064fe10640b8b799999a2f
|
|
BLAKE2b-256 checksum How to use checksums |
93a5d91b2031b35f0dade604aac268731bd8b39299ed74a68fe9b38d0149eb50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
