# CCE Calculators

Documentation for the calculator objects called by Simulator object.

## Base class

class RunObject(timespace, clusters, bath, magnetic_field, alpha, beta, state, spin, zfs, gyro, nbstates=None, bath_state=None, seed=None, masked=True, fixstates=None, projected_bath_state=None, parallel=False, direct=False, parallel_states=False, **kwargs)

Abstract class of the CCE simulation runner.

Implements cluster correlation expansion, interlaced averaging, and sampling over random bath states. Requires definition of the following methods, from which the kernel will be automatically created:

• .generate_hamiltonian(self) method which, using the attributes of the self object, computes cluster hamiltonian stored in self.cluster_hamiltonian.

• .compute_result(self) method which, using the attributes of the self, computes the resulting quantity for the given cluster.

Alternatively, user can define the kernel manually. Then the following methods have to be overridden:

• .kernel(self, cluster, *args, **kwargs) method which takes indexes of the bath spins in the given cluster as a first positional argument. This method is required for usual CCE runs.

• .interlaced_kernel(self, cluster, supercluster, *args, **kwargs) method which takes indexes of the bath spins in the given cluster as a first positional argument, indexes of the supercluster as a second positional argument. This method is required for interlaced CCE runs.

Parameters
• timespace (ndarray with shape (t, )) – Time delay values at which to compute propagators.

• clusters (dict) – Clusters included in different CCE orders of structure {int order: ndarray([[i,j],[i,j]])}.

• bath (BathArray with shape (n,)) – Array of n bath spins.

• magnetic_field (ndarray) – Magnetic field of type magnetic_field = np.array([Bx, By, Bz]).

• alpha (int or ndarray with shape (2s+1, )) – $$\ket{0}$$ state of the qubit in $$S_z$$ basis or the index of eigenstate to be used as one.

• beta (int or ndarray with shape (2s+1, )) – $$\ket{1}$$ state of the qubit in $$S_z$$ basis or the index of the eigenstate to be used as one.

• state (ndarray with shape (2s+1, )) – Initial state of the central spin, used in gCCE and noise autocorrelation calculations. Defaults to $$\frac{1}{N}(\ket{0} + \ket{1})$$ if not set OR if alpha and beta are provided as indexes.

• spin (float) – Value of the central spin.

• zfs (ndarray with shape (3,3)) – Zero Field Splitting tensor of the central spin.

• gyro (float or ndarray with shape (3, 3)) –

Gyromagnetic ratio of the central spin

OR

tensor corresponding to interaction between magnetic field and central spin.

• nbstates (int) – Number of random bath states to sample over in bath state sampling runs.

• bath_state (ndarray) – Array of bath states in any accepted format.

• seed (int) – Seed for the random number generator in bath states sampling.

• masked (bool) – True if mask numerically unstable points (with result > result[0]) in the sampling over bath states False if not. Default True.

• fixstates (dict) –

If provided, contains indexes of bath spins with fixed pure state for sampling runs and interlaced runs.

Each key is the index of bath spin, value - fixed $$\hat{I}_z$$ projection of the pure $$\hat{I}_z$$ eigenstate of bath spin.

• projected_bath_state (ndarray with shape (n,)) – Array with z-projections of the bath spins states. Overridden in runs with random bath state sampling.

• parallel (bool) – True if parallelize calculation of cluster contributions over different mpi processes. Default False.

• direct (bool) – True if use direct approach in run (requires way more memory but might be more numerically stable). False if use memory efficient approach. Default False.

• parallel_states (bool) – True if use MPI to parallelize the calculations of density matrix for each random bath state.

• **kwargs – Additional keyword arguments to be set as the attributes of the given object.

result_operator(b, /)

Operator which will combine the result of expansion,.

Default: operator.imul.

contribution_operator(b, /)

Operator which will combine multiple contributions of the same cluster in the optimized approach.

Default: operator.ipow.

removal_operator(b, /)

Operator which will remove subcluster contribution from the given cluster contribution. First argument cluster contribution, second - subcluster contribution.

Defalut: operator.itruediv.

addition_operator(axis=None, dtype=None, out=None, keepdims=<no value>, initial=<no value>, where=<no value>)

Group operation which will combine contributions from the different clusters into one contribution in the direct approach.

Default: numpy.prod.

nbstates

Number of random bath states to sample over in bath state sampling runs.

Type

int

timespace

Time points at which result will be computed.

Type

ndarray with shape (t, )

clusters

Clusters included in different CCE orders of structure {int order: ndarray([[i,j],[i,j]])}.

Type

dict

bath

Array of n bath spins.

Type

BathArray with shape (n,)

spin

Value of the central spin

Type

float

zfs

Zero Field Splitting tensor of the central spin.

Type

ndarray with shape (3, 3)

gyro

float or ndarray with shape (3, 3): Gyromagnetic ratio of the central spin

OR

tensor corresponding to interaction between magnetic field and central spin.

bath_state

Array of bath states in any accepted format.

Type

ndarray

projected_bath_state

Array with z-projections of the bath spins states. Overridden in runs with random bath state sampling.

Type

ndarray with shape (n,)

magnetic_field

Magnetic field of type magnetic_field = np.array([Bx, By, Bz]).

Type

ndarray

initial_alpha

$$\ket{0}$$ state of the qubit in $$S_z$$ basis or the index of eigenstate to be used as one.

Type

ndarray

initial_beta

$$\ket{1}$$ state of the qubit in $$S_z$$ basis or the index of eigenstate to be used as one.

Type

ndarray

alpha

$$\ket{0}$$ state of the qubit in $$S_z$$ basis. If initially provided as index, generated as a state during the run.

Type

ndarray

beta

$$\ket{1}$$ state of the qubit in $$S_z$$ basis. If initially provided as index, generated as a state during the run.

Type

ndarray

state

Initial state of the central spin, used in gCCE and noise autocorrelation calculations.

Defaults to $$\frac{1}{N}(\ket{0} + \ket{1})$$ if not set OR if alpha and beta are provided as indexes.

Type

ndarray

parallel

True if parallelize calculation of cluster contributions over different mpi processes. Default False.

Type

bool

parallel_states

True if use MPI to parallelize the calculations of density matrix for each random bath state.

Type

bool

direct

True if use direct approach in run (requires way more memory but might be more numerically stable). False if use memory efficient approach. Default False.

Type

bool

seed

Seed for the random number generator in bath states sampling.

Type

int

True if mask numerically unstable points (with result > result[0]) in the sampling over bath states False if not. Default True.

Type

bool

fixstates

If provided, contains indexes of bath spins with fixed pure state for sampling runs and interlaced runs.

Each key is the index of bath spin, value - fixed $$\hat{I}_z$$ projection of the pure $$\hat{I}_z$$ eigenstate of bath spin.

Type

dict

hamiltonian

central spin hamiltonian.

Type

ndarray

energies

Eigen energies of the central spin hamiltonian.

Type

ndarray

eigenvectors

Eigen states of the central spin hamiltonian.

Type

ndarray

cluster

Array of the bath spins inside the given cluster.

Type

BathArray

states

Array of the states of bath spins inside the given cluster.

Type

ndarray

others

Array of the bath spins outside the given cluster.

Type

BathArray

other_states

Array of the z-projections of the states of bath spins outside the given cluster.

Type

ndarray

cluster_hamiltonian

Full hamiltonian of the given cluster. In conventional CCE, tuple with two projected hamiltonians.

Type

Hamiltonian or tuple

result

Result of the calculation.

Type

ndarray

preprocess()

Method which will be called before cluster-expanded run.

postprocess()

Method which will be called after cluster-expanded run.

kernel(cluster, *args, **kwargs)

Central kernel that will be called in the cluster-expanded calculations

Parameters
• cluster (ndarray) – Indexes of the bath spins in the given cluster.

• *args – Positional arguments of the kernel.

• **kwargs – Keyword arguments of the kernel.

Returns

Results of the calculations.

Return type

ndarray

run(*args, **kwargs)

Method that runs cluster-expanded single calculation.

Parameters
• *args – Positional arguments of the kernel.

• **kwargs – Keyword arguments of the kernel.

Returns

Results of the calculations.

Return type

ndarray

sampling_run(*args, **kwargs)

Method that runs bath sampling calculations.

Parameters
• *args – Positional arguments of the kernel.

• **kwargs – Keyword arguments of the kernel.

Returns

Results of the calculations.

Return type

ndarray

interlaced_kernel(cluster, supercluster, *args, **kwargs)

Central kernel that will be called in the cluster-expanded calculations with interlaced averaging of bath spin states.

Parameters
• cluster (ndarray) – Indexes of the bath spins in the given cluster.

• supercluster (ndarray) – Indexes of the bath spins in the supercluster of the given cluster. Supercluster is the union of all clusters in .clusters attribute, for which given cluster is a subset.

• *args – Positional arguments of the kernel.

• **kwargs – Keyword arguments of the kernel.

Returns

Results of the calculations.

Return type

ndarray

interlaced_run(*args, **kwargs)

Method that runs cluster-expanded single calculation with interlaced averaging of bath spin states.

Parameters
• *args – Positional arguments of the interlaced kernel.

• **kwargs – Keyword arguments of the interlaced kernel.

Returns

Results of the calculations.

Return type

ndarray

sampling_interlaced_run(*args, **kwargs)

Method that runs bath sampling calculations with interlaced averaging of bath spin states.

Parameters
• *args – Positional arguments of the interlaced kernel.

• **kwargs – Keyword arguments of the interlaced kernel.

Returns

Results of the calculations.

Return type

ndarray

classmethod from_simulator(sim, **kwargs)

Class method to generate RunObject from the properties of Simulator object.

Parameters
• sim (Simulator) – Object, whose properties will be used to initialize RunObject instance.

• **kwargs – Additional keyword arguments that will replace ones, recovered from the Simulator object.

Returns

New instance of RunObject class.

Return type

RunObject

generate_supercluser_states(self, supercluster)

Helper function to generate all possible pure states of the given supercluster.

Parameters
• self (RunObject) – Instance of the RunObject class, used in the calculation.

• supercluster (ndarray with shape (n, )) – Indexes of the bath spins in the supercluster.

Yields

ndarray with shape (n, ) – Pure state of the given supercluster.

## Conventional CCE

propagators(timespace, H0, H1, pulses, as_delay=False)

Function to compute propagators U0 and U1 in conventional CCE.

Parameters
• timespace (ndarray with shape (t, )) – Time delay values at which to compute propagators.

• H0 (ndarray with shape (n, n)) – Hamiltonian projected on alpha qubit state.

• H1 (ndarray with shape (n, n)) – Hamiltonian projected on beta qubit state.

• pulses (int or Sequence) – Sequence of pulses.

• as_delay (bool) – True if time points are delay between pulses. False if time points are total time.

Returns

tuple containing:

• ndarray with shape (t, n, n): Matrix representation of the propagator conditioned on the alpha qubit state for each time point.

• ndarray with shape (t, n, n): Matrix representation of the propagator conditioned on the beta qubit state for each time point.

Return type

tuple

compute_coherence(H0, H1, timespace, N, as_delay=False, states=None)

Function to compute cluster coherence function in conventional CCE.

Parameters
• H0 (ndarray) – Hamiltonian projected on alpha qubit state.

• H1 (ndarray) – Hamiltonian projected on beta qubit state.

• timespace (ndarray) – Time points at which to compute coherence function.

• N (int) – Number of pulses in CPMG.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time.

• states (ndarray) – ndarray of bath states in any accepted format.

Returns

Coherence function of the central spin.

Return type

ndarray

class CCE(*args, pulses=0, as_delay=False, second_order=False, level_confidence=0.95, **kwargs)

Class for running conventional CCE simulations.

Note

Subclass of the RunObject abstract class.

Parameters
• *args – Positional arguments of the RunObject.

• pulses (int or Sequence) – number of pulses in CPMG sequence or instance of Sequence object. For now, only CPMG sequences are supported in conventional CCE simulations.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time.

• second_order (bool) – True if add second order perturbation theory correction to the cluster Hamiltonian. If set to True sets the qubit states as eigenstates of central spin Hamiltonian from the following procedure. If qubit states are provided as vectors in $$S_z$$ basis, for each qubit state compute the fidelity of the qubit state and all eigenstates of the central spin and chose the one with fidelity higher than level_confidence. If such state is not found, raises an error.

• level_confidence (float) – Maximum fidelity of the qubit state to be considered eigenstate of the central spin Hamiltonian. Default 0.95.

• **kwargs – Keyword arguments of the RunObject.

initial_pulses

Input pulses

Type

int or Sequence

pulses

If input Sequence contains only pi pulses at even delay, stores number of pulses. Otherwise stores full Sequence.

Type

int or Sequence

as_delay

True if time points are delay between pulses, False if time points are total time.

Type

bool

second_order

True if add second order perturbation theory correction to the cluster hamiltonian.

Type

bool

level_confidence

Maximum fidelity of the qubit state to be considered eigenstate of the central spin hamiltonian.

Type

float

energy_alpha

Eigen energy of the alpha state in the central spin Hamiltonian.

Type

float

energy_beta

Eigen energy of the beta state in the central spin Hamiltonian.

Type

float

energies

All eigen energies of the central spin Hamiltonian.

Type

ndarray with shape (2s+1, )

projections_alpha_all

Array of vectors with spin operator matrix elements of type $$[\bra{0}\hat S_x\ket{i}, \bra{0}\hat S_y\ket{i}, \bra{0}\hat S_z\ket{i}]$$, where $$\ket{0}$$ is the alpha qubit state, $$\ket{i}$$ are all eigenstates of the central spin hamiltonian.

Type

ndarray with shape (2s+1, 3)

projections_beta_all

Array of vectors with spin operator matrix elements of type $$[\bra{1}\hat S_x\ket{i}, \bra{1}\hat S_y\ket{i}, \bra{1}\hat S_z\ket{i}]$$, where $$\ket{1}$$ is the beta qubit state, $$\ket{i}$$ are all eigenstates of the central spin hamiltonian.

Type

ndarray with shape (2s+1, 3)

projections_alpha

Vector with spin operator matrix elements of type $$[\bra{0}\hat S_x\ket{0}, \bra{0}\hat S_y\ket{0}, \bra{0}\hat S_z\ket{0}]$$, where $$\ket{0}$$ is the alpha qubit state

Type

ndarray with shape (3,)

projections_beta

Vectors with spin operator matrix elements of type $$[\bra{1}\hat S_x\ket{1}, \bra{1}\hat S_y\ket{1}, \bra{1}\hat S_z\ket{1}]$$, where $$\ket{1}$$ is the beta qubit state.

Type

ndarray with shape (3,)

use_pulses

True if use full Sequence. False if use only number of pulses.

Type

bool

preprocess()

Method which will be called before cluster-expanded run.

postprocess()

Method which will be called after cluster-expanded run.

generate_hamiltonian()

Using the attributes of the self object, compute the two projected cluster hamiltonians.

Returns

Tuple containing:

• Hamiltonian: Cluster hamiltonian when qubit in the alpha state.

• Hamiltonian: Cluster hamiltonian when qubit in the alpha state.

Return type

tuple

compute_result()

Using the attributes of the self object, compute the coherence function as overlap in the bath evolution.

Returns

Computed coherence.

Return type

ndarray

## Generalized CCE

propagator(timespace, hamiltonian, pulses=None, as_delay=False)

Function to compute time propagator U.

Parameters
• timespace (ndarray with shape (t, )) – Time points at which to compute propagators.

• hamiltonian (ndarray with shape (n, n)) – Matrix representation of the cluster hamiltonian.

• pulses (Sequence) – Pulses as an instance of Sequence class with rotations already generated. Default is None.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time. Default is False.

Returns

Array of propagators, evaluated at each time point in timespace.

Return type

ndarray with shape (t, n, n)

compute_dm(dm0, H, timespace, pulse_sequence=None, as_delay=False, states=None)

Function to compute density matrix of the central spin, given Hamiltonian H.

Parameters
• dm0 (ndarray) – Initial density matrix of central spin.

• H (ndarray) – Cluster Hamiltonian.

• timespace (ndarray) – Time points at which to compute density matrix.

• pulse_sequence (Sequence) – Sequence of pulses.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time.

• states (ndarray) – ndarray of bath states in any accepted format.

Returns

Array of density matrices evaluated at all time points in timespace.

Return type

ndarray

full_dm(dm0, H, timespace, pulse_sequence=None, as_delay=False)

A function to compute density matrix of the cluster, using hamiltonian H from the initial density matrix of the cluster.

Parameters
• dm0 (ndarray) – Initial density matrix of the cluster

• H (ndarray) – Cluster Hamiltonian

• timespace (ndarray) – Time points at which to compute coherence function.

• pulse_sequence (Sequence) – Sequence of pulses.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time. Ignored if delays are provided in the pulse_sequence.

Returns

Array of density matrices of the cluster, evaluated at the time points from timespace.

Return type

ndarray

generate_dm0(dm0, dimensions, states=None)

A function to generate initial density matrix or statevector of the cluster. :param dm0: Initial density matrix of the central spin. :type dm0: ndarray :param dimensions: ndarray of bath spin dimensions. Last entry - electron spin dimensions. :type dimensions: ndarray :param states: ndarray of bath states in any accepted format. :type states: ndarray

Returns

Initial density matrix of the cluster OR statevector if dm0 is vector and states are provided as list of pure states.

Return type

ndarray

generate_pure_initial_state(state0, dimensions, states)

A function to generate initial state vector of the cluster with central spin.

Parameters
• state0 (ndarray) – Initial state of the central spin.

• dimensions (ndarray) – ndarray of bath spin dimensions. Last entry - electron spin dimensions.

• states (ndarray) – ndarray of bath states in any accepted format.

Returns

Initial state vector of the cluster.

Return type

ndarray

gen_density_matrix(states=None, dimensions=None)

Generate density matrix from the ndarray of states.

Parameters
• states (ndarray) –

Array of bath spin states. If None, assume completely random state. Can have the following forms:

• array of the $$\hat{I}_z$$ projections for each spin. Assumes that each bath spin is in the pure eigenstate of $$\hat{I}_z$$.

• array of the diagonal elements of the density matrix for each spin. Assumes mixed state and the density matrix for each bath spin is diagonal in $$\hat{I}_z$$ basis.

• array of the density matrices of the bath spins.

• dimensions (ndarray) – array of bath spin dimensions. Last entry - electron spin dimensions.

Returns

Density matrix of the system.

Return type

ndarray

class gCCE(*args, as_delay=False, pulses=None, **kwargs)

Class for running generalized CCE simulations.

Note

Subclass of the RunObject abstract class.

Parameters
• *args – Positional arguments of the RunObject.

• pulses (Sequence) – Sequence object, containing series of pulses, applied to the system.

• as_delay (bool) – True if time points are delay between pulses, False if time points are total time.

• **kwargs – Keyword arguments of the RunObject.

pulses

Sequence object, containing series of pulses, applied to the system.

Type

Sequence

as_delay

True if time points are delay between pulses, False if time points are total time.

Type

bool

dm0

Initial density matrix of the central spin.

Type

ndarray with shape (2s+1, 2s+1)

normalization

Coherence at time 0.

Type

float

zero_cluster

Coherence computed for the isolated central spin.

Type

ndarray with shape (n,)

preprocess()

Method which will be called before cluster-expanded run.

postprocess()

Method which will be called after cluster-expanded run.

generate_hamiltonian()

Using the attributes of the self object, compute the cluster hamiltonian including the central spin.

Returns

Cluster hamiltonian.

Return type

Hamiltonian

compute_result()

Using the attributes of the self object, compute the coherence function of the central spin.

Returns

Computed coherence.

Return type

ndarray

## Noise Autocorrelation

correlation_it_j0(operator_i, operator_j, dm0_expanded, U)

Function to compute correlation function of the operator i at time t and operator j at time 0

Parameters
• operator_i (ndarray with shape (n, n)) – Matrix representation of operator i.

• operator_j (ndarray with shape (n, n)) – Matrix representation of operator j.

• dm0_expanded (ndarray with shape (n, n)) – Initial density matrix of the cluster.

• U (ndarray with shape (t, n, n)) – Time evolution propagator, evaluated over t time points.

Returns

Autocorrelation of the z-noise at each time point.

Return type

ndarray with shape (t,)

compute_correlations(nspin, dm0_expanded, U, central_spin=None)

Function to compute correlations for the given cluster, given time propagator U.

Parameters
• nspin (BathArray) – BathArray of the given cluster of bath spins.

• dm0_expanded (ndarray with shape (n, n)) – Initial density matrix of the cluster.

• U (ndarray with shape (t, n, n)) – Time evolution propagator, evaluated over t time points.

• central_spin (float) – Value of the central spin.

Returns

correlation of the Overhauser field, induced by the given cluster at each time point.

Return type

ndarray with shape (t,)

class gCCENoise(*args, **kwargs)

Class for running generalized CCE simulations of the noise autocorrelation function.

Note

Subclass of the RunObject abstract class.

Parameters
• *args – Positional arguments of the RunObject.

• **kwargs – Keyword arguments of the RunObject.

result_operator(b, /)

Overridden operator which will combine the result of expansion: operator.iadd.

contribution_operator(b, /)

Overridden operator which will combine multiple contributions of the same cluster in the optimized approach: operator.imul.

removal_operator(b, /)

Overridden operator which remove subcluster contribution from the given cluster contribution: operator.isub.

addition_operator(axis=None, dtype=None, out=None, keepdims=<no value>, initial=<no value>, where=<no value>)

Overridden group operation which will combine contributions from the different clusters into one contribution in the direct approach: numpy.sum.

preprocess()

Method which will be called before cluster-expanded run.

postprocess()

Method which will be called after cluster-expanded run.

generate_hamiltonian()

Using the attributes of the self object, compute the cluster hamiltonian including the central spin.

Returns

Cluster hamiltonian.

Return type

Hamiltonian

compute_result()

Using the attributes of the self object, compute autocorrelation function of the noise from bath spins in the given cluster.

Returns

Computed autocorrelation function.

Return type

ndarray

class CCENoise(*args, **kwargs)

Class for running conventional CCE simulations of the noise autocorrelation function.

Note

Subclass of the RunObject abstract class.

Warning

In general, for calculations of the autocorrelation function, better results are achieved with generalized CCE, which accounts for the evolution of the entangled state of the central spin.

Second order couplings between nuclear spins are not implemented.

Parameters
• *args – Positional arguments of the RunObject.

• **kwargs – Keyword arguments of the RunObject.

result_operator(b, /)

Overridden operator which will combine the result of expansion: operator.iadd.

contribution_operator(b, /)

Overridden operator which will combine multiple contributions of the same cluster in the optimized approach: operator.imul.

removal_operator(b, /)

Overridden operator which remove subcluster contribution from the given cluster contribution: operator.isub.

addition_operator(axis=None, dtype=None, out=None, keepdims=<no value>, initial=<no value>, where=<no value>)

Overridden group operation which will combine contributions from the different clusters into one contribution in the direct approach: numpy.sum.

preprocess()

Method which will be called before cluster-expanded run.

postprocess()

Method which will be called after cluster-expanded run.

generate_hamiltonian()

Using the attributes of the self object, compute the projected cluster hamiltonian, averaged for two qubit states.

Returns

Cluster hamiltonian.

Return type

Hamiltonian

compute_result()

Using the attributes of the self object, compute autocorrelation function of the noise from bath spins in the given cluster.

Returns

Computed autocorrelation function.

Return type

ndarray

## Cluster-correlation Expansion Decorators

The way we find cluster in the code.

generate_clusters(bath, r_dipole, order, r_inner=0, ignore=None, strong=False, nclusters=None)

Generate clusters for the bath spins.

Parameters
• bath (BathArray) – Array of bath spins.

• r_dipole (float) – Maximum connectivity distance.

• order (int) – Maximum size of the clusters to find.

• r_inner (float) – Minimum connectivity distance.

• ignore (list or str, optional) – If not None, includes the names of bath spins which are ignored in the cluster generation.

• strong (bool) – Whether to find only completely interconnected clusters (default False).

• nclusters (dict) –

Dictionary which contain maximum number of clusters of the given size. Has the form n_clusters = {order: number}, where order is the size of the cluster, number is the maximum number of clusters with this size.

If provided, sorts the clusters by the strength of cluster interaction, equal to the lowest pairwise interaction in the cluster. Then the strongest number of clusters is taken.

Returns

Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (matrix, N). Here matrix is the number of clusters of given size, N is the size of the cluster. Each row contains indexes of the bath spins included in the given cluster.

Return type

dict

make_graph(bath, r_dipole, r_inner=0, ignore=None, max_size=5000)

Make a connectivity matrix for bath spins.

Parameters
• bath (BathArray) – Array of bath spins.

• r_dipole (float) – Maximum connectivity distance.

• r_inner (float) – Minimum connectivity distance.

• ignore (list or str, optional) – If not None, includes the names of bath spins which are ignored in the cluster generation.

• max_size (int) – Maximum size of the bath before less optimal (but less memory intensive) approach is used.

Returns

Connectivity matrix.

Return type

crs_matrix

connected_components(csgraph, directed=False, connection='weak', return_labels=True)

Find connected components using scipy.sparse.csgraph. See documentation of scipy.sparse.csgraph.connected_components

find_subclusters(maximum_order, graph, labels, n_components, strong=False)

Find subclusters from connectivity matrix.

Parameters
• maximum_order (int) – Maximum size of the clusters to find.

• graph (csr_matrix) – Connectivity matrix.

• labels (ndarray with shape (n,)) – Array of labels of the connected components.

• n_components (int) – The number of connected components n.

• strong (bool) – Whether to find only completely interconnected clusters (default False).

Returns

Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (matrix, N). Here matrix is the number of clusters of given size, N is the size of the cluster. Each row contains indexes of the bath spins included in the given cluster.

Return type

dict

combine_clusters(cs1, cs2)

Combine two dictionaries with clusters.

Parameters
• cs1 (dict) – First cluster dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (matrix, N).

• cs2 (dict) – Second cluster dictionary with the same structure.

Returns

Combined dictionary with unique clusters from both dictionaries.

Return type

dict

expand_clusters(sc)

Expand dict so each new cluster will include all possible additions of one more bath spin. This increases maximum size of the cluster by one.

Parameters

sc (dict) – Initial clusters dictionary.

Returns

Dictionary with expanded clusters.

Return type

dict

find_valid_subclusters(graph, maximum_order, nclusters=None, bath=None, strong=False)

Find subclusters from connectivity matrix.

Parameters
• maximum_order (int) – Maximum size of the clusters to find.

• graph (csr_matrix) – Connectivity matrix.

• nclusters (dict) – Dictionary which contain maximum number of clusters of the given size.

• bath (BathArray) – Array of bath spins.

• strong (bool) – Whether to find only completely interconnected clusters (default False).

Returns

Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (matrix, N). Here matrix is the number of clusters of given size, N is the size of the cluster. Each row contains indexes of the bath spins included in the given cluster.

Return type

dict

General decorators that are used to expand kernel of the RunObject class or subclasses to the whole bath via CCE.

This module contains information about the way the cluster expansion is implemented in the package.

cluster_expansion_decorator(_func=None, *, result_operator=<built-in function imul>, contribution_operator=<built-in function ipow>, removal_operator=<built-in function itruediv>, addition_operator=<function prod>)

Decorator for creating cluster correlation expansion of the method of RunObject class.

Parameters
• _func (func) – Function to expand.

• result_operator (func) – Operator which will combine the result of expansion (default: operator.imul).

• contribution_operator (func) – Operator which will combine multiple contributions of the same cluster (default: operator.ipow) in the optimized approach.

• result_operator – Operator which will combine the result of expansion (default: operator.imul).

• removal_operator (func) – Operator which will remove subcluster contribution from the given cluster contribution. First argument cluster contribution, second - subcluster contribution (default: operator.itruediv).

• addition_operator (func) – Group operation which will combine contributions from the different clusters into one contribution (default: np.prod).

Returns

Expanded function.

Return type

func

optimized_approach(function, self, *arg, result_operator=<built-in function imul>, contribution_operator=<built-in function ipow>, **kwarg)

Optimized approach to compute cluster correlation expansion.

Parameters
• function (func) – Function to expand.

• self (RunObject) – Object whose method is expanded.

• *arg – list of positional arguments of the expanded function.

• result_operator (func) – Operator which will combine the result of expansion (default: operator.imul).

• contribution_operator (func) – Operator which will combine multiple contributions of the same cluster (default: operator.ipow).

• **kwarg – Dictionary containing all keyword arguments of the expanded function.

Returns

Expanded function.

Return type

func

direct_approach(function, self, *arg, result_operator=<built-in function imul>, removal_operator=<built-in function itruediv>, addition_operator=<function prod>, **kwarg)

Direct approach to compute cluster correlation expansion.

Parameters
• function (func) – Function to expand.

• self (RunObject) – Object whose method is expanded.

• result_operator (func) – Operator which will combine the result of expansion (default: operator.imul).

• removal_operator (func) – Operator which will remove subcluster contribution from the given cluster contribution. First argument cluster contribution, second - subcluster contribution (default: operator.itruediv).

• addition_operator (func) – Group operation which will combine contributions from the different clusters into one contribution (default: np.prod).

• **kwarg – Dictionary containing all keyword arguments of the expanded function.

Returns

Expanded method.

Return type

func

interlaced_decorator(_func=None, *, result_operator=<built-in function imul>, contribution_operator=<built-in function ipow>)

Decorator for creating interlaced cluster correlation expansion of the method of RunObject class.

Parameters
• _func (func) – Function to expand.

• result_operator (func) – Operator which will combine the result of expansion (default: operator.imul).

• contribution_operator (func) – Operator which will combine multiple contributions of the same cluster (default: operator.ipow) in the optimized approach.

Returns

Expanded method.

Return type

func

Decorators that are used to perform bath state sampling over the kernel of RunObject.

generate_bath_state(bath, nbstates, seed=None, fixstates=None, parallel=False)

Generator of the random pure $$\hat{I}_z$$ bath eigenstates.

Parameters
• bath (BathArray) – Array of bath spins.

• nbstates (int) – Number of random bath states to generate.

• seed (int) – Optional. Seed for RNG.

• fixstates (dict) – Optional. dict of which bath states to fix. Each key is the index of bath spin, value - fixed $$\hat{I}_z$$ projection of the mixed state of nuclear spin.

Yields

ndarray – Array of shape = len(bath) containing z-projections of the bath spins states.

monte_carlo_method_decorator(func)

Decorator to sample over random bath states given function.