MesoHOPS 1.4.1

This commit presents a minor upgrade to MesoHOPS 1.4.0:
1. A bug in hops_aux.py that randomly caused false flux up terms to appear in the equation of motion is fixed.
2. Added a pyproject.toml that automatically installs all dependencies during installation in place of the setup.py file.

Author: CaptainExasperated

README.md

@@ -1,16 +1,90 @@
+
 # What is MesoHOPS?
-Documentation: [mesohops.readthedocs.io](https://mesohops.readthedocs.io/en/latest/)
 
-MesoHOPS is a formally exact trajectory based approach for solving the time evolution of open quantum systems coupled to non-Markovian thermal environments. MesoHOPS extends the Hierarchy Of Pure States (HOPS) formalism to leverage the dynamic localization present in the wave functions and construct an adaptive basis. Using the adaptive basis MesoHOPS is able to be computationally tractable with large system sizes. 
+MesoHOPS is a Python library for running simulations with the Hierarchy of Pure States (HOPS), a formally exact trajectory-based approach for solving the time-evolution of open quantum systems coupled to non-Markovian thermal environments. The main feature of MesoHOPS is the implementation of adaptive HOPS (adHOPS), an extension of the HOPS formalism that leverages the dynamic localization of excitations to construct an adaptive basis. The moving adHOPS basis significantly reduces the computational cost of simulations and exhibits a size-invariant scaling in large systems.
+
+
+Get started with [the MesoHOPS website](https://captainexasperated.github.io/Readthedocs-Tutorial/)! 
 
+# Dependencies and Installation
+MesoHOPS is supported by [Python](https://www.python.org/) 3.9-3.11 and relies on the [NumPy](https://numpy.org/), [SciPy](https://scipy.org/), and [Numba](https://numba.readthedocs.io/en/stable/#) packages. Additionally, our tests use the [pytest](https://docs.pytest.org/en/7.4.x/) and [pytest-level](https://pypi.org/project/pytest-level/) packages. All of these packages are automatically installed by the included pyproject.toml file.
 
-# Why use MesoHOPS?
-To summarize our MesoHOPS algorithm:
-1.  is a formally exact solution to the time evolution of a quantum state coupled to a non-Markovian thermal reservoir
-2.  is embarrassingly parallel
-3.  scales to large systems
-4.  is well documented
-5.  is open source 
+To download and install MesoHOPS, enter the following commands:
+```
+git clone https://github.com/MesoscienceLab/mesohops.git
+cd mesohops
+python3 -m pip install .
+```
+Using a version of pip earlier than 23.3.2 may cause installation to fail.
 
 # Using MesoHOPS
-Please refer to our documentation page located [here](https://mesohops.readthedocs.io/en/latest/) for a quick start guide on how to use MesoHOPS.
+## Getting Started
+To run a simple MesoHOPS simulation, please refer to our [quickstart tutorial](https://captainexasperated.github.io/Readthedocs-Tutorial/Quickstart/). [Additional tutorials](https://captainexasperated.github.io/Readthedocs-Tutorial/tutorials/) explain the use of mesoHOPS in more detail. We provide the input scripts for the advanced simulations run in various papers as supplementary materials.
+
+## Units
+The units of the HOPS equation of motion are energy and time, both given by the definition of $\hbar$, which is located in mesohops.util.physical_constants and is set to units of  cm$^{-1}\cdot$fs.
+
+## Large-Scale Calculations
+Because MesoHOPS supports perfectly-parallel trajectories, we recommend running large-scale simulations with parallelization through a Slurm array or the [multiprocessing package](https://docs.python.org/3/library/multiprocessing.html).
+
+## Memory and CPU Profiling
+When necessary, we recommend using [Memray](https://bloomberg.github.io/memray/) to profile memory and [SnakeViz](https://jiffyclub.github.io/snakeviz/) to profile CPU time.
+
+## Convergence Scans
+Because of the large number of convergence parameters present in MesoHOPS, testing convergence is non-trivial. We provide an introduction in our [convergence tutorial](https://captainexasperated.github.io/Readthedocs-Tutorial/Convergence/) and an in-depth example of convergence testing on production-scale calculations in the SI of [this paper on simulating exciton dynamics in large LH2 complexes](https://pubs.acs.org/doi/10.1021/acs.jpclett.3c00086).
+
+# Developer Guide
+We believe that good scientific code reflects two of the dearest scientific virtues: collaboration and clarity. As such, we encourage users to experiment with the MesoHOPS code and develop new features.
+
+Most of the development in this library takes place in a private repository. Because we regularly implement new features and alter the structure of our code to improve performance and clarity, updates made to the current version of the MesoHOPS code directly may have to be rewritten for the next version of MesoHOPS.  If you have developed a feature or found an improvement that you believe is broadly useful, or are interested in development, please [reach out to us](https://cm.utexas.edu/component/cobalt/item/12-chemistry/5200-raccah-doran?Itemid=1251) about a potential collaboration.
+
+## Style
+All code developed by the MesoScience Lab follows stylistic guidelines laid out on our style guide (hosted on the [lab website](https://www.mesosciencelab.com/tools)). Documentation is the key to well-maintained code: as such, all functions and methods should be detailed with a docstring that clearly defines parameters and returns.
+
+## Exceptions
+We support a number of built-in exceptions at mesohops.util.exceptions for user and developer convenience.
+
+## Testing
+To test the code, navigate to the testing directory and enter the command
+```
+pytest
+```
+to run all tests or
+```
+pytest --level 1
+```
+to skip the time-consuming tests of Gaussian complex white noise generation, which is managed by code in mesohops/dynamics/hops_noise.py that should not be altered. Tests should be run whenever a change is made to the code to ensure that no unexpected errors have been introduced.
+
+All newly-implemented features should be matched with unit tests (that is, a test of exactly one function or method) when possible and an integrated test (a test of how multiple pieces of the code interact) when necessary. Tests are managed with pytest and pytest-level and should be placed in an appropriate file in the testing directory. If a test is particularly time-consuming, it should have the decorator
+```
+@pytest.mark.level(2)
+```
+to allow users to run only the tests that take a short time. A properly-written test includes cases that intentionally result in errors to ensure that the expected exceptions are raised: examples may be found in our own code or in [the pytest documentation](https://docs.pytest.org/en/7.1.x/how-to/assert.html).
+
+# Citing MesoHOPS
+When using MesoHOPS version 1.4 or later please cite:
+- B. Citty, J. K. Lynd, T. Gera, L. Varvelo, and D. I. G. B. Raccah, "MesoHops: Size-invariant scaling calculations of multi-excitation open quantum systems," [preprint (2024)](https://arxiv.org/abs/2401.07443). 
+*This paper extends the adaptive algorithm to account for arbitrary couplings between thermal environments and vertical excitation energies. Furthermore, it introduces a low-temperature correction and effective integration of the noise that simplify simulations with ultrafast vibrational relaxations.*
+
+When using the adaptive basis (by setting  $\delta_A,\delta_S>0$) , please also cite:
+- L. Varvelo, J. K. Lynd, and D. I. G. B(ennett) Raccah, "Formally exact simulations of mesoscale exciton dynamics in molecular materials," [Chem. Sci. (2021)](https://doi.org/10.1039/D1SC01448J). 
+*This paper introduces and derives an adaptive basis construction algorithm motivated by dynamic localization in the HOPS equation of motion. Proof-of-concept calculations show that the resulting adaptive Hierarchy of Pure States (adHOPS) exhibits size-invariant scaling in large molecular aggregates.*
+
+When using the linear absorption HOPS equation of motion, please also cite:
+- L. Chen, D. I. G. B(ennett) Raccah, and A. Eisfeld, "Simulation of absorption spectra of molecular aggregates: A hierarchy of stochastic pure state approach," [J. Chem. Phys. (2022)](https://doi.org/10.1063/5.0078435). 
+*This paper introduces a new HOPS equation of motion for simulating linear absorption spectra using a pure-state decomposition of the dipole correlation function.*
+
+When using the Dyadic adaptive HOPS (DadHOPS) equations, please also cite:
+- T. Gera, L. Chen, A. Eisfeld, J. R. Reimers, E. J. Taffet, and D. I. G. B. Raccah, "Simulating optical linear absorption for mesoscale molecular aggregates: An adaptive hierarchy of pure states approach," [J. Chem. Phys. (2023)](https://doi.org/10.1063/5.0141882). 
+*This paper introduces a dyadic adaptive Hierarchy of Pure States (DadHOPS) implementation for simulating linear absorption spectra in large aggregates, as well as an initial state decomposition that allows for convenient scaling. Proof-of-concept calculations show that DadHOPS exhibits size-invariant scaling in large molecular aggregates.*
+
+
+To better understand the NMQSD and HOPS formalism, please review:
+- L. Diósi and W. T. Strunz, "The non-Markovian stochastic Schrödinger equation for open systems," [Phys. Lett. A (1997)](https://doi.org/10.1016/S0375-9601(97)00717-2).
+*This paper presents a formally exact non-Markovian stochastic Schrödinger (NMQSD) equation of motion for trajectories representing realizations of the environmental state of open quantum systems.*
+
+- D. Suess, A. Eisfeld, and W. T. Strunz, "Hierarchy of Stochastic Pure States for Open Quantum System Dynamics," [Phys. Rev. Lett. (2014)](https://doi.org/10.1103/PhysRevLett.113.150403). 
+*This paper derives the Hierarchy of Pure States (HOPS) equation, a solution to the formally exact trajectory-based Non-Markovian Quantum State Diffusion (NMQSD) method for solving the time-evolution of open quantum systems. Both a linear and nonlinear HOPS equation are presented.*
+
+- L. Chen, D. I. G. B(ennett) Raccah, and A. Eisfeld, "Calculating nonlinear response functions for multidimensional electronic spectroscopy using dyadic non-Markovian quantum state diffusion," [J. Chem. Phys. (2022)](https://doi.org/10.1063/5.0107925). 
+*This paper introduces an NMQSD formalism propagated in a dyadic Hilbert space to construct multi-point time correlation functions. This is then mapped into HOPS calculations of nonlinear spectra.*

mesohops/dynamics/hops_aux.py

@@ -562,25 +562,63 @@ def dict_aux_m1(self):
         return self._dict_aux_m1
 
 @njit
-def numba_get_list_id_up(keys,values,mode_insert,ref_id,num_mode_digits): 
-    # Only works when mode_insert is a single number
-    # Need to make it work for ordered list of modes to take full advantage of algorithm
+def numba_get_list_id_up(keys,values,mode_insert,ref_id,num_mode_digits):
+    """
+    Finds all auxiliary vectors one step up along each mode from the given auxiliary
+    vector.
+    Parameters
+    ----------
+    1. keys : list(int)
+              Sorted list of (absolute) modes present in the given auxiliary vector.
+    2. values : list(int)
+                Depth of the given auxiliary vector in each of the modes from keys.
+    3. mode_insert : list(int)
+                     Sorted list of (absolute) modes along which the given auxiliary
+                     vector connects to higher-lying auxiliaries.
+    4. ref_id : str
+                The id string of the given auxiliary vector.
+    5. num_mode_digits : int
+                         The number of digits needed to uniquely identify all modes
+                         in the full basis of modes.
+
+    Returns
+    -------
+    1. id_up: list(str)
+              The id strings of all auxiliary vectors one step up in the hierarchy
+              from the given auxiliary vector.
+    2. value_connect: list(int)
+                      The depth of the given auxiliary vector in the mode
+                      connecting to each auxiliary vector listed in id_up.
+    3. mode_connect: list(int)
+                     The mode along which the given auxiliary vector connects to
+                     each auxiliary vector listed in id_up.
+    """
     insert_index = 0 #index of string insertion
     key_index = 0 #index of key in keys
     value_connect = 0
     id_up = [""] * len(mode_insert)
     value_connect = [0] * len(mode_insert)
     mode_connect = [0] * len(mode_insert)
-    for (ins_index,mode_ins) in enumerate(mode_insert): 
-        
-        while(key_index < len(keys)): #Find string insertion index
+
+    # Loop over all modes along which we will find a higher-lying auxiliary vector.
+    for (ins_index,mode_ins) in enumerate(mode_insert):
+        # Find where each mode in mode_ins lies in relation to the modes represented
+        # in the given auxiliary.
+        while(key_index < len(keys)):
+            # Ensure that modes are ordered properly in the string representation of
+            # each auxiliary.
             if(keys[key_index] < mode_ins):
                 insert_index += values[key_index] * num_mode_digits
                 key_index = key_index + 1
+            # Modes already represented in the given auxiliary yield a non-zero
+            # value_connect.
+            elif (keys[key_index] == mode_ins):
+                value_connect[ins_index] = values[key_index]
+                break
             else:
                 break
-        if (keys[key_index] == mode_ins):
-            value_connect[ins_index] = values[key_index]
+
+        # Create the string representation of the higher-lying auxiliary.
         id_up[ins_index] = ref_id[0:insert_index] + ((num_mode_digits - len(str(mode_ins))) * "0" + str(mode_ins)) + ref_id[insert_index:]
         mode_connect[ins_index] = mode_ins
-    return id_up, value_connect, mode_connect
+    return id_up, value_connect, mode_connect

pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "mesohops"
+version = "1.4.1"
+dependencies = [
+  "numpy",
+  "scipy",
+  "numba",
+  "pytest",
+  "pytest-level"
+]
+requires-python = ">=3.9"
+authors = [
+  {name = "Leonel Varvelo", email = "[email protected]"},
+  {name = "Jacob Lynd", email = "[email protected]"},
+  {name = "Brian Citty", email = "[email protected]"},
+  {name = "Tarun Gera", email = "[email protected]"},
+  {name = "Doran I. G. B. Raccah", email = "[email protected]"},
+]
+maintainers = [
+  {name = "Doran I. G. B. Raccah", email = "[email protected]"}
+]
+description = "Python Distribution of (adaptive) Hierarchy of Pure States (HOPS)"
+readme = "README.md"
+license = {file = "LICENSE"}
+keywords = ["open quantum systems", "mesoscale", "spectroscopy", "excited-state dynamics", "non-Markovian"]
+classifiers = [
+  "Development Status :: full release 1.4.1",
+  "Programming Language :: Python"
+]
+
+[project.urls]
+Homepage = "https://captainexasperated.github.io/Readthedocs-Tutorial/"
+Repository = "https://github.com/MesoscienceLab/mesohops"