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.

# A spin in a classical coherent state needs only two parameters,
# theta, phi to define its orientation.
classical_spin = CoherentSpin(theta=np.pi / 2, phi=0)
assert classical_spin.theta == np.pi / 2
assert classical_spin.phi == 0

# These angles define the Cartesian coordinates of the spin vector.
assert np.sin(classical_spin.theta) * np.cos(classical_spin.phi) == classical_spin.x
assert np.sin(classical_spin.theta) * np.sin(classical_spin.phi) == classical_spin.y
assert np.cos(classical_spin.theta) == classical_spin.z

# We can also build a coherent spin from a list of (x,y,z) components.
classical_spin_from_cartesian = CoherentSpin.from_cartesian(
    classical_spin.x.item(), classical_spin.y.item(), classical_spin.z.item()
)
assert classical_spin_from_cartesian.theta == classical_spin.theta
assert classical_spin_from_cartesian.phi == classical_spin.phi
assert classical_spin_from_cartesian == classical_spin

# To represent a general spin, we need to store a list of majhorana spin components.
# We can convert between a coherent spin and a majorana spin representation
# using the as_generic method.
# Here, n_stars sets the number of majorana spins in the representation
n_stars = 5
generic_spin = classical_spin.as_generic(n_stars=n_stars)

# We can also use a momentum state representation to analyze spin states
# For spin 1/2, state[0] represents the spin up component and
# state[1] represents the spin down component.
momentum_state = generic_spin.momentum_states
assert momentum_state.shape == (n_stars + 1,)
# We can also build up a generic spin directly from the momentum components
generic_from_momentum = Spin.from_momentum_state(momentum_state)
np.testing.assert_allclose(
    generic_from_momentum.momentum_states, generic_spin.momentum_states
)

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.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(*, spin: GenericSpin, displacement: ParticleDisplacement = <factory>, parallel_velocity: float, gyromagnetic_ratio: float = -204000000.0)#

Bases: object

Represents the state of a particle in the simulation.

as_coherent() → list[CoherentParticleState]#: Convert to a CoherentParticleState.

displacement: ParticleDisplacement#

gyromagnetic_ratio: float = -204000000.0#

parallel_velocity: float#

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.Trajectory(*, spins: GenericSpinList, displacement: ParticleDisplacement, parallel_velocity: float)#

Bases: Sequence[Any]

A trajectory of a particle through the simulation.

displacement: ParticleDisplacement#

static from_states(states: Iterable[ParticleState]) → Trajectory#: Create a Trajectory from a list of ParticleStates.

parallel_velocity: float#

spins: GenericSpinList#

class spinecho_sim.state.TrajectoryList(*, spins: Spin[tuple[int, int, int]], displacements: ParticleDisplacementList, parallel_velocities: ndarray[Any, dtype[floating]])#

Bases: Sequence[Trajectory]

A list of trajectories.

displacements: ParticleDisplacementList#

static from_trajectories(trajectories: Iterable[Trajectory]) → TrajectoryList#: Create a TrajectoryList from a list of Trajectories.

parallel_velocities: ndarray[Any, dtype[floating]]#

spins: Spin[tuple[int, int, int]]#

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.

spinecho_sim.state package#

This Page