spinguin.core.states

This module provides functions for creating state vectors.

alpha_state(basis: ndarray, spins: ndarray, index: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index (int) – Index of the spin that has the alpha state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

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

Return type:

ndarray or csc_array

beta_state(basis: ndarray, spins: ndarray, index: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index (int) – Index of the spin that has the beta state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

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

Return type:

ndarray or csc_array

equilibrium_state(basis: ndarray, spins: ndarray, H_left: ndarray | csc_array, T: float, sparse: bool = False, zero_value: float = 1e-18) → ndarray | csc_array

Returns the state vector corresponding to thermal equilibrium.

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• H_left (ndarray) – Left-side coherent Hamiltonian superoperator.

• T (float) – Temperature of the spin bath in Kelvin.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

• zero_value (float, default=1e-18) – This threshold value is used to estimate the convergence of Taylor series in matrix exponential, and to eliminate value smaller than this threshold while squaring the matrix during the matrix exponential.

Returns:

rho_eq – Thermal equilibrium state vector.

Return type:

ndarray or csc_array

measure(basis: ndarray, spins: ndarray, rho: ndarray | csc_array, operator: str) → complex

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• rho (ndarray or csc_array) – State vector that describes the density matrix.

• operator (str) –

  Defines the operator to be measured. The operator string must follow the rules below:

  • Cartesian and ladder operators: I(component,index) or I(component). Examples:

    • I(x,4) –> Creates x-operator for spin at index 4.

    • I(x)–> Creates x-operator for all spins.

  • Spherical tensor operators: T(l,q,index) or T(l,q). Examples:

    • T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.

    • T(1, -1) –> Creates operator with l=1, q=-1 for all spins.

  • Product operators have * in between the single-spin operators: I(z,0) * I(z,1)

  • Sums of operators have + in between the operators: I(x,0) + I(x,1)

  • Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)

  Special case: An empty operator string is considered as unit operator.

  Whitespace will be ignored in the input.

  NOTE: Indexing starts from 0!

Returns:

ex – Expectation value.

Return type:

complex

singlet_state(basis: ndarray, spins: ndarray, index_1: int, index_2: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index_1 (int) – Index of the first spin in the singlet state.

• index_2 (int) – Index of the second spin in the singlet state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the singlet state.

Return type:

ndarray or csc_array

state_from_op_def(basis: ndarray, spins: ndarray, op_def: ndarray, sparse: bool = False) → ndarray | csc_array

Generates a state from the given operator definition. The output of this function is a column vector where the requested state has been populated.

Normalization: The output of this function corresponds to the non-normalized operator. However, because the basis set operators are constructed from products of normalized single-spin spherical tensor operators, requesting a state that corresponds to any operator O will result in a coefficient of norm(O) for the state.

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• op_def (ndarray) – An array of integers that specify the product operator.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the requested state.

Return type:

ndarray or csc_array

state_from_string(basis: ndarray, spins: ndarray, operator: str, sparse: bool = False) → ndarray | csc_array

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

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

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• operator (str) –

  Defines the state to be generated. The operator string must follow the rules below:

  • Cartesian and ladder operators: I(component,index) or I(component). Examples:

    • I(x,4) –> Creates x-operator for spin at index 4.

    • I(x)–> Creates x-operator for all spins.

  • Spherical tensor operators: T(l,q,index) or T(l,q). Examples:

    • T(1,-1,3) –> Creates operator with l=1, q=-1 for spin at index 3.

    • T(1, -1) –> Creates operator with l=1, q=-1 for all spins.

  • Product operators have * in between the single-spin operators: I(z,0) * I(z,1)

  • Sums of operators have + in between the operators: I(x,0) + I(x,1)

  • Unit operators are ignored in the input. Interpretation of these two is identical: E * I(z,1), I(z,1)

  Special case: An empty operator string is considered as unit operator.

  Whitespace will be ignored in the input.

  NOTE: Indexing starts from 0!

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the requested state.

Return type:

ndarray or csc_array

state_to_truncated_basis(index_map: list, rho: ndarray | csc_array) → ndarray | csc_array

Transforms a state vector to a truncated basis using the index_map, which contains indices that determine the elements that are retained after the transformation.

Parameters:

• index_map (list) – Index mapping from the original basis to the truncated basis.

• rho (ndarray or csc_array) – State vector to be transformed.

Returns:

rho_transformed – State vector transformed into the truncated basis.

Return type:

ndarray or csc_array

state_to_zeeman(basis: ndarray, spins: ndarray, rho: ndarray | csc_array, sparse: bool = True) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• rho (ndarray or csc_array) – State vector defined in the normalized spherical tensor basis.

• sparse (bool, default=True) – Specifies whether to return the density matrix as sparse or dense array.

Returns:

rho_zeeman – Spin density matrix defined in the Zeeman eigenbasis.

Return type:

ndarray or csc_array

triplet_minus_state(basis: ndarray, spins: ndarray, index_1: int, index_2: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index_1 (int) – Index of the first spin in the triplet minus state.

• index_2 (int) – Index of the second spin in the triplet minus state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the triplet minus state.

Return type:

ndarray or csc_array

triplet_plus_state(basis: ndarray, spins: ndarray, index_1: int, index_2: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index_1 (int) – Index of the first spin in the triplet plus state.

• index_2 (int) – Index of the second spin in the triplet plus state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the triplet plus state.

Return type:

ndarray or csc_array

triplet_zero_state(basis: ndarray, spins: ndarray, index_1: int, index_2: int, sparse: bool = False) → ndarray | csc_array

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

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• index_1 (int) – Index of the first spin in the triplet zero state.

• index_2 (int) – Index of the second spin in the triplet zero state.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

Returns:

rho – State vector corresponding to the triplet zero state.

Return type:

ndarray or csc_array

unit_state(basis: ndarray, spins: ndarray, sparse: bool = False, normalized: bool = True) → ndarray | csc_array

Returns a unit state vector. This is equivalent to the density matrix, which has ones on the diagonal. Because the basis set is normalized, the coefficient of the unit operator in the state vector is equal to the norm of the unit operator.

Parameters:

• basis (ndarray) – A 2-dimensional array containing the basis set that contains sequences of integers describing the Kronecker products of irreducible spherical tensors.

• spins (ndarray) – A 1-dimensional array specifying the spin quantum numbers of the system.

• sparse (bool, default=False) – If False, returns a NumPy array. If True, returns a SciPy csc_array.

• normalized (bool, default=True) – If set to True, the function will return a state vector that represents the trace-normalized density matrix. If False, returns a state vector that corresponds to the identity operator.

Returns:

rho – State vector corresponding to the unit state.

Return type:

ndarray or csc_array