Basis package

Basis Class

mesohops.dynamics.hops_basis class

class HopsBasis(system, hierarchy, eom)

Bases: object

Every HOPS calculation is defines 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 will interact with them.

_check_hierarchy_list(self, Φ, delta_t, z_step)

This is a function that determines the auxiliaries which should be included in the adaptive integration for the next time point.

Parameters

1. Φnp.array

the current full hierarchy

2. delta_tfloat

the timestep for the calculation

3. z_steplist

the list of noise terms (compressed) for the next timestep

Returns

1. list_aux_stablelist

a list of the stable auxiliaries (H_S)

2. list_aux_boundarylist

a list of auxiliaries that share a boundary with stable auxiliaries (H_B)

_check_state_list(self, Φ, delta_t, z_step, list_index_aux_stable)

This is a function that determines the states which should be included in the adaptive integration for the next time point.

Parameters

1. Φnp.array

the current full hierarchy

2. delta_tfloat

the timestep for the calculation

3. z_steplist

the list of noise terms (compressed) for the next timestep

4. list_index_aux_stablelist

a list of relative indices for the stable auxiliaries

Returns

1. list_state_stablelist

list of stable states (absolute state index, S_S)

2. list_state_boundarylist

a list of the boundary states (absolute state index, S_B)

_determine_basis_from_list(self, error_by_member, max_error, list_member)

This function 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

a list of error values

2. max_errorfloat

the maximum error value

3. list_membernp.array

a list of members

Returns

1. list_indexnp.array

a list of indices for the members

2. list_new_memberlist

a list of the members

_determine_boundary_hier(self, list_e2_kflux, list_index_aux_stable, bound_error)

This function determines the set of boundary auxiliaries for the next time step

Parameters

1. list_e2_kfluxlist

a list of list containing the error values for the flux up and flux down terms

2. list_index_aux_stablelist

a list of the indices for stable auxiliaries

3. bound_errorfloat

the boundary error value

Returns

1. list_aux_uplist

a list of the flux up auxiliaries

2. list_aux_downlist

a list of the flux down auxiliaries

static _determine_error_thresh(sorted_error, max_error)

This function determines which error value becomes the error threshold such that the sum of all errors below the threshold remains less then max_error.

Parameters

1. sorted_errornp.array

a list of error values

2. max_errorfloat

the maximum error value

Returns

3. error_threshfloat

the error value at which the threshold is established

define_basis(self, Φ, delta_t, z_step)

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

Parameters

1. Φnp.array

the current full hierarchy

2. delta_tfloat

the timestep for the calculation

3. z_steplist

the list of noise terms (compressed) for the next timestep

Returns

1. state_update :

   1. list_state_newlist

      list of states in the new basis (S_1)

   2. list_state_stablelist

      list of stable states in the new basis (S_S)

   3. list_state_boundlist

      list of boundary states in the new basis (S_B)

2. hierarchy_update :

   4. list_aux_newlist

      list of auxiliaries in new basis (H_1)

   5. list_stable_auxlist

      list of stable auxiliaries in the new basis (H_S)

   6. list_aux_boundlist

      list of boundary auxiliaries in the new basis (H_B)

error_boundary_state(self, Φ, list_index_stable, list_index_aux_stable)

This function determines the error associated with neglecting flux into n’ not a member of S_t.

\[\sum_{\vec{k} \in \mathcal{H}_{t}} \left \vert (\hat{H} \psi^{(\vec{k})}_t)_n \right\vert^2\]

Parameters

1. Φnp.array

the current full hierarchy vector

2. list_index_stablelist

a list of the stable states

3. list_index_aux_stablelist

a list relative indices for the stable auxiliaries

Returns

1. list_index_nonzerolist

a list of the nonzero state boundary indices

2. list_error_nonzerolist

a list of the nonzero state boundary error values

error_deletion(self, Φ, delta_t)

The error associated with setting the corresponding component of Phi to 0. This is equivalent to adding a term to our approximate derivative that is absent in the full derivative, corresponding to

\[\sum_{n \in \mathcal{S}_{t}} \frac{\vert \psi^{(\vec{k})}_{t,n}\vert^2}{dt}\]

\[\sum_{\vec{k} \in \mathcal{H}_{t}} \frac{\vert \psi^{(\vec{k})}_{t,n}\vert^2}{dt}\]

Parameters

1. Φnp.array

The current position of the full hierarchy vector

2. delta_tfloat

the timestep for the calculation

Returns

1. E2_site_auxnp.array

the error induced by removing components of Φ in H_t+S_t

error_deriv(self, Φ, z_step, list_index_aux_stable=None)

The error associated with losing all flux terms into the k auxiliary and n’ state. Where k is in H_t and n’ is in S_t.

\[\sum_{n \in \mathcal{S}_{t}} \left\vert \frac{\delta_{a} \psi^{(\vec{k})}_{t,n}}{\delta t_a} \right\vert^2\]

\[\sum_{\vec{k} \in \mathcal{H}_{t}} \left\vert \frac{\delta_{a} \psi^{(\vec{k})}_{t,n}}{\delta t_a} \right\vert^2\]

Parameters

1. Φnp.array

The current full hierarchy vector

2. z_steplist

the list of noise terms (compressed) for the next timestep

3. list_index_aux_stablelist

a list relative indices for the stable auxiliaries

Returns

1. E2_del_phinp.array

the error associated with losing flux to a component (either hierarchy or state basis element) in H_t direct sum S_t

error_flux_down(self, Φ, type)

A function that returns the error associated with neglecting flux from members of H_t to auxiliaries in H_t^C that arise due to flux from higher auxiliaries to lower auxiliaries.

\[\sum_{n \in \mathcal{S}_{t}} \left \vert F[\vec{k}-\vec{e}_n] \frac{g_n}{\gamma_n} N^{(\vec{k})}_t \psi_{t,n}^{(\vec{k})}\right \vert^2\]

\[\sum_{\vec{k} \in \mathcal{H}_{t}} \left \vert F[\vec{k}-\vec{e}_n] \frac{g_n}{\gamma_n} N^{(\vec{k})}_t \psi_{t,n}^{(\vec{k})}\right \vert^2\]

Parameters

1. Φnp.array

The current state of the hierarchy

2. type: string

‘H’ - Hierarchy type calculation ‘S’ - State type calculation

Returns

1. E2_flux_down_errornp.array

the error induced by neglecting flux from H_t (or H_S) to auxiliaries with higher summed index in H_t^C.

error_flux_up(self, Φ)

A function that returns the error associated with neglecting flux from members of H_t to auxiliaries in H_t^C that arise due to flux from lower auxiliaries to higher auxiliaries.

\[\sum_{n \in \mathcal{S}_{t}} \left \vert F[\vec{k}+\vec{e}_n] \gamma_n (1+\vec{k}[n]) \psi_{t,n}^{(\vec{k})} \right \vert^2\]

\[\sum_{\vec{k} \in \mathcal{H}_{t}}\left \vert F[\vec{k}+\vec{e}_n] \gamma_n (1+\vec{k}[n]) \psi_{t,n}^{(\vec{k})} \right \vert^2\]

Parameters

1. Φnp.array

The current state of the hierarchy

Returns

1. E2_flux_up_errornp. array

the error induced by neglecting flux from H_t (or H_S) to auxiliaries with lower summed index in H_t^C.

error_sflux_hier(self, Φ, list_s0)

The error associated with losing all flux terms inside the kth auxiliary to states not contained in S_t.

\[\sum_{n \notin \mathcal{S}_{t}} \left \vert (\hat{H} \psi^{(\vec{k})}_t)_n \right\vert^2\]

Parameters

1. Φnp.array

the current full hierarchy vector

2. list_s0list

a list of the current states (absolute index)

Returns

1. E2_flux_statearray

the error introduced by losing flux within k from S_t to S_t^C for each k in H_t

error_sflux_state(self, Φ, list_index_aux_stable, list_states)

The error associated with losing all flux out of n’ in S_t. This flux always involves changing the state index and, as a result, can be rewritten in terms of the -iH component of the self-interaction.

\[\sum_{\vec{k} \in \mathcal{H}_{t}} \sum_{n' \notin \mathcal{S}_t} \vert \hat{H}_{n',n} \vert^2 \vert \psi^{(\vec{k})}_{t,n} \vert^2\]

Parameters

1. Φnp.array

the current full hierarchy vector

2. list_index_aux_stablelist

a list relative indices for the stable auxiliaries (H_S)

3. list_stateslist

the list of current states (absolute index)

Returns

1. E1_state_fluxarray

the error associated with flux out of each state in S_t

error_stable_state(self, Φ, delta_t, z_step, list_index_aux_stable)

This function 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

the current full hierarchy vector

2. delta_tfloat

the timestep for the calculation

3. z_steplist

the list of noise terms (compressed) for the next timestep

4. list_index_aux_stablelist

a list relative indices for the stable auxiliaries (H_S)

Returns

1. errornp.array

list of error associated with removing each state

hier_stable_error(self, Φ, delta_t, z_step)

This function finds the total error associated with removing k’ in H_t. This includes the error associated with deleting a auxiliary from the basis, the error associated with losing all flux into a k’ auxiliary, and the error associated with losing all flux out of a k’ auxiliary.

Parameters

1. Φnp.array

the current full hierarchy vector

2. delta_tfloat

the timestep for the calculation

3. z_steplist

the list of noise terms (compressed) for the next timestep

Returns

1. errornp.array

list of error associated with removing each auxiliary in H_t

2. E2_flux_upnp.array

the error induced by neglecting flux from H_t (or H_S)

to auxiliaries with lower summed index in H_t^C.

3. E2_flux_downnp.array

the error induced by neglecting flux from H_t (or H_S)

to auxiliaries with higher summed index in H_t^C.

initialize(self, psi_0)

This function 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

the initial wave function

Returns

1. dsystem_dtfunction

this is the core function for calculating the time-evolution of the wave function

update_basis(self, Φ, state_update, aux_update)

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

Parameters

1. Φnp.array

the current full hierarchy

2. state_updatelist

list of list containing list_state_new, list_stable_state, and list_add_state

3. aux_updatelist

list of list containing list_aux_new, list_stable_aux, and list_add_aux

Returns

1. Φ_newnp.array

the updated full hierarchy

2. dsystem_dtfunction

the 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)

This function creates a state list depending on whether the calculation is adaptive or not

Parameters

1. flag_adaptiveboolean

a boolean that defines the adaptivity True: Adaptive, False: Static

2. psi_0np.array

the initial user inputted wave function

Returns

None

static reduce_sparse_matrix(coo_mat, state_list)

This function takes in a sparse matrix and list which represents the absolute state to a new relative state represented in a sparse matrix

NOTE: This function assumes that all states associated with the non-zero elements of the sparse matrix are present in the state list!

Parameters

1. coo_matscipy sparse matrix

a sparse matrix

2. state_listlist

a 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)

Parameters

1. auxtuple

an auxiliary to check

2. list_booleanlist

the modes to filter True-filter, False-No filter

3. kmaxint

the maximum depth of the hierarchy

4. kdepthint

the 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)

This function checks whether a auxiliary is a an allowed markovian mode or a non-markovian mode PARAMETERS ———- 1. aux : AuxiliaryVector object 2. list_boolean : list

a 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

a list of booleans: True-Filter, False-No Filter

3. kmaxint

the maximum depth of the hierarchy

4. kdepthint

the depth beyond which only edge members of hierarchy are kept for filtered modes

Returns

1. list_new_auxlist

a 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

a list of auxiliary tuples

2. list_boolean_by_modelist

a 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

a filtered list of auxiliaries

filter_markovian(list_aux, list_boolean)

This function filter’s a list of auxiliaries based on whether it is a non markovian auxiliary or an allowed markovian auxiliary Parameters ———- 1. list_aux : list

list of unfiltered auxiliaries

2. list_booleanlist

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

apply_filter(self, list_aux, filter_name, params)

This is a function that 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

the list of auxiliaries that needs to be filtered

2. filter_namestr

name of filter

3. paramslist

the list of parameters for the filter

Returns

1. list_auxlist

a list of filtered auxiliaries

ALLOWED LIST OF FILTERS:

• Triangular: bolean_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: bolean_by_mode, [kmax, kdepth]

  Beyond kdepth, only keep the edge terms upto kmax.

static define_triangular_hierarchy(n_hmodes, maxhier)

This function creates a triangular hierarchy

Parameters

1. n_hmodesint

number of modes that appear in the hierarchy

2. maxhierint

the max single value of the hierarchy

Returns

1. list_auxlist

list of auxiliaries in the new triangular hierarchy

filter_aux_list(self, list_aux)

A function that applies all of the filters defined for the hierarchy in “STATIC_FILTERS”

Parameters

1. list_auxlist

the list of auxiliaries that is to be filtered

Returns

1. list_auxlist

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

dot(self, vec)

This is a function that performs a sparse dot product between the auxiliary index vector and another vector.

Parameters

1. vecnp.array

a vector

Returns

1. productfloat

the dot product value

e_step(self, mode, step)

This function returns a new Auxiliary Vector with the desired step in the given mode

Parameters

1. modeint

The absolute mode index

2. stepint

The change in the aux value for the given mode

Returns

1. aux_vectuple

the new sparse auxiliary vector

get_values(self, index_slice)

This function gets the dense auxiliary vector values from a sub-indexed list

Parameters

1. index_slicelist

a list of indices

Returns

1. valuesarray

an array of values at the given indices

get_values_nonzero(self, index_slice)

This function 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

a list of indices

Returns

1. valuesarray

a sparse array of the non-zero auxiliary vector values

hash_from_e_step(self, mode, step)

This function returns the hash of a new Auxiliary Vector with the desired step in the given mode

Parameters

1. modeint

The absolute mode index

2. stepint

The change in the aux value for the given mode

Returns

1. hash :

   the hash of the tuple sparse auxiliary vector created from e_step

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

the absolute index for an auxiliary

keys(self)

This function returns an array of mode indices for the auxiliary vectors

Parameters

None

Returns

1. keysarray

an array of mode indices with nonzero auxiliary index

sum(self, **unused_kwargs)

This function returns the sum of the auxiliary vector values

Parameters

None

Returns

1. sumfloat

the sum of the nonzero values of the auxiliary vectors

toarray(self)

This function converts a dict to an array

Parameters

None

Returns

1. arrayarray

a dict in an array form

todense(self)

This function will take a sparse vector and make it dense

Parameters

None

Returns

1. outputarray

the 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

The absolute mode index

2. stepint

The change in the aux value for the given mode

Returns

1. tuple_auxtuple

The sparse representation of the auxiliary (sorted mode order)

values(self)

This function returns an array of the auxiliary vector values

Parameters

None

Returns

1. valuesarray

an array of nonzero auxiliary index values

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)

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_absindex_L2_by_mode : relative list_absindex_mode : mapping from relative–>absolute

Parameters

1. z_memlist

a list of memory terms in absolute indices

2. list_avg_L2list

relative list of the expectation values of the L operators

3. list_glist

list of pre exponential factors for bath correlation functions [absolute]

3. list_wlist

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

4. list_absindex_L2_by_modelist

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.

5. list_absindex_modelist

list of the absolute indices of the modes in current basis

Returns

1. delta_z_memlist

a 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)

This function computes the correction factor for propagating the normalized wavefunction.

Parameters

1. phinp.array

the full hierarchy

2. z_hatlist

the memory term with both with random noise

3. list_avg_L2list

relative list of the expectation values of the L operators

4. list_L2list

list of L operators

5. nstateint

the current dimension (size) of the system

6. list_index_L2_by_modelist

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

7. list_glist

list of pre exponential factors for bath correlation functions [absolute]

8. list_wlist

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

Returns

1. deltafloat

the norm correction factor

compress_zmem(z_mem, list_index_L2_by_mode, list_absindex_mode)

This function compresses all of the memory terms into their respective slots for each L_operator.

Parameters

1. z_memlist

a list of all the memory terms in absolute basis

2. list_index_L2_by_modelist

list of length equal to the number of modes in the current hierarchy basis

3. list_absindex_modelist

list of absolute mode indices in relative mode order

Returns

1. dz_hatlist

a list of compressed memory terms indexed by list_index_L2_by_mode

operator_expectation(oper, vec)

This is a function that calculates the expectation value of a sparse operator

Parameters

1. opernp.array

dense or sparse operator

2. vecnp.array

a nx1 matrix

Returns

1. expectation_valuefloat

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

mesohops.dynamics.eom_hops_ksuper module

calculate_ksuper(system, hierarchy)

This calculates all the pieces we need to time-evolve the system EXCEPT for the normalization term.

Parameters

1. systemHopsSystem Class

an instance of HopsSystem

2. hierarchyHopsHierarchy Class

an instance of HopsHierarchy

Returns

1. K0sparse matrix

updated time invariant self interaction super operator

2. Z0sparse matrix

updated time varying self interaction super operator

3. Kp1sparse matrix

updated time invariant K+1 interaction super operator

4. Zp1sparse matrix

updated time varying K+1 interaction super operator

5. Km1sparse matrix

updated time invariant K-1 interaction super operator

update_ksuper(K0, Z0, Kp1, Zp1, Km1, stable_aux, add_aux, stable_state, list_old_ilop, system, hierarchy, n_old, perm_index)

This function 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 super operator

2. Z0sparse matrix

time varying self interaction super operator

3. Kp1sparse matrix

time invariant K+1 interaction super operator

4. Zp1sparse matrix

time varying K+1 interaction super operator

5. Km1sparse matrix

time invariant K-1 interaction super operator

6. stable_auxlist

list of stable auxiliaries

7. add_auxlist

list of new auxiliaries

8. stable_statelist

list of stable states

9. list_old_iloplist

list of the absolute indices of L operators in the last basis

10. systemHopsSystem class

an instance of HopsSystem

11. hierarchyHopsHierarchy class

an instance of HopsHierarchy

12. n_oldint

size of the full hierarchy in the previous basis

13. perm_indexlist

a list of column list and row list that define the permutation matrix

Returns

1. K0sparse matrix

updated time invariant self interaction super operator

2. Z0sparse matrix

updated time varying self interaction super operator

3. Kp1sparse matrix

updated time invariant K+1 interaction super operator

4. Zp1sparse matrix

updated time varying K+1 interaction super operator

5. Km1sparse matrix

updated time invariant K-1 interaction super operator

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.