Sagittarius

Sagittarius is a research SDK for classical simulation of Rydberg neutral-atom analog dynamics. It combines a Julia physics and solver backend with a Python SDK for experiment-oriented pulse studies and algorithm prototypes.

The project is under active development. APIs, backend support, and benchmark results may change unless covered by tests and documented artifacts. Sagittarius is a simulation layer, not a calibrated hardware control stack.

Capabilities

• 2D and 3D atom registers, including chains, square lattices, and unit-disk graphs.
• Full and Rydberg-blockade-reduced Hilbert spaces.
• Global and local Rabi-frequency and detuning controls.
• Constant, ramp, piecewise, Gaussian, Blackman, sinc, and sine-squared pulses.
• Schrodinger, Lindblad, and Monte Carlo wave-function evolution.
• Per-atom Rydberg populations and parameter sweeps.
• CPU execution and experimental GPU backends, with CUDA as the primary target.
• Python and Julia APIs with shared physical semantics.
• Runtime diagnostics and versioned result serialization.
• MWIS-oriented register and visualization primitives for unit-disk-graph studies.

See the API guides and physics guides for the supported public contracts.

Repository Layout

Sagittarius/
|-- Sagittarius.jl/          # Julia backend
|-- sagittarius_py/          # Python SDK and tests
|-- docs/                    # User, API, and physics documentation
`-- scripts/                 # Repository maintenance tools

Keep long-running experiments in a separate project rather than under this repository.

Installation

Requirements: Git, Julia 1.10.3 or newer, a Python version supported by sagittarius_py/pyproject.toml, and optionally uv.

For contributors and local development, use a complete source checkout followed by Python dependency synchronization and JuliaPkg resolution. Editable/source installs prefer the top-level Sagittarius.jl/ backend so Julia edits take effect immediately, while released wheels use the embedded backend under sagittarius/julia/Sagittarius.jl.

git clone <repository_url> Sagittarius
cd Sagittarius/sagittarius_py
uv sync
uv run python -m juliapkg resolve

Without uv:

cd Sagittarius/sagittarius_py
python -m pip install -e .
python -m juliapkg resolve

The pip install -e . path is development-only and still depends on the editable source checkout for Python code updates. For consumer installations, Sagittarius is available on production PyPI:

python -m pip install sagittarius-py
sagittarius backend resolve

For reproducible environments, pin the version required by your project.

See the Python package installation guide for virtual-environment setup, verification, upgrades, and uninstall guidance.

For source installs, backend setup, package-release status, container setup, and environment troubleshooting, see the installation overview. Python-specific setup lives under docs/getting-started/python; Julia-native setup lives under docs/getting-started/julia.

Independent Python Projects

mkdir -p ~/workspace/my_experiment
cd ~/workspace/my_experiment
uv init
uv add --editable ../Sagittarius/sagittarius_py
uv run python -m juliapkg resolve
uv run python scripts/rabi_simulation.py

Independent Julia Projects

mkdir -p ~/workspace/my_julia_experiment/scripts
cd ~/workspace/my_julia_experiment
julia --project=. -e 'using Pkg; Pkg.develop(path="../Sagittarius/Sagittarius.jl"); Pkg.instantiate()'
julia --project=. scripts/rabi_simulation.jl

Use --project=. instead of modifying JULIA_LOAD_PATH. The Julia projects guide contains the recommended layout and a Julia example.

Python Quick Start

This example runs a one-atom Rabi oscillation and records the Rydberg population:

import numpy as np
from sagittarius import Atom, Register, Simulation, PulseSequence, SolverConfig

reg = Register([Atom(0.0, 0.0, 0.0)], C6=0.0)
sim = Simulation(
    reg,
    PulseSequence(omega=2.0 * np.pi, delta=0.0),
    SolverConfig(reltol=1e-7, abstol=1e-7),
)

psi0 = np.array([1.0, 0.0], dtype=complex)
result = sim.run(psi0, 0.0, 0.5, observables={"pop_atom_0": 0})
print(result.to_pandas().tail())

For a reduced basis, set SolverConfig(blockade_radius=...) and allocate the initial state using the size returned by sim.validate(). See the Python minimal examples for complete full- and reduced-basis workflows.

Solver selection is explicit through SolverConfig(method=...). The default is adaptive Tsit5; Vern9 is available for higher-accuracy adaptive checks; fixed-step RK4 requires SolverConfig(method="RK4", adaptive=False, dt=...). Run manifests record both requested and effective solver settings.

Julia Quick Start

using Sagittarius

reg = chain_register(3; spacing=0.5, C6=100.0)
context = reduced_basis_context(reg; blockade_radius=0.6)
H = hamiltonian(reg, fill(1.0, 3), zeros(3); basis_context=context)

println("Reduced basis size: ", length(context.basis))

See the Julia native API and Python/Julia parity contract.

Physical Units and Indexing

Numeric inputs do not carry units. Coordinates, times, angular frequencies, interaction coefficients, and decay rates must use one consistent unit system. See physical units and parameter selection for blockade_radius, C6, pulse parameters, and open-system rates.

Python atom indices are zero-based and follow Register.atoms order; Julia indices are one-based. See the pulse and indexing contract.

GPU and Diagnostics

Enable GPU execution through SolverConfig:

cfg = SolverConfig(use_gpu=True, gpu_backend="CUDA")

Backend names include CUDA, AMDGPU, and Metal, but support and test coverage differ. CPU is the stable default, CUDA is experimental, and AMDGPU/Metal remain planned backends.

from sagittarius import backend_maturity, doctor, version_info

print(version_info())
print(backend_maturity())
print(doctor(backend="CUDA", initialize_backend=True))

CUDA is the primary containerized development target, but remains experimental. GPU execution still requires compatible host drivers, runtime libraries, and device passthrough.

Verification

cd sagittarius_py
uv run sagittarius doctor
uv run python -m pytest tests/

CPU tests do not require CUDA. GPU tests are opt-in and require a working backend. Performance results must record the hardware, solver settings, backend configuration, version metadata, and retained benchmark artifacts.

Documentation

• Installation overview
• Python minimal examples
• Julia minimal examples
• Physical units and parameter selection
• Python/Julia parity contract
• Solver configuration
• Noise models

License

Sagittarius is distributed under the Apache License 2.0.