API Reference

NeutralAtoms

Simulation tools for neutral-atom experiments in optical tweezers.

The package focuses on the workflow used in two-photon Rydberg experiments: trap characterization, thermal sampling of atom motion, stochastic laser phase noise, Lindblad dynamics for single-atom excitation, and blockade-mediated two-qubit phase-gate simulations.

w0_to_z0(w0, λ, M2=1.0)

Return the Rayleigh length associated with a beam waist w0.

The conversion is

\[z_0 = \frac{\pi w_0^2}{\lambda M^2}.\]

Arguments

• w0: beam waist radius in μm.
• λ: beam wavelength in μm.
• M2 = 1.0: beam-quality factor. M2 = 1 corresponds to an ideal Gaussian beam.

Returns

• Rayleigh length in μm.

trap_frequencies(atom_params, trap_params)

Return the harmonic trap frequencies for a Gaussian optical tweezer.

Arguments

• atom_params: [m, T], with mass m in atomic mass units and temperature T in μK.
• trap_params: [U0, w0, z0], with trap depth U0 in μK, waist w0 in μm, and Rayleigh length z0 in μm.

Returns

• (ωr, ωz): radial and longitudinal trap frequencies in MHz.

E(x, y, z, w0, z0; n=1, θ=0.0)

Return the normalized complex field profile A(...) * A_phase(...).

I(x, y, z, w0, z0; n=1, θ=0.0)

Return the normalized intensity profile associated with A.

get_trap_params(ωr, ωz, U0, λ; m = 87.0, dif=true)

Infer Gaussian-tweezer parameters from target trap frequencies.

The trap is assumed to be formed by a single Gaussian beam with equal radial frequencies in x and y.

Arguments

• ωr: radial oscillation frequency in MHz.
• ωz: longitudinal oscillation frequency in MHz.
• U0: trap depth in μK.
• λ: trap wavelength in μm.

Keywords

• m = 87.0: atom mass in atomic mass units.
• dif = true: when true, infer the trap geometry from the frequency difference and return the implied depth.

Returns

• (w0, z0, U): waist, Rayleigh length, and effective depth in package units.

H(cord, trap_params, m; harmonic=false)

Return the total energy of one sampled atom in the tweezer model.

Set harmonic = true to use Π_Harmonic; otherwise the full Gaussian potential Π is used.

samples_generate(trap_params, atom_params, N; freq=10, skip=1000, harmonic=true)

Generate Monte Carlo samples of initial atom coordinates and velocities.

Arguments

• trap_params: [U0, w0, z0], with U0 in μK and lengths in μm.
• atom_params: [m, T], with mass in atomic mass units and temperature in μK.
• N: number of Monte Carlo samples.

Keywords

• freq = 10: number of Metropolis updates skipped between retained samples.
• skip = 1000: burn-in length for the Metropolis sampler.
• harmonic = true: use the harmonic approximation instead of the full Metropolis sampler.
• eps = 1e-2: reject samples with total energy above U0 * (1 - eps).

Returns

• (samples, acc_rate), where each sample is [x, y, z, vx, vy, vz]. For harmonic = true, the acceptance rate is reported as 1.

R(t, ri, vi, ω; free=false)

Return the position of one Cartesian coordinate at time t.

For free = false, the coordinate follows harmonic motion with frequency ω; for free = true, it follows ballistic motion.

V(t, ri, vi, ω; free=false)

Return the velocity of one Cartesian coordinate at time t.

This is the velocity companion to R.

release_recapture(tspan, trap_params, atom_params, N; freq=10, skip=1000, eps=1e-3, harmonic=true)

Estimate a release-and-recapture curve by averaging over N sampled atoms.

This is the package's temperature-estimation entry point for optical-tweezer experiments: sample thermal initial conditions, evolve each atom during the release window, and average the recapture outcomes.

Arguments

• tspan: release times in μs.
• trap_params: [U0, w0, z0], with U0 in μK and lengths in μm.
• atom_params: [m, T], with mass in atomic mass units and temperature in μK.
• N: number of Monte Carlo samples.

Keywords

• freq = 10: number of Metropolis updates skipped between retained samples.
• skip = 1000: burn-in length for the Metropolis sampler.
• eps = 1e-3: recapture cutoff passed to release_evolve.
• harmonic = true: when true, use the harmonic approximation for fast Gaussian sampling. When false, use the Metropolis sampler in the full trap potential.

Returns

• (recapture, acc_rate), where recapture is the recapture probability at each time in tspan and acc_rate is the Metropolis acceptance rate. For harmonic = true, the acceptance rate is 1.

Sϕ(f, laser_phase_params)

Return the laser phase-noise spectral density sampled on the frequency grid f.

laser_phase_params is expected to be [h0, hg, σg, fg]: a white-noise floor h0 plus optional Gaussian servo bumps with amplitudes hg, widths σg, and center frequencies fg. The returned spectrum is divided by f^2, matching the conversion from frequency-noise to phase-noise spectral density used in the single-atom Rydberg model.

ϕ_amplitudes(f, laser_phase_params)

Convert a phase-noise spectral-density model into cosine-series amplitudes.

The amplitudes are suitable for ϕ, which samples random initial phases and constructs a time-domain phase-noise realization for one laser trajectory.

ϕ(tspan, f, amplitudes)

Sample one stochastic laser phase-noise trajectory on tspan.

Arguments

• tspan: time grid in μs.
• f: frequency grid in MHz.
• amplitudes: Fourier amplitudes, typically produced by ϕ_amplitudes.

Returns

• Vector of phase samples in radians.

RydbergConfig

Configuration for single-atom two-photon Rydberg simulations.

This type bundles the ingredients used by the single-atom model inspired by arXiv:1802.10424: thermal atom motion, laser phase noise, detuning, and spontaneous decay channels.

Fields

• tspan::Vector{Float64}: time points in μs used for solver output.
• ψ0: initial pure state in the five-level basis.
• atom_params::Vector{Float64}: [m, T], with mass in atomic mass units and temperature in μK.
• trap_params::Vector{Float64}: [U0, w0, z0], with U0 in μK and lengths in μm.
• n_samples::Int64: number of Monte Carlo trajectories to average.
• f::Vector{Float64}: phase-noise frequency grid in MHz.
• first_laser_phase_amplitudes::Vector{Float64}: Fourier amplitudes for the first-laser phase-noise trace.
• second_laser_phase_amplitudes::Vector{Float64}: Fourier amplitudes for the second-laser phase-noise trace.
• first_laser_params::Dict{String, Any}: dict-based description of the first laser beam and coupling.
• second_laser_params::Dict{String, Any}: dict-based description of the second laser beam and coupling.
• shift::Vector{Float64}: static spatial shift applied to the sampled atom position before simulation.
• detuning_params::Vector{Float64}: [Δ0, δ0] single- and two-photon detunings in angular-frequency units.
• decay_params::Vector{Float64}: spontaneous decay rates from the intermediate and Rydberg states.
• error_options::Dict{String, Any}: switches controlling motion, Doppler shifts, phase noise, and spontaneous-decay channels.

Computational ground state |0⟩ in the package's five-level basis.

Computational ground state |1⟩ in the package's five-level basis.

Target Rydberg state |r⟩ in the package's five-level basis.

Intermediate excited state |p⟩ used by the two-photon model.

Loss state |l⟩ used to collect population outside the ideal manifold.

gauss_field(x, y, z, w0, z0; n0=1, θ0=0)

Return the normalized complex Gaussian field envelope used by the refactored dict-based beam parameter API.

This is the Gaussian-beam specialization that Ω uses when laser_params["type"] == "gauss".

simulation(cfg::RydbergConfig; temperature_calibrate=false, ode_kwargs...)

Simulate single-atom two-photon Rydberg excitation and average over Monte Carlo realizations.

The model combines the mechanisms emphasized in arXiv:1802.10424: finite-temperature atomic motion and Doppler dephasing, spontaneous emission from the intermediate and Rydberg states, and stochastic laser phase noise.

Arguments

• cfg::RydbergConfig: simulation configuration.

Keywords

• temperature_calibrate = false: if true, first adjust the ideal laser parameters with calibrate_two_photon.
• ode_kwargs...: keyword arguments forwarded to timeevolution.master_dynamic.

Returns

• (ρ, ρ2), the first and second moments of the density-matrix trajectory.

Ω_twophoton(Ωr, Ωb, Δ)

Return the effective two-photon Rabi frequency

\[\Omega_{\mathrm{2ph}} = \left| \frac{\Omega_r \Omega_b}{2 \Delta} \right|.\]

T_twophoton(Ωr, Ωb, Δ)

Return the effective two-photon Rabi period 2π / Ω_twophoton(Ωr, Ωb, Δ).

δ_twophoton(Ωr, Ωb, Δ)

Return the differential AC Stark shift of the effective two-photon transition:

\[\delta_{\mathrm{2ph}} = \frac{|\Omega_r|^2 - |\Omega_b|^2}{4 \Delta}.\]

Ωr_required(Ω, Ωb, Δ)

Return the red-laser single-photon Rabi frequency needed to realize an effective two-photon coupling Ω with blue-laser coupling Ωb and detuning Δ.

get_rydberg_probs(ρ, ρ2, eps=1e-12)

Extract single-atom level populations and estimated sampling errors from the first and second moments returned by simulation.

plot_rydberg_probs(tspan, probs_dict)

Plot the single-atom populations stored in probs_dict, typically produced by get_rydberg_probs.

simple_flattopHG_field(x, y, z, laser_params)

Return the complex field amplitude of the package's simple Hermite-Gauss flat-top beam model.

This helper is used by Ω when the blue excitation beam is described by a Hermite-Gauss superposition instead of a single Gaussian mode.

simple_flattopLG_field(x, y, z, laser_params)

Return the complex field amplitude of the package's simple Laguerre-Gauss flat-top beam model.

HG_coeff(k, n)

Return the coefficient multiplying the kth Hermite-Gauss term in the simple flat-top expansion of order n.

HG_coefficients(p, q)

Return the coefficient matrix used by the separable Hermite-Gauss flat-top construction.

decomposition_HG_2d(x, y, F, w, dx, dy; n_max=20, m_max=20)

Decompose a sampled two-dimensional field profile into a Hermite-Gauss basis.

The returned coefficient matrix can be passed to reconstruct_HG_field_2d.

reconstruct_HG_field_2d(x, y, z, Ω_w_z, c_xy)

Reconstruct a complex Hermite-Gauss beam field from its coefficient matrix c_xy at point (x, y, z).

Ω_w_z is expected to contain [Ω, w0, z0].

CZLPConfig

Configuration for the blockade-mediated controlled-phase simulation.

This extends RydbergConfig with the atom-pair geometry and phase-gate calibration parameters used by simulation_czlp and the fidelity-analysis helpers. The intended workflow follows the global-pulse CZ protocol discussed in arXiv:1908.06101.

Fields

• tspan, ψ0, atom_params, trap_params, n_samples, f, first_laser_phase_amplitudes, second_laser_phase_amplitudes, first_laser_params, second_laser_params, detuning_params, decay_params, error_options: same meaning as in RydbergConfig.
• atom_centers::Vector{Vector{Float64}}: equilibrium positions of the two traps in μm.
• c6::Float64: van der Waals interaction coefficient used for blockade.
• ΔtoΩ::Float64: detuning-to-Rabi ratio used when calibrating the CZ pulse.
• Ωτ::Float64: pulse-area parameter used by downstream calibration utilities.
• ξ::Float64: phase step between the two global Rydberg pulses.
• ϕ_RZ::Float64: single-qubit RZ compensation phase used in parity analysis.

simulation_czlp(cfg::CZLPConfig; ode_kwargs...)

Simulate the two-atom global-pulse controlled-phase protocol.

The model follows the blockade-based CZ logic highlighted in arXiv:1908.06101: two global Rydberg pulses, an inter-pulse phase step ξ, finite-temperature motion, and optional laser noise and spontaneous decay.

Arguments

• cfg::CZLPConfig: two-atom phase-gate configuration.

Keywords

• ode_kwargs...: keyword arguments forwarded to timeevolution.master_dynamic.

Returns

• (ρ, ρ2), the first and second moments of the two-atom density-matrix trajectory.

get_two_qubit_probs(ρ, ρ2, eps=1e-12)

Extract computational-basis populations and estimated sampling errors from the first and second moments returned by simulation_czlp.

plot_two_qubit_probs(tspan, probs_dict)

Plot the computational-basis populations stored in probs_dict, typically produced by get_two_qubit_probs.

get_fidelity_with_rz_phi(ρ, state, ϕ_rz)

Return the fidelity with a target state after applying a global two-qubit RZ(ϕ_rz) ⊗ RZ(ϕ_rz) correction.

This helper is used when calibrating the phase of the blockade-mediated CZ sequence.

CZ_calibration_by_fidelity_oscillation(cfg::CZLPConfig; ode_kwargs...)

Scan a global RZ phase and return the Bell-state fidelity curve used to calibrate the CZ protocol.

Returns

• (ϕ_list, F_list, ϕ_opt), where ϕ_opt maximizes the fidelity proxy.

get_parity_osc(ρ, ϕ_cal)

Compute the parity oscillation expected after applying the CZ sequence and the phase correction ϕ_cal.

get_rydberg_fidelity_configs(cfg, n_samples=20)

Construct a set of derived configurations used for single-atom error-budget analysis.

Each returned configuration isolates one decoherence mechanism or the combined error budget.

get_rydberg_infidelity(cfg::RydbergConfig; U=dense(identityoperator(basis)),
    states=basis_fidelity_states, n_samples=100, ode_kwargs...)

Estimate a single-atom gate infidelity budget by averaging over input states and error channels.

The returned dictionary separates motion, laser noise, spontaneous decay, and total error contributions for the effective two-photon model.

get_cz_infidelity(cfg::CZLPConfig; n_samples=1, ode_kwargs...)

Estimate a CZ-gate infidelity budget using the parity-calibration workflow.

The result separates calibration error from the remaining decoherence channels.

get_gate(U)

Embed a 2 × 2 qubit unitary U into the five-level single-atom basis.

Only the computational subspace spanned by ket_0 and ket_1 is modified; the other levels are left unchanged.

project_on_qubit(ρ, n=1)

Project a one- or two-atom density operator onto the computational qubit subspace.

Arguments

• ρ: density operator in the five-level basis.
• n = 1: number of atoms to project.

Returns

• Density operator restricted to the |0⟩, |1⟩ subspace for each atom.