# Utility Functions

Here are the various functions used throughout the PyCCE code. There is no real structure in this section.

## InteractionMap

class InteractionMap(rows=None, columns=None, tensors=None)

Dict-like object containing information about tensor interactions between two spins.

Each key is a tuple of two spin indexes.

Parameters
• rows (array-like with shape (n, )) – Indexes of the bath spins, appearing on the left in the pairwise interaction.

• columns (array-like with shape (n, )) – Indexes of the bath spins, appearing on the right in the pairwise interaction.

• tensors (array-like with shape (n, 3, 3)) – Tensors of pairwise interactions between two spins with the indexes in rows and columns.

mapping

Actual dictionary storing the data.

Type

dict

property indexes

Array with the indexes of pairs of spins, for which the tensors are stored.

Type

ndarray with shape (n, 2)

shift(start, inplace=True)

Add an offset start to the indexes. If inplace is False, returns the copy of InteractionMap.

Parameters
• start (int) – Offset in indexes.

• inplace (bool) – If True, makes changes inplace. Otherwise returns copy of the map.

Returns

Map with shifted indexes.

Return type

InteractionMap

keys()a set-like object providing a view on D’s keys
items()a set-like object providing a view on D’s items
subspace(array)

Get new InteractionMap with indexes readressed from array. Within the subspace indexes are renumbered.

Examples

The subspace of [3,4,7] indexes will contain InteractionMap only within [3,4,7] elements with new indexes [0, 1, 2].

>>> import numpy as np
>>> im = InteractionMap()
>>> im[0, 3] = np.eye(3)
>>> im[3, 7] = np.ones(3)
>>> for k in im: print(k, '\n', im[k],)
(0, 3)
[[1. 0. 0.]
[0. 1. 0.]
[0. 0. 1.]]
(3, 7)
[[1. 1. 1.]
[1. 1. 1.]
[1. 1. 1.]]
>>> array = [3, 4, 7]
>>> sim = im.subspace(array)
>>> for k in sim: print(k, '\n', sim[k])
(0, 2)
[[1. 1. 1.]
[1. 1. 1.]
[1. 1. 1.]]

Parameters

array (ndarray) – Either bool array containing True for elements within the subspace or array of indexes presented in the subspace.

Returns

The map for the subspace.

Return type

InteractionMap

classmethod from_dict(dictionary, presorted=False)

Generate InteractionMap from the dictionary.

Parameters
• dictionary (dict) – Dictionary with tensors.

• presorted (bool) – If true, assumes that the keys in the dictionary were already presorted.

Returns

New instance generated from the dictionary.

Return type

InteractionMap

## Noise Filter Functions

Module with helper functions to obtain CPMG coherence from the noise autocorrelation function.

filterfunc(ts, tau, npulses)

Time-domain filter function for the given CPMG sequence.

Parameters
• ts (ndarray with shape (n,)) – Time points at which filter function will be computed.

• tau (float) – Delay between pulses.

• npulses (int) – Number of pulses in CPMG sequence.

Returns

Filter function for the given CPMG sequence.

Return type

ndarray with shape (n,)

gaussian_phase(timespace, corr, npulses, units='khz')

Compute average random phase squared assuming Gaussian noise.

Parameters
• timespace (ndarray with shape (n,)) – Time points at which correlation function was computed.

• corr (ndarray with shape (n,)) – Noise autocorrelation function.

• npulses (int) – Number of pulses in CPMG sequence.

• units (str) – If units contain frequency or angular frequency (‘rad’ in units).

Returns

Random phase accumulated by the qubit.

Return type

ndarray with shape (n,)

## Spin matrix generators

class SpinMatrix(s)

Class containing the spin matrices in Sz basis.

Parameters

s (float) – Total spin.

class MatrixDict(*spins)

Class for storing the SpinMatrix objects.

keys()a set-like object providing a view on D’s keys
stevo(sm, k, q)

Stevens operators (from I.D. Ryabov, Journal of Magnetic Resonance 140, 141–145 (1999)).

Parameters
• sm (SpinMatrix) – Spin matrices of the given spin.

• k (int) – $$k$$ index of the Stevens operator.

• q (int) – $$q$$ index of the Stevens operator.

Returns

Stevens operator representation in $$S_z$$ basis.

Return type

ndarray with shape (n, n)

dimensions_spinvectors(bath=None, central_spin=None)

Generate two arrays, containing dimensions of the spins in the cluster and the vectors with spin matrices.

Parameters
• bath (BathArray with shape (n,)) – Array of the n spins within cluster.

• central_spin (CenterArray, optional) – If provided, include dimensions of the central spins.

Returns

tuple containing:

• ndarray with shape (n,): Array with dimensions for each spin.

• list: List with vectors of spin matrices for each spin in the cluster (Including central spin if central_spin is not None). Each with shape (3, N, N) where N = prod(dimensions).

Return type

tuple

vecs_from_dims(dimensions)

Generate ndarray of spin vectors, given the array of spin dimensions.

Parameters

dimensions (ndarray with shape (n,)) – Dimensions of spins.

Returns

Array of spin vectors in full Hilbert space.

Return type

ndarray with shape (n, 3, X, X)

spinvec(j, dimensions)

Generate single spin vector, given the index and dimensions of all spins in the cluster.

Parameters
• j (int) – Index of the spin.

• dimensions (ndarray with shape (n,)) – Dimensions of spins.

Returns

Spin vector of $$j$$-sth spin in full Hilbert space.

Return type

ndarray with shape (3, X, X)

numba_gen_sm(dim)

Numba-friendly spin matrix. :param dim: dimensions of the spin marix. :type dim: int

Returns

Return type

ndarray

## Other

rotmatrix(initial_vector, final_vector)

Generate 3D rotation matrix which applied on initial vector will produce vector, aligned with final vector.

Examples

>>> R = rotmatrix([0,0,1], [1,1,1])
>>> R @ np.array([0,0,1])
array([0.577, 0.577, 0.577])

Parameters
• initial_vector (ndarray with shape(3, )) – Initial vector.

• final_vector (ndarray with shape (3, )) – Final vector.

Returns

Rotation matrix.

Return type

ndarray with shape (3, 3)

expand(matrix, i, dim)

Expand matrix M from it’s own dimensions to the total Hilbert space.

Parameters
• matrix (ndarray with shape (dim[i], dim[i])) – Inital matrix.

• i (int) – Index of the spin dimensions in dim parameter.

• dim (ndarray) – Array pf dimensions of all spins present in the cluster.

Returns

Expanded matrix.

Return type

ndarray with shape (prod(dim), prod(dim))

partial_trace(dmarray, dimensions, sel)

Compute partial trace of the operator (or array of operators).

Parameters
• dmarray (ndarray with shape (N, N) or (m, N, N) –

• dimensions (array-like) – Array of all dimensions of the system.

• sel (int or array-like) – Index or indexes of dimensions to keep.

Returns

Partially traced operator.

Return type

ndarray with shape (n, n) or (m, n, n)

partial_inner_product(avec, total, dimensions, index=- 1)

Returns partial inner product $$\ket{b}=\bra{a}\ket{\psi}$$, where $$\ket{a}$$ provided by avec contains degrees of freedom to be “traced out” and $$\ket{\psi}$$ provided by total is the total statevector.

Parameters
• avec (ndarray with shape (a,)) –

• total (ndarray with shape (a*b,)) –

• dimensions (ndarray with shape (n,)) –

• () (index) –

Returns:

shorten_dimensions(dimensions, central_number)

Combine the dimensions, corresponding to the central spins.

Parameters
• dimensions (ndarray with shape (n, )) – Array of the dimensions of the spins in the cluster.

• central_number (int) – Number of central spins.

Returns

Array of the shortened dimensions;

Return type

ndarray with shape (n - central_number)

outer(s1, s2)

Outer product of two complex vectors $$\ket{s_1}ra{s_2}$$.

Parameters
• s1 (ndarray with shape (n, )) – First vector.

• s2 (ndarray with shape (m, )) – Second vector.

Returns

Outer product.

Return type

ndarray with shape (n, m)

tensor_vdot(tensor, ivec)

Compute product of the tensor and spin vector.

Parameters
• tensor (ndarray with shape (3, 3)) – Tensor in real space.

• ivec (ndarray with shape (3, n, n)) – Spin vector.

Returns

Right-side tensor vector product $$Tv$$.

Return type

ndarray with shape (3, n, n)

vvdot(vec_1, vec_2)

Compute product of two spin vectors.

Parameters
• vec_1 (ndarray with shape (3, N, N)) – First spin vector.

• vec_2 (ndarray with shape (3, N, N)) – Second spin vector.

Returns

Product of two vectors.

Return type

ndarray with shape (N, N)

rotate_tensor(tensor, rotation=None, style='col')

Rootate tensor in real space, given rotation matrix.

Parameters
• tensor (ndarray with shape (3, 3)) – Tensor to be rotated.

• rotation (ndarray with shape (3, 3)) – Rotation matrix.

• style (str) – Can be ‘row’ or ‘col’. Determines how rotation matrix is initialized.

Returns

Rotated tensor.

Return type

ndarray with shape (3, 3)

rotate_coordinates(xyz, rotation=None, cell=None, style='col')

Rootate coordinates in real space, given rotation matrix.

Parameters
• xyz (ndarray with shape (..., 3)) – Array of coordinates.

• rotation (ndarray with shape (3, 3)) – Rotation matrix.

• cell (ndarray with shape (3, 3)) – Cell matrix if coordinates are given in cell coordinates.

• style (str) – Can be ‘row’ or ‘col’. Determines how rotation matrix and cell matrix are initialized.

Returns

Array of rotated coordinates.

Return type

ndarray with shape (…, 3))

normalize(vec)

Normalize vector to 1.

Parameters

vec (ndarray with shape (n, )) – Vector to be normalized.

Returns

Normalized vector.

Return type

ndarray with shape (n, )

vec_tensor_vec(v1, tensor, v2)

Compute product v @ T @ v. :param v1: Leftmost expanded spin vector. :type v1: ndarray with shape (3, n, n) :param tensor: 3x3 interaction tensor in real space. :type tensor: ndarray with shape (3, 3) :param v2: Rightmost expanded spin vector. :type v2: ndarray with shape (3, n, n)

Returns

Product $$vTv$$.

Return type

ndarray with shape (n, n)

gen_state_list(states, dims)

Generate list of states from $$S_z$$ projections of the pure states.

Parameters
• states (ndarray with shape (n,)) – Array of $$S_z$$ projections.

• dims (ndarray with shape (n,)) – Array of the dimensions of the spins in the cluster.

Returns

list of state vectors.

Return type

List

vector_from_s(s, d)

Generate vector state from $$S_z$$ projection.

Parameters
• s (float) – $$S_z$$ projection.

• d (int) – Dimensions of the given spin.

Returns

State vector of a pure state.

Return type

ndarray with shape (d, )