API / Code Reference

Python package for simulating light-pulse atom interferometers.

class aisim.AtomicEnsemble(phase_space_vectors, state_kets=[1, 0], time: float = 0.0)

Bases: object

Represents an atomic ensemble consisting of n atoms.

Each atom is is defined by its phase space vector (x0, y0, z0, vx, vy, vz) at time t=0. From this phase space vector the position at later times can be calculated.

Parameters:

phase_space_vectors (ndarray) – n x 6 dimensional array representing the phase space vectors (x0, y0, z0, vx, vy, vz) of the atoms in an atomic ensemble
state_kets (m x 1 or n x m x 1 array or list, optional) – vector(s) representing the m internal degrees of freedom of the atoms. If the list or array is one-dimensional, all atoms are initialized in the same internal state. Alternatively, each atom can be initialized with a different state vector by passing an array of state vectors for every atom. E.g. to initialize all atoms in the ground state of a two-level system, pass [1, 0] which is the default.
time (float, optional) – the initial time (default 0) when the phase space and state vectors are initialized

phase_space_vectors

n x 6 dimensional array representing the phase space vectors (x0, y0, z0, vx, vy, vz) of the atoms in an atomic ensemble

Type:: ndarray

calc_position(t)

Calculate the positions (x, y, z) of the atoms after propagation.

Parameters:: t (float) – time when the positions should be calculated
Returns:: pos – n x 3 dimensional array of the positions (x, y, z)
Return type:: array

property density_matrices

Density matrix of the m level system of the n atoms.

These are pure states.

Type:: (n x m x m) array

property density_matrix

Density matrix of the ensemble’s m level system.

Type:: (m x m) array

fidelity(rho_target)

Calculate fidelity of ensemble’s density matrix and target matrix [1].

Parameters:: rho_target (array) – target density matrix as m x m array
Returns:: fidelity – fidelity of AtomicEnsemble’s compared to target density matrix
Return type:: float

References

[1] https://en.wikipedia.org/wiki/Fidelity_of_quantum_states

plot(ax: Axes | None = None, view_from: Literal['x', 'y', 'z'] = 'z', bins: int = 50, **kwargs) → tuple[Figure, Axes]

Plot the positions of the atoms in the ensemble.

axAxis, optional: If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
view_fromstr: View from which direction the plot is created. Options are “x”, “y”, “z”.
binsint: Number of bins for the histogram
**kwargs: Additional keyword arguments for the plot function

Returns:: fig, ax – The figure and axis of the plot
Return type:: tuple of plt.Figure and plt.Axes

property position

Positions (x, y, z) of the atoms in the ensemble.

Type:: (n x 3) array

property state_bras

The bra vectors of the m level system.

Type:: (n x 1 x m) array

property state_kets

The ket vectors of the m level system.

Type:: (n x m x 1) array

state_occupation(state)

Calculate the state population of each atom in the ensemble.

Parameters:: state (int or list_like) – Specifies which state population should be calculated. E.g. the excited state of a two-level system can be calculated by passing either 1 or [0, 1].
Returns:: occupation – n dimensional array of the state population of each of the n atom
Return type:: array

property time

Time changes when propagating the atomic ensemble.

Type:: float

property velocity

Velocities (vx, vy, vz) of the atoms in the ensemble.

Type:: n x 3) array

class aisim.Detector(t_det, **kwargs)

Bases: object

A generic detection zone.

This is only a template without functionality. Deriving classes have to implement _detected_idx.

Parameters:

t_det (float) – time of the detection
**kwargs – Additional arguments used by classes that inherit from this class. All keyworded arguments are stored as attribues.

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

detected_atoms(atoms)

Determine wheter a position is within the detection zone.

Returns a new AtomicEnsemble object containing only the detected phase space vectors.

Parameters:: atoms (AtomicEnsemble) – the atomic ensemble
Returns:: detected_atoms – atomic ensemble containing only phase space vectors that are eventually detected
Return type:: AtomicEnsemble

class aisim.FreePropagator(time_delta, **kwargs)

Bases: Propagator

Propagator implementing free propagation without light-matter interaction.

Parameters:: time_delta (float) – time that should be propagated

class aisim.IntensityProfile(*, r_profile, center_rabi_freq, r_beam=None)

Bases: object

Class that defines a Gaussian intensity profile in terms of the Rabi frequency.

Parameters:

r_profile (float) – 1/e² radius of the Gaussian intensity profile in m
center_rabi_freq (float) – Rabi frequency at center of intensity profile in rad/s
r_beam (float (optional)) – Beam radius in m. Can be set if the intensity profile is limited by an aperture. Rabi frequency will be set to 0 outside of the beam.

r_beam

Beam radius in m. If set, Rabi frequency will be set to 0 outside of the beam.

Type:: float or None

profile_func

Function that calculates the Rabi frequency at a position of a Gaussian beam.

Type:: function

get_rabi_freq(pos)

Rabi frequency at a position of a Gaussian beam.

Parameters:: pos ((n x 2) array or (n x 3) array) – positions of the n atoms in two or three dimensions (x, y, [z]).
Returns:: rabi_freqs – the Rabi frequencies for the n positions. If r_beam is set, the Rabi frequency will be set to 0 outside of the beam.
Return type:: array of float

class aisim.PolarDetector(t_det, **kwargs)

Bases: Detector

A spherical detection zone.

All atoms within a circle with the specified radius within the x-y plane will be detected.

Parameters:

t_det (float) – time of the detection
r_det – radius of the spherical detection zone

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

class aisim.Propagator(time_delta, **kwargs)

Bases: object

A generic propagator.

This is just a template class without an implemented propagation matrix.

Parameters:

time_delta (float) – time that should be propagated
**kwargs – Additional arguments used by classes that inherit from this class. All keyworded arguments are stored as attribues.

propagate(atoms)

Propagate an atomic ensemble.

Parameters:: atoms (AtomicEnsemble) – atomic ensemble that should be is propagated

class aisim.SpatialSuperpositionTransitionPropagator(time_delta, intensity_profile, n_pulses, n_pulse, wave_vectors=None, wf=None, phase_scan=0)

Bases: TwoLevelTransitionPropagator

An effective Raman two-level system.

It is implemented as a time propagator as defined in [1]. In addition to class TwoLevelTransitionPropagator, this adds spatial superpositions in z-direction that occour at each pulse.

Parameters:

time_delta (float) – length of pulse
intensity_profile (IntensityProfile) – Intensity profile of the interferometry lasers
wave_vectors (Wavevectors) – wave vectors of the two Raman beams for calculation of Doppler shifts
wf (Wavefront , optional) – wavefront aberrations of the interferometry beam
phase_scan (float) – effective phase for fringe scans
n_pulses (int) – overall number of intended light pulses in symmetric atom interferometry sequence. Each pulse adds two spatial eigenstates.
n_pulse (int) – number of light pulse of symmetric atom-interferometry sequence.

References

[1] Young, B. C., Kasevich, M., & Chu, S. (1997). Precision atom interferometry with light pulses. In P. R. Berman (Ed.), Atom Interferometry (pp. 363–406). Academic Press. https://doi.org/10.1016/B978-012092460-8/50010-2

class aisim.SphericalDetector(t_det, **kwargs)

Bases: Detector

A spherical detection zone.

All atoms within a sphere of the specified radius will be detected.

Parameters:

t_det (float) – time of the detection
r_det – radius of the spherical detection zone

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

class aisim.TwoLevelTransitionPropagator(time_delta, intensity_profile, wave_vectors=None, wf=None, phase_scan=0)

Bases: Propagator

A time propagator of an effective Raman two-level system.

Parameters:

time_delta (float) – length of pulse
intensity_profile (IntensityProfile) – Intensity profile of the interferometry lasers
wave_vectors (Wavevectors) – wave vectors of the two Raman beams for calculation of Doppler shifts
wf (Wavefront , optional) – wavefront aberrations of the interferometry beam
phase_scan (float) – effective phase for fringe scans

Notes

The propagator is for example defined in [1].

References

[1] Young, B. C., Kasevich, M., & Chu, S. (1997). Precision atom interferometry with light pulses. In P. R. Berman (Ed.), Atom Interferometry (pp. 363–406). Academic Press. https://doi.org/10.1016/B978-012092460-8/50010-2

class aisim.Wavefront(r_wf: float, coeff: dict[int, float], r_beam: float | None = None, zern_order: ZernikeOrder = ZernikeOrder.WYANT, zern_norm: ZernikeNorm | None = None)

Bases: object

Class that defines a wavefront.

Parameters:

r_wf (float) – radius of the wavefront data in m
coeff (dict) – Dictionary of the Zernike coefficients. The keys are the Zernike polynomial single indices j and the values are the coefficients depends on the Zernike order and normalization.
r_beam (float (optional)) – Beam radius in m. Can be set if the beam is smaller than the wavefront data. Values outside of the beam will be set to NaN.
zern_order (ZernikeOrder or str) – Ordering scheme for the Zernike polynomials. See ZernikeOrder for possible values.
zern_norm (ZernikeNorm, str or None) – Normalization scheme for the Zernike polynomials. See ZernikeNorm for possible values.

r_wf

radius of the wavefront data in m

Type:: float

coeff

Dictionary of the Zernike coefficients. The keys are the Zernike polynomial single indices j and the values are the coefficients depends on the Zernike order and normalization.

Type:: dict

r_beam

Beam radius in m. If set, values outside of the beam will be set to NaN.

Type:: float or None

zern_order

Ordering scheme for the Zernike polynomials.

Type:: ZernikeOrder or str

zern_norm

Normalization scheme for the Zernike polynomials.

Type:: ZernikeNorm, str or None

get_value(pos: ndarray) → ndarray

Get the wavefront at a position.

Parameters:: pos (n x 3 array) – array of position vectors (x, y, z) where the wavefront is probed
Returns:: wf – The value of the wavefront at the positions
Return type:: nd array

plot(ax: Axes | None = None, cmap: str | Colormap = 'RdBu', levels: int = 100, **kwargs) → tuple[Figure, Axes]

Plot the wavefront data.

Parameters:

ax (Axis , optional) – If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
cmap (str or Colormap) – Colormap for the plot
level (int) – Number of levels for the contour plot
**kwargs – Additional keyword arguments for the plot function

Returns:

fig, ax – The figure and axis of the plot

Return type:

tuple of plt.Figure and plt.Axes

plot_coeff(ax: Axes | None = None, **kwargs) → tuple[Figure, Axes]

Plot the coefficients as a bar chart.

Parameters:: ax (Axis , optional) – If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
Returns:: fig, ax – The figure and axis of the plot
Return type:: tuple of plt.Figure and plt.Axes

class aisim.Wavevectors(k1=8055366, k2=-8055366)

Bases: object

Class that defines the wave vectors of the two Ramen beams.

Parameters:

k1 (float) – 1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m, defaults to 2*pi/780e-9
k2 (float) – 1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m, defaults to 2*pi/780e-9

k1, k2

1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m

Type:: float

doppler_shift(atoms)

Calculate the Doppler shifts for an atomic ensemble.

Parameters:: atoms (AtomicEnsemble) – an atomic enemble with a finite velocity in the z direction
Returns:: dopler_shift – Doppler shift of each atom in the ensemble in rad/s
Return type:: ndarray

class aisim.ZernikeNorm(*values)

Bases: StrEnum

Enumeration of Zernike conventions for normalization.

There are two common conventions for normalizing Zernike polynomials. The Noll convention [1] normalizes the polynomials with a factor sqrt(n+1), while the OSA convention [2, 3] normalizes the polynomials to have unity variance.

References

[1] Noll, R. J. (1976).: Zernike polynomials and atmospheric turbulence*. J. Opt. Soc. Am., 66, 207-211. https://opg.optica.org/josa/fulltext.cfm?uri=josa-66-3-207&id=56041
[2] Thibos, L. N., Applegate, R. A., Schwiegerling, J. T., & Webb, R. (2000).: Standards for Reporting the Optical Aberrations of Eyes. Optics InfoBase Conference Papers. https://doi.org/10.3928/1081-597x-20020901-30
[3] Lakshminarayanan, V., & Fleck, A. (2011).: Zernike polynomials: A guide. Journal of Modern Optics (Vol. 58, Issue 7). https://doi.org/10.1080/09500340.2011.554896

NOLL = 'NOLL': Noll normalization [1], sqrt(n+1).

OSA = 'OSA': OSA normalization [2], sqrt(2n+2) for m=0 and sqrt(n+1) for m!=0.

class aisim.ZernikeOrder(*values)

Bases: StrEnum

Enumeration of conventions for ordering Zernike polynomials with a single index.

There are different ways to order the Zernike polynomials with a single index. The most common conventions are the OSA or ANSI convention [1, 2], the Noll convention [3], the Fringe/University of Arizona/Air Force convention [4], and the Wyant convention [5].

References

[1] Noll, R. J. (1976).: Zernike polynomials and atmospheric turbulence*. J. Opt. Soc. Am., 66, 207–211. https://opg.optica.org/josa/fulltext.cfm?uri=josa-66-3-207&id=56041
[2] Thibos, L. N., Applegate, R. A., Schwiegerling, J. T., & Webb, R. (2000).: Standards for Reporting the Optical Aberrations of Eyes. Optics InfoBase Conference Papers.
[3] ANSI Z80.28-2017.: American National Standard for Ophthalmics - Methods for Reporting Optical Aberrations Of Eyes.
[4] Yen, A. (2021).: Straightforward path to Zernike polynomials. Journal of Micro/Nanopatterning, Materials and Metrology, 20(2). https://doi.org/10.1117/1.JMM.20.2.020501
[5] Wikipedia contributors. (2025).: Zernike polynomials. In Wikipedia, The Free Encyclopedia. https://en.wikipedia.org/wiki/Zernike_polynomials

ANSI = 'ANSI': Ordering according to OSA and ANSI Z80.28-2017.

FRINGE = 'FRINGE': Fringe/University of Arizona/Air Force ordering.

NOLL = 'NOLL': Noll ordering.

WYANT = 'WYANT': Wyant’s ordering.

class aisim.ZernikePolynomial(coeffs: dict[int, float], order: ZernikeOrder = ZernikeOrder.NOLL, norm: ZernikeNorm | None = None)

Bases: object

Class for evaluating Zernike polynomials.

Parameters:

coeffs (dict) – Coefficients of the Zernike polynomial. The keys of the dict are the single indices j of the Zernike polynomials according to the given ordering scheme. If the ordering scheme starts at 1, index 0 (if present) is ignored.
order (ZernikeOrder or str) – Ordering scheme for the Zernike polynomials. Default is ZernikeOrder.NOLL. See ZernikeOrder for possible values.
norm (ZernikeNorm, str or None (optional)) – Normalization scheme for the Zernike polynomials. Default is None, which means no normalization. See ZernikeNorm for possible values.

coeffs

Coefficients of the Zernike polynomial with the single index j as keys.

Type:: dict

order

Ordering scheme for the Zernike polynomials. See ZernikeOrder for possible values.

Type:: ZernikeOrder or str

norm

Normalization scheme for the Zernike polynomials. See ZernikeNorm for possible values.

Type:: ZernikeNorm, str or None

zernike_funcs

Dict of Zernike polynomial functions for each coefficient indexed by the single index j.

Type:: dict

zern_sum(rho: ndarray, theta: ndarray) → ndarray

Calculate the sum of the Zernike polynomials at the given coordinates.

Parameters:

rho (ndarray) – 1 dimensional array of normalized radial coordinates.
theta (ndarray) – 1 dimensional array of azimuthal coordinates. Must have the same length as rho.

Returns:

n dimensional array of the sum of the Zernike polynomial terms at the n coordinates.

Return type:

ndarray

zern_terms(rho: ndarray, theta: ndarray) → dict[int, ndarray]

Evaluate the Zernike polynomial terms at the given coordinates.

Parameters:

rho (ndarray) – 1 dimensional array of normalized radial coordinates.
theta (ndarray) – 1 dimensional array of azimuthal coordinates. Must have the same length as rho.

Returns:

Dictionary with the Zernike polynomial terms for all coordinates and for each coefficient. The keys are the single indices j depending on the ordering scheme.

Return type:

dict

aisim.cart2pol(cart)

Convert vectors in cartesian coordinates to polar coordinates.

Parameters:: cart (n × 3 array) – array of n vectors in cartesian coordinates (x, y, z)
Returns:: pol – array of n vectors in polar coordinates (rho, theta, z)
Return type:: n × 3 array

aisim.create_random_ensemble(n_samples: int, *, mean_x: float = 0.0, mean_y: float = 0.0, mean_z: float = 0.0, mean_vx: float = 0.0, mean_vy: float = 0.0, mean_vz: float = 0.0, x_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), y_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), z_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), vx_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=3e-06), vy_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=3e-06), vz_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=1.6e-07), seed: int | None = None, **kwargs) → AtomicEnsemble

Create a random atomic ensemble from given distributions.

Have a look at the example notebooks to see how to use partial to create distributions with different user defined parameters.

Parameters:

n_samples (int) – number of random samples
mean_x (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_y (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_z (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_vx (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
mean_vy (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
mean_vz (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
x_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
y_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
z_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vx_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vy_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vz_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
seed (int or 1-d array_like, optional) – Set the seed of the random number generator to get predictable samples. If set, this number is passed to numpy.random.seed.
**kwargs – Optional keyworded arguments passed to AtomicEnsemble

Returns:

ensemble – Atomic ensemble containing the generated phase space vectors.

Return type:

AtomicEnsemble

aisim.gen_wavefront(r_wf: float, std: float = 0.0, r_beam: float | None = None, n_zern: int = 36, zern_order: ZernikeOrder = ZernikeOrder.NOLL, zern_norm: ZernikeNorm | None = None, seed: int | None = None) → Wavefront

Create an artificial wavefront.

Parameters:

r_wf (float) – radius of the wavefront data in m
std (float) – standard deviation of each Zernike polynomial coefficient in multiples of the wavelength.
r_beam (float, optional) – Beam radius in m. Can be set if the beam is smaller than the wavefront data. Values outside of the beam will be set to NaN.
n_zern (int) – number of Zernike polynomials to be used
zern_order (ZernikeOrder or str) – Ordering scheme for the Zernike polynomials. See ZernikeOrder for possible values.
zern_norm (ZernikeNorm, str or None) – Normalization scheme for the Zernike polynomials. See ZernikeNorm for possible values.
seed (int, optional) – seed for the random number generator

Returns:

wf – artificial wavefront

Return type:

Wavefront

aisim.j_to_n_m(j: int, order: ZernikeOrder) → tuple[int, int]

Map the single index j to the pair of indices (n, m).

Parameters:

j (int) – Single index of the Zernike polynomial.
order (ZernikeOrder) – Ordering scheme for the Zernike polynomials.

Returns:

Degree and azimuth of the Zernike polynomial.

Return type:

tuple of int

Notes

Some of the implementations were taken from the hcipy library: https://github.com/ehpor/hcipy/blob/master/hcipy/mode_basis/zernike.py

aisim.phase_error_to_grav(phase, T, keff)

Convert a phase error to gravitational acceleration.

Takes the phase shift measured in a Mach Zehnder atom interferometer and converts it to the corresponding gravitional accleration.

Parameters:

phase (float) – Interferometer phase in rad
T (float) – interferometer time in s
keff (float) – effective wavenumber in rad/m

Returns:

gravitational acceleration in in m/s^2

Return type:

float

aisim.pol2cart(pol)

Convert vectors in polar coordinates to cartesian coordinates.

Parameters:: pol (n × 3 array) – array of n vectors in polar coordinates (rho, theta, z)
Returns:: cart – array of n vectors in cartesian coordinates (x, y, z)
Return type:: n × 3 array

aisim.temp(sigma_v, species='Rb87')

Calculate the temperature of an atomic cloud from its velocity spread.

Parameters:

sigma_v (float) – velocity spread (1 sigma) in meters per second
species (str) – the atomic species, has to be a key in mass

Returns:

temp – temperature of the cloud in Kelvin

Return type:

float

Raises:

ValueError – If negative velocity spread is passed

aisim.vel_from_temp(temp, species='Rb87')

Calculate the velocity spread (1 sigma) from the temperature of the cloud.

Parameters:

temp (float) – temperature of the cloud in Kelvin
species (str) – the atomic species, has to be a key in mass

Returns:

vel – velocity spread (1 sigma)

Return type:

float

Raises:

ValueError – If negative temperature is passed

aisim.velocity_dist_for_box_pulse_velsel(n: int, pulse_duration: float, wavelenth: float = 7.8e-07, n_lobes: int = 3) → ndarray

Create a random velocity distribution for a box pulse velocity selection.

The velocity distribution is created by sampling the inverse cumulative distribution function of the Fourier transform of a box pulse with a uniform distribution. The box pulse is defined by its duration and the velocity distribution is given by |τ sinc(2*τ*v/λ)|^2 where τ is the pulse duration, λ the wavelength and v is the velocity of the atoms.

Parameters:

n (int) – number of samples
pulse_duration (float) – duration of the box pulse in seconds
wavelenth (float, optional) – wavelength of the light in meters (default 780e-9)
n_lobes (int, optional) – number of lobes of the sinc function that are sampled (default 3)

Returns:

velocities – n-dimensional array of the randomly selected velocities

Return type:

array

aisim.velocity_dist_for_gaussian_velsel(n: int, pulse_duration: float, wavelength: float = 7.8e-07)

Create a random velocity distribution for a Gaussian pulse velocity selection.

Parameters:

n (int) – number of samples
pulse_duration (float) – duration of the Gaussian pulse in seconds (1/sqrt(2) full width, i.e. 2*sigma)
wavelength (float, optional) – wavelength of the light in meters (default 780e-9)

Returns:

velocities – n-dimensional array of the randomly selected velocities

Return type:

array

Submodules

aisim.atoms module

Classes and functions related to the atomic cloud.

class aisim.atoms.AtomicEnsemble(phase_space_vectors, state_kets=[1, 0], time: float = 0.0)

Bases: object

Represents an atomic ensemble consisting of n atoms.

Each atom is is defined by its phase space vector (x0, y0, z0, vx, vy, vz) at time t=0. From this phase space vector the position at later times can be calculated.

Parameters:

phase_space_vectors (ndarray) – n x 6 dimensional array representing the phase space vectors (x0, y0, z0, vx, vy, vz) of the atoms in an atomic ensemble
state_kets (m x 1 or n x m x 1 array or list, optional) – vector(s) representing the m internal degrees of freedom of the atoms. If the list or array is one-dimensional, all atoms are initialized in the same internal state. Alternatively, each atom can be initialized with a different state vector by passing an array of state vectors for every atom. E.g. to initialize all atoms in the ground state of a two-level system, pass [1, 0] which is the default.
time (float, optional) – the initial time (default 0) when the phase space and state vectors are initialized

phase_space_vectors

n x 6 dimensional array representing the phase space vectors (x0, y0, z0, vx, vy, vz) of the atoms in an atomic ensemble

Type:: ndarray

calc_position(t)

Calculate the positions (x, y, z) of the atoms after propagation.

Parameters:: t (float) – time when the positions should be calculated
Returns:: pos – n x 3 dimensional array of the positions (x, y, z)
Return type:: array

property density_matrices

Density matrix of the m level system of the n atoms.

These are pure states.

Type:: (n x m x m) array

property density_matrix

Density matrix of the ensemble’s m level system.

Type:: (m x m) array

fidelity(rho_target)

Calculate fidelity of ensemble’s density matrix and target matrix [1].

Parameters:: rho_target (array) – target density matrix as m x m array
Returns:: fidelity – fidelity of AtomicEnsemble’s compared to target density matrix
Return type:: float

References

[1] https://en.wikipedia.org/wiki/Fidelity_of_quantum_states

plot(ax: Axes | None = None, view_from: Literal['x', 'y', 'z'] = 'z', bins: int = 50, **kwargs) → tuple[Figure, Axes]

Plot the positions of the atoms in the ensemble.

axAxis, optional: If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
view_fromstr: View from which direction the plot is created. Options are “x”, “y”, “z”.
binsint: Number of bins for the histogram
**kwargs: Additional keyword arguments for the plot function

Returns:: fig, ax – The figure and axis of the plot
Return type:: tuple of plt.Figure and plt.Axes

property position

Positions (x, y, z) of the atoms in the ensemble.

Type:: (n x 3) array

property state_bras

The bra vectors of the m level system.

Type:: (n x 1 x m) array

property state_kets

The ket vectors of the m level system.

Type:: (n x m x 1) array

state_occupation(state)

Calculate the state population of each atom in the ensemble.

Parameters:: state (int or list_like) – Specifies which state population should be calculated. E.g. the excited state of a two-level system can be calculated by passing either 1 or [0, 1].
Returns:: occupation – n dimensional array of the state population of each of the n atom
Return type:: array

property time

Time changes when propagating the atomic ensemble.

Type:: float

property velocity

Velocities (vx, vy, vz) of the atoms in the ensemble.

Type:: n x 3) array

aisim.atoms.create_random_ensemble(n_samples: int, *, mean_x: float = 0.0, mean_y: float = 0.0, mean_z: float = 0.0, mean_vx: float = 0.0, mean_vy: float = 0.0, mean_vz: float = 0.0, x_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), y_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), z_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function position_dist_gaussian>, std=0.0015), vx_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=3e-06), vy_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=3e-06), vz_dist: ~typing.Callable[[int], ~numpy.ndarray] = functools.partial(<function velocity_dist_from_temp>, temperature=1.6e-07), seed: int | None = None, **kwargs) → AtomicEnsemble

Create a random atomic ensemble from given distributions.

Have a look at the example notebooks to see how to use partial to create distributions with different user defined parameters.

Parameters:

n_samples (int) – number of random samples
mean_x (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_y (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_z (float, optional) – mean position of the atomic ensemble in meters (default 0.0)
mean_vx (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
mean_vy (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
mean_vz (float, optional) – mean velocity of the atomic ensemble in meters per second (default 0.0)
x_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
y_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
z_dist (callable) – Function that returns a random position distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vx_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vy_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
vz_dist (callable) – Function that returns a random velocity distribution. The function takes a single integer argument n and returns a n-dimensional array of random samples. To be used with partial to set the parameters of the distributions from the dist module.
seed (int or 1-d array_like, optional) – Set the seed of the random number generator to get predictable samples. If set, this number is passed to numpy.random.seed.
**kwargs – Optional keyworded arguments passed to AtomicEnsemble

Returns:

ensemble – Atomic ensemble containing the generated phase space vectors.

Return type:

AtomicEnsemble

aisim.beam module

Classes and functions related to the interferometry lasers.

class aisim.beam.IntensityProfile(*, r_profile, center_rabi_freq, r_beam=None)

Bases: object

Class that defines a Gaussian intensity profile in terms of the Rabi frequency.

Parameters:

r_profile (float) – 1/e² radius of the Gaussian intensity profile in m
center_rabi_freq (float) – Rabi frequency at center of intensity profile in rad/s
r_beam (float (optional)) – Beam radius in m. Can be set if the intensity profile is limited by an aperture. Rabi frequency will be set to 0 outside of the beam.

r_beam

Beam radius in m. If set, Rabi frequency will be set to 0 outside of the beam.

Type:: float or None

profile_func

Function that calculates the Rabi frequency at a position of a Gaussian beam.

Type:: function

get_rabi_freq(pos)

Rabi frequency at a position of a Gaussian beam.

Parameters:: pos ((n x 2) array or (n x 3) array) – positions of the n atoms in two or three dimensions (x, y, [z]).
Returns:: rabi_freqs – the Rabi frequencies for the n positions. If r_beam is set, the Rabi frequency will be set to 0 outside of the beam.
Return type:: array of float

class aisim.beam.Wavefront(r_wf: float, coeff: dict[int, float], r_beam: float | None = None, zern_order: ZernikeOrder = ZernikeOrder.WYANT, zern_norm: ZernikeNorm | None = None)

Bases: object

Class that defines a wavefront.

Parameters:

r_wf (float) – radius of the wavefront data in m
coeff (dict) – Dictionary of the Zernike coefficients. The keys are the Zernike polynomial single indices j and the values are the coefficients depends on the Zernike order and normalization.
r_beam (float (optional)) – Beam radius in m. Can be set if the beam is smaller than the wavefront data. Values outside of the beam will be set to NaN.
zern_order (ZernikeOrder or str) – Ordering scheme for the Zernike polynomials. See ZernikeOrder for possible values.
zern_norm (ZernikeNorm, str or None) – Normalization scheme for the Zernike polynomials. See ZernikeNorm for possible values.

r_wf

radius of the wavefront data in m

Type:: float

coeff

Dictionary of the Zernike coefficients. The keys are the Zernike polynomial single indices j and the values are the coefficients depends on the Zernike order and normalization.

Type:: dict

r_beam

Beam radius in m. If set, values outside of the beam will be set to NaN.

Type:: float or None

zern_order

Ordering scheme for the Zernike polynomials.

Type:: ZernikeOrder or str

zern_norm

Normalization scheme for the Zernike polynomials.

Type:: ZernikeNorm, str or None

get_value(pos: ndarray) → ndarray

Get the wavefront at a position.

Parameters:: pos (n x 3 array) – array of position vectors (x, y, z) where the wavefront is probed
Returns:: wf – The value of the wavefront at the positions
Return type:: nd array

plot(ax: Axes | None = None, cmap: str | Colormap = 'RdBu', levels: int = 100, **kwargs) → tuple[Figure, Axes]

Plot the wavefront data.

Parameters:

ax (Axis , optional) – If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
cmap (str or Colormap) – Colormap for the plot
level (int) – Number of levels for the contour plot
**kwargs – Additional keyword arguments for the plot function

Returns:

fig, ax – The figure and axis of the plot

Return type:

tuple of plt.Figure and plt.Axes

plot_coeff(ax: Axes | None = None, **kwargs) → tuple[Figure, Axes]

Plot the coefficients as a bar chart.

Parameters:: ax (Axis , optional) – If axis is provided, they will be used for the plot. if not provided, a new plot will automatically be created.
Returns:: fig, ax – The figure and axis of the plot
Return type:: tuple of plt.Figure and plt.Axes

class aisim.beam.Wavevectors(k1=8055366, k2=-8055366)

Bases: object

Class that defines the wave vectors of the two Ramen beams.

Parameters:

k1 (float) – 1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m, defaults to 2*pi/780e-9
k2 (float) – 1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m, defaults to 2*pi/780e-9

k1, k2

1D wave vectors (wavenumber) in z-direction of the two Raman beams in rad/m

Type:: float

doppler_shift(atoms)

Calculate the Doppler shifts for an atomic ensemble.

Parameters:: atoms (AtomicEnsemble) – an atomic enemble with a finite velocity in the z direction
Returns:: dopler_shift – Doppler shift of each atom in the ensemble in rad/s
Return type:: ndarray

aisim.beam.gen_wavefront(r_wf: float, std: float = 0.0, r_beam: float | None = None, n_zern: int = 36, zern_order: ZernikeOrder = ZernikeOrder.NOLL, zern_norm: ZernikeNorm | None = None, seed: int | None = None) → Wavefront

Create an artificial wavefront.

Parameters:

r_wf (float) – radius of the wavefront data in m
std (float) – standard deviation of each Zernike polynomial coefficient in multiples of the wavelength.
r_beam (float, optional) – Beam radius in m. Can be set if the beam is smaller than the wavefront data. Values outside of the beam will be set to NaN.
n_zern (int) – number of Zernike polynomials to be used
zern_order (ZernikeOrder or str) – Ordering scheme for the Zernike polynomials. See ZernikeOrder for possible values.
zern_norm (ZernikeNorm, str or None) – Normalization scheme for the Zernike polynomials. See ZernikeNorm for possible values.
seed (int, optional) – seed for the random number generator

Returns:

wf – artificial wavefront

Return type:

Wavefront

aisim.convert module

Functions to convert various quantities.

aisim.convert.arrival_time(z, t0=0.0, z0=0.0, v0=0.0, g=9.80665)

Calculate time when the atomic ensemble reaches a certaini position.

Parameters:

z (float) – position in m
t0 (float) – time reference in s (at which z0 and v0 are known)
z0 (float) – initial position and velocity (in m and m/s, respectively), i.e. position and velocity at t_ref
v0 (float) – initial position and velocity (in m and m/s, respectively), i.e. position and velocity at t_ref
g (float) – gravitational acceleration in m/s**2

Returns:

t – The two times when atoms reach the position z in seconds.

Return type:

list of float

aisim.convert.cart2pol(cart)

Convert vectors in cartesian coordinates to polar coordinates.

Parameters:: cart (n × 3 array) – array of n vectors in cartesian coordinates (x, y, z)
Returns:: pol – array of n vectors in polar coordinates (rho, theta, z)
Return type:: n × 3 array

aisim.convert.kb = 1.3806488e-23: Boltzmann constant in J/K.

aisim.convert.mass = {'Rb87': 1.443161e-25}: Atomic mass in kg.

aisim.convert.phase_error_to_grav(phase, T, keff)

Convert a phase error to gravitational acceleration.

Takes the phase shift measured in a Mach Zehnder atom interferometer and converts it to the corresponding gravitional accleration.

Parameters:

phase (float) – Interferometer phase in rad
T (float) – interferometer time in s
keff (float) – effective wavenumber in rad/m

Returns:

gravitational acceleration in in m/s^2

Return type:

float

aisim.convert.pol2cart(pol)

Convert vectors in polar coordinates to cartesian coordinates.

Parameters:: pol (n × 3 array) – array of n vectors in polar coordinates (rho, theta, z)
Returns:: cart – array of n vectors in cartesian coordinates (x, y, z)
Return type:: n × 3 array

aisim.convert.temp(sigma_v, species='Rb87')

Calculate the temperature of an atomic cloud from its velocity spread.

Parameters:

sigma_v (float) – velocity spread (1 sigma) in meters per second
species (str) – the atomic species, has to be a key in mass

Returns:

temp – temperature of the cloud in Kelvin

Return type:

float

Raises:

ValueError – If negative velocity spread is passed

aisim.convert.vel_from_temp(temp, species='Rb87')

Calculate the velocity spread (1 sigma) from the temperature of the cloud.

Parameters:

temp (float) – temperature of the cloud in Kelvin
species (str) – the atomic species, has to be a key in mass

Returns:

vel – velocity spread (1 sigma)

Return type:

float

Raises:

ValueError – If negative temperature is passed

aisim.det module

Classes and functions related to the detection system.

class aisim.det.Detector(t_det, **kwargs)

Bases: object

A generic detection zone.

This is only a template without functionality. Deriving classes have to implement _detected_idx.

Parameters:

t_det (float) – time of the detection
**kwargs – Additional arguments used by classes that inherit from this class. All keyworded arguments are stored as attribues.

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

detected_atoms(atoms)

Determine wheter a position is within the detection zone.

Returns a new AtomicEnsemble object containing only the detected phase space vectors.

Parameters:: atoms (AtomicEnsemble) – the atomic ensemble
Returns:: detected_atoms – atomic ensemble containing only phase space vectors that are eventually detected
Return type:: AtomicEnsemble

class aisim.det.PolarDetector(t_det, **kwargs)

Bases: Detector

A spherical detection zone.

All atoms within a circle with the specified radius within the x-y plane will be detected.

Parameters:

t_det (float) – time of the detection
r_det – radius of the spherical detection zone

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

class aisim.det.SphericalDetector(t_det, **kwargs)

Bases: Detector

A spherical detection zone.

All atoms within a sphere of the specified radius will be detected.

Parameters:

t_det (float) – time of the detection
r_det – radius of the spherical detection zone

t_det

time of the detection

Type:: float

\*\* kwargs: all keyworded arguments that are passed upon creation

aisim.prop module

Classes to propagate atomic ensembles.

class aisim.prop.FreePropagator(time_delta, **kwargs)

Bases: Propagator

Propagator implementing free propagation without light-matter interaction.

Parameters:: time_delta (float) – time that should be propagated

class aisim.prop.Propagator(time_delta, **kwargs)

Bases: object

A generic propagator.

This is just a template class without an implemented propagation matrix.

Parameters:

time_delta (float) – time that should be propagated
**kwargs – Additional arguments used by classes that inherit from this class. All keyworded arguments are stored as attribues.

propagate(atoms)

Propagate an atomic ensemble.

Parameters:: atoms (AtomicEnsemble) – atomic ensemble that should be is propagated

class aisim.prop.SpatialSuperpositionTransitionPropagator(time_delta, intensity_profile, n_pulses, n_pulse, wave_vectors=None, wf=None, phase_scan=0)

Bases: TwoLevelTransitionPropagator

An effective Raman two-level system.

It is implemented as a time propagator as defined in [1]. In addition to class TwoLevelTransitionPropagator, this adds spatial superpositions in z-direction that occour at each pulse.

Parameters:

time_delta (float) – length of pulse
intensity_profile (IntensityProfile) – Intensity profile of the interferometry lasers
wave_vectors (Wavevectors) – wave vectors of the two Raman beams for calculation of Doppler shifts
wf (Wavefront , optional) – wavefront aberrations of the interferometry beam
phase_scan (float) – effective phase for fringe scans
n_pulses (int) – overall number of intended light pulses in symmetric atom interferometry sequence. Each pulse adds two spatial eigenstates.
n_pulse (int) – number of light pulse of symmetric atom-interferometry sequence.

References

[1] Young, B. C., Kasevich, M., & Chu, S. (1997). Precision atom interferometry with light pulses. In P. R. Berman (Ed.), Atom Interferometry (pp. 363–406). Academic Press. https://doi.org/10.1016/B978-012092460-8/50010-2

class aisim.prop.TwoLevelTransitionPropagator(time_delta, intensity_profile, wave_vectors=None, wf=None, phase_scan=0)

Bases: Propagator

A time propagator of an effective Raman two-level system.

Parameters:

time_delta (float) – length of pulse
intensity_profile (IntensityProfile) – Intensity profile of the interferometry lasers
wave_vectors (Wavevectors) – wave vectors of the two Raman beams for calculation of Doppler shifts
wf (Wavefront , optional) – wavefront aberrations of the interferometry beam
phase_scan (float) – effective phase for fringe scans

Notes

The propagator is for example defined in [1].

References

[1] Young, B. C., Kasevich, M., & Chu, S. (1997). Precision atom interferometry with light pulses. In P. R. Berman (Ed.), Atom Interferometry (pp. 363–406). Academic Press. https://doi.org/10.1016/B978-012092460-8/50010-2