CCE Calculators

Documentation for the calculator objects called by Simulator object.

Base class

class pycce.run.base.RunObject(timespace, clusters, bath, magnetic_field, center=None, pulses=None, nbstates=None, seed=None, masked=True, parallel=False, direct=False, parallel_states=False, store_states=False, as_delay=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.

Args:

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.

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

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.

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.

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.

as_delay: bool: True if time points are delay between pulses, False if time points are total time.

base_hamiltonian: Hamiltonian: Hamiltonian of the given cluster without mean field additions. In conventional CCE, also excludes additions from central spins.

bath: BathArray with shape (n,): Array of n bath spins.

center: CenterArray: Properties of the central spin.

cluster: BathArray: Array of the bath spins inside the given cluster.

cluster_evolved_states: ndarray or bool: State of the cluster after the evolution

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

contribution_operator(a, b, /)

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

Default: operator.ipow.

delays: list or None: List with delays before each pulse or None if equispaced. Generated by .generate_pulses method.

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.

classmethod from_simulator(sim, **kwargs)

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

Args:: 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:: RunObject: New instance of RunObject class.

generate_pulses()

Generate list of matrix representations of the rotations, induced by the sequence of the pulses.

Returns:

tuple: tuple containing:

list or None: List with delays before each pulse or None if equispaced.
list: List with matrix representations of the rotation from each pulse.

generate_supercluser_states(supercluster)

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

Args:: supercluster (ndarray with shape (n, )): Indexes of the bath spins in the supercluster.
Yields:: ndarray with shape (n, ): Pure state of the given supercluster.

get_hamiltonian_variable_bath_state(index=0)

Generate Hamiltonian in case of the complicated pulse sequence.

Args:: index (int): Index of the flips of spin states.
Returns:: ndarray with shape (n, n): Hamiltonian with mean field additions from the given set of projected states.

hamiltonian: ndarray: Full cluster Hamiltonian.

has_states: bool: Whether there are states provided in the bath during the run.

initial_states_mask: ndarray: Bool array of the states, initially present in the bath.

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

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

Args:

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:

ndarray: Results of the calculations.

interlaced_run(*args, **kwargs)

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

Args:: *args: Positional arguments of the interlaced kernel. **kwargs: Keyword arguments of the interlaced kernel.

Returns:

ndarray: Results of the calculations.

kernel(cluster, *args, **kwargs)

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

Args:: cluster (ndarray): Indexes of the bath spins in the given cluster. *args: Positional arguments of the kernel. **kwargs: Keyword arguments of the kernel.

Returns:

ndarray: Results of the calculations.

magnetic_field: ndarray or callable: Magnetic field of type magnetic_field = np.array([Bx, By, Bz]), or a function that takes position as an argument.

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

nbstates: int: Number of random bath states to sample over in bath state sampling runs.

parallel: bool: True if parallelize calculation of cluster contributions over different mpi processes. Default False.

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

postprocess(): Method which will be called after cluster-expanded run.

preprocess(): Method which will be called before cluster-expanded run.

projected_states: ndarray: Array of \(S_z\) projections of the bath spins after each control pulse, involving bath spins.

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

removal_operator(a, b, /)

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

Defalut: operator.itruediv.

result: ndarray: Result of the calculation.

result_operator(a, b, /)

Operator which will combine the result of expansion,.

Default: operator.imul.

rotations: list: List with matrix representations of the rotation from each pulse. Generated by .generate_pulses method.

run(*args, **kwargs)

Method that runs cluster-expanded single calculation.

Args:: *args: Positional arguments of the kernel. **kwargs: Keyword arguments of the kernel.

Returns:

ndarray: Results of the calculations.

run_with_total_bath(*args, **kwargs)

Numerical simulation using the full bath. Emulates kernel with preprocess and postprocess added.

Args:: *args: Positional arguments of the kernel. **kwargs: Keyword arguments of the kernel.

Returns:

ndarray: Results of the calculations.

sampling_interlaced_run(*args, **kwargs)

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

Args:: *args: Positional arguments of the interlaced kernel. **kwargs: Keyword arguments of the interlaced kernel.

Returns:

ndarray: Results of the calculations.

sampling_run(*args, **kwargs)

Method that runs bath sampling calculations.

Args:: *args: Positional arguments of the kernel. **kwargs: Keyword arguments of the kernel.

Returns:

ndarray: Results of the calculations.

seed: int: Seed for the random number generator in bath states sampling.

store_states: bool: True if store the intermediate state of the cluster. Default False.

timespace: ndarray with shape (t, ): Time points at which result will be computed.

pycce.run.base.combine_cluster_central(cluster_state, central_state)

Combine bath spin states and the state of central spin. Args:

cluster_state (ndarray with shape (n,) or (n, n)): State vector or density matrix of the bath spins. central_state (ndarray with shape (m,) or (m, m)): State vector or density matrix of the central spins.

Returns:: ndarray with shape (mn, ) or (mn, mn): State vector or density matrix of the full system.

pycce.run.base.from_central_state(dimensions, central_state)

Generate density matrix of the system if all spins apart from central spin are in completely mixed state.

Args:: dimensions (ndarray with shape (n,)): Array of the dimensions of the spins in the cluster. central_state (ndarray with shape (x,)): Density matrix of central spins.
Returns:: ndarray with shape (N, N): Density matrix for the whole cluster.

pycce.run.base.from_none(dimensions)

Generate density matrix of the systems if all spins are in completely mixed state. Args:

dimensions (ndarray with shape (n,)): Array of the dimensions of the spins in the cluster.

Returns:: ndarray with shape (N, N): Density matrix for the whole cluster.

pycce.run.base.from_sigma(sigma, i, dims)

Generate spin vector from dictionary with spin matrices.

Args:: sigma (dict): Dictionary, which contains spin matrices of form {'x': Sx, 'y': Sy, 'z': Sz}. i (int): Index of the spin in the order of dims. dims (ndarray with shape (N,)): Dimensions of the spins in the given cluster.
Returns:: ndarray with shape (3, n, n): Spin vector in a full Hilbert space.

pycce.run.base.from_states(states)

Generate density matrix of the systems if all spins are in pure states. Args:

states (array-like): Array of the pure spin states.

Returns:: ndarray with shape (N, N): Spin vector for the whole cluster.

pycce.run.base.generate_initial_state(dimensions, states=None, central_state=None)

Generate initial state of the cluster.

Args:: dimensions (ndarray with shape (n, )): Dimensions of all spins in the cluster. states (BathState, optional): States of the bath spins. If None, assumes completely random state. central_state (ndarray): State of the central spin. If None, assumes that no central spin is present

in the Hilbert space of the cluster.
Returns:: ndarray with shape (N,) or (N, N): State vector or density matrix of the cluster.

pycce.run.base.generate_rotated_projected_states(bath, pulses)

Generate projected states after each control pulse, involving bath spins.

Args:

bath (BathArray with shape (n, )): Array of bath spins. pulses (Sequence): Sequence of pulses.

Returns:

ndarray with shape (n, x):: Array of \(S_z\) projections of bath spin states after each pulse, involving bath spins. Each \(i\)-th column is projections before the \(i\)-th pulse involving bath spins.

pycce.run.base.pulse_bath_rotation(pulse, vectors)

Generate rotation of the bath spins from the given pulse.

Args:: pulse (Pulse): Control pulse. vectors (ndarray with shape (n, 3, N, N): Array of spin vectors.
Returns:: ndarray with shape (x, x): Matrix representation of the spin rotation.

pycce.run.base.rand_state(d)

Generate random state of the spin.

Args:: d (int): Dimensions of the spin.
Returns:: ndarray with shape (d, d): Density matrix of the random state.

pycce.run.base.simple_propagator(timespace, hamiltonian)

Generate a simple propagator \(U=\exp[-\frac{i}{\hbar} \hat H]\) from the Hamiltonian.

Args:

timespace (ndarray with shape (n, )): Time points at which to evaluate the propagator. hamiltonian (ndarray with shape (N, N)): Hamiltonian of the system.

Returns:: ndarray with shape (n, N, N): Propagators, evaluated at each timepoint.

Conventional CCE

class pycce.run.cce.CCE(*args, second_order=False, level_confidence=0.95, **kwargs)

Class for running conventional CCE simulations.

Note

Subclass of the RunObject abstract class.

Args:

*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.
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.

compute_result()

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

Returns:

ndarray: Computed coherence.

energies: ndarray with shape (2s+1, ): All eigen energies of the central spin Hamiltonian.

energy_alpha: float: Eigen energy of the alpha state in the central spin Hamiltonian.

energy_beta: float: Eigen energy of the beta state in the central spin Hamiltonian.

generate_hamiltonian()

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

Returns:

tuple: Tuple containing:

Hamiltonian: Cluster hamiltonian when qubit in the alpha state.

Hamiltonian: Cluster hamiltonian when qubit in the alpha state.

initial_pulses: int or Sequence: Input pulses

level_confidence: float: Maximum fidelity of the qubit state to be considered eigenstate of the central spin hamiltonian.

postprocess(): Method which will be called after cluster-expanded run.

preprocess(): Method which will be called before cluster-expanded run.

projections_alpha: ndarray with shape (3,): 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

projections_alpha_all: ndarray with shape (2s+1, 3): 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.

projections_beta: ndarray with shape (3,): 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.

projections_beta_all: ndarray with shape (2s+1, 3): 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.

propagators()

Generate two propagators, conditioned on the qubit state.

Returns:

tuple: 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.

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

second_order: bool: True if add second order perturbation theory correction to the cluster hamiltonian.

use_pulses: bool: True if use full Sequence. False if use only number of pulses.

pycce.run.cce.propagate_propagators(v0, v1, number)

From two simple propagators and number of pulses in CPMG sequence generate two full propagators. Args:

v0 (ndarray with shape (n, N, N)): Propagator conditioned on the alpha qubit state for each time point. v1 (ndarray with shape (n, N, N)): Propagator conditioned on the beta qubit state for each time point. number (int): Number of pulses.

Returns:

tuple:

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

pycce.run.cce.simple_propagators(delays, hamiltonian_alpha, hamiltonian_beta)

Generate two simple propagators \(U=\exp[-\frac{i}{\hbar} \hat H]\) from the Hamiltonians, conditioned on two qubit levels.

Args:

delays (ndarray with shape (n, )): Time points at which to evaluate the propagator. hamiltonian_alpha (ndarray with shape (N, N)): Hamiltonian of the bath spins with qubit in alpha state. hamiltonian_beta (ndarray with shape (N, N)): Hamiltonian of the bath spins with qubit in beta state.

Returns:

tuple:

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

Generalized CCE

class pycce.run.gcce.gCCE(*args, i=None, j=None, fulldm=False, normalized=True, **kwargs)

Class for running generalized CCE simulations.

Note

Subclass of the RunObject abstract class.

Args:

*args: Positional arguments of the RunObject.

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

fulldm (bool):: True if return full density matrix. Default False.

**kwargs: Keyword arguments of the RunObject.

compute_result()

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

Returns:

ndarray: Computed coherence.

dm0: ndarray with shape (2s+1, 2s+1): Initial density matrix of the central spin.

fulldm: bool: True if return full density matrix.

generate_hamiltonian()

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

Returns:: Hamiltonian: Cluster hamiltonian.

normalization: float: Coherence at time 0.

postprocess(): Method which will be called after cluster-expanded run.

preprocess(): Method which will be called before cluster-expanded run.

process_dm(density_matrix)

Obtain the result from the density matrices.

Args:

density_matrix (ndarray with shape (n, N, N)): Array of the density matrices.

Returns:

ndarray:: Depending on the parameters, returns the off diagonal element of the density matrix or full matrix.

propagator()

Function to compute time propagator U.

Returns:: ndarray with shape (t, n, n): Array of propagators, evaluated at each time point in self.timespace.

zero_cluster: ndarray with shape (n,): Coherence computed for the isolated central spin.

pycce.run.gcce.rotation_propagator(u, rotations)

Generate the propagator from the simple propagator and set of \(2 au\) equispaced rotation operators.

Note

While the spacing between rotation operators is assumed to be \(2 au\), the spacing before and after the first and the last rotation respectively is assumed to be :math:` au`.

Args:: u (ndarray with shape (n, N, N)): Simple propagator. rotations (ndarray with shape (x, N, N)): Array of rotation operators.
Returns:: ndarray with shape (n, N, N): Full propagator.

Noise autocorrelation

class pycce.run.corr.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.

Args:: *args: Positional arguments of the RunObject. **kwargs: Keyword arguments of the RunObject.

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.

compute_result()

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

Returns:

ndarray: Computed autocorrelation function.

contribution_operator(a, b, /): Overridden operator which will combine multiple contributions of the same cluster in the optimized approach: operator.imul.

generate_hamiltonian()

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

Returns:: Hamiltonian: Cluster hamiltonian.

postprocess(): Method which will be called after cluster-expanded run.

preprocess(): Method which will be called before cluster-expanded run.

removal_operator(a, b, /): Overridden operator which remove subcluster contribution from the given cluster contribution: operator.isub.

result_operator(a, b, /): Overridden operator which will combine the result of expansion: operator.iadd.

pycce.run.corr.compute_correlations(nspin, dm0_expanded, U, central_spin=None)

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

Args:

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 (CenterArray): Array of central spins.

Returns:

ndarray with shape (t,):: correlation of the Overhauser field, induced by the given cluster at each time point.

pycce.run.corr.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

Args:

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:

ndarray with shape (t,): Autocorrelation of the z-noise at each time point.

class pycce.run.corr.gCCENoise(*args, **kwargs)

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

Note

Subclass of the RunObject abstract class.

Args:: *args: Positional arguments of the RunObject. **kwargs: Keyword arguments of the RunObject.

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.

compute_result()

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

Returns:

ndarray: Computed autocorrelation function.

contribution_operator(a, b, /): Overridden operator which will combine multiple contributions of the same cluster in the optimized approach: operator.imul.

generate_hamiltonian()

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

Returns:: Hamiltonian: Cluster hamiltonian.

postprocess(): Method which will be called after cluster-expanded run.

preprocess(): Method which will be called before cluster-expanded run.

removal_operator(a, b, /): Overridden operator which remove subcluster contribution from the given cluster contribution: operator.isub.

result_operator(a, b, /): Overridden operator which will combine the result of expansion: operator.iadd.

Cluster-correlation expansion decorators

The way we find cluster in the code.

pycce.find_clusters.combine_clusters(cs1, cs2)

Combine two dictionaries with clusters.

Args:

cs1 (dict): First cluster dictionary with keys corresponding to size of the cluster,: and value corresponds to ndarray of shape (M, N).

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

Returns:

dict: Combined dictionary with unique clusters from both dictionaries.

pycce.find_clusters.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

pycce.find_clusters.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.

Args:: sc (dict): Initial clusters dictionary.
Returns:: dict: Dictionary with expanded clusters.

pycce.find_clusters.find_subclusters(maximum_order, graph, labels, n_components, strong=False)

Find subclusters from connectivity matrix.

Args:

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:

dict:: Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (M, N). Here M 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.

pycce.find_clusters.find_valid_subclusters(graph, maximum_order, nclusters=None, bath=None, strong=False, compute_strength=None)

Find subclusters from connectivity matrix.

Args:

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:

dict:: Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (M, N). Here M 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.

pycce.find_clusters.generate_clusters(bath, r_dipole, order, r_inner=0, ignore=None, strong=False, nclusters=None)

Generate clusters for the bath spins.

Args:

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:

dict:
Dictionary with keys corresponding to size of the cluster, and value corresponds to ndarray of shape (M, N). Here M 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.

pycce.find_clusters.make_graph(bath, r_dipole, r_inner=0, ignore=None, max_size=5000)

Make a connectivity matrix for bath spins.

Args:

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:

crs_matrix: Connectivity matrix.

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.

pycce.run.clusters.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.

Args:

_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 (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).

Returns:

func: Expanded function.

pycce.run.clusters.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.

Args:

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:

func: Expanded method.

pycce.run.clusters.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.

Args:

_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:

func: Expanded method.

pycce.run.clusters.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.

Args:

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:

func: Expanded function.

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

pycce.run.mc.generate_bath_state(bath, nbstates, seed=None, parallel=False)

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

Args:: bath (BathArray): Array of bath spins. nbstates (int): Number of random bath states to generate. seed (int): Optional. Seed for RNG. parallel (bool): True if run in parallel mode. Default False.
Yields:: List: list of the pure bath spin state vectors.

pycce.run.mc.monte_carlo_method_decorator(func): Decorator to sample over random bath states given function.