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 subclasses 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 timeevolution 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 systembath 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 Truefilter, FalseNo 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
Truekeep aux, Falseremove aux.

check_markovian
(aux, list_boolean)¶ Checks whether an auxiliary is an allowed markovian mode or a nonmarkovian mode.
 Parameters
 1. auxinstance(AuxiliaryVector)
 2. list_booleanlist
List of boolean values True: markovian mode, False: nonmarkovian mode.
 Returns
 1. allowedboolean
True: nonmarkovian/ 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: TrueFilter, FalseNo 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 nonzero 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: TrueFilter, FalseNo 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 nonzero 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 nonmarkovian 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: nonmarkovian 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 nonzero 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 Markovianfiltered 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 LongEdgefiltered 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 LongEdgefiltered 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 subindexed 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 subindexed 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 nonzero 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 ((Nn1 , Lsum(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 nonzero 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!(nk)!).

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 Loperators that have any nonzero 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, <vecOpervec> /( <vecvec>).
mesohops.dynamics.eom_hops_ksuper module¶

calculate_ksuper
(system, hierarchy, mode)¶ Calculates all the pieces needed to timeevolve the system EXCEPT for the normalization term. Used to create the timeevolution superoperators when they have not yet been constructed.
 Parameters
 1. systeminstance(HopsSystem)
 2. hierarchyinstance(HopsHierarchy)
 3. modeinstance(HopsMode)
 Returns
 1. K0sparse matrix
Updated timeinvariant selfinteraction superoperator.
 2. Kp1sparse matrix
Updated timeinvariant K+1 interaction superoperator.
 3. Zp1sparse matrix
Updated timevarying K+1 interaction superoperator.
 4. Km1sparse matrix
Updated timeinvariant K1 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
Timeinvariant selfinteraction superoperator.
 2. Kp1sparse matrix
Timeinvariant K+1 interaction superoperator.
 3. Zp1sparse matrix
Timevarying K+1 interaction superoperator.
 4. Km1sparse matrix
Timeinvariant K1 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 timeinvariant selfinteraction superoperator.
 2. Kp1sparse matrix
Updated timeinvariant K+1 interaction superoperator.
 3. Zp1sparse matrix
Updated timevarying K+1 interaction superoperator.
 4. Km1sparse matrix
Updated timeinvariant K1 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 timeevolving 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 adaptivehops strategies are used.