Basis package

Basis Class

mesohops.dynamics.hops_basis class

class HopsBasis(system, hierarchy, eom)

Bases: object

Every HOPS calculation is defined by the HopsSystem, HopsHierarchy, and HopsEOM classes (and their associated parameters). These form the basis set for the calculation. HopsBasis is the class that contains all of these sub-classes and mediates the way the HopsTrajectory interacts with them.

_define_hierarchy_basis(self, Φ, delta_t, z_step)

Determines the auxiliaries which should be included in the adaptive integration for the next time point.

Parameters

1. Φnp.array

Current full hierarchy.

2. delta_tfloat

Timestep for the calculation.

3. z_steplist

List of noise terms (compressed) for the next timestep.

Returns

1. list_aux_stablelist

List of the stable auxiliaries (H_S).

2. list_aux_boundarylist

List of auxiliaries that share a boundary with stable auxiliaries (H_B).

_define_state_basis(self, Φ, delta_t, z_step, list_index_aux_stable, list_aux_bound)

Determines the states which should be included in the adaptive integration for the next time point.

Parameters

1. Φnp.array

Current full hierarchy.

2. delta_tfloat

Timestep for the calculation.

3. z_steplist

List of noise terms (compressed) for the next timestep.

4. list_index_aux_stablelist(int)

List of relative indices for the stable auxiliaries.

5. list_aux_bound: list(HopsAux)

List of the auxiliary objects in the Boundary Auxiliary Basis.

Returns

1. list_state_stablelist

List of stable states (absolute state index, S_S).

2. list_state_boundarylist

List of the boundary states (absolute state index, S_B).

static _determine_basis_from_list(error_by_member, max_error, list_member)

Determines the members of a list that must be kept in order for the total error (terms that are dropped) to be below the max_error value.

Parameters

1. error_by_membernp.array

List of error values.

2. max_errorfloat

Maximum error value.

3. list_membernp.array

List of members.

Returns

1. list_indexnp.array

List of indices for the members.

2. list_new_memberlist

List of the members.

_determine_boundary_hier(self, list_e2_kflux, list_index_aux_stable, bound_error)

Determines the set of boundary auxiliaries for the next time step.

Parameters

1. list_e2_kfluxlist

List of list containing the squared error values for the flux up and flux down terms.

2. list_index_aux_stablelist

List of the indices for stable auxiliaries.

3. bound_errorfloat

Boundary error value.

Returns

1. list_aux_boundarylist

List of the flux up and flux down auxiliaries.

define_basis(self, Φ, delta_t, z_step)

Determines the basis that is needed for a given full hierarchy (Φ) in order to construct an approximate derivative with error below the specified threshold.

Parameters

1. Φnp.array

Current full hierarchy.

2. delta_tfloat

Timestep for the calculation.

3. z_steplist

List of noise terms (compressed) for the next timestep.

Returns

1. list_state_newlist

List of states in the new basis (S_1).

2. list_aux_newlist

List of auxiliaries in new basis (H_1).

hier_stable_error(self, Φ, delta_t, z_step)

Finds the total error associated with removing k in A_t.

Parameters

1. Φnp.array

Current full hierarchy vector.

2. delta_tfloat

Timestep for the calculation.

3. z_steplist

List of noise terms (compressed) for the next timestep.

Returns

1. errornp.array

List of error associated with removing each auxiliary in A_t.

2. E2_flux_upnp.array

Error induced by neglecting flux from A_t to auxiliaries with lower summed index in A_t^C.

3. E2_flux_downnp.array

Error induced by neglecting flux from A_t to auxiliaries with higher summed index in A_t^C.

initialize(self, psi_0)

Initializes the hierarchy and equations of motion classes so that everything is prepared for integration. It returns the dsystem_dt function to be used in the integrator.

Parameters

1. psi_0np.array

Initial wave function.

Returns

1. dsystem_dtfunction

The core function for calculating the time-evolution of the wave function.

state_stable_error(self, Φ, delta_t, z_step, list_index_aux_stable, list_aux_bound)

Finds the total error associated with neglecting n in the state basis S_t. This includes the error associated with deleting a state from the basis, the error associated with losing all flux into a state, and the error associated with losing all flux out of a state.

Parameters

1. Φnp.array

Current full hierarchy vector.

2. delta_tfloat

Timestep for the calculation.

3. z_steplist

List of noise terms (compressed) for the next timestep.

4. list_index_aux_stablelist(int)

List of relative indices for the stable auxiliaries (A_s).

5. list_aux_boundlist(HopsAux)

List of Auxiliary Objects in the Boundary Auxiliary Basis.

Returns

1. errornp.array

List of error associated with removing each state.

update_basis(self, Φ, list_state_new, list_aux_new)

Updates the derivative function and full hierarchy vector (Φ) for the new basis (hierarchy and/or system).

Parameters

1. Φnp.array

Current full hierarchy.

2. list_state_new: list

New list of states.

3. list_aux_newlist

New list of auxiliaries.

Returns

1. Φ_newnp.array

Updated full hierarchy.

2. dsystem_dtfunction

Updated derivative function.

System Class

mesohops.dynamics.hops_system class

class HopsSystem(system_param)

Bases: object

HopsSystem is a class that stores the basic information about the system and system-bath coupling.

initialize(self, flag_adaptive, psi_0)

Creates a state list depending on whether the calculation is adaptive or not.

Parameters

1. flag_adaptiveboolean

Boolean that defines the adaptivity True: Adaptive, False: Static.

2. psi_0np.array

Initial user inputted wave function.

Returns

None

static reduce_sparse_matrix(coo_mat, state_list)

Takes in a sparse matrix and list which represents the absolute state to a new relative state represented in a sparse matrix

Parameters

1. coo_matscipy sparse matrix

Sparse matrix.

2. state_listlist

List of relative index.

Returns

1. sparsenp.array

Sparse matrix in relative basis.

Hierarchy Class

mesohops.dynamics.hierarchy_functions module

check_long_edge(aux_vec, list_boolean, kmax, kdepth)

Checks if an individual auxiliary should be filtered out by the longedge filter.

Parameters

1. auxtuple

Auxiliary to check.

2. list_booleanlist

The modes to filter True-filter, False-No filter.

3. kmaxint

Maximum depth of the hierarchy.

4. kdepthint

Depth beyond which only edge members of hierarchy are kept for filtered modes.

Returns

1. check_auxbool

True-keep aux, False-remove aux.

check_markovian(aux, list_boolean)

Checks whether an auxiliary is an allowed markovian mode or a non-markovian mode.

Parameters

1. auxinstance(AuxiliaryVector)

2. list_booleanlist

List of boolean values True: markovian mode, False: non-markovian mode.

Returns

1. allowedboolean

True: non-markovian/ allowed markovian, False: disallowed markovian.

filter_aux_longedge(list_aux, list_boolean_by_mode, kmax, kdepth)

Beyond kdepth, only keep the edge terms upto kmax.

Parameters

1. list_auxlist

List of auxiliaries.

2. list_boolean_by_modelist

List of booleans: True-Filter, False-No Filter.

3. kmaxint

Maximum depth of the hierarchy.

4. kdepthint

Depth beyond which only edge members of hierarchy are kept for filtered modes.

Returns

1. list_new_auxlist

Filtered list of auxiliaries.

filter_aux_triangular(list_aux, list_boolean_by_mode, kmax, kdepth)

If the mode has a non-zero value, then it is kept only if the value is less than kmax and the total auxillary is less than kdepth. This essentially truncates some modes at a lower order than the other modes.

Parameters

1. list_auxlist

List of auxiliary tuples.

2. list_boolean_by_modelist

List of booleans: True-Filter, False-No Filter.

3. kmaxint

The largest value a filtered mode can have in an auxiliary.

4. kdepthint

The largest depth of an auxiliary at which a filtered mode can have a non-zero value.

Returns

1. list_new_auxlist

Filtered list of auxiliaries.

filter_markovian(list_aux, list_boolean)

Filters a list of auxiliaries based on whether it is a non-markovian auxiliary or an allowed markovian auxiliary.

Parameters

1. list_auxlist

List of unfiltered auxiliaries.

2. list_booleanlist

List of boolean values True: markovian mode, False: non-markovian mode

Returns

list_auxlist

Filtered auxiliary list.

mesohops.dynamics.hops_hierarchy class

class HopsHierarchy(hierarchy_param, system_param)

Bases: mesohops.util.dynamic_dict.Dict_wDefaults

HopsHierarchy defines the representation of the hierarchy in the HOPS calculation. It contains the user parameters, helper functions, and the list of all nodes contained in the hierarchy.

add_connections(self)

The method responsible for adding the connections between HopsAux objects composing an auxiliary list.

Parameters

None

Returns

None

apply_filter(self, list_aux, filter_name, params)

Implements a variety of different hierarchy filtering methods. In all cases, this filtering begins with the current list of auxiliaries and then prunes down from that list according to a set of rules.

Parameters

1. list_auxlist

List of auxiliaries that needs to be filtered.

2. filter_namestr

Name of filter.

3. paramslist

List of parameters for the filter.

Returns

1. list_auxlist

List of filtered auxiliaries.

ALLOWED LIST OF FILTERS:

• Triangular: boolean_by_mode, [kmax, kdepth]

  If the mode has a non-zero value, then it is kept only if the value is less than kmax and the total auxillary is less than kdepth. This essentially truncates some modes at a lower order than the other modes.

• LongEdge: boolean_by_mode, [kmax, kdepth]

  Beyond kdepth, only keep the edge terms upto kmax.

• Markovian: boolean_by_mode

  All vectors with depth in the specified modes are filtered out unless they are the “unit auxiliary:” that is, its indexing vector is 1 in the Markovian-filtered mode. Equivalent to a Triangular filter with kmax = kdepth = 1 in the filtered modes.

static define_markovian_and_LE_filtered_triangular_hierarchy(n_hmodes, maxhier, list_boolean_mark, list_boolean_le, edge_le)

Creates a triangular hierarchy when the Markovian and LongEdge filters are in use, applying the filters as the hierarchy is constructed to reduce transient memory burdens.

IMPORTANT: This function relies on being filtered after it runs to get rid of the terms with a depth greater than LE_depth in the modes filtered by list_boolean_LE. THIS FUNCTION SHOULD NEVER BE RUN WITHOUT BEING WRAPPED BY SELF.FILTER_AUX_LIST()!

Parameters

1. n_hmodesint

Number of modes that appear in the hierarchy.

2. maxhierint

Max single value of the hierarchy.

3. list_boolean_marklist(boolean)

List by mode of whether the Markovian filter will be applied.

4. list_boolean_LE: list(boolean)

List by mode of whether the LongEdge filter will be applied.

5. depth_le: int

Allowed hierarchy depth of the LongEdge-filtered modes. This parameter is unused in the code: we include it due to the dictionary structure associated with the LongEdge filter.

6. edge_le: int

Depth beyond which LongEdge-filtered modes retain only edge terms.

Returns

1. list_auxlist

List of auxiliaries in the new triangular hierarchy.

static define_markovian_filtered_triangular_hierarchy(n_hmodes, maxhier, list_boolean_mark)

Creates a triangular hierarchy when the Markovian filter is in use, applying the Markovian filter as the hierarchy is constructed to reduce transient memory burdens.

Parameters

1. n_hmodesint

Number of modes that appear in the hierarchy.

2. maxhierint

Max single value of the hierarchy

3. list_boolean_marklist(boolean)

List by mode of whether the Markovian filter will be applied

Returns

1. list_auxlist

List of auxiliaries in the new triangular hierarchy.

static define_triangular_hierarchy(n_hmodes, maxhier)

Creates a triangular hierarchy for a given number of modes at a given depth.

Parameters

1. n_hmodesint

Number of modes that appear in the hierarchy.

2. maxhierint

Max single value of the hierarchy.

Returns

1. list_auxlist

List of auxiliaries in the new triangular hierarchy.

filter_aux_list(self, list_aux)

Applies all of the filters defined for the hierarchy in “STATIC_FILTERS”.

Parameters

1. list_auxlist

List of auxiliaries to be filtered.

Returns

1. list_auxlist

Filtered list of auxiliaries.

initialize(self, flag_adaptive)

This function will initialize the hierarchy.

Parameters

1. flag_adaptiveboolean

Boolean describing whether the calculation is adaptive or not.

Returns

None

mesohops.dynamics.hops_aux class

class AuxiliaryVector(aux_array, nmodes)

Bases: collections.abc.Mapping

This is a class that encodes a sparse representation of auxiliary vectors with some extra helper functions to simplify some common actions, such as: determining the absolute index, adding a unit vector, and calculating the sum.

The class is not mutable - which is to say, once an auxiliary vector is defined, it cannot be changed.

add_aux_connect(self, index_mode, aux_other, type)

Updates the HopsAux object to contain a pointer to the other HopsAux objects it is connected to.

Parameters

1. index_modeint

Mode along which the two HopsAux objects are connected.

2. aux_otherHopsAux

HopsAux object that self is connected to.

3. typeint

+1 or -1 depending on if the other aux has a larger or smaller sum.

Returns

None

difference_by_mode(self, other)

Compares the current HopsAux object to another HopsAux object. If they differ by only 1 step, then it returns the mode along which they differ.

Parameters

1. other: HopsAux object

The HopsAux object to which the current object is compared.

Returns

1. diff_modeint or False

The mode index along which they differ or False if they differ by more than 1 step.

dot(self, vec)

Performs a sparse dot product between the auxiliary index vector and another vector.

Parameters

1. vecnp.array

A vector.

Returns

1. productfloat

Dot product value.

e_step(self, mode, step)

Returns a new Auxiliary Vector with the desired step in the given mode.

Parameters

1. modeint

Absolute mode index.

2. stepint

Change in the aux value for the given mode.

Returns

1. aux_vectuple

New sparse auxiliary vector.

get_list_identity_string_down(self)

Construct the hash values for all auxiliaries that are one step down from this auxiliary.

Parameters

None

Returns

None

get_list_identity_string_up(self, modes_in_use)

Constructing all auxiliaries within one step ‘up’ from the current auxiliary along modes that are currently in the basis.

[Explain algorithm]

Parameters

1. modes_in_uselist

List of modes along which the new identity string will be calculated

Returns

1. list_hash_string_uplist

List of hash strings of downward auxiliary connections

2. list_value_connectslist

List of values of the auxiliary corresponding to 1.

3. list_mode_connectslist

List of modes of auxiliary connections corresponding to 1.

get_values(self, index_slice)

Gets the dense auxiliary vector values from a sub-indexed list.

Parameters

1. index_slicelist

List of indices.

Returns

1. valuesarray

Array of values at the given indices.

get_values_nonzero(self, index_slice)

Gets the sparse auxiliary vector values from a sub-indexed list. NOTE: the values are returned in key order, not the order they are present in index_slice.

Parameters

1. index_slicelist

List of indices.

Returns

1. valuesarray

Sparse array of the non-zero auxiliary vector values.

index_analytic(self)

This function provides an absolute index value for an auxiliary vector using an analytic function of the indices. The basic idea is that the indices are always ordered by increasing hierarchy ‘level’ (i.e. the sum of the indices). Within a level they are ordered by first comparing the first values, then the second values, etc.

This gives the indexing a particularly simple form with a level: L = sum(i_0,…,i_n) (i_0, … i_N) = sum_n<N sum_L>ln>i_n ((N-n-1 , L-sum(aux[:n])-ln) where ((L,K)) denotes a L multichoose K.

The derivation of the following equations is given on p. 68 of Quantum Notebook #1. The sums have been removed by making use of the binomial sum property and the binomial symmetry property. The result is a equation that only sums over a number of elements equal to the number of non-zero terms in aux.

Parameters

None

Returns

1. indexint

Absolute index for an auxiliary.

keys(self)

Returns an array of mode indices for the auxiliary vectors.

Parameters

None

Returns

1. keysarray

Array of mode indices with nonzero auxiliary index.

remove_aux_connect(self, index_mode, type)

Removes the connection between the HopsAux object and another connected with type (+1/-1) along index mode.

Parameters

1. index_modeint

Mode along which the two HopsAux objects are connected.

2. typeint

+1 or -1 depending on if the other aux has a larger or smaller sum.

Returns

None

remove_pointers(self)

Removes all pointers targeting the current HopsAux object from the set of HopsAux objects it has connections to.

Parameters

None

Returns

None

sum(self, **unused_kwargs)

Calculates the sum of the auxiliary vector values.

Parameters

None

Returns

1. sumfloat

Sum of the nonzero values of the auxiliary vectors.

toarray(self)

Converts a dict to an array.

Parameters

None

Returns

1. arrayarray

Dict in an array form.

todense(self)

Convert a sparse vector into a dense vector.

Parameters

None

Returns

1. outputarray

Dense vector.

tuple_from_e_step(self, mode, step)

Returns the sparse tuple representation of the auxiliary that is the given step length along the given absolute mode index away from the current auxiliary.

Parameters

1. modeint

Absolute mode index.

2. stepint

Change in the aux value for the given mode.

Returns

1. tuple_auxtuple

Sparse representation of the auxiliary (sorted mode order).

values(self)

Returns an array of the auxiliary vector values.

Parameters

None

Returns

1. valuesarray

Array of nonzero auxiliary index values.

binom_integer(n_arr, k_arr)

A binomial distribution calculator that uses only Python integers to achieve arbitrary precision and avoid issues with float overflow. Takes in any iterable or single value

Parameters

1. n_arrarray(int)

Number of options - must be larger than or equal to k.

2. k_arrarray(int)

Number of choices - must be smaller than or equal to n.

Returns

1. distint

Result of the formula n!/(k!(n-k)!).

intsum(arr)

Helper function similar to np.sum that is exclusively for use with integers and does not change the data type at any point.

Parameters

1. arrarray(int)

Array of integers to be summed over.

Returns

1. sumint

Sum of the array of integers.

EOM Class

mesohops.dynamics.eom_functions module

calc_delta_zmem(z_mem, list_avg_L2, list_g, list_w, list_index_L2_by_mode, list_absindex_mode, list_index_L2_active)

This updates the memory term. The form of the equation depends on expanding the memory integral assuming an exponential expansion.

NOTE: THIS ASSUMES THE NOISE HAS EXPONENTIAL FORM.

NOTE: Again this function mixes relative and absolute

indexing which makes it much more confusing. z_mem : absolute list_avg_L2 : relative list_g : absolute list_w : absolute list_index_L2_by_mode : relative list_absindex_mode : mapping from relative–>absolute list_index_L2_active : relative

Parameters

1. z_memlist(complex)

List of memory terms in absolute indices.

2. list_avg_L2list(complex)

Relative list of the expectation values of the L operators.

3. list_glist(complex)

List of pre exponential factors for bath correlation functions [ absolute].

4. list_wlist(complex)

List of exponents for bath correlation functions (w = γ+iΩ) [absolute].

5. list_index_L2_by_modelist(int)

List of length equal to the number of ‘modes’ in the current hierarchy basis and each entry is an index for the absolute list_L2.

6. list_absindex_modelist(int)

List of the absolute indices of the modes in current basis.

7. list_index_L2_activelist(int)

List of relative indices of L-operators that have any non-zero values.

Returns

1. delta_z_memlist(complex)

List of updated memory terms.

calc_norm_corr(phi, z_hat, list_avg_L2, list_L2, nstate, list_index_phi_L2_mode, list_g, list_w)

Computes the correction factor for propagating the normalized wave function.

Parameters

1. phinp.array(complex)

Full hierarchy.

2. z_hatlist(complex)

List of memory term with both with random noise.

3. list_avg_L2list(complex)

Relative list of the expectation values of the L operators.

4. list_L2list(sparse matrix)

List of L operators.

5. nstateint

Current dimension (size) of the system.

6. list_index_L2_by_modelist(int)

List of length equal to the number of modes in the current hierarchy basis: each entry is an index for the relative list_L2.

7. list_glist(complex)

List of pre exponential factors for bath correlation functions [ absolute].

8. list_wlist(complex)

List of exponents for bath correlation functions (w = γ+iΩ) [absolute].

Returns

1. deltafloat

Norm correction factor.

compress_zmem(z_mem, list_index_L2_by_mode, list_absindex_mode)

Compresses all of the memory terms into their respective slots for each L_operator.

Parameters

1. z_memlist(complex)

List of all the memory terms in absolute basis.

2. list_index_L2_by_modelist(complex)

List of length equal to the number of modes in the current hierarchy basis.

3. list_absindex_modelist(int)

List of absolute mode indices in relative mode order.

Returns

1. dz_hatlist(complex)

List of compressed memory terms indexed by list_index_L2_by_mode.

operator_expectation(oper, vec, flag_gcorr=False)

Calculates the expectation value of a sparse operator

Parameters

1. opernp.array

Dense or sparse operator.

2. vecnp.array

An nx1 matrix.

3. flag_gcorrbool

Whether to correct the normalization for the inclusion of a ground state (in the dyadic equation governing absorption).

Returns

1. expectation_valuefloat

Expectation value of the operator, <vec|Oper|vec> /( <vec|vec>).

mesohops.dynamics.eom_hops_ksuper module

calculate_ksuper(system, hierarchy, mode)

Calculates all the pieces needed to time-evolve the system EXCEPT for the normalization term. Used to create the time-evolution super-operators when they have not yet been constructed.

Parameters

1. systeminstance(HopsSystem)

2. hierarchyinstance(HopsHierarchy)

3. modeinstance(HopsMode)

Returns

1. K0sparse matrix

Updated time-invariant self-interaction superoperator.

2. Kp1sparse matrix

Updated time-invariant K+1 interaction superoperator.

3. Zp1sparse matrix

Updated time-varying K+1 interaction superoperator.

4. Km1sparse matrix

Updated time-invariant K-1 interaction superoperator.

update_ksuper(K0, Kp1, Zp1, Km1, system, hierarchy, mode, perm_index)

Updates the EOM matrices to incorporate changes to the hierarchy. At the moment, this function is the key step to handling Dynamic Filtering of the hierarchy.

Parameters

1. K0sparse matrix

Time-invariant self-interaction superoperator.

2. Kp1sparse matrix

Time-invariant K+1 interaction superoperator.

3. Zp1sparse matrix

Time-varying K+1 interaction superoperator.

4. Km1sparse matrix

Time-invariant K-1 interaction superoperator.

5. systeminstance(HopsSystem)

6. hierarchyinstance(HopsHierarchy)

7. modeinstance(HopsMode)

8. perm_indexlist(list(int))

List of column list and row list that define the permutation matrix.

Returns

1. K0sparse matrix

Updated time-invariant self-interaction superoperator.

2. Kp1sparse matrix

Updated time-invariant K+1 interaction superoperator.

3. Zp1sparse matrix

Updated time-varying K+1 interaction superoperator.

4. Km1sparse matrix

Updated time-invariant K-1 interaction superoperator.

mesohops.dynamics.hops_eom class

class HopsEOM(eom_params)

Bases: mesohops.util.dynamic_dict.Dict_wDefaults

HopsEOM is the class that defines the equation of motion for time-evolving the hops trajectory. Its primary responsibility is to define the derivative of the system state. It also contains the parameters that determine what kind of adaptive-hops strategies are used.