API

Simulations using spin descriptions

superspinsim.simspins(coefficients: list[callable], time_start: float, time_end: float, time_step: float, spins: list[list[dict]], spin_interactions: list[dict], group_interactions: dict, density_initial: ndarray, number_of_exponentials: int = 5, number_of_fine_divisions: int = 1, number_of_quadratic_repeats: int = 35, use_rotating: bool = True, use_residual: bool = True, use_kernel: bool = False, use_unitary: bool = False, verbose: bool = False)

Run a simulation based on a description of spins, as described in Spin description syntax.

Parameters

coefficients: list[callable]: A list of the coefficients of the von Neumann and Dissipator generators. The first entries are the x, y, and z magnetic fields, in Tesla. The final entry is the inceherent optical excitation as fraction of saturation.
time_start: float: The initial time of the simulation.
time_end: float: The final time of the simulation.
time_step: float: The time step at which to provide solutions. These steps are conducted in parallel.
spins: list[list[dict]]: Descriptions of individual “atoms” of spin. See Individual spins .
spin_interactions: list[dict[tuple[int, int], dict]]: Descriptions of coherent interactions between spins. See Spin-spin interaction description .
group_interactions: dict[tuple[tuple[int, int], tuple[int, int]], dict]: Description of incoherent interactions between spins. See Incoherent interactions between coherent blocks .
density_initial: numpy.ndarray: Initial density matrix to evolve through time.
number_of_exponentials: int (default is 5): A shorthand for the kind of commutator-free Magnus integrator method being used in the simulator. Choose 1 for the CF2:1 second-order method. Choose 2 for the CF4:2 fourth-order method. Choose 3 for the CF4:3 fourth-order method. Choose 5 for the CF6:5 sixth-order method. Choose 6 for the CF6:6 sixth-order method.
number_of_fine_divisions: int (default is 1): The number of integration steps to conduct per every time step given in the solution. These steps are not conducted in parallel.
number_of_quadratic_repeats: int (default is 35): Twice the number of repeated squares to use in matrix exponentiation.
use_rotating: bool (default is True): Whether or not to use the generalised rotating frame technique.
use_residual: bool (default is True): Whether or not to use the residual arithmetic technique.
use_kernel: bool (default is False): Whether or not to use the equivalence class technique.
use_unitary: bool (default is False): Whether or not to simplify representations when there are only unitary dynamics.
verbose: book (default is False): Prints debug information.

Returns

time: np.ndarray: Time samples in seconds.
density: np.ndarray: Evaluated density matrices at the times given by time .

superspinsim.models.nv_7(quiescent_magnetic_field: ndarray = None, params=None)

A spin description of the 7-level NV model. Can be used with superspinsim.simspins() .

Parameters

quiescent_magnetic_field: numpy.ndarray (default is zero vector): Bias/system/quiescent magnetic field in Tesla. If defined, magnetic field terms generated by this field are added to the system Hamiltonian/Lindbladian. In this case, dynamic magnetic field coefficients are perturbations from this field.
params: module (optional): Python module defining NV parameter values. Default is the current internal one.

Returns

spins: list[list[dict]]: Descriptions of individual “atoms” of spin. See Individual spins .
spin_interactions: list[dict[tuple[int, int], dict]]: Descriptions of coherent interactions between spins. See Spin-spin interaction description .
group_interactions: dict[tuple[tuple[int, int], tuple[int, int]], dict]: Description of incoherent interactions between spins. See Incoherent interactions between coherent blocks .

Spin description syntax

SuperSpinsim comes with helper tools to construct spin systems, like NV centres in diamond, using a description from standard python datastructures.

At the lowest level, we have individual spins, which are based on a model of atoms. These describe an electron spin, a nuclear spin, their individual properties, and their hyperfine interactions.

Spins are then grouped into “blocks” in which all spins in the block have the ability to be coherent with each other and have spin-spin interactions. These block structures can also be used for defining multiple hyperfine interactions between electrons and neighbouring nuclei in a crystal structure.

Finally, multiple blocks can be defined which can only have incoherent interactions between them. This can be used to model the incoherent transitions between orbitals in an NV centre.

Individual spins

The description of each individual spin is organised into a python dict using the keys as described below. The dict s of individual spins inside a coherent block are organised into a python list. Finally, all of the list s describing individual blocks are organised into an encompassing list.

This means that the definition of all individual spins to be simulated will be a list of list s, of dict s. Here the main list contains the list s of group descriptions, and the group descriptions contain the dict s spin descriptions.

General

Key	Description
`B0`	Bias/system/quiescent magnetic field in Tesla. If defined, magnetic field terms generated by this field are added to the system Hamiltonian/Lindbladian. In this case, dynamic magnetic field coefficients are perturbations from this field.
`T`	Spin temperature in Kelvin. Used in calculating the \(T_1\) collapse operators.
`Rb_gets_a`	Coordinate transformation matrix between the perspective of the spin to the perspective of applied magnetic field. Can be used to define \(z\) for spins to be the quantisation axis, and \(z\) for magnetic fields to be something that makes more sense spatially.

Electron

Key	Description
`S`	Electron spin quantum number. Can be absent if a nuclear spin is defined.
`g`	Longitudinal electron g factor.
`g_perp`	Transverse electron g factor. If undefined, it is assumed that g is isotropic.
`D`	Zero-field splitting in radians/second.
`E`	Transverse zero-field splitting in radians/second.
`TS1`	Electron \(T_1\) time in seconds.
`TS2`	Electron \(T_2\) time in seconds.

Nucleus

Key	Description
`I`	Nuclear spin quantum number.
`gN`	Longitudinal nuclear g factor (nuclear magneton convention).
`gN_perp`	Transverse nuclear g factor (nuclear magneton convention). If no transverse nuclear g factor is undefined, it is assumed that gN/gI1 is isotropic.
`gI`	Longitudinal nuclear g factor (Bohr magneton convention).
`gI_perp`	Transverse nuclear g factor (Bohr magneton convention). If no transverse nuclear g factor is undefined, it is assumed that gN/gI1 is isotropic.
`P`	Nuclear qudrupole moment in radians/second.
`A`	Longitudinal hyperfine interaction in radians/second.
`A_perp`	Transverse hyperfine interaction in radians/second. If undefined, it is assumed that A is isotropic.
`TI1`	Nuclear \(T_1\) time in seconds.
`TI2`	Nuclear \(T_2\) time in seconds.

Spin-spin interaction description

The interaction between two spins within a coherent block is described by a python dict, using the keys as described below. Each of these individual descriptions for just two spins are organised into an encompassing dict for the entire coherent block. Here, the keys for the block dict are python tuple s of the list indices of the individual atom description. For example, the dict under the key (0, 1) will define the coupling between spins 0 and 1. There is then an encompassing list which contains the dict s that describe each coherent block.

Therefore, the description of the coherent interactions between spins takes the form of a list of dict s of dict s.

Key	Description
`J`	Longitudinal interaction between the two spins in radians/second.
`J_perp`	Transverse interaction between the two spins in radians/s. If undefined, it is assumed that J is isotropic.

Incoherent interactions between coherent blocks

The incoherent interaction between two spins in different coherent blocks is defined by a python dict, with keys as defined below. These dict s are organised into an encompassing dict under keys of the form ((block_0, spin_0), (block_1, spin_1)). Here, the spin of index spin_0 from coherent block block_0 is interacting with a spin of index spin_0 from coherent block block_0 .

Therefore, the description of the incoherent interactions between spins of different blocks takes the form of a dict of dict s.

These blocks are designed to model the orbital interactions of the NV centre.

Key	Description
`rel`	Spin-conserving optical relaxation rate in population/second.
`rel_n`	Spin-nonconserving optical relaxation rate in population/second.
`s_gets_0`	Transition rate from the \(m_S=0\) state of a triplet to a singlet, in population/second. Useful for modelling NV centres in diamond.
`s_gets_1`	Transition rate from the \(m_S=\pm1\) states of a triplet to a singlet, in population/second. Useful for modelling NV centres in diamond.
`0_gets_s`	Transition rate from a singlet to the \(m_S=0\) state of a triplet, in population/second. Useful for modelling NV centres in diamond.
`1_gets_s`	Transition rate from a singlet to the \(m_S=\pm1\) states of a triplet, in population/second. Useful for modelling NV centres in diamond.

Simulations using QuTiP-syntax

superspinsim.mesolve(H, rho0: ndarray, ti: float, tf: float, dt: float, c_ops=None, allowed: ndarray = None, use_rotating: bool = True, number_of_exponentials: int = 5, number_of_fine_divisions: int = 10)

A wrapper for superspinsim to provide a similar syntax to other simulators, like qutip.mesolve.

Parameters

H: Hamiltonian of the system. Static Hamiltonians can be defined as either a numpy.ndarray, or a qutip.Qobj. Dynamic Hamiltonians can be defined using a two-element list, where the first element is a static Hamiltonian, and the second element is a python function which defines a time-dependent coefficient of said Hamiltonian. Multiple static and dynamic Hamiltonians can be combined by providing a list of Hamiltonians in the format described above.
rho0: numpy.ndarray: The initial density matrix of the system.
ti: float: The initial time of the simulation.
tf: float: The final time of the simulation.
dt: float: The time step at which to provide solutions. These steps are conducted in parallel.
c_ops (optional): Jump (collapse) operators of the system. Static jump operators can be defined as either a numpy.ndarray, or a qutip.Qobj. Dynamic jump operators can be defined using a two-element list, where the first element is a static jump operator, and the second element is a python function which defines a time-dependent coefficient of said jump operator. Multiple static and dynamic jump operators can be combined by providing a list of jump operators in the format described above.
allowed: numpy.ndarray (optional): A mask (matrix of zeroes and ones) of the locations of allowed non-zero density matrix elements. This can be used to exclude certain elements that are known to be zero, i.e., the coherences of between known incoherent states.
use_rotating: bool (default is True): Whether or not to transform the problem into the generalised rotating frame.
number_of_exponentials: int (default is 5): The choice of which commutator-free magnus integrator to use, labelled by the number of exponentials per step used in said integrator.
number_of_fine_divisions: int (default is 10): The number of integration steps to conduct per every time step given in the solution. These steps are not conducted in parallel.

Returns

time: np.ndarray: Time samples in seconds.
density: np.ndarray: Evaluated density matrices at the times given by :obj”time .

Visualisation

superspinsim.colour_complex_matrix(inp: ndarray)

Returns an RGB image representing a complex matrix. Complex phase is represented by hue. Can be used to plot a density matrix.

Parameters

inp: numpy.ndarray: The complex matrix to visualise.

Returns

out: numpy.ndarray: An RGB matrix representing the complex matrix.