Main functionality

Main functionality#

This module provides user friendly wrapper functions of the Spinguin’s core functionality by making use of the SpinSystem class.

class SpinSystem(isotopes: list | tuple | ndarray | str)[source]#

Initializes a spin system with the given isotopes. Examples:

spin_system = SpinSystem(['1H', '15N', '19F'])
spin_system = SpinSystem("/path/to/isotopes.txt")

Parameters:

isotopes (list or tuple or ndarray or str) –

Specifies the isotopes that constitute the spin system and determine other properties, such as spin quantum numbers and gyromagnetic ratios.

Two input types are supported:

If ArrayLike: A 1D array of size N containing isotope names as strings.
If str: Path to the file containing the isotopes.

The input will be converted and stored as a NumPy array.

property basis: Basis#: Contains the basis set for the SpinSystem. Includes functionality for restricting the maximum spin order, building the basis set, and applying more advanced truncation to the basis set.

property gammas: ndarray#: Gyromagnetic ratios of each isotope in the SpinSystem in rad/s/T.

property isotopes: ndarray#

Specifies the isotopes that constitute the spin system and determine other properties, such as spin quantum numbers and gyromagnetic ratios. Example:

np.array(['1H', '15N', '19F'])

Isotopes are set during the initialization of the spin system.

property mults: ndarray#: Spin multiplicities for each isotope in the SpinSystem.

property nspins: int#: Number of spins in the spin system.

property quad: ndarray#: Returns the quadrupolar moments in m^2.

property relaxation: RelaxationProperties#: Contains the properties that define the relaxation of the SpinSystem. Allows the definition of relaxation theory, correlation time, relaxation times, etc.

property spins: ndarray#: Spin quantum numbers for each isotope the spin system.

alpha_state(spin_system: SpinSystem, index: int) → ndarray | csc_array[source]#

Generates the alpha state for a given spin-1/2 nucleus. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the alpha state is created.
index (int) – Index of the spin that has the alpha state.

Returns:

rho – State vector corresponding to the alpha state of the given spin index.

Return type:

ndarray or csc_array

Combines two state vectors when spin systems associate in a chemical reaction A + B -> C.

Example. We have spin system A that has two spins and spin system B that has three spins. These systems associate to form a composite spin system C that has five spins that are indexed (0, 1, 2, 3, 4). Of these, spins (0, 2) are from subsystem A and (1, 3, 4) from subsystem B. We have to choose how the spin systems A and B will be indexed in spin system C by defining the spin maps as follows:

spin_map_A = np.ndarray([0, 2])
spin_map_B = np.ndarray([1, 3, 4])

Parameters:

spin_system_A (SpinSystem) – Spin system A.
spin_system_B (SpinSystem) – Spin system B.
spin_system_C (SpinSystem) – Spin system C.
rho_A (ndarray or csc_array) – State vector of spin system A.
rho_B (ndarray or csc_array) – State vector of spin system B.
spin_map_A (list or tuple or ndarray) – Indices of spin system A within spin system C.
spin_map_B (list or tuple or ndarray) – Indices of spin system B within spin system C.

Returns:

rho_C – State vector of the composite spin system C.

Return type:

ndarray or csc_array

beta_state(spin_system: SpinSystem, index: int) → ndarray | csc_array[source]#

Generates the beta state for a given spin-1/2 nucleus. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the beta state is created.
index (int) – Index of the spin that has the beta state.

Returns:

rho – State vector corresponding to the beta state of the given spin index.

Return type:

ndarray or csc_array

Dissociates the density vector of composite system C into density vectors of two subsystems A and B in a chemical reaction C -> A + B.

Example. Spin system C has five spins, which are indexed as (0, 1, 2, 3, 4). We want to dissociate this into two subsystems A and B. Spins 0 and 2 should go to subsystem A and the rest to subsystem B. In this case, we define the following spin maps:

spin_map_A = np.array([0, 2])
spin_map_B = np.array([1, 3, 4])

Parameters:

spin_system_A (SpinSystem) – Spin system A.
spin_system_B (SpinSystem) – Spin system B.
spin_system_C (SpinSystem) – Spin system C.
rho_C (ndarray or csc_array) – State vector of the composite spin system C.
spin_map_A (list or tuple or ndarray) – Indices of spin system A within spin system C.
spin_map_B (list or tuple or ndarray) – Indices of spin system B within spin system C.

Returns:

rho_A (ndarray or csc_array) – State vector of spin system A.
rho_B (ndarray or csc_array) – State vector of spin system B.

equilibrium_state(spin_system: SpinSystem) → ndarray | csc_array[source]#

Creates the thermal equilibrium state for the spin system.

Parameters:: spin_system (SpinSystem) – Spin system for which the equilibrium state is going to be created.
Returns:: rho – Equilibrium state vector.
Return type:: ndarray or csc_array

frequency_to_chemical_shift(frequency: float | ndarray, reference_frequency: float, spectrometer_frequency: float) → float | ndarray[source]#

Converts a frequency (or an array of frequencies, e.g., a frequency axis) to a chemical shift value based on the reference frequency and the spectrometer frequency.

Parameters:

frequency (float or ndarray) – Frequency (or array of frequencies) to convert [in Hz].
reference_frequency (float) – Reference frequency for the conversion [in Hz].
spectrometer_frequency (float) – Spectrometer frequency for the conversion [in Hz].

Returns:

chemical_shift – Converted chemical shift value (or array of values).

Return type:

float or ndarray

hamiltonian(spin_system: SpinSystem, interactions: list[Literal['zeeman', 'chemical_shift', 'J_coupling']] = ['zeeman', 'chemical_shift', 'J_coupling'], side: Literal['comm', 'left', 'right'] = 'comm') → ndarray | csc_array[source]#

Creates the requested Hamiltonian superoperator for the spin system.

Parameters:

spin_system (SpinSystem) – Spin system for which the Hamiltonian is going to be generated.
interactions (list, default=["zeeman", "chemical_shift", "J_coupling"]) –
Specifies which interactions are taken into account. The options are:
- ’zeeman’ – Zeeman interaction
- ’chemical_shift’ – Isotropic chemical shift
- ’J_coupling’ – Scalar J-coupling
side ({'comm', 'left', 'right'}) –
The type of superoperator:
- ’comm’ – commutation superoperator (default)
- ’left’ – left superoperator
- ’right’ – right superoperator

Returns:

H – Hamiltonian superoperator.

Return type:

ndarray or csc_array

inversion_recovery(spin_system: SpinSystem, isotope: str, npoints: int, time_step: float) → tuple[ndarray, ndarray][source]#

Performs the inversion-recovery experiment. The experiment differs slightly from the actual inversion-recovery experiments performed on spectrometers. In this experiment, the inversion is performed only once, and the magnetization is detected at each step during the recovery (much faster).

If the traditional inversion recovery is desired, use the function inversion_recovery_fid().

This experiment requires the following spin system properties to be defined:

spin_system.basis : must be built
spin_system.relaxation.theory
spin_system.relaxation.thermalization : must be True

This experiment requires the following parameters to be defined:

parameters.magnetic_field : magnetic field of the spectrometer in Tesla
parameters.temperature : temperature of the sample in Kelvin

Parameters:

spin_system (SpinSystem) – Spin system to which the inversion-recovery experiment is performed.
isotope (str) – Specifies the isotope, for example “1H”, whose magnetization is inverted and detected. This function applies hard pulses.
npoints (int) – Number of points in the simulation. Defines the total simulation time together with time_step.
time_step (float) – Time step in the simulation (in seconds). Should be kept relatively short (e.g. 1 ms).

Returns:

magnetizations – Two-dimensional array of size (nspins, npoints) containing the observed z-magnetizations for each spin at various times.

Return type:

ndarray

liouvillian(H: ndarray | csc_array = None, R: ndarray | csc_array = None, K: ndarray | csc_array = None) → ndarray | csc_array#

Constructs the Liouvillian superoperator from the Hamiltonian, relaxation superoperator, and exchange superoperator.

Parameters:

H (ndarray or csc_array) – Hamiltonian superoperator.
R (ndarray or csc_array) – Relaxation superoperator
K (ndarray or csc_array) – Exchange superoperator.

Returns:

L – Liouvillian superoperator.

Return type:

ndarray or csc_array

measure(spin_system: SpinSystem, rho: ndarray | csc_array, operator: str) → complex[source]#

Computes the expectation value of the specified operator for a given state vector. Assumes that the state vector rho represents a trace-normalized density matrix.

Parameters:

spin_system (SpinSystem) – Spin system whose state is going to be measured.
rho (ndarray or csc_array) – State vector that describes the density matrix.
operator (str) –
Defines the operator to be measured. The operator string must follow the rules below:
- Cartesian and ladder operators: I(component,index) or I(component). Examples:
  - I(x,4) –> Creates x-operator for spin at index 4.
  - I(x) –> Creates x-operator for all spins.
- Spherical tensor operators: T(l,q,index) or T(l,q). Examples:
  - T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.
  - T(1, -1) –> Creates operator with l=1, q=-1 for all spins.
- Product operators have * in between the single-spin operators: I(z,0) * I(z,1)
- Sums of operators have + in between the operators: I(x,0) + I(x,1)
- Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)
Special case: An empty operator string is considered as unit operator.

Whitespace will be ignored in the input.

NOTE: Indexing starts from 0!

Returns:

ex – Expectation value.

Return type:

complex

operator(spin_system: SpinSystem, operator: str) → ndarray | csc_array[source]#

Generates an operator for the spin_system in Hilbert space from the user-specified operator string.

Parameters:

spin_system (SpinSystem) – Spin system for which the operator is going to be generated.
operator (str) –
Defines the operator to be generated. The operator string must follow the rules below:
- Cartesian and ladder operators: I(component,index) or I(component). Examples:
  - I(x,4) –> Creates x-operator for spin at index 4.
  - I(x)–> Creates x-operator for all spins.
- Spherical tensor operators: T(l,q,index) or T(l,q). Examples:
  - T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.
  - T(1, -1) –> Creates operator with l=1, q=-1 for all spins.
- Product operators have * in between the single-spin operators: I(z,0) * I(z,1)
- Sums of operators have + in between the operators: I(x,0) + I(x,1)
- Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)
Special case: An empty operator string is considered as unit operator.

Whitespace will be ignored in the input.

NOTE: Indexing starts from 0!

Returns:

op – An array representing the requested operator.

Return type:

ndarray or csc_array

permute_spins(spin_system: SpinSystem, rho: ndarray | csc_array, spin_map: list | tuple | ndarray) → ndarray | csc_array[source]#

Permutes the state vector of a spin system to correspond to a reordering of the spins in the system.

Example. Our spin system has three spins, which are indexed (0, 1, 2). We want to perform the following permulation:

0 –> 2 (Spin 0 goes to position 2)
1 –> 0 (Spin 1 goes to position 0)
2 –> 1 (Spin 2 goes to position 1)

In this case, we want to assign the following map:

spin_map = np.array([2, 0, 1])

Parameters:

spin_system (SpinSystem) – The spin system whose density vector is going to be permuted.
rho (ndarray or csc_array) – State vector of the spin system.
spin_map (list or tuple or ndarray) – Indices of the spins in the spin system after permutation.

Returns:

rho – Permuted state vector of the spin system.

Return type:

ndarray or csc_array

propagator(L: ndarray | csc_array, t: float) → ndarray | csc_array[source]#

Constructs the time propagator exp(L*t).

Parameters:

L (csc_array) – Liouvillian superoperator, L = -iH - R + K.
t (float) – Time step of the simulation in seconds.

Returns:

expm_Lt – Time propagator exp(L*t).

Return type:

csc_array or ndarray

propagator_to_rotframe(spin_system: SpinSystem, P: ndarray | csc_array, t: float, center_frequencies: dict = None) → ndarray | csc_array[source]#

Transforms the time propagator to the rotating frame.

Parameters:

spin_system (SpinSystem) – Spin system whose time propagator is going to be transformed.
P (ndarray or csc_array) – Time propagator in the laboratory frame.
t (float) – Time step of the simulation in seconds.
center_frequencies (dict) – Dictionary that describes the center frequencies for each isotope in the units of ppm.

Returns:

P_rot – The time propagator transformed into the rotating frame.

Return type:

ndarray or csc_array

pulse(spin_system: SpinSystem, operator: str, angle: float) → ndarray | csc_array[source]#

Creates a pulse superoperator that is applied to a state by multiplying from the left.

Parameters:

spin_system (SpinSystem) – Spin system for which the pulse superoperator is going to be created.
operator (str) –
Defines the pulse to be generated. The operator string must follow the rules below:
- Cartesian and ladder operators: I(component,index) or I(component). Examples:
  - I(x,4) –> Creates x-operator for spin at index 4.
  - I(x)–> Creates x-operator for all spins.
- Spherical tensor operators: T(l,q,index) or T(l,q). Examples:
  - T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.
  - T(1, -1) –> Creates operator with l=1, q=-1 for all spins.
- Product operators have * in between the single-spin operators: I(z,0) * I(z,1)
- Sums of operators have + in between the operators: I(x,0) + I(x,1)
- Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)
Special case: An empty operator string is considered as unit operator.

Whitespace will be ignored in the input.

NOTE: Indexing starts from 0!
angle (float) – Pulse angle in degrees.

Returns:

P – Pulse superoperator.

Return type:

ndarray or csc_array

pulse_and_acquire(spin_system: SpinSystem, isotope: str, center_frequency: float, npoints: int, dwell_time: float, angle: float) → ndarray[source]#

Simple pulse-and-acquire experiment.

This experiment requires the following spin system properties to be defined:

spin_system.basis : must be built
spin_system.relaxation.theory
spin_system.relaxation.thermalization : must be True

This experiment requires the following parameters to be defined:

parameters.magnetic_field : magnetic field of the spectrometer in Tesla
parameters.temperature : temperature of the sample in Kelvin

Parameters:: spin_system (SpinSystem) – Spin system to which the pulse-and-acquire experiment is performed.
Returns:: fid – Free induction decay signal.
Return type:: ndarray

relaxation(spin_system: SpinSystem) → ndarray | csc_array[source]#

Creates the relaxation superoperator using the requested relaxation theory.

Requires that the following spin system properties are set:

spin_system.relaxation.theory : must be specified
spin_system.basis : must be built

If phenomenological relaxation theory is requested, the following must be set:

spin_system.relaxation.T1
spin_system.relaxation.T2

If redfield relaxation theory is requested, the following must be set:

spin_system.relaxation.tau_c
parameters.magnetic_field

If sr2k is requested, the following must be set:

parameters.magnetic_field

If thermalization is requested, the following must be set:

parameters.magnetic_field
parameters.thermalization

Parameters:: spin_system (SpinSystem) – Spin system for which the relaxation superoperator is going to be generated.
Returns:: R – Relaxation superoperator.
Return type:: ndarray or csc_array

resonance_frequency(isotope: str, offset: float = 0, unit: Literal['Hz', 'rad/s'] = 'Hz') → float[source]#

Computes the resonance frequency of the given isotope at the specified magnetic field.

Parameters:

isotope (str) – Nucleus symbol (e.g. ‘1H’) used to select the gyromagnetic ratio required for the conversion.
offset (float, default=0) – Offset in ppm.
unit ({'Hz', 'rad/s'}) – Specifies in which units the frequency is returned.

Returns:

omega – Resonance frequency in the requested units.

Return type:

float

Notes

Required global parameters:

parameters.magnetic_field

singlet_state(spin_system: SpinSystem, index_1: int, index_2: int) → ndarray | csc_array[source]#

Generates the singlet state between two spin-1/2 nuclei. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the singlet state is created.
index_1 (int) – Index of the first spin in the singlet state.
index_2 (int) – Index of the second spin in the singlet state.

Returns:

rho – State vector corresponding to the singlet state.

Return type:

ndarray or csc_array

spectral_width_to_dwell_time(spectral_width: float, isotope: str) → float[source]#

Calculates the dwell time (in seconds) from the spectral width given in ppm.

Parameters:

spectral_width (float) – Spectral width in ppm.
isotope (str) – Nucleus symbol (e.g. ‘1H’) used to select the gyromagnetic ratio required for the conversion.

Returns:

dwell_time – Dwell time in seconds.

Return type:

float

Notes

Requires that the following is set:

parameters.magnetic_field

spectrum(signal: ndarray, dwell_time: float, normalize: bool = True, part: Literal['real', 'imag'] = 'real') → tuple[ndarray, ndarray][source]#

A wrapper function for the Fourier transform. Computes the Fourier transform and returns the frequency and spectrum (either the real or imaginary part of the Fourier transform).

Parameters:

signal (ndarray) – Input signal in the time domain.
dwell_time (float) – Time step between consecutive samples in the signal.
normalize (bool, default=True) – Whether to normalize the Fourier transform.
part ({'real', 'imag'}) – Specifies which part of the Fourier transform to return. Can be “real” or “imag”.

Returns:

freqs (ndarray) – Frequencies corresponding to the Fourier-transformed signal.
spectrum (ndarray) – Specified part (real or imaginary) of the Fourier-transformed signal in the frequency domain.

Notes

Required global parameters:

parameters.dwell_time

state(spin_system: SpinSystem, operator: str) → ndarray | csc_array[source]#

This function returns a column vector representing the density matrix as a linear combination of spin operators. Each element of the vector corresponds to the coefficient of a specific spin operator in the expansion.

Normalization: The output of this function uses a normalised basis built from normalised products of single-spin spherical tensor operators. However, the coefficients are scaled so that the resulting linear combination represents the non-normalised version of the requested operator.

NOTE: This function is sometimes called often and is cached for high performance.

Parameters:

spin_system (SpinSystem) – Spin system for which the state is created.
operator (str) –
Defines the state to be generated. The operator string must follow the rules below:
- Cartesian and ladder operators: I(component,index) or I(component). Examples:
  - I(x,4) –> Creates x-operator for spin at index 4.
  - I(x)–> Creates x-operator for all spins.
- Spherical tensor operators: T(l,q,index) or T(l,q). Examples:
  - T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.
  - T(1, -1) –> Creates operator with l=1, q=-1 for all spins.
- Product operators have * in between the single-spin operators: I(z,0) * I(z,1)
- Sums of operators have + in between the operators: I(x,0) + I(x,1)
- Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)
Special case: An empty operator string is considered as unit operator.

Whitespace will be ignored in the input.

NOTE: Indexing starts from 0!

Returns:

rho – State vector corresponding to the requested state.

Return type:

ndarray or csc_array

state_to_zeeman(spin_system: SpinSystem, rho: ndarray | csc_array) → ndarray | csc_array[source]#

Takes the state vector defined in the normalized spherical tensor basis and converts it into the Zeeman eigenbasis. Useful for error checking.

Parameters:

spin_system (SpinSystem) – Spin system whose state vector is going to be converted into a density matrix.
rho (ndarray or csc_array) – State vector defined in the normalized spherical tensor basis.

Returns:

rho_zeeman – Spin density matrix defined in the Zeeman eigenbasis.

Return type:

ndarray or csc_array

superoperator(spin_system: SpinSystem, operator: str, side: Literal['comm', 'left', 'right'] = 'comm') → ndarray | csc_array[source]#

Generates a Liouville-space superoperator for the spin_system from the user-specified operator string.

Parameters:

spin_system (SpinSystem) – Spin system for which the superoperator is going to be generated.
operator (str) –
Defines the superoperator to be generated. The operator string must follow the rules below:
- Cartesian and ladder operators: I(component,index) or I(component). Examples:
  - I(x,4) –> Creates x-operator for spin at index 4.
  - I(x)–> Creates x-operator for all spins.
- Spherical tensor operators: T(l,q,index) or T(l,q). Examples:
  - T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.
  - T(1, -1) –> Creates operator with l=1, q=-1 for all spins.
- Product operators have * in between the single-spin operators: I(z,0) * I(z,1)
- Sums of operators have + in between the operators: I(x,0) + I(x,1)
- Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)
Special case: An empty operator string is considered as unit operator.

Whitespace will be ignored in the input.

NOTE: Indexing starts from 0!
side ({'comm', 'left', 'right'}) – The type of superoperator: - ‘comm’ – commutation superoperator (default) - ‘left’ – left superoperator - ‘right’ – right superoperator

Returns:

sop – An array representing the requested superoperator.

Return type:

ndarray or csc_array

time_axis(npoints: int, time_step: float)[source]#

Generates a 1D array with npoints elements using a constant time_step.

Parameters:

npoints (int) – Number of points.
time_step (float) – Time step (in seconds).

triplet_minus_state(spin_system: SpinSystem, index_1: int, index_2: int) → ndarray | csc_array[source]#

Generates the triplet minus state between two spin-1/2 nuclei. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the triplet minus state is created.
index_1 (int) – Index of the first spin in the triplet minus state.
index_2 (int) – Index of the second spin in the triplet minus state.

Returns:

rho – State vector corresponding to the triplet minus state.

Return type:

ndarray or csc_array

triplet_plus_state(spin_system: SpinSystem, index_1: int, index_2: int) → ndarray | csc_array[source]#

Generates the triplet plus state between two spin-1/2 nuclei. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the triplet plus state is created.
index_1 (int) – Index of the first spin in the triplet plus state.
index_2 (int) – Index of the second spin in the triplet plus state.

Returns:

rho – State vector corresponding to the triplet plus state.

Return type:

ndarray or csc_array

triplet_zero_state(spin_system: SpinSystem, index_1: int, index_2: int) → ndarray | csc_array[source]#

Generates the triplet zero state between two spin-1/2 nuclei. Unit state is assigned to the other spins.

Parameters:

spin_system (SpinSystem) – Spin system for which the triplet zero state is created.
index_1 (int) – Index of the first spin in the triplet zero state.
index_2 (int) – Index of the second spin in the triplet zero state.

Returns:

rho – State vector corresponding to the triplet zero state.

Return type:

ndarray or csc_array

unit_state(spin_system: SpinSystem, normalized: bool = True) → ndarray | csc_array[source]#

Returns a unit state vector, which represents the identity operator. The output can be either normalised (trace equal to one) or unnormalised (raw identity matrix).

Parameters:

spin_system (SpinSystem) – Spin system to which the unit state is created.
normalized (bool, default=True) – If set to True, the function will return a state vector that represents the trace-normalized density matrix. If False, returns a state vector that corresponds to the identity operator.

Returns:

rho – State vector corresponding to the unit state.

Return type:

ndarray or csc_array

Main functionality

Contents

Main functionality#