Developer

Note

If you are a developer and would like to add your own features to teacups this secion of the documentation may be useful. It presents all modules and their functions.

TEACUPS consists of 13 Python modules, which contain classes and functions. They can be roughly sorted into three main categories, namely specific simulation modules, general modules, and structuring modules.

Specific simulation modules

These modules include all functions that are specific for the simulation of transient EPR spectra. The main file simulations.py calls all functions in the right order to obtain the spectrum. The other modules are used to set up and transform the explicit matrices as described by the theory. The functions of the specific simulation modules use a four-class system as input and output, which consists of Sys, Exp, SimOpt and Cal. All information needed for the simulation is provided and sorted in these four classes as attributes:

• Sys contains all spin system parameters including relaxation times.

• Exp contains all experimental parameters.

• SimOpt contains simulations options, e.g. the choice of the space, the number of grid points, and the simulation mode.

• Cal is at the beginning an empty class, but it is filled with the results of the calculations during the simulation. These results are fed to further functions later.

creators.py

In the creators-module functions for creating matrix-objects like tensors, detection operator or spinoperator can be found.

teacups.creators.create_dipol_tensor_diagonals(D: float, E: float) → ndarray

Create an array with three diagonal elements of the dipolar interaction tensor of two spin species. Calculate this values from the axial dipolar coupling $D$ and the rhombic dipolar coupling $E$ by:

\[D+E; D-E; -2D.\]

Parameters:

• D (float) – Axial dipolar coupling.

• E (float) – Rhombic dipolar coupling.

Returns:

diag – The three diagonal elements of a dipol tensor (D+E, -D-E, -2D). This is a 1D-array.

Return type:

np.ndarray

teacups.creators.create_tensor(diag: list, phi: ndarray, theta: ndarray, first_rotation=[]) → object

Setup any tensor. An object of class mt.Tensor is built. Diagonal elements are filled into the tensor in its diagonal coordinate frame. If first_rotation is not empty, an initial rotation to laboratory frame will be carried out. Afterwards the tensor.multirot attribute is built by using the tensor.multirotation function with the angle-arrays phi and theta.

Parameters:

• diag (list) – A list of the three diagonal elements of the tensor.

• phi (np.ndarray) – Array with the phi values for each angle point.

• theta (np.ndarray) – Array with the theta values for each angle point.

• first_rotation (list) – If a first rotation into laboratory frame is wished, first_rotation must be set to a list of the three euler angles phi, theta and psi around which the tensor is rotated. If it is empty, no rotation will be carried out. Default is an empty list.

Returns:

tensor – Tensor object with initialized tensor and multirot.

Return type:

object

teacups.creators.create_zfs_tensor_diagonals(D: float, E: float) → ndarray

Create an array with three diagonal elements of the zero-field splitting (ZFS) tensor. Calculate this values from the zero-field-splitting parameters D and E by:

\[-1/3*D+E; -1/3*D-E; 2/3*D.\]

Parameters:

• D (float) – Zero-field-splitting parameter D.

• E (float) – Zero-field-splitting parameter E.

Returns:

diag – The three diagonal elements of a ZFS tensor (-1/3*D+E, -1/3*D-E, 2/3*D). This is a 1D-array.

Return type:

np.ndarray

teacups.creators.set_up_observable(sys: object, opt: object, cal: object) → None

Set up the observable operator for an EPR-Experiment in the singlet-triplet basis of the radical pair. Observation direction is y-direction (in case of the static magnetic field set in z-direction). The total spin operator of a radical pair is taken and transforem to ST-basis. For calculations in hilbert-space the operator is given back as a 4x4-matrix. For calculations in liouville-space it is given back as a 16x1 vector.

Parameters:

• opt (object) – Contains simulation option parameters. This function uses opt.space (set either to ‘hilbert’ or ‘liouville’), which defines the space in which the calculation is carried out.

• cal (object) – Container for calculated results during the simulation. This function uses the total spinoperator cal.s (e.g. built by the function set_up_radical_pair_spinoperators).

cal.observable

Observable operator (S_y-operator in ST-basis) either as a matrix (calculations in hilbert-space) or as a vector (calculations in liouville space).

Type:

np.ndarray

Return type:

None.

teacups.creators.set_up_spinoperator(sys: object, cal: object) → None

Set up the spin matrix operators for the spin system.

Parameters:

• sys (object) – Contains parameters of the spin system. This function needs sys.s which is a list of the quantum numbers of the spin system.

• cal (object) – Container for calculated spinoperators. This object may be empty.

cal.s

Spinoperator of the spin system. This is a Spinoperator object.

Type:

object

Return type:

None.

teacups.creators.set_up_tensors(sys: object, cal: object) → None

Set up all wished tensors for further calculations. The tensors are set up for all orientations and are saved as tensor objects. Furthermore, if the frame argument in sys is given, the tensors will be rotated to an initial frame.

Parameters:

• sys (object) – Contains parameters concerning the spin system. This function can use the following arguments and returns the tensors: g1, g2 (g-tensors of a radical pair) + g1_frame/g2_frame [lists] g (g-tensor of a radical) + g_frame [lists] g_tri (g-tensor of a triplet) + g_tri_frame [lists] D, E (dipole coupling parameters of a coupled spin system) [floats] + D_frame [list], if D, E are not given, they will be set to zero D_tri, E_tri (ZFS parameters of a triplet) [floats] + D_tr_frame [list], if D, E are not given, they will be set to zero

• cal (object) – Container for calculated tensors. The attributes cal.phi and cal.theta (arrays with the angle points on a sphere for rotations) are needed.

cal.g1_tensor

g1-tensor of the radical pair. This is a Tensor object. (optional)

Type:

object

cal.g2_tensor

g2-tensor of the radical pair. This is a Tensor object. (optional)

Type:

object

cal.D_tensor

D-tensor of coupled electrons. This is a Tensor object. (optional)

Type:

object

cal.g_tri_tensor

g-tensor of the triplet precursor. This is a Tensor object.

Type:

object

cal.D_tri_tensor

D-Tensor of the triplet precursor. This is a Tensor object.

Type:

object

cal.g_tensor

g-Tensor of a radical. This is a Tensor object. (optional)

Type:

object

cal.g_iso

Isotropic g-value.

Type:

float

Return type:

None.

density_matrices.py

A function that sets up an initial density matrix (dependent on precursor and spin system) is provided in this module.

teacups.density_matrices.set_up_density_matrix(sys: object, exp: object, opt: object, cal: object) → None

Calculate the density matrix in the basis and shape of the systems Hamiltonian.

Parameters:

• sys (object) – Sys contains all spin system attributes. This function uses the following attributes: sys.precursor: The density matrix, for which the populations are given, is set up in the precursors basis. Depending on the spin system the precursor can be set to the following strings: ‘zf’ (population of zero-field levels), ‘eigen’ (population of eigenvalues of the system), ‘singlet’ (a radical pair in pure singlet state), ‘triplet-zf’ (a triplet precursor populated in the triplets zero-field basis of a radical pair or a triplet doublet pair) sys.spin_system: The spin system attribute has to be set to a string defining the spin system. This may be ‘rp’ (radical pair), ‘trip’ (triplet), ‘doub’ (doublet), or ‘tdp’ (triplet doublet pair). sys.population: Diagonal elements of the density matrix/ population of the states in the basis given by the precursor attribute. The length of the population vector equals the dimension of the spin system.

• exp (object) – Contains the experimental parameters. This function needs the attribute exp.B_z (static magnetic field vector).

• opt (object) – Contains the simulation option parameters. This function needs the attributes opt.space (defining the space for the calculations as hilbert or liouville) and opt.grid_points (number of angle combinations).

• cal (object) – Contains calculated results during the simulation. This function uses the attribute cal.s (the spin operator) and dependent on the choice of precursor and spin system optionally different hamiltonians. For a zf-triplet-precursor cal.phi and cal.theta are used as well.

Raises:

AttributeError – In case a wrong combination of spin system and basis is given.

Return type:

None

cal.rho

The density matrix is added as an attribute to the cal-object. Its shape is B_angle_matrix like in case of hilbert space calcultations ans B_angle_vector like for liouvlle space calculations (more details in the multioperator module). The density matrix is returned in the basis of the system Hamiltonian.

Type:

np.ndarray

hamiltonians.py

The module hamiltonians contains all functions that are concerned with setting up any hamiltonian for the provided spin systems.

teacups.hamiltonians.set_up_commutator_superoperator(sys: object, opt: object, cal: object) → None

Build a commutator superoperator from a hilbert space hamiltonian for further calculations in liouville space.

Parameters:

• sys (object) – Contains information on the spin system. This function uses information on the relaxation times, i.e. sys.dynamics or sys.T_relax_1 and sys.T_relax_2.

• opt (object) – Contains simulation option parameters. This function uses the attribute opt.space. If it is set to liouville the commutator superoperator will be calculated. Else the function will do nothing.

• cal (object) – Container for results of calculations during the simulation. This function uses the attribute cal.ham, a hamiltonian in hilbert space (B_angle_matrix is required, can be calculated e.g. by the function set_up_rp_hamiltonian). The hamiltonian is used to set up the commutator superoperator.

cal.ham_superop

The attribute will be built, if opt.space is set to liouville. This is the commutator superoperator given as a B_angle_matrix attribute from the class Multioperator.

Type:

np.ndarray

Return type:

None.

teacups.hamiltonians.set_up_doublet_hamiltonian(exp: object, opt: object, cal: object) → ndarray

Calculate a doublet Hamiltonian. The high-field-Hamiltonian is set up as a multioperator object for each orientation and each magnetic field point. The Zeeman-interaction is included. The spinfunctions alpha and beta are used as the basis set. As the Hamiltonian is set up in the rotating frane, secular approximation is applied.

Parameters:

• exp (object) – Contains experimental parameters. This functions uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation option parameters. This function uses the attribute opt.grid_points, which is the number of angle combinations that shall be caluclated for the powder average.

• cal (object) – Container for results of calculations during the simulation. This function uses the tensor object cal.g_tensor, which may be created by the function set_up_tensors and cal.s (spinoperator of the doublet).

Returns:

ham – Doublet high field hamiltonian. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

teacups.hamiltonians.set_up_mw_hamiltonian(sys: object, exp: object, opt: object, cal: object) → ndarray

Calculate a Hamiltonian matrix operator for the coupling of a spin system with a weak microwave field in x-direction. The Hamiltonian is calculated for all orientations and magnetic field points and returned as a B_angle_matrix attribute from the class Multioperator. Secular approximation is presumed. By a shift of the lamor frequencies the Hamitlonian is transformed to the rotating frame. Therefore, the microwave Hamiltonian is not time dependent. In case the spin system is a radical pair the Hamiltonian is transferred to the singlet triplet basis. Otherwise it is left in the product basis.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.spin_system.

• exp (object) – Contains experimental parameters. This function uses the attributes exp.B_mw (strength of microwave field) and exp.freq_mw (microwave frequency).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.g_iso (e.g. from the function set_up_tensors) and the spinoperator object cal.s.

Returns:

ham_mw – Microwave coupling hamiltonian in the rotating frame. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

teacups.hamiltonians.set_up_rp_hamiltonian(sys: object, exp: object, opt: object, cal: object) → ndarray

Calculate a Hamiltonian matrix operator for a radical pair. Coupling with the static magnetic field is included as well as interactions of the two spins. The Hamiltonian is calculated for all orientations and magnetic field points in the singlet-triplet-basis and returned as a B_angle_matrix attribute from the class Multioperator. Secular approximation is presumed.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.g1, sys.g2 and optional sys.J_ex (if given).

• exp (object) – Contains experimental parameters. This function uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.g1_tensor and cal.g2_tensor and optional cal.D_tensor if it is given (e.g. from set_up_tensors).

Returns:

ham_rp – Radical pair hamiltonian in the singlet triplet basis. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

teacups.hamiltonians.set_up_tdp_hamiltonian(sys: object, exp: object, opt: object, cal: object) → ndarray

Calculate a Hamiltonian matrix operator for a coupled triplet doublet pair. Coupling with the static magnetic field of the triplet and the doublet is included each as well as the ZFS of the triplet and the interactions of the two spins. The Hamiltonian is calculated for all orientations and magnetic field points in the product basis and returned as a B_angle_matrix attribute from the class Multioperator. Secular approximation is presumed.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.g_tri and sys.J_ex.

• exp (object) – Contains experimental parameters. This function uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.g_tensor and cal.g_tri_tensor, cal.D_tri_tensor and cal.D_tensor (e.g. from set_up_tensors). Further cal.s (spinoperator for a triplet-doublet-system is needed)

Returns:

ham_tdp – Triplet-doublet-pair hamiltonian in the shape of a B_angle_matrix from the class Multioperator. The hamiltonian is given in the product basis of doublet and triplet: |a, +1>, |a, 0>, |a, -1>, |b, +1>, |b, 0>, |b, -1>.

Return type:

np.ndarray

teacups.hamiltonians.set_up_tdp_high_field_pnm_hamiltonian(sys: object, exp: object, opt: object, cal: object) → ndarray

Calculate a Hamiltonian matrix operator for a coupled triplet doublet pair. Coupling with the static magnetic field of the triplet and the doublet is included each as well as the ZFS of the triplet and the interactions of the two spins. The Hamiltonian is calculated for all orientations and magnetic field points in the product basis of the spin operator functions and returned as a B_angle_matrix attribute from the class Multioperator. The interaction matrices are calculated by direct prducts of spin matrices and interaction tensors and no secular approximation is applied.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.J_ex.

• exp (object) – Contains experimental parameters. This function uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.g_tensor and cal.g_tri_tensor, cal.D_tri_tensor and cal.D_tensor (e.g. from set_up_tensors).

Returns:

ham_hf – Full triplet-doublet-pair high-field hamiltonian in the shape of a B_angle_matrix from the class Multioperator. The hamiltonian is given in the product basis of doublet and triplet high field functions: |a, +1>, |b, +1>, |a, 0>, |b, 0>, |a, -1>, |b, -1>.

Return type:

np.ndarray

teacups.hamiltonians.set_up_tdp_high_field_xyz_hamiltonian(sys: object, exp: object, opt: object, cal: object) → ndarray

Calculate a Hamiltonian matrix operator for a coupled triplet doublet pair. Coupling with the static magnetic field of the triplet and the doublet is included each as well as the ZFS of the triplet and the interactions of the two spins. The Hamiltonian is calculated for all orientations and magnetic field points in the xyz-Basis (basis in which the ZFS-Hamiltonian of the triplet is diagonal) and returned as a B_angle_matrix attribute from the class Multioperator. The interaction matrices are calculated by direct prducts of spin matrices and interaction tensors and no secular approximation is applied.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.J_ex.

• exp (object) – Contains experimental parameters. This function uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.g_tensor and cal.g_tri_tensor, cal.D_tri_tensor and cal.D_tensor (e.g. from set_up_tensors).

Returns:

ham_hf – Full triplet-doublet-pair high-field hamiltonian in the shape of a B_angle_matrix from the class Multioperator. The hamiltonian is given in the xyz-Basis of doublet and triplet: |a, x>, |b, x>, |a, y>, |b, y>, |a, z>, |b, z>.

Return type:

np.ndarray

teacups.hamiltonians.set_up_triplet_hamiltonian(exp: object, opt: object, cal: object) → ndarray

Calculate the triplet Hamiltonian. The high-field-Hamiltonian is set up as a multioperator object for each grid point and for each magnetic field point. Interactions included are: Zeeman-interaction and dipolar interaction (=ZFS). The spinfunctions (+1, 0, -1) are used as a basis set. As the Hamiltonian is set up in the rotating frame, secular approximation is applied:

\[H = D_{zz} * (S_z^2 - 1/3*S^2) + H_\mathrm{Zeeman}\]

Parameters:

• exp (object) – Contains experimental parameters. This function uses the attribute exp.B_z (magnetic field array).

• opt (object) – Contains simulation options. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses the tensor objects cal.g_tri_tensor and cal.D_tri_tensor. They may be created by the function set_up_tensors. Further cal.s (spinoperator of the triplet) is used.

Returns:

ham – Triplet high field hamiltonian. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

teacups.hamiltonians.set_up_triplet_high_field_pnm_hamiltonian(exp: object, opt: object, cal: object) → ndarray

Calculate the hamiltonian of a triplet state in high magnetic field in the basis of the spin operators (+1, 0, -1). It is built as the sum of the ZFS and the Zeeman interaction.

The triplet hamiltonian is calculated for different B_z-values and all combinations of the euler angels phi and theta (grid_points points distributed on the fibonacci sphere). All hamiltonians are returned in cal.ham_tri wich is an object of the class Multioperator.

Parameters:

• exp (object) – Contains experimental parameters. This function uses exp.B_z

• opt (object) – Contains simulation option parameters. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses the attributes cal.D_tri_tensor and cal.g_tri_tensor (e.g.built by the function set_up_tensors).

Returns:

ham_tri_hf – Hamiltonian of a triplet precursor of a radical pair in high field. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

teacups.hamiltonians.set_up_triplet_high_field_xyz_hamiltonian(exp: object, opt: object, cal: object) → ndarray

Calculate the hamiltonian of a triplet state in high magnetic field in the D-tensor main-axis system (Tx, Ty, Tz). It is built as the sum of the ZFS and the Zeeman interaction.

The triplet hamiltonian is calculated for different B_z-values and all combinations of the euler angels phi and theta (grid_points points distributed on the fibonacci sphere). All hamiltonians are returned in cal.ham_tri wich is an object of the class Multioperator.

Parameters:

• exp (object) – Contains experimental parameters. This function uses exp.B_z

• opt (object) – Contains simulation option parameters. This function uses opt.grid_points.

• cal (object) – Container for results of calculations during the simulation. This function uses the attributes cal.D_tri_tensor and cal.g_tri_tensor (e.g.built by the function set_up_tensors).

Returns:

ham_tri_hf – Hamiltonian of a triplet precursor of a radical pair in high field. This is a B_angle_matrix attribute from the class Multioperator.

Return type:

np.ndarray

hyperfine.py

Functions for setting up hyperfine-tensors and the hyperfine-hamiltonian for a system of one or two spins. Further a function, that calculates the trEPR signal with all hyperfine-interactions can be found here.

teacups.hyperfine.create_hf_hamiltonian(spins: list, coupling_nucs: list, hf_tensors: list) → list

Calculate the diagonal elements of a hyperfine interaction hamiltonian of any number of spins with any number of nuclei. Input parameters are given as lists, their dimensions are described below. The interaction hamiltonian is calculated for all grid_points and for all combinations of spin and nuceus. The hamiltonian is set up for each spin with the given coupling nuclei and returned in a list with the length of the number of spins. The spin-hamiltonians lengths are given as the product of the multiplicities of the spin and the coupling nuclei.

Parameters:

• spins (list) – List containing the spin quantum numbers of the spins in the system as floats.

• coupling_nucs (list) – List containing lists of the spin quantum numbers of the coupling nuclei. In the coupling_nucs list has to be a list of floats for each spin. The quantum numbers of the nuclei are placed into the lists, which are refered to their spin. E.g. if a nucleus couples to the second spin in the spins-list its quantum number is set into the second list in coupling_nucs-list.

• hf_tensors (list) – List containing lists of the hyperfine tensors. The list is set up analogously to the coupling_nucs list. For each nucleus a tensor is placed at the same position of the hf_tensors-list. The tensors in the list are objects of class Tensor and have the multirot attribute initialized.

Returns:

For each spin an array is returned in this list. The array contains the diagonal elements of the hyperfine interaction in the product basis. The shape of the arrays is gridpoints x (multiplicity_spin*product of multiplicity_of_all_coupling_nucs).

Return type:

list

Examples

>>> A = mt.Tensor([1, 1, 1])
>>> A.multirotation(1)
>>> create_hf_hamiltonian([1/2], [[1/2]], [[A]])
[array([[ 0.25+0.j, -0.25+0.j, -0.25+0.j,  0.25+0.j]])]

>>> create_hf_hamiltonian([1/2, 1/2], [[1/2],[1]], [[A],[A]])
[array([[ 0.25+0.j, -0.25+0.j, -0.25+0.j,  0.25+0.j]]),
 array([[ 0.5+0.j,  0. +0.j, -0.5+0.j, -0.5+0.j,  0. +0.j,  0.5+0.j]])]

>>> h = create_hf_hamiltonian([1/2, 1], [[1/2, 1/2],[]], [[A, A],[]])
>>> h
[array([[ 0.5+0.j,  0. +0.j,  0. +0.j, -0.5+0.j, -0.5+0.j,  0. +0.j,
          0. +0.j,  0.5+0.j]]),
 array([[0.+0.j, 0.+0.j, 0.+0.j]])]
>>> h[0].shape
(1, 8)

teacups.hyperfine.hyperfine_of_coupled_system(hams_hf: list, combinations: list, dimensions: list, dim_total: float) → list

Calculate the hyperfine hamiltonian of a spin system of two coupled spins. For each spin M_i hamiltonians are calculated, where M_i is the the total number of magnetic quantum numbers. E.g. if one nucleus with spin 1/2 is coupled M_i is 2, if one nucleus with spin 1/2 and one nucleus with spin 1 are coupled to the spin M_i is 2*3 = 6. A list with the diagonal elements of the two hamiltonians is returned. The shape of each element of the list is M_i x grid_points x total_dimension_of_spinsystem.

Parameters:

• hams_hf (list) – List with two hyperfine hamiltonians (one for each spin). The hamiltonians are B_angle_matrices as returned by the function create_hf_hamiltonian.

• combinations (list) – List of two integers, one for each spin. This is the number of combinations of the magnetic quantum numbers of spin and coupling nuclei. The number can be calculated by: hf_hamiltonian_shape/multiplicity_of_spin

• dimensions (list) – List of integers, one for each spin. They give the multiplicity of each spin. E.g. if S = 1, dimension = 2*1+2 = 3.

• dim_total (float) – Total dimension of the spinsystem. E.g if s_1 = 1/2, s_2 = 1 the total dimension is 2*3=6.

Returns:

List with two hyperfine interaction hamiltonians. Their shape is M_i x grid_points x total_dimension_of_spinsystem each.

Return type:

list

Examples

>>> A = mt.Tensor([1, 1, 1])
>>> A.multirotation(1)
>>> h = create_hf_hamiltonian([1/2, 1], [[1/2, 1/2],[]], [[A, A],[]])
>>> h
[array([[ 0.5+0.j,  0. +0.j,  0. +0.j, -0.5+0.j, -0.5+0.j,  0. +0.j,
          0. +0.j,  0.5+0.j]]),
 array([[0.+0.j, 0.+0.j, 0.+0.j]])]
>>>  hyperfine_of_coupled_system(h, [4, 1], [2, 3], 6)
[array([[[ 0.5+0.j,  0.5+0.j,  0.5+0.j, -0.5+0.j, -0.5+0.j, -0.5+0.j]],
        [[ 0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j]],
        [[ 0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j,  0. +0.j]],
        [[-0.5+0.j, -0.5+0.j, -0.5+0.j,  0.5+0.j,  0.5+0.j,  0.5+0.j]]]),
 array([[[0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j]]])]

teacups.hyperfine.make_signal_with_hyperfine(sys: object, exp: object, opt: object, cal: object) → None

Calculate the timeresolved signal of a trEPR-experiment a system consisting of one or two spins including hyperfine interactions. The Hamiltonian is set up for all combinations of magnetic quantum numbers of the spins and the coupling nucs. The propagaion and the signal are calculated for each orientation. Therefore, all attributes needed in sap.propagation and sap.make_signal are needed in this function. Further attributes are listed below.

Parameters:

• sys (object) – Object of class spinsystem. This function uses sys.s (list of spin quantum numbers of the spins) and sys.spin_system (string with the name of the spin system).

• exp (object) – Experimental parameters object.

• opt (object) – Simulation options object.

• cal (object) – Object of class Calculations. Results during the simulation are saved here. This function uses from previous functions the following attributes: cal.ham (hamiltonian of the system excluding the hyperfines) cal.ham_hf (hyperfine hamiltonian, e.g. built by create_hf_hamiltonian)

cal.spec_sim

This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z. So the shape is len(t)xlen(B).

Type:

np.ndarray

Return type:

None

teacups.hyperfine.set_up_hyperfine_tensors(sys: object, cal: object) → None

Set up a set of hyperfine tensors, optionally rotate them to an initial frame and rotate them to a set of angles theta and phi. The function cr.create_tensor is used.

Parameters:

• sys (object) – Contains parameters concerning the spin system. This function takes use of the attribute sys.A which contains a list of lists with the three diagonal elements af a hyperfine-tensor each. If sys.A_frame is given (list of same dimension as sys.A) the tensors are rotated to the given initial frame.

• cal (object) – Contains calculated results during the simulation. Cal.phi and cal. theta are needed, which contain all angle points.

cal.A_tensor

List of tensor objects one for each hyperfine tensor given in sys.

Type:

list

Return type:

None.

input_handler.py

The functions of this module deal with the input parameters. Parameters are scaled and transformed to other types for further calculations. The basic class Calculations is set up here.

class teacups.input_handler.Calculations

An object of class Calculations has no attributes at the beginning. The object of the Calculations-Class is used during the simulation by several functions to save results.

teacups.input_handler.create_grid(opt: object, cal: object) → None

Create the orientational grid and set up pairs of theta and phi for each angle point. The variable grid_points is changed from the input value (Number of points between theta=0 and theta=pi/2) to the number of angle points. A fibonacci grid or a sophe grid either is built, or a “grid” consisting of user-chosen angle points.

Parameters:

• opt (object) – Object of class Options. The attribute opt.grid sets the chosen grid. It may be ‘sophe’ or ‘fibonacci’ either. It has to contain the attribute opt.grid_points which is the number of points between theta=0 and theat=pi/2 on the orientational sphere that shall be calculated. In case of a sophe grid opt.sym has to contain a string that defines the symmetry of the system. If opt.grid is set to ‘single’ user-chosen orientations can be calculated. In that case opt.theta and opt.phi have to be given as lists containing the desired angle inputs.

• cal (object) – Container for calculated values.

cal.phi

Array with the phi values for each angle point.

Type:

np.ndarray

cal.theta

Array with the theta values for each angle point.

Type:

np.ndarray

opt.grid_points

Number of angle points.

Type:

int

Return type:

None

teacups.input_handler.hyperfine_converter(sys: object) → None

Allow flexible input of hyperfine parameters. Function has the following possibilities for handling hyperfine parameters:

• No hyperfines are given: Only sys.I is set as an empty list. No further hyperfine correlated attributes are added to the sys object.

• Hyperfines are given in the spinsystem attributes sys.I, sys.A and sys.A_frame as lists (like the lists like needed by set_up_hyperfine_tensors and create_hf_hamiltonian): Function just returns; it does not change the attributes.

• Hyperfines are given as numbered attributes of sys, e.g. sys.I1, sys.I2 etc., the spin_system is not ‘rp’: Attributes sys.A, sys.I and sys.A_frame are build as lists (like needed by set_up_hyperfine_tensors and create_hf_hamiltonian) and filled with all n numbered attributes. If no sys.A_frame_i is given the values in sys.A_frame are set to [0, 0, 0]. The attribute sys.n_i determines the number of times the type of core is added to sys.A/I/A_frame.

• Hyperfines are given as numbered attributes of sys, e.g. sys.I1, sys.I2 etc. and the spin_system is ‘rp’: The attributes are created as if spin_sytem would not be ‘rp’ but the resulting lists contain two instead of one list of hyperfine parameters, one for each electron. The place where the numbered elements shall be placed is defined by the attributes donor_list and acceptor list.

Parameters:

sys (object) – Spin system object. May contain parameters for the hyperfine coupling.

Return type:

None

Examples

>>> sys = Sys()
>>> sys.spin_system = 'doub'
>>> sys.I1 = 1/2
>>> sys.n1 = 2
>>> sys.A1 = [2, 2, 2]
>>> hyperfine_converter(sys)
>>> sys.A
[[[2, 2, 2], [2, 2, 2]]]
>>> sys.I
[[1/2, 1/2]]
>>> sys.A_frame
[[[0, 0, 0], [0, 0, 0]]]

>>> sys.spin_system = 'rp'
>>> sys.I1 = 1/2
>>> sys.n1 = 1
>>> sys.A1 = [1, 2, 3]
>>> sys.I2 = 1
>>> sys.n2 = 1
>>> sys.A2 = [4, 5, 6]
>>> sys.A2_frame = [7, 7, 7]
>>> sys.acceptor_list = [1]
>>> sys.donor_list = [2]
>>> hyperfine_converter(sys)
>>> sys.I
[[1/2], [1]]
>>> sys.A
[[[1, 2, 3]], [[4, 5, 6]]]
>>> sys.A_frame
[[[0, 0, 0]], [[7, 7, 7]]]

teacups.input_handler.initialize_spin_system(sys: object) → None

Set up the spin quantum numer s for a given spinsystem.

Parameters:

sys (object) – Object of class spin system. The needed attribute spin_system is a string describing the type of the spin system. This is either ‘rp’ for a radical pair, ‘doub’ for a doublet or ‘trip’ for a triplet.

sys.s

This list contains the spin_quantum numbers of the spin system.

Type:

list

Return type:

None

teacups.input_handler.input_object_handler(Sys: object, Exp: object, Opt: object) → tuple[object, object, object, object]

Build copys of the three input objects, that contain all simulation parameters. Create a Calculation object.

Parameters:

• Sys (object) – This is a Spinsystem object, that should contain all spinsystem parameters needed for a simulation.

• Exp (object) – This is an Experiment object, that should contain all experimental parameters needed for a simulation.

• Opt (object) – This is an Options object, that should contain all simulation option parameters needed for a simulation.

Returns:

• sys (object) – Copy of Sys.

• exp (object) – Copy of Exp.

• opt (object) – Copy of Opt.

• cal (object) – Freshly initialized object from the class Calculations. This is needed for saving results during the simulation.

teacups.input_handler.predefinitions(sys, exp: object, cal: object) → None

Predefine arrays needed for the calculations: A linear spaced t-axis, and an empty signal-array.

Parameters:

• exp (object) – Contains experimental parameters. This function uses exp.B_z, exp.t_scale and exp.t_points.

• cal (object) – Container for calculated spaces.

cal.t

Linear spaced 1D-array with time points at which the spectrum will be simulated.

Type:

np.ndarray

cal.spec_sim

Array contains only zeros and will be filled later. The shape is nPoints x tPoints.

Type:

np.ndarray

Return type:

None.

teacups.input_handler.scale_inputs(sys: object, exp: object, opt: object) → None

Change the unit of the attributes of the input to Hz or T.

Parameters:

• sys (object) – Parameters of the spinsystem. All coupling parameters are changed to Hz.

• exp (object) – Experimental parameters. The microwave frequency is change to Hz, all magnetic parameters are changed to T.

• opt (object) – Simulation options object. If the sophe grid is chosen, the gaussian line width for interpolation is scaled.

teacups.input_handler.split_grid(sys: object, exp: object, opt: object, cal: object) → None

Find the memory-bottleneck for a routine and split the grid into a number of chunks defined by the available memory.

Parameters:

• sys (object) – Contains spinsystem parameters. This function uses the attributes sys.spin_system and sys.precursor.

• exp (object) – Contains experimental parameters. This function uses the attributes exp.B_z.

• opt (object) – Contains simulation options. This function uses opt.grid_points and opt.grid.

• cal (object) – Container for results of calculations during the simulation. This function uses cal.phi, cal.theta and in case that opt.grid is ‘sophe’ cal.weights.

cal.phi_split

List with the array of phi angle points split into multiple numpy arrays. Their length is dependent on the available memory and the simulations bottleneck.

Type:

list of np.ndarrays

cal.theta_split

List with the array of theta angle points split into multiple numpy arrays. Their length is dependent on the available memory and the simulations bottleneck.

Type:

list of np.ndarrays

cal.weights_split

List with the array of weights (in case of SOPHE-grid) split into multiple numpy arrays. Their length is dependent on the available memory and the simulations bottleneck.

Type:

list of np.ndarrays (optional)

Return type:

None

relaxation.py

Functions for the definition of relaxation superoperators are provided in this module.

teacups.relaxation.create_relaxation_superoperator(sys: object, cal: object) → ndarray

Calculate a relaxation superoperator matrix dependend on the user input. If a relaxation time is given the phenomenological relaxation superoperator is returned. If a matrix is given in the attribute sys.dynamics this matrix is taken to set up a superoperator describing any dynamic system.

Parameters:

• sys (Spin system object.) – Contains information about the relaxation process. If it has an attribute sys.T_relax_1 (and sys.T_relax_2) these are two floats that are the longitudinal (and transversal) relaxation time in seconds. If sys has an attribute called sys.dynamics relaxation times are ignored and the matrix provided in sys.dynamics is used to set up an relaxation superoperator. The matrix has to have the shape nxn where n is the dimension of the systems spinoperator. The basis are the eigenfunctions in ascending order. Elements of the matrix are rate constants (1/s) of the transtions between the eigenstates.

• cal (Object containing results during calculations.) – This function uses the spin attribute cal.s and the systems eigenvectors cal.eigvec.

Raises:

AttributeError – An attribute error is raised if neither sys.T_relax_1 nor sys.dynamics is given.

Returns:

relax – Relaxation superoperator, dimension n**2 x n**2. The relaxation superoperator is given back in the basis of the systems Hamiltonian.

Return type:

np.ndarray

teacups.relaxation.phenomenological_relaxation_superoperator(T_relax_1: float, T_relax_2: float, dimension: float) → ndarray

Create the phenomenological relaxation superoperator for a spin system using the relaxation times T1 (longitudinal) and T2 (transversal). The superoperator matrix is set up in the eigenbasis of the system with ascending order of the eigenvalues.

Parameters:

• T_relax_1 (float) – Longitudinal relaxation time describing spin-lattice relaxation.

• T_relax_2 (float) – Transversal relaxation time describing FID.

• dimension (float) – Hilbert space dimension of the matrices. E.g. for a triplet dimension = 3.

Returns:

relaxation_superop – Relaxation superoperator matrix in the systems eigenbasis. Its shape is dimension**2 x dimension**2.

Return type:

numpy.array

teacups.relaxation.relaxation_operator_to_hamiltonian_basis(relaxation_superoperator: ndarray, eigvec: ndarray) → ndarray

Transform the relaxation superoperator from the eigenbasis of the Hamiltonian to the basis of the Hamiltonian that is used during all calculations. The Hamiltonian is B-angle-matrix-style. After transformation the relaxaton superoperator has this shape too, as basistransformation is done for every B- and angle-point.

The matrix containing the eigenvectors of the system is defined by:

\[H_\mathrm{diag} = v^{-1} H v\]

In superoperator space the transformationmatrix for the identical basistransformation can be set up as

\[v_\mathrm{super} = v \otimes v\]

so that a basistransformation of a superoperator R can be done by:

\[R_\mathrm{H basis} = v_\mathrm{super} \cdot R_\mathrm{diag} \cdot v_\mathrm{super}^{-1}.\]

Parameters:

• relaxation_superoperator (np.ndarray) – Quadratic superoperator containing the relaxation rates between the eigenstates of the spinsystem in ascending order from left to right.

• eigvec (np.ndarray) – Eigenvectors of the spin systems Hamiltonian that can be used for basistransformation between the eigenstates and the main basis for further calculations. The shape of this array is B_points x angle_points x dim x dim.

Returns:

relaxation – Relaxationsuperoperator in the same basis as the systems Hamiltonian. It has the shape of a B-angle-matrix now.

Return type:

np.ndarray

teacups.relaxation.superoperator_coherence_relaxation(k, dimension)

Calculate a superoperator for the decay of the coherences of a matrix. The coherences will decay with the rate constant k.

Parameters:

• k (float) – Rate constant of the decay of the coherences.

• dimension (int) – Hilbert space dimension of the matrices. E.g. for a triplet dimension = 3.

Returns:

R – Relaxationsuperoperator for the coherences. All diagonal elements that are assignable to the coherences are set to the negative value of k. E.g.:

   aa ab ba bb
aa
ab    -k
ba      -k
bb

Return type:

np.ndarray

teacups.relaxation.superoperator_population_relaxation(k_matrix)

Calculate a relaxation superoperator for transitions between the states. A matrix k_matrix can be given containing the relaxation rates for the transitions between the populations. The decay of the populations is calculated as a sum of the transitions to other states. Diagonal elements of the k_matrix give decay rates of populations to other states (which are not described by the matrix, e.g. a ground state). Attention: If diagonal elements are defined the superoperator changes the trace of the density matrix and it does not stay 1.

Parameters:

k_matrix (np.ndarray) –

Matrix containing the transition rates between the states. E.g.:

             a b c
           a 4 1 2
k_matrix = b 1   3
           c 2 3

for the transition sceme:

a <-> b: 1
a <-> c: 2
b <-> c: 3

Returns:

R – Relaxation superoperator. Its dimension is the dimension of T1_matrix squared. E.g.:

   aa  ab  ac  ba  bb  bc  ca  cb  cc
aa 1                1               2
ab
ac
ba
bb  1              -4               3
bc
ca
cb
cc  2               3              -5

Return type:

np.ndarray

signals_and_processing.py

Timeevoultion and detection functions can be found in this module.

teacups.signals_and_processing.make_signal(exp: object, opt: object, cal: object) → None

Calculate the signal of a transient EPR experiment. Signals will be given back as an array containing the intensity in abitrary units for each combination of time, magnetic field and orientation.

It can be chosen if the signal will be calculated in liouville or in hilbert space. In lioville space optionally (if opt.pop_evolution is set to True) the time evolution of the population of the eigenstates is calculated. The signal is returned in cal.signal, the population evolution in cal.pop_evolution.

Parameters:

• exp (object) – Contains experimental parameters. This function uses exp.B_z.

• opt (object) – Contains simulation option parameters. This function uses opt.space for choosing the space in which the signal shall be calculated (hilbert or liouville) and opt.grid_points. In liouville space the attribute opt.pop_evolution is necessary (True or Flase) to choose if the population evolution shall be calculated. Further the number of desired cpu cores has to be given to opt.cpu_cores.

• cal (object) – Contains the results calculated during the simulation. This function uses the space cal.t (e.g. built by the function set_up_spaces), cal.propagation (propagation matrix see above), cal.rho (see set_up_density_matrix) and cal.observable (see set_up_observable).

cal.signal

This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z and all orientation points. So the shape is len(t)xlen(B)xgrid_points.

Type:

np.ndarray

cal.pop_evolution

Conrtains the populations of all eigenstates as a function of time. As eigenstates the states of the first magnetic field point and the first angle point are chosen.

Type:

np.array

Return type:

None.

teacups.signals_and_processing.multicore(time_evolution_function: callable) → callable

Using multiprocessing.Pool() with starmap() for parallel computing of a time evolution. The spectrum is split along the orientations-axis.

Parameters:

time_evolution_function (callable) – Time evolution function dependent on the calculations object cal.

Returns:

multicore_wrapper – The origin time evolution callable as multicore version.

Return type:

callable

teacups.signals_and_processing.powder_average(opt: object, cal: object) → None

Build the powder average of a signal. Depending on the chosen grid, points are just summed up for all orientations (opt.grid=’fibonacci’, opt.grid=’single’) or the signal is weightened and summed up for all orientations (opt.grid=’sophe’).

Parameters:

• exp (object) – Contains experimental parameters. This function uses exp.B_z for the interpolation.

• opt (object) – Contains simulation option parameters. This function uses opt.grid in order to determine if interpolation shall be done. In case of a sophe grid the attributes opt.number_of_peaks (number of peaks that are expected for each orientational spectrum) and opt.width_intp(the scaled gaussian line width for convolution before peak finding is done) are used.

• cal (object) – Contains the results calculated during the simulation. This function uses cal.signal. This array contains the intensities of a signal for all time points, magnetic field points and orientational points and can be built by the function make_signal.

cal.spec_sim

This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z. So the shape is len(t)xlen(B).

Type:

np.ndarray

Return type:

None

teacups.signals_and_processing.propagation(sys: object, opt: object, cal: object) → None

Calculate a time propagation operator matrix for a given hamiltonian. It can be chosen in which space (hilbert or liouville) the operator will be set up. A relaxation operator is taken into account.

Parameters:

• sys (object) – Contains parameters of the spin system. This function uses the relaxation time attributes T_relax_1 and T_relax_2 (if space is set to ‘liouville’) and decay (if space ist set to ‘hilbert’).

• opt (object) – Contains simulation option parameters. This function uses opt.space to choose in which space the propagation matrix is calculated.

• cal (object) – Contains calculated results during the simulation. This function uses cal.ham (the hamiltonian) and cal.t (time space).

cal.propagation

Time propagation operator. If opt.space is hilbert the dimension of the matrix will be B x grid_points x 4 x 4. If opt.space is liouville the dimension of the matrix will be B x grid_points x 16 x 16. It contains a single propagation operator which has to be used on the density matrix t_points times in a row.

Type:

np.ndarray

Return type:

None.

teacups.signals_and_processing.signal_hilbert_decay(sys: object, cal: object) → None

Multiply each time-spectrum with an exponential term for simulating a decay of the system in hilbert space.

Parameters:

• sys (object) – Contains parameters of the spin system. This function uses sys.decay (decay time in s).

• cal (object) – Contains results calculated during the simulation. This function uses cal.spec_sim (from the function make_signal) and cal.t (time-array).

cal.spec_sim

The time arrays are multiplied with an exponential decay. The shape is not changed.

Type:

np.ndarray

Return type:

None

teacups.signals_and_processing.time_evolution_hilbert(cal: object) → ndarray

Calculate the time evoluted signal in hilbert space.

Parameters:

cal (object) – Contains premier calculated results. This function uses the propagator cal.propagation, the time axis cal.t, the density matrix cal.rho and the observable operator cal.observable.

Returns:

cal.signal – This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z and all orientation points. So the shape is len(t)xlen(B)xgrid_points.

Return type:

np.ndarray

teacups.signals_and_processing.time_evolution_liouville(cal: object) → ndarray

Calculate the time evoluted signal in liouville space.

Parameters:

cal (object) – Contains premier calculated results. This function uses the propagator cal.propagation (in superoperator dimension), the time axis cal.t, the density matrix cal.rho (as a vector) and the observable operator cal.observable (as a vector).

Returns:

cal.signal – This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z and all orientation points. So the shape is len(t)xlen(B)xgrid_points.

Return type:

np.ndarray

teacups.signals_and_processing.time_evolution_multicore(opt: object, cal: object) → None

Calculate the time evolution of a signal on multiple cpu-cores. It can be chosen in the calculation is done in hilbert or in liouville space.

Parameters:

• opt (object) – Simulation options object. This function uses opt.space to choose the calculation space and opt.cpu_cores to determine the number of cores used for calculation. Further opt.grid_points has to be given.

• cal (object) – Previously calculated results. This function uses the propagator cal.propagation, the time axis cal.t, the density matrix cal.rho and the observable operator cal.observable.

cal.signal

This matrix contains the intensities in abitrary units of a transient epr spectrum for all time points t in cal.t and all magnetic field points in exp.B_z and all orientation points. So the shape is len(t)xlen(B)xgrid_points.

Type:

np.ndarray

Return type:

None

simulations.py

Here the main simulation function, that calls all other functions in the neccessary order, can be found.

teacups.simulations.teacups(Sys: object, Exp: object, SimOpt: object) → ndarray

Simulate a 2D transient EPR spectrum of a spinpolarized spin system.

Parameters:

• Sys (object) – Spinsystem object, that contains parameters of the spin system. Attributes can be given to this object in the following syntax: sys.attribute = ?.

• Exp (object) – Experiment object, that contains parameters of the experiment. Attributes can be given to this object in the following syntax: sys.attribute = ?.

• SimOpt (object) – Simulationoptions object, that contains simulation option parameters. Attributes can be given to this objects in the following syntax: sys.attribute = ?.

Returns:

• intensity (np.ndarray) – 2D Array containing the simulated intensities in arbitrary units. One dimension is the magnetic field, the other is the time.

• pop_evolution (np.ndarray) – Population_evolution is optionally given back if SimOpt.pop_evolution is True and SimOpt.space is ‘liouville’.

General modules

These modules contain functions that are generally usable (and could be used outside of teacups). Included are, amongst other things, the setup of a grid on a sphere, the Gaussian convolution of a spectrum, or the general setup of a relaxation matrix/ Hamiltonian. The functions take parameters as input and return the desired output. They do not use the four-class system, which makes them more flexible.

convolution.py

The functions in this module are written to convolve a calculated 2D-spectrum along the B-axis. Gaussian convolution or isotrope hyperfine convolution are provided.

teacups.convolution.extend_time_axis(t: ndarray, spec: ndarray) → ndarray

If the time axis is shorter than the time-dimension of the spectrum it gets extended by negative values.

Parameters:

• t (np.ndarray) – Time axis.

• spec (np.ndarray) – 2D-Array containing values of the ordinate of a spectrum. In case of TREPR spectra this would be the intensity for each time and magnetic field point. The convolution is carried out along the second axis.

Returns:

t_extended – Time axis. If it has been shorter than the first dimension of spec before it is extended by negative values.

Return type:

np.ndarray

teacups.convolution.voigt_convolution(sigma_time: float, width: float, spectrum: ndarray, extend_t=False) → ndarray

Calculate the Voigt profile of a Lorentzian function by convolution of the existing Lorentzian function and a Gaussian distribution with a given FWHH. A 2D-spectrum is convolved with the Gaussian function along its second axis, which should be the B-field-axis. Additional the spectrum is convolved with a second Gaussian distribution along the first axis (time-axis) for simulating the time resoltuion of the signal.

Parameters:

• width_time (float) – Standardderivation of the Gauß-Filter, Time resolution of the signal. In pixels.

• width (float) – Gaussian line width, standard deviation. In pixels.

• spectrum (np.ndarray) – 2D-Array containing values of the ordinate of a spectrum. In case of TREPR spectra this would be the intensity for each time and magnetic field point. The convolution is carried out along the second axis.

• extend_t (bool) – If true the time axis is extended by a zero-baseline with 5*time_sigma pixels. Default is False.

Returns:

spectrum_conv – Array containing convoluted values of the ordinate. In case of TREPR spectra this would be the covoluted intensities of the spectrum for each magnetic field and time point. Spectrum_conv is computed using the convolution alogrithm of SciPy.

Return type:

np.ndarray

grid.py

Functions for the calculation of a given number of points equally distributed on a fibonacci sphere or using a sophe grid and coordinate transformation from cartesian to spherical coordinates are provided here.

teacups.grid.cartesian2sphereical(xyz: ndarray) → ndarray

Convert a set of three cartesian coordinates (x, y and z) to a set of three spherical coordinates (r, theta and phi).

Parameters:

xyz (np.ndarray) – This array contains n sets of cartesian coordinates x, y and z and its shape is (nx3)

Returns:

rtp – This array contains the transformed sets of xyz. Its shape is (nx3).

Return type:

np.ndarray

teacups.grid.fibonacci_grid(grid_points: int) → tuple['np.ndarray', 'np.ndarray']

Get a number (grid_points) of angle pairs theta-phi describing points equally distributet on a fibonacci sphere. The radius is 1.

Parameters:

grid_points (int) – Number of points on the sphere.

Returns:

• theta (np.ndarray) – 1D-Array with grid_points theta angles. Each angle is the theta-part of the spherical coordinate of each point.

• phi (np.ndarray) – 1D-Array with grid_points phi angles. Each angle is the phi-part of the spherical coordinate of each point.

teacups.grid.sophe_grid(grid_size: int, sym: str) → tuple['np.ndarray', 'np.ndarray', 'np.ndarray']

Calculate the angles phi and theta of a set of unique orientations on a sphere. The grid used is called SOPHE grid (see: D. Wang, G. R. Hanson J.Magn.Reson. A, 117, 1-8 (1995) https://doi.org/10.1006/jmra.1995.9978) or Y. Kurihara, Monthly Weather Review 93(7), 399-415 (July 1965) https://doi.org/10.1175/1520-0493(1965)093<0399:NIOTPE>2.3.CO;2). The grid is set up by the epr_grid module, which is written by Florian Quintes.

Parameters:

• grid_size (int) – Number of points between theta=0 and theta=pi/2.

• sym (str) – Point group symmetry. “C1” returns the full sphere, other point groups result in smaller parts of the sphere.

Returns:

• phi (np.ndarray) – Set of spherical angles phi for all orientations.

• theta (np.ndarray) – Set of spherical angles theta for all orientations.

• weights (np.ndarray) – Associated weights for each orientation.

teacups.grid.sphere_fibonacci_grid_points(ng: int, hemisphere=True) → ndarray

Calculate Fibonacci spiral gridpoints on a hemisphere or full sphere.

Parameters:

• ng (int) – Number of points that shall be calculated.

• hemisphere (boolean, optional) – Define wether a full or a hemisphere is calculated. Default is True.

Returns:

• xg (np.ndarray) – Coordinates of the desired number of grid points. The three cartesian coordinates are given. The shape of the array is 3xng.

• Licensing

• ——— – This code is distributed under the GNU LGPL license. https://people.sc.fsu.edu/~jburkardt/py_src/sphere_fibonacci_grid/sphere_fibonacci_grid.py

• Modified

• ——– – 15 May 2015

• Author

• —— – John Burkardt

• Reference

• ——— – Richard Swinbank, James Purser, Fibonacci grids: A novel approach to global modelling, Quarterly Journal of the Royal Meteorological Society, Volume 132, Number 619, July 2006 Part B, pages 1769-1793.

teacups.grid.spherical2cartesian(rtp: ndarray) → ndarray

Convert a set of three spherical coordinates (r, theta and phi) to a set of three cartesian coordinates (x, y and z).

Parameters:

rtp (np.ndarray) – This array contains n sets of spherical coordinates r, theta and phi and its shape is (nx3).

Returns:

xyz – This array contains n sets of cartesian coordinates x, y and z. Its shape is (nx3).

Return type:

np.ndarray

orientation_dependent_ham.py

The tensor rotation function and the creation of linear and bilinear Hamiltonians can be found here.

teacups.orientation_dependent_ham.create_bilinear_hamiltonian(spinop1: ndarray, tensor: ndarray, spinop2: ndarray) → ndarray

Create a bilinear interaction Hamiltonian between two spin vectors, spinop1 and spinop2, and an interaction matrix tensor.

Parameters:

• spinop1 (np.ndarray) – Spin vector operator of the first interacting Spin. Contains nxn spin-operator-matrices: [S_x, S_y, S_z].

• tensor (np.ndarray) – 3x3 - Interaction matrix between the two spin vectors.

• spinop2 (np.ndarray) – Spin vector operator of the second interacting spin. Contains nxn spin-operator-matrices: [S_x, S_y, S_z].

Returns:

ham – Bilinear interaction Hamiltonian. H = spinop1*tensor*spinop2. The shape will be nxn.

Return type:

np.ndarray

Examples

>>> sigma_x = np.array([[0, 0.5], [0.5, 0]])
>>> sigma_y = np.array([[0, -1j/2], [1j/2, 0]])
>>> sigma_z = np.array([[0.5, 0], [0, -0.5]])
>>> unit = np.eye(2)
>>> S_x = np.kron(sigma_x, unit)
>>> S_y = np.kron(sigma_y, unit)
>>> S_z = np.kron(sigma_z, unit)
>>> S = np.array([S_x, S_y, S_z])
>>> D = np.array([[0.5, 0, 0], [0, 1.5, 0], [0, 0, -2]])
>>> create_bilinear_hamiltonian(S, D, S)
array([[0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j]])

teacups.orientation_dependent_ham.create_linear_hamiltonian(tensor: ndarray, spinop: ndarray, z=True) → ndarray

Create a linear interaction Hamiltonian (e.g. Zeeman interaction) between a spin vector S and an interaction matrix tensor.

Choose between either the x- and y- components of a third vector beeing multiplied (e.g. static magnetic field vector) set to zero (perpendicular magnetic field) or the y- and z- components set to zero (parallel magnetic field).

Parameters:

• tensor (np.ndarray) – Interaction matrix between spin vector and magnetic field. The shape is 3x3.

• spinop (np.ndarray) – Spin vector operator. Contains nxn spin-operator-matrices: [S_x, S_y, S_z].

• z (bool, optional) – Gives choice which component of the third vector is not set to zero. The default is True.

Returns:

ham – Linear interaction Hamiltonian. The shape is nxn H = S*tensor*magnetic-field-vector.

Return type:

np.ndarray

Examples

>>> sigma_x = np.array([[0, 0.5], [0.5, 0]])
>>> sigma_y = np.array([[0, -1j/2], [1j/2, 0]])
>>> sigma_z = np.array([[0.5, 0], [0, -0.5]])
>>> unit = np.eye(2)
>>> S_x = np.kron(sigma_x, unit)
>>> S_y = np.kron(sigma_y, unit)
>>> S_z = np.kron(sigma_z, unit)
>>> S = np.array([S_x, S_y, S_z])
>>> g = np.array([[2.0, 0, 0], [0, 2.01, 0], [0, 0, 2.02]])
>>> create_linear_hamiltonian(g, S)
array([[ 1.01+0.j,  0.  +0.j,  0.  +0.j,  0.  +0.j],
       [ 0.  +0.j,  1.01+0.j,  0.  +0.j,  0.  +0.j],
       [ 0.  +0.j,  0.  +0.j, -1.01+0.j,  0.  +0.j],
       [ 0.  +0.j,  0.  +0.j,  0.  +0.j, -1.01+0.j]])
>>> create_linear_hamiltonian(g, S, z=False)
array([[0.+0.j, 0.+0.j, 1.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j, 0.+0.j, 1.+0.j],
       [1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
       [0.+0.j, 1.+0.j, 0.+0.j, 0.+0.j]])

teacups.orientation_dependent_ham.tensor_rotation(tensor: ndarray, phi: float, theta: float, psi=0.0) → ndarray

Euler transformation of a given tensor using y-convention.

Euler matrix is set up with the given angles in the multiplicated form. Unitytransformation is carried out.

Parameters:

• tensor (np.ndarray) – Tensor in main axes system which will be rotated by euler transformation. The shape has to be 3x3.

• phi (float) – First euler angle given in rad.

• theta (float) – Second euler angle given in rad.

• psi (float, optional) – Third euler angle given in rad. The default is 0.

Returns:

rotated_tensor – Tensor after euler transformation.

Return type:

np.ndarray

Examples

>>> tensor_rotation(np.array(([1, 2, 3], [0, 0, 0], [0, 0, 0])), 1, 2)
array([[ 0.821379  , -0.05376802, -0.17383894],
       [ 3.07396785, -0.20122401, -0.65058311],
       [-1.79474586,  0.11748527,  0.37984501]])

Structuring modules

All matrices of the specific simulation modules are objects of the classes defined in the structuring modules: matrix_tools and multioperator_tools. Both classes define matrices including methods like rotation to a number of angle combinations, the setup of a Hamiltonian etc. An object of class Multioperator has an attribute called B_angle_matrix. This is a three-dimensional NumPy array containing the values of the operator for a number of magnetic field points and a number of angle points. Its dimension is len(B) x len(angles) x spinsystem dimension x spinsystem dimension. The specific simulation modules often use objects of Multioperator-type, which has the advantage, that calculations can be done for all field points and angle points at once without using loops. This makes the code much faster.

matrix_tools.py

This module provides classes for basic matrices that are needed for calculations of EPR spectra like a Hamiltonian, tensor or a spinoperator.

class teacups.matrix_tools.Hamiltonian(dimension: int)

A Hamiltonian object is the same as an Operator object, but some functions are added.

Parameters:

dimension (int) – Dimension of matrix which is generated.

matrix

Array containing only zeros. The shape of the array is dimension x dimension.

Type:

np.ndarray

dimension

Dimension of the matrix.

Type:

int

vector

Flattened matrix. The new dimension is 1 x dimension^2.

Type:

np.ndarray

superop

Attribute can be filled by the function build_superoperator.

Type:

None

dipol_coupling(spinoperator1: object, D_tensor: ndarray, spinoperator2: object) → None

Calculate the hamiltonian of a dipolar coupling of two spins.

Parameters:

• spinoperator1 (object) – Spin vector operator of the first interacting spin. This is a Spinoperator object.

• D_tensor (np.ndarray) – Dipolar coupling tensor in xyz-frame. The shape is 3 x 3.

• spinoperator2 (object) – Spin vector operator of the first interacting spin. This is a Spinoperator object.

matrix

Hamiltonian of dipolar coupling.

Type:

np.ndarray

Return type:

None.

Examples

>>> h = Hamiltonian(4)
>>> s1 = Spinoperator(1/2, 1/2)
>>> s2 = mt.Spinoperator(1/2, 1/2)
>>> s2.matrix = s1.matrix_coupling_spins[0]
>>> d = Tensor(np.arange(1, 4))
>>> h.dipol_coupling(s1, d.matrix, s2)
>>> h.matrix
array([[ 4.5+0.j,  0. +0.j,  0. +0.j, -0.5+0.j],
       [ 0. +0.j,  1.5+0.j,  1.5+0.j,  0. +0.j],
       [ 0. +0.j,  1.5+0.j,  1.5+0.j,  0. +0.j],
       [-0.5+0.j,  0. +0.j,  0. +0.j,  4.5+0.j]])

exchange_coupling(spinoperator1: object, J_ex: float, spinoperator2: object) → None

Calculate interaction hamiltonian of the exchangecoupling of two spins.

Parameters:

• spinoperator1 (object) – Spin vector operator of the first interacting spin. This is a Spinoperator object.

• J_ex (float) – Exchange coupling constant.

• spinoperator2 (object) – Spin vector operator of the second interacting spin. This is a Spinoperator object.

matrix

Hamiltonian of exchange coupling in matrix representation.

Type:

np.ndarray

Return type:

None.

Examples

>>> h = Hamiltonian(2)
>>> j = 5.2
>>> s = Spinoperator(1/2)
>>> h.exchange_coupling(s, j, s)
>>> h.matrix
array([[-10.4+0.j,  -0. +0.j],
       [ -0. +0.j, -10.4+0.j]])

microwave_coupling(omega_mw: float, omega_nut: float, spinoperator: object) → None

Calculate the interaction hamiltonian of a spinoperator with a magnetic microwave-field in the rotating frame representation. Therefore, the hamiltonian is set up as the sum of the interaction hamiltonian with the microwave-field and the offset-hamiltonian which describes the shift of all lamor frequencies in rotating frame: H = H_mw - H_off.

Parameters:

• omega_mw (float) – Frequency of the microwave-field. Used as rotation frequency of the rotating frame.

• omega_nut (float) – Nutation frequency of precession of the spin around microwave- field. Calculatable by omega_nut = 1/2*g*mu_B*B_x (all scalars).

• spinoperator (object) – Spin vector operator of the interacting spin. This is a Spinoperator object.

matrix

Hamiltonian of coupling with the microwave-field in a rotating frame in matrix representation.

Type:

np.ndarray

Return type:

None.

Examples

>>> h = Hamiltonian(2)
>>> s = Spinoperator(1/2)
>>> h.microwave_coupling(9.75, 1.4, s)
>>> h.matrix
array([[ 4.875+0.j, -0.7  +0.j],
       [-0.7  +0.j, -4.875+0.j]])

zeeman_coupling(g: ndarray, B_z: float, spinoperator: object) → None

Calculate the hamiltonian of the Zeeman coupling of a spin (represented by a spin vector operator) and a magnetic field along the z-Axis.

Parameters:

• g (np.ndarray) – g-Tensor of electron interacting with the magnetic field in xyz-frame. The dimension is 3 x 3.

• B_z (float) – Magnetic field strenght in z-direction. All other directions are set to zero!

• spinoperator (object) – Spin vector operator of the interacting spin. This is a Spinoperator object.

matrix

Hamiltonian of coupling with a static magnetic field in z-direction.

Type:

np.ndarray

Return type:

None.

Examples

>>> h = Hamiltonian(2)
>>> s = Spinoperator(1/2)
>>> g = Tensor(np.arange(1, 4))
>>> h.zeeman_coupling(g.matrix, 42.5, s)
>>> h.matrix
array([[ 63.75+0.j,   0.  +0.j],
       [  0.  +0.j, -63.75+0.j]])

class teacups.matrix_tools.Matrix(dimension: int)

A Matrix-object contains the dimension and the matrix of a square matrix.

Parameters:

dimension (int) – Dimension of matrix which is generated.

matrix

Array containing only zeros. The shape of the array is dimension x dimension.

Type:

np.ndarray

dimension

Dimension of matrix.

Type:

int

Raises:

ValueError – ValueError is raised, if the dimension is no integer.

Examples

>>> m = Matrix(2)
>>> m.matrix
array([[0., 0.],
       [0., 0.]])
>>> m.dimension
2

basis_transformation(trans: ndarray, inverse_left=True, orthonormal=False) → None

Change the basis of matrix. trans is the transformation matrix:

\[M = T^{-1} \cdot M \cdot T.\]

Parameters:

• trans (np.ndarray) – Transformation matrix containing arrays of the new basis. The array has to have the same shape as the matrix attribute.

• inverse_left (boolean, optional) – Defines the direction of the basis transformation. If set to True the inverse of the transformation matrix is multiplied from the left side. If set to false, the inverse of the transformation matrix is multiplied from the right side and the direction of the basistransformation is reversed. The default is True.

• orthonormal (boolean, optional) – If orthonormal is set to True the basis transforation is done by using the adjungate instead of the inverse transformation matrix in calculation. This is possible if old and new basis consist only of orthonormal vectors. The default is False.

matrix

Matrix in new basis system.

Type:

np.ndarray

Return type:

None.

Examples

>>> m = Matrix(2)
>>> m.matrix = np.arange(1, 5).reshape((2,2))
>>> trans = np.array([[0, 1/2], [-1/2, 0]])
>>> m.basis_transformation(trans)
>>> m.matrix
array([[ 4., -3.],
       [-2.,  1.]])

product(scd_matrix: ndarray, left=False) → None

Build matrix product of the matrix attribute and a second matrix being multiplied either from right (default) or from left side.

Parameters:

• scd_matrix (np.ndarray) – Matrix of same dimension as matrix attribute, which shall be multiplied with the matrix attribute.

• left (boolean, optional) – If left is set to True the matrix attribute is multiplied from the left side. If left is set to False it is multiplied from the right. The default is False.

Raises:

IndexError – IndexError is raised if the dimension of the second matrix is not the same as the dimension of matrix attribute.

matrix

Matrix attribute is changed to the multiplication product. The dimension is not changed.

Type:

np.ndarray

Return type:

None.

Examples

>>> a = np.arange(1, 5).reshape((2, 2))
>>> m = Matrix(2)
>>> m.matrix = a
>>> m.matrix
array([[1, 2],
       [3, 4]])
>>> m.product(m.matrix)
>>> m.matrix
array([[ 7, 10],
       [15, 22]])

scalar(multipliers: ndarray) → None

Build scalar product of the matrix attribute with the product of all multipliers.

Parameters:

multipliers (np.ndarray) – Array containing all scalars which shall be multiplied with each other and with the matrix. The shape of the array is n x 1.

matrix

Matrix attribute is changed by being multiplied with the scalars. The shape of the matrix is still dimension x dimension.

Type:

np.ndarray

Return type:

None.

Examples

>>> m = Matrix(2)
>>> m.matrix[0, 0] = 2
>>> m.matrix[1, 1] = 3
>>> multipliers = np.array([2, 3, 4])
>>> m.matrix
array([[2., 0.],
       [0., 3.]])
>>> m.scalar(multipliers)
>>> m.matrix
array([[48.,  0.],
       [ 0., 72.]])

class teacups.matrix_tools.Operator(dimension: int)

An Operator object is an object of class matrix, which has two additional attributes: The vector attribute and the superop attribute.

Parameters:

dimension (int) – Dimension of matrix which is generated.

matrix

Array containing only zeros. The shape of the array is dimension x dimension.

Type:

np.ndarray

dimension

Dimension of the matrix.

Type:

int

vector

Flattened matrix. The new dimension is 1 x dimension^2.

Type:

np.ndarray

superop

Attribute can be filled by the function build_superoperator.

Type:

None

build_superoperator(swap=False) → None

Double the dimension of the matrix operator (in case of use in a higher dimensional space). Tensor product of operator with unit matrix of the same dimension is built using the numpy.kron function.

Parameters:

swap (Boolean, optional) – If swap is False the tensor product is built wiht matrix on left and unit matrix on right site. If swap is set to any other value matrix and unit matrix are swapped. The default is False.

superop

Result of tensor product of matrix and unit matrix. The dimension is 2*dimension x 2*dimension.

Type:

numpy array

Return type:

None.

Examples

>>> o = Operator(2)
>>> o.matrix[0, 0] = 1
>>> o.build_superoperator()
>>> o.superop
array([[1., 0., 0., 0.],
       [0., 1., 0., 0.],
       [0., 0., 0., 0.],
       [0., 0., 0., 0.]])
>>> o.build_superoperator(swap=True)
>>> o.superop
array([[1., 0., 0., 0.],
       [0., 0., 0., 0.],
       [0., 0., 1., 0.],
       [0., 0., 0., 0.]])

build_vector() → None

Changing the dimension of the matrix attribute to a 1d vector using .flatten()-function for numpy arrays. Lines are simply written in only one long line.

vector

Vector array containing all values of the matrix in one line. The new dimension is 1 x dimension^2

Type:

np.ndarray

Return type:

None.

Examples

>>> o = Operator(2)
>>> o.matrix[1, 0] = 1
>>> o.matrix
array([[0., 0.],
       [1., 0.]])
>>> o.build_vector()
>>> o.vector
array([0., 0., 1., 0.])

class teacups.matrix_tools.Spinoperator(spin=0.5, coupling_spins=None)

By creating a spinoperator object the pauli matrices for a spin (with any spin quantum number) are calculated. Optionally the spin is coupled to any number of further arbitrary spins (e.g. nuclear spins). In this case the Pauli matrices of the coupled spins will be calculated, too.

If no nuclear spin quantum number(s) is (are) provided, the Pauli matrices are only set up for the uncoupled spin.

If the uncoupled spin is not provided, an electron spin of s = 1/2 is used. The Pauli matrices of the coupled spins are ordered according to the corresponding input array as the tensor products are calculated in exactly this order.

Parameters:

• spin (float, optional) – Spin quantum number for the spin of the Spinoperator object. The default is 1/2.

• coupling_spins (np.ndarray, optional) – Spin quantum number or an array of spin quantum numbers of further coupling spins. The default is None.

matrix

This array contains three nxn-matrices. The first one is the x-spinoperator, second is y-operator and third is z-operator.

Type:

np.ndarray

dimension

Hilbert-space-dimension of single spin-operators of each cartesian direction.

Type:

int

matrix_coupling_spins

If coupling spins are provided this matrix contains the three Pauli matrices for all coupling spins in the order of the input array.

Type:

np.ndarray

vector

Flattened matrix attribute.

Type:

np.ndarray

Examples

>>> s = Spinoperator(1/2)
>>> s.matrix
array([[[ 0. +0.j ,  0.5+0.j ],
        [ 0.5+0.j ,  0. +0.j ]],

       [[ 0. +0.j ,  0. -0.5j],
        [ 0. +0.5j,  0. +0.j ]],

       [[ 0.5+0.j ,  0. +0.j ],
        [ 0. +0.j , -0.5+0.j ]]])
>>> s.dimension
2

>>> s = spinoperator(1/2, 1/2)
>>> print(s.matrix)
[[[[ 0. +0.j   0. +0.j   0.5+0.j   0. +0.j ]
[ 0. +0.j   0. +0.j   0. +0.j   0.5+0.j ]
[ 0.5+0.j   0. +0.j   0. +0.j   0. +0.j ]
[ 0. +0.j   0.5+0.j   0. +0.j   0. +0.j ]]
[[ 0. +0.j   0. +0.j   0. -0.5j  0. +0.j ]
[ 0. +0.j   0. +0.j   0. +0.j   0. -0.5j]
[ 0. +0.5j  0. +0.j   0. +0.j   0. +0.j ]e vector attribute and the superop attrib
[ 0. +0.j   0. +0.5j  0. +0.j   0. +0.j ]]
[[ 0.5+0.j   0. +0.j   0. +0.j   0. +0.j ]
[ 0. +0.j   0.5+0.j   0. +0.j   0. +0.j ]
[ 0. +0.j   0. +0.j  -0.5+0.j  -0. +0.j ]
[ 0. +0.j   0. +0.j  -0. +0.j  -0.5+0.j ]]]]
>>> print(s.matrix_coupling_spins)
[[[[ 0. +0.j   0.5+0.j   0. +0.j   0. +0.j ]
[ 0.5+0.j   0. +0.j   0. +0.j   0. +0.j ]
[ 0. +0.j   0. +0.j   0. +0.j   0.5+0.j ]
[ 0. +0.j   0. +0.j   0.5+0.j   0. +0.j ]]
[[ 0. +0.j   0. -0.5j  0. +0.j   0. +0.j ]
[ 0. +0.5j  0. +0.j   0. +0.j   0. +0.j ]
[ 0. +0.j   0. +0.j   0. +0.j   0. -0.5j]
[ 0. +0.j   0. +0.j   0. +0.5j  0. +0.j ]]
[[ 0.5+0.j   0. +0.j   0. +0.j   0. +0.j ]
[ 0. +0.j  -0.5+0.j   0. +0.j  -0. +0.j ]
[ 0. +0.j   0. +0.j   0.5+0.j   0. +0.j ]
[ 0. +0.j  -0. +0.j   0. +0.j  -0.5+0.j ]]]]

get(coordinate: str) → ndarray

Get the spin operator matrices for each cartesian direction out of the matrix attribute.

Parameters:

coordinate (str) – Coordinate can be either ‘x’, ‘y’ or ‘z’. The appropriate spin operator is chosen.

Raises:

ValueError – If an other character is filld in for coordinate.

Returns:

matrix[i] – Cartesian operator of S which is chosen by coordinate.

Return type:

np.ndarray

Examples

>>> s = Spinoperator(1/2)
>>> s.get('x')
array([[0. +0.j, 0.5+0.j],
       [0.5+0.j, 0. +0.j]])

pauli_matrices(spin: float)

Create the three Pauli matrices for each cartesian direction for a given spin quantum number.

Parameters:

spin (float) – Spin quantum number of spin. Matrix operators are set up for this spin quantum number.

Returns:

• sigma_x (np.ndarray) – Array contains the x-Pauli-matrix.

• sigma_y (np.ndarray) – Array contains the y-Pauli-matrix.

• sigma_z (np.ndarray) – Array contains the z-Pauli-matrix.

Examples

>>> s = Spinoperator(1/2)
>>> s.pauli_matrices(1/2)
(array([[0. +0.j, 0.5+0.j],
        [0.5+0.j, 0. +0.j]]),
 array([[0.-0.j , 0.-0.5j],
        [0.+0.5j, 0.-0.j ]]),
 array([[ 0.5+0.j,  0. +0.j],
        [ 0. +0.j, -0.5+0.j]]))

Notes

©Stephan Rein, modified by Theresia Quintes

class teacups.matrix_tools.Tensor(diagonal: list)

An object from class Tensor is a special Matrix object. The matrix attribute contains a diagonal 3x3 matrix. The diagonal elements are given when setting up the object. The class Tensor provides functions for the rotation of a tensor to other frames.

Parameters:

diagonal (np.ndarray) – 1D-List (or array) containing exactly 3 diagonal elements of the tensor. All other values in the tensor matrix will be set to zero.

matrix

The matrix attribute is a diagonal 3x3-matrix which contains the diagonal elements given in “diagonal”.

Type:

np.ndarray

dimension

The dimension of the matrix attribute is 3.

Type:

int

Examples

>>> a = np.arange(1, 4)
>>> t = tensor(a)
>>> t.matrix
array([[1., 0., 0.],
       [0., 2., 0.],
       [0., 0., 3.]])
>>> t.dimension
3

multirotation(phi: ndarray, theta: ndarray) → None

Rotate the tensor attribute to all combinations of theta and phi. The two arrays contain angles for each point that shall be calculated. All results are saved in a new multirot attribute.

Parameters:

• phi (np.ndarray) – Array with the phi values for each angle point.

• theta (np.ndarray) – Array with the theta values for each angle point.

multirot

Matrix containing the rotated tensor for each angle combination. The matrix has the dimension nKnots x 3 x 3.

Type:

np.ndarray

Return type:

None.

rotation(phi: float, theta: float, psi=0.0) → None

Rotate the tensor attribute by Euler rotation. The result is given to the attribute rot, while tensor remains unchanged.

Parameters:

• phi (float) – First euler angle given in rad.

• theta (float) – Second euler angle given in rad.

• psi (float, optional) – Third euler angle given in rad. The default is 0.

Raises:

ValueError – If dimension of tensor is not 3x3 ValueError will be raised, as the Euler transformation is not possible.

Return type:

None.

self.rot

Contains elements of the rotated tensor. The dimension is 3 x 3.

Type:

np.ndarray

Examples

>>> a = np.arange(1, 4)
>>> t = tensor(a)
>>> t.rotation(1, 1)
>>> t.rot
array([[ 2.62285229,  0.24564775, -0.58737276],
       [ 0.24564775,  1.29192658,  0.3825737 ],
       [-0.58737276,  0.3825737 ,  2.08522113]])

multioperator_tools.py

The Multioperator class is introduced here together with all its methods. This class is usable for fast array calculations as loops are not longer necessary. A Multioperator consists of a 3D-array: The outest dimension is the magnetic field, followed by the angle combinations. In the innerst dimension quadratic operators can be found. This are e.g. Hamiltonians. The Multioperaor provides the same methods as the classes from matrix_tools but they a applied for all quadratic matrices in the Multioperator.

class teacups.multioperator_tools.Multioperator(spinop: object, grid_points: int, B: ndarray)

An object of class Multioperator contains matrix attributes of different dimensions (see below). Furthermore it contains a tensor, a spinoperator and a magnetic fiels vector setting the dimensions. Spinoperator, rotated tensor and magnetic field vector are given to initialisation function.

Parameters:

• spinop (object) – Initialised attribute of the class Spinoperator. Therefore, it contains the spin of the system.

• grid_points (int) – Number of different orientations that shall be calculated. This determines the angle-dimension.

• B (np.ndarray) – Magnetic field vector. The length of this vector determines the B-dimension of the multioperator. This is a 1D-array

spinop

The spinop attribute contains the spinoperator given.

Type:

object

B

The B attribute contains the magnetic field vector given.

Type:

np.ndarray

dimension

The cartesian spinoperator matrices have the shape (dimension, dimension)

Type:

int

angle_shape

Dimension of angles and cartesian spinoperator matrices. The tuple order is: (grid_points, dimension, dimension)

Type:

tuple

B_angle_shape

Dimension of B-variation, angle-variations and cartesian spinoperator matrices. The tuple order is: (len(B), grid_points, dimension, dimension).

Type:

tuple

matrix

The matrix attribute contains only zeros but values can be changed. Represents the operator matrix for a single orientation and a single B-field-value. Its dimension is dimension x dimension.

Type:

np.ndarray

angle_matrix

Contains a dimension x dimension array for each pair of phi and theta angles. Its shape is equal to angle_shape.

Type:

np.ndarray

B_angle_matrix

Contains a angle_matrix for each B-fieldpoint. Its shape is equal to B_angle_shape.

Type:

np.ndarray

B_angle_vector

After initialisation it is NoneType but attribute can be changed later by the function build_vector. Afterwards it represents the B_angle_matrix in vector-dimension.

Type:

None

B_angle_superop

After initialisation it is NoneType but attribute can be changed later by the function build_superoperator. Afterwards it represents the B_angle_matrix in superoperator-dimension.

Type:

None

create_bilinear_operator(tensor, spinop2: object) → None

Create a bilinear interaction hamiltonian (e.g. dipol interaction) between the spinoperator attribute spinop, the interaction matrix tensor and a second spinoperator given to the function. The interaction hamiltonian is built for all angle combinations of phi and theta by using the rotated tensors from tensor.multirot. The interaction matrices are saved to angle_matrix attribute.

Parameters:

• tensor (object) – Tensor of for the bilinear interaction. E.g. for the dipolar interaction this would be the D-tensor. This parameter has to be an object from class tensor. The multiroation-function has to be carried out.

• spinop2 (object) – Spin vector operator of the second interacting spin. This has to be an object of class Spinoperator.

angle_matrix

Contains the bilinear interaction operators for each angle combination of phi and theta.

Type:

np.ndarray

Return type:

None.

create_linear_operator(tensor) → None

Create a linear interaction hamiltonian (e.g. Zeeman interaction) between the spinoperator attribute spinop and the interaction matrix tensor in case that the magnetic field vector is defined in z-direction. This is done for each angle combination of phi and theta by using the rotated tensors from tensor.multirot. The interaction matrices are saved to angle_matrix attribute.

Parameters:

tensor (object) – Tensor of for the linear interaction. E.g. for the Zeeman interaction this would be the g-tensor. This parameter has to be an object from class tensor. The multiroation-function has to be carried out.

angle_matrix

Contains the linear interaction operators for each angle combination of phi and theta.

Type:

np.ndarray

Return type:

None.

exchange_coupling(J_ex: float, spinop2: object) → None

Create an isotropic exchange coupling hamiltonian of two spins. Matrix attribute is changed and afterwards filled in angle_matrix and B_angle_matrix by using the function matrix_changed().

Parameters:

• J_ex (float) – Exchange coupling constant.

• spinop2 (object) – Spin vector operator of the second interacting spin. This has to be an object of class Spinoperator.

matrix

The exchange coupling hamiltonian of the spin and a second spin.

Type:

np.ndarray

angle_matrix

Contains the new built values of the matrix attribute for each angle combination.

Type:

np.ndarray

B_angle_matrix

Contains the new built values of the matrix attribute for each angle combination and each B-field point.

Type:

np.ndarray

Return type:

None.

microwave_coupling(omega_nut: float, omega_mw: float) → None

Calculate an isotropic interaction hamiltonian of spinoperator with a magnetic microwave-field in the rotating frame representation. Therefore, the hamiltonian is set up as the sum of the interaction hamiltonian with the microwave-field and the offset-hamiltonian which describes the shift of all lamor frequencies in rotating frame:

\[H = H_\mathrm{mw} - H_\mathrm{off}.\]

The matrix attribute is changed and afterwards filld in angle_matrix and B_angle_matrix by using the function matrix_changed().

Parameters:

• omega_mw (float) – Frequency of the microwave-field. Used as rotation frequency of the rotating frame.

• omega_nut (float) – Nutation frequency of precession of the spin around microwave- field. Calculatable by omega_nut = 1/2*g*mu_B*B_x (all scalars).

matrix

The microwave coupling hamiltonian of the spin and a microwave field in rotating frame representation.

Type:

np.ndarray

angle_matrix

Contains the new built values of the matrix attribute for each angle combination.

Type:

np.ndarray

B_angle_matrix

Contains the new built values of the matrix attribute for each angle combination and each B-field point.

Type:

np.ndarray

Return type:

None.

zeeman_coupling(g_tensor) → None

Claculate the hamiltonian of the zeeman coupling. Therefore, the interaction matrix is calculated by using the function create_linear_operator() for each angle combination. Afterwards each element from B attribute is multiplied to all hamiltonians (for each angle combination). The matrices (different for all angle pairs and B-field points) are saved to B_angle_matrix.

Parameters:

tensor (object) – g-Tensor of for the Zeeman interaction. This parameter has to be an object from class tensor. The multiroation-function has to be carried out.

B_angle_matrix

Contains the zeeman interaction hamiltonian for each magnetic field point and each angle combination of phi and theta.

Type:

np.ndarray

Return type:

None.