spinecho_sim.state package#

Module for representing and manipulating spin states.

In this package, spin states are represented by the Spin class, which encapsulates the properties of a spin. An example of its useage can be seen below.

 8# A spin in a classical coherent state needs only two parameters,
 9# theta, phi to define its orientation.
10classical_spin = CoherentSpin(theta=np.pi / 2, phi=0)
11assert classical_spin.theta == np.pi / 2
12assert classical_spin.phi == 0
13
14# These angles define the Cartesian coordinates of the spin vector.
15assert np.sin(classical_spin.theta) * np.cos(classical_spin.phi) == classical_spin.x
16assert np.sin(classical_spin.theta) * np.sin(classical_spin.phi) == classical_spin.y
17assert np.cos(classical_spin.theta) == classical_spin.z
18
19# We can also build a coherent spin from a list of (x,y,z) components.
20classical_spin_from_cartesian = CoherentSpin.from_cartesian(
21    classical_spin.x.item(), classical_spin.y.item(), classical_spin.z.item()
22)
23assert classical_spin_from_cartesian.theta == classical_spin.theta
24assert classical_spin_from_cartesian.phi == classical_spin.phi
25assert classical_spin_from_cartesian == classical_spin
26
27# To represent a general spin, we need to store a list of majhorana spin components.
28# We can convert between a coherent spin and a majorana spin representation
29# using the as_generic method.
30# Here, n_stars sets the number of majorana spins in the representation
31n_stars = 5
32generic_spin = classical_spin.as_generic(n_stars=n_stars)
33
34# We can also use a momentum state representation to analyze spin states
35# For spin 1/2, state[0] represents the spin up component and
36# state[1] represents the spin down component.
37momentum_state = generic_spin.momentum_states
38assert momentum_state.shape == (n_stars + 1,)
39# We can also build up a generic spin directly from the momentum components
40generic_from_momentum = Spin.from_momentum_state(momentum_state)
41np.testing.assert_allclose(
42    generic_from_momentum.momentum_states, generic_spin.momentum_states
43)
class spinecho_sim.state.CoherentSpin(theta: float, phi: float)#

Bases: Spin[tuple[()]]

A class representing a single coherent spin with theta and phi angles.

as_generic(*, n_stars: int = 1) → GenericSpin#

Return a generic Spin representation of this coherent spin.

static from_cartesian(x: float, y: float, z: float) → CoherentSpin#

Create a Spin from Cartesian coordinates.

property phi: ndarray[tuple[()], dtype[floating]]#

Return the phi angle of the spin.

property shape: tuple[()]#

Return the shape of a single coherent spin.

property theta: ndarray[tuple[()], dtype[floating]]#

Return the theta angle of the spin.

class spinecho_sim.state.EmptySpin#

Bases: Spin[tuple[int]]

Represents the absence of rotational angular momentum with zero Majorana stars.

flat_iter() → Iterator[CoherentSpin]#

Return an empty iterator since there are no Majorana stars.

property n_stars: int#

Override the number of Majorana stars to return zero.

class spinecho_sim.state.EmptySpinList(shape: tuple[int, int])#

Bases: Spin[tuple[int, int]]

Represents a list of empty spins with zero Majorana stars.

flat_iter() → Iterator[CoherentSpin]#

Return an iterator over all empty spins.

property n_stars: int#

Override the number of Majorana stars to return zero.

class spinecho_sim.state.EmptySpinListList(shape: tuple[int, int, int])#

Bases: Spin[tuple[int, int, int]]

Represents the absence of rotational angular momentum with zero Majorana stars in a 3D structure.

flat_iter() → Iterator[CoherentSpin]#

Return an iterator over all empty spins.

property n_stars: int#

Override the number of Majorana stars to return zero.

class spinecho_sim.state.MonatomicParticleState(*, displacement: 'ParticleDisplacement' = <factory>, parallel_velocity: 'float', _spin_angular_momentum: 'GenericSpin', coefficients: 'tuple[float, float, float, float]' = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185), gyromagnetic_ratio: 'float' = -204000000.0)#

Bases: ParticleState

as_coherent() → Sequence[CoherentMonatomicParticleState]#
displacement: ParticleDisplacement#
gyromagnetic_ratio: float = -204000000.0#
parallel_velocity: float#
property rotational_angular_momentum: GenericSpin#
property spin: GenericSpin#
class spinecho_sim.state.MonatomicTrajectory(*, _spin_angular_momentum: 'GenericSpinList', displacement: 'ParticleDisplacement', parallel_velocity: 'float', coefficients: 'tuple[float, float, float, float]' = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: Trajectory

static from_monatomic_states(states: Iterable[MonatomicParticleState]) → MonatomicTrajectory#

Create a Trajectory from a list of ParticleStates.

property rotational_angular_momentum: GenericSpinList#
class spinecho_sim.state.MonatomicTrajectoryList(*, _spin_angular_momentum: Spin[tuple[int, int, int]], displacements: ParticleDisplacementList, parallel_velocities: ndarray[Any, dtype[floating]], coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: TrajectoryList

A list of monatomic trajectories.

static from_monatomic_trajectories(trajectories: Iterable[MonatomicTrajectory]) → MonatomicTrajectoryList#

Create a MonatomicTrajectoryList from a list of MonatomicTrajectories.

property rotational_angular_momentum: Spin[tuple[int, int, int]]#
class spinecho_sim.state.ParticleDisplacement(*, r: float = 0, theta: float = 0)#

Bases: object

Represents the displacement of a particle in the simulation.

This defines the displacement in the x-y plane, perpendicular to the particle’s velocity. The displacement is stored in polar coordinates (r, theta), where: - r is the radial distance from the origin (0, 0) in the x-y plane. - theta is the angle from the positive x-axis in the x-y plane.

static from_cartesian(x: float, y: float) → ParticleDisplacement#

Create a ParticleDisplacement from Cartesian coordinates.

r: float = 0#
theta: float = 0#
property x: float#

Get the x-coordinate of the displacement.

property y: float#

Get the y-coordinate of the displacement.

class spinecho_sim.state.ParticleDisplacementList(*, r: ndarray[Any, dtype[floating]], theta: ndarray[Any, dtype[floating]])#

Bases: Sequence[ParticleDisplacement]

A list of particle displacements.

static from_displacements(displacements: Iterable[ParticleDisplacement]) → ParticleDisplacementList#

Create a ParticleDisplacementList from a list of ParticleDisplacements.

r: ndarray[Any, dtype[floating]]#
property shape: tuple[int, ...]#

Get the shape of the displacement list.

theta: ndarray[Any, dtype[floating]]#
property x: ndarray[Any, dtype[floating]]#

Get the x-displacement of the particles.

property y: ndarray[Any, dtype[floating]]#

Get the y-displacement of the particles.

class spinecho_sim.state.ParticleState(*, displacement: ParticleDisplacement = <factory>, parallel_velocity: float, _spin_angular_momentum: GenericSpin, _rotational_angular_momentum: GenericSpin, coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: object

State of a diatomic particle.

coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185)#
displacement: ParticleDisplacement#
parallel_velocity: float#
property rotational_angular_momentum: GenericSpin#
property spin: GenericSpin#
class spinecho_sim.state.Spin(spins: ndarray[tuple[Unpack[S_], int], dtype[float64]])#

Bases: Sequence[Any], Generic

A class representing a collection of lists of CoherentSpin objects.

property cartesian: np.ndarray[tuple[int, *S], np.dtype[np.floating]]#

Get the Cartesian coordinates of the spin vector.

flat_iter() → Iterator[CoherentSpin]#

Iterate over all CoherentSpin objects in a flat manner.

static from_iter(spins: Iterable[Spin[S_]]) → Spin[tuple[int, *S_]]#

Create a Spin from a nested list of CoherentSpin objects.

static from_momentum_state(spin_coefficients: ndarray[tuple[int], dtype[complex128]]) → Spin[tuple[int]]#

Create a Spin from a series of momentum states represented by complex coefficients.

This function takes a list of spin coefficients `python spin_coefficients[i,j] ` where i is the state index and j is the list index.

item(index: int) → CoherentSpin#

Iterate over all CoherentSpin objects.

property momentum_states: ndarray[tuple[int, Unpack[S_]], dtype[complex128]]#

Convert the spin representation to a momentum state.

property n_stars: int#

Return the number of components in each spin momentum state (e.g., 2J+1 for spin-J).

property ndim: int#

Return the number of dimensions of the spins array.

property phi: np.ndarray[tuple[*S,], np.dtype[np.floating]]#

Return the phi angle of the spin.

property shape: tuple[*S,]#

Return the shape of the spin list.

property size: int#

Return the total number of spins.

property theta: np.ndarray[tuple[*S,], np.dtype[np.floating]]#

Return the theta angle of the spin.

property x: np.ndarray[tuple[*S,], np.dtype[np.floating]]#

Get the x-component of the spin vector.

property y: np.ndarray[tuple[*S,], np.dtype[np.floating]]#

Get the y-component of the spin vector.

property z: np.ndarray[tuple[*S,], np.dtype[np.floating]]#

Get the z-component of the spin vector.

class spinecho_sim.state.StateVectorParticleState(state_vector: ndarray[tuple[int], dtype[complex128]], hilbert_space_dims: tuple[int, int], displacement: ParticleDisplacement, parallel_velocity: float, coefficients: tuple[float, float, float, float])#

Bases: ParticleState

Particle state that directly uses state vector arrays instead of Spin classes.

static from_spin_state(state: ParticleState) → StateVectorParticleState#

Create a StateVectorParticleState from a traditional ParticleState.

hilbert_space_dims: tuple[int, int]#
property rotational_angular_momentum: GenericSpin#
property spin: GenericSpin#
state_vector: np.ndarray[tuple[int], np.dtype[np.complex128]]#
class spinecho_sim.state.StateVectorTrajectory(state_vectors: np.ndarray[tuple[int, int], np.dtype[np.complex128]], hilbert_space_dims: tuple[int, int], displacement: ParticleDisplacement, parallel_velocity: float, coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: Trajectory

A trajectory that uses state vector representation instead of Spin classes.

static from_state_vector_states(states: Iterable[StateVectorParticleState]) → StateVectorTrajectory#

Create a StateVectorTrajectory from a list of StateVectorParticleStates.

static from_trajectory(trajectory: Trajectory, hilbert_space_dims: tuple[int, int]) → StateVectorTrajectory#

Convert a regular Trajectory to a StateVectorTrajectory.

hilbert_space_dims: tuple[int, int]#
property rotational_angular_momentum: Spin[tuple[int, int]]#

The rotational angular momentum is not directly accessible in state vector representation.

property spin: Spin[tuple[int, int]]#

The spin components are not directly accessible in state vector representation.

state_vectors: np.ndarray[tuple[int, int], np.dtype[np.complex128]]#
class spinecho_sim.state.StateVectorTrajectoryList(state_vectors: ndarray, hilbert_space_dims: tuple[int, int], displacements: ParticleDisplacementList, parallel_velocities: ndarray, coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: TrajectoryList

A list of state vector trajectories.

static from_state_vector_trajectories(trajectories: Iterable[StateVectorTrajectory]) → StateVectorTrajectoryList#

Create a StateVectorTrajectoryList from a list of StateVectorTrajectories.

hilbert_space_dims: tuple[int, int]#
property rotational_angular_momentum: Spin[tuple[int, int, int]]#
property spin: Spin[tuple[int, int, int]]#
state_vectors: ndarray[tuple[int, int, int], dtype[complex128]]#
class spinecho_sim.state.Trajectory(*, _spin_angular_momentum: GenericSpinList, _rotational_angular_momentum: GenericSpinList, displacement: ParticleDisplacement, parallel_velocity: float, coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: Sequence[Any]

A trajectory of a diatomic particle through the simulation.

coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185)#
displacement: ParticleDisplacement#
static from_states(states: Iterable[ParticleState]) → Trajectory#

Create a Trajectory from a list of ParticleStates.

parallel_velocity: float#
property rotational_angular_momentum: GenericSpinList#
property spin: GenericSpinList#
class spinecho_sim.state.TrajectoryList(*, _spin_angular_momentum: Spin[tuple[int, int, int]], _rotational_angular_momentum: Spin[tuple[int, int, int]], displacements: ParticleDisplacementList, parallel_velocities: ndarray[Any, dtype[floating]], coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185))#

Bases: Sequence[Trajectory]

A list of diatomic trajectories.

coefficients: tuple[float, float, float, float] = (267538030.37970677, 41919527.413910046, 715026.4879570369, 362414.1285181185)#
displacements: ParticleDisplacementList#
static from_trajectories(trajectories: Iterable[Trajectory]) → TrajectoryList#

Create a DiatomicTrajectoryList from a list of DiatomicTrajectories.

parallel_velocities: ndarray[Any, dtype[floating]]#
property rotational_angular_momentum: Spin[tuple[int, int, int]]#
property spin: Spin[tuple[int, int, int]]#
spinecho_sim.state.get_bargmann_expectation_values(spins: Spin[tuple[Unpack[S_], int]]) → ndarray[tuple[Literal[3], Unpack[S_]], dtype[floating]]#

Get the expectation values of the spin.

Returns an array of shape (3, *spins.shape) where the first dimension corresponds to the expectation values for S_x, S_y, and S_z.

spinecho_sim.state.get_expectation_values(spins: Spin[tuple[Unpack[S_], int]]) → ndarray[tuple[Literal[3], Unpack[S_]], dtype[floating]]#

Get the expectation values of the spin.

Returns an array of shape (3, *spins.shape) where the first dimension corresponds to the expectation values for S_x, S_y, and S_z.

spinecho_sim.state.sample_gaussian_velocities(n: int, average_velocity: float, std_velocity: float) → ndarray[Any, dtype[floating]]#

Sample N velocities from a Gaussian distribution.

spinecho_sim.state.sample_uniform_displacement(n: int, r_max: float) → ParticleDisplacementList#

Sample N random radii uniformly distributed over a disk of radius r_max.

On this page

This Page