MesoHOPS 1.8.0

[alexiahartzell]

MesoHOPS 1.8.0

This commit introduces tensor-network HOPS, a Matrix Product State representation of the hierarchy wavefunction, and adds rectangular hierarchy truncation, nondyadic spectroscopy, and per-step timing instrumentation.

Key improvements and features:

1. Tensor-network HOPS: The new mesohops.tensor subpackage represents the hierarchy wavefunction as a Matrix Product State rather than a flat auxiliary-enumerated vector. HopsTensorWavefunction handles MPS storage, normalization, operator application, and bond-dimension control; HopsTensorEOM evaluates the equation of motion directly on the MPS; and mpo_constructors.py builds the Hamiltonian, dipole, and state-number MPOs. Hierarchy depth is encoded in the MPS core dimensions (k_max + 1 per mode) rather than through explicit auxiliary-vector enumeration, so n_hier, n_hmodes, and ADAPTIVE_H do not apply on this path. Two representations are available via method: 'number', in which the ground state is implicit as the all-zero MPS configuration, and 'fullstate'. Tensor adaptivity is not supported in this release — see the note below.

2. Rectangular hierarchy truncation: HopsHierarchy gains a TRUNCATION_METHOD parameter ('triangular', the default and prior behavior, or 'rectangular'). define_rectangular_hierarchy() admits every per-mode depth combination in [0, MAXHIER]^n_hmodes, matching the MPS core structure used by tensor HOPS. Rectangular truncation is unsupported for adaptive calculations and raises NotImplementedError, because the vector adaptive flux filters enforce the MAXHIER boundary through total auxiliary depth, which is inherently triangular. Relatedly, add_connections no longer short-circuits the k+1 loop on total depth, which rectangular hierarchies require since their per-mode depths may sum above MAXHIER.

3. Nondyadic spectroscopy: util/nondyadic_spectroscopy.py dispatches on trajectory type, tensor method, and Hilbert-space convention: embedded, where the ground state occupies an explicit basis slot; vacuum, where it is the implicit all-zero MPS configuration; and excited_only.

4. Nearest-neighbor Hamiltonian detection: HopsSystem exposes flag_nearest_neighbor_ham, computed at construction, indicating whether all non-zero Hamiltonian elements satisfy |row - col| <= 1. Explicit stored zeros are eliminated first so that a user-supplied sparse matrix with padded off-diagonals is not misclassified.

5. Per-step timing and storage additions: A new STORE_STEP_TIMING integration parameter (default False) records wall-clock time for each integration step. When enabled, storage.metadata["LIST_PROPAGATION_TIME"] holds (t, elapsed) tuples per step rather than a single total-elapsed float per propagate() call; the default is unchanged. A psi_g_traj storage option captures <0,...,0|psi> per step, which the vacuum-convention spectroscopy path requires because extract_psi sees only the excited-state slots.

6. Integrator rename and hierarchy error handling: mesohops.integrator.integrator_rk is renamed to mesohops.integrator.integrator, so code importing runge_kutta_step or runge_kutta_variables must update the import path. Integrator setup moved into an overridable HopsTrajectory._setup_integrator() hook so subclasses can register additional integrators.

Warning

NOTE — this release breaks existing scripts that import the Runge-Kutta integrator. mesohops.integrator.integrator_rk is renamed to mesohops.integrator.integrator, with no backwards-compatible alias, so any script importing from the old path fails immediately with ModuleNotFoundError:

# before (1.7.0)
from mesohops.integrator.integrator_rk import runge_kutta_step, runge_kutta_variables
# after (1.8.0)
from mesohops.integrator.integrator import runge_kutta_step, runge_kutta_variables

Warning

NOTE — adaptivity is not supported for tensor HOPS in this release. The adaptive code paths (HopsTensorBasis.update_basis, tensor_functions_adaptive.py, and HopsTensorTrajectory.make_adaptive) are present in the source but are not finished. Calling make_adaptive() on a HopsTensorTrajectory is not blocked at runtime, so do not use tensor adaptivity for production results. Non-adaptive tensor HOPS is unaffected.

These enhancements extend MesoHOPS beyond vector HOPS into tensor-network territory, broadening the range of system sizes and bath structures the library can reach.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️