final docs review before release.

ci/emu_mps/pyproject.toml

@@ -23,7 +23,7 @@ classifiers=[
 ]
 dynamic = ["version"]
 dependencies = [
-  "emu-base==1.2.3"]
+  "emu-base==1.2.4"]
 
 [tool.hatch.version]
 path = "../../emu_mps/__init__.py"

doc_requirements.txt

@@ -3,7 +3,7 @@ mkdocs-material
 mkdocstrings
 mkdocstrings-python
 mkdocs-section-index
-mkdocs-jupyter
+mkdocs-jupyter==0.24.7 # on 0.25 latex in notebooks is not rendered
 mkdocs-exclude
 notebook<7
 markdown-exec

docs/CONTRIBUTING.md

@@ -4,7 +4,7 @@ We're grateful for your interest in participating in EMU-MPS! Please follow our
 
 ## Reporting an Issue or Proposing a Feature
 
-Your course of action will depend on your objective, but generally, you should start by creating an issue. If you've discovered a bug or have a feature you'd like to see added to EMU-MPS, feel free to create an issue on [the issue tracker](https://gitlab.pasqal.com/emulation/rydberg-atoms/emu-ct/-/issues). Here are some steps to take:
+Your course of action will depend on your objective, but generally, you should start by creating an issue. If you've discovered a bug or have a feature you'd like to see added to EMU-MPS, feel free to create an issue on [the issue tracker](https://github.com/pasqal-io/emulators/issues). Here are some steps to take:
 
 1. Quickly search the existing issues using relevant keywords to ensure your issue hasn't been addressed already.
 2. If your issue is not listed, create a new one. Try to be as detailed and clear as possible in your description.
@@ -14,7 +14,7 @@ Your course of action will depend on your objective, but generally, you should s
 
 ## Submitting a Pull Request
 
-We're excited that you're eager to contribute to EMU-MPS! To contribute, create a branch on the EMU-MPS repository and once you are satisfied with your feature and all the tests pass create a [Merge Request](https://gitlab.pasqal.com/emulation/rydberg-atoms/emu-ct/-/merge_requests).
+We're excited that you're eager to contribute to EMU-MPS! To contribute, create a branch on the EMU-MPS repository and once you are satisfied with your feature and all the tests pass create a [Merge Request](https://github.com/pasqal-io/emulators/pulls).
 
 Here's the process for making a contribution:
 
@@ -24,7 +24,7 @@ Make a new branch via
 git branch <your initials>/<branch name>
 ```
 
-Next, checkout your new branch, and associate a branch to it on the gitlab server:
+Next, checkout your new branch, and associate a branch to it on the GitHub server:
 
 ```shell
 git checkout <your initials>/<branch name>
@@ -89,17 +89,11 @@ hatch -e docs run mkdocs build --clean --strict
 ```
 
 Without `hatch`, `pip` install those libraries first:
-"mkdocs",
-"mkdocs-material",
-"mkdocstrings",
-"mkdocstrings-python",
-"mkdocs-section-index",
-"mkdocs-jupyter",
-"mkdocs-exclude",
-"markdown-exec"
-
+```shell
+pip install -r doc_requirements.txt
+```
 
-And then:
+Then build the documentation:
 
 ```shell
  mkdocs build --clean --strict

docs/benchmarks/accuracy.md

@@ -1,26 +1,24 @@
 # Accuracy
 
-Here we discuss the emulator accuracy, as compared to Pulser state vector solver backend (qutip), but in the future we might directly compare with QPU results.
+Here we discuss the emulator accuracy, as compared to Pulser state vector solver [backend](https://pulser.readthedocs.io/en/stable/tutorials/simulating.html), but in the future we might directly compare with QPU results.
 Accuracy, here, specifically refers to observables:
 
 - __Energy:__ $E = \langle\psi|H|\psi\rangle$
 - __Energy variance:__ $\Delta E = \langle\psi|H^2|\psi\rangle-E^2$
 - __Magnetization:__ $\langle P_{0}^j\rangle$ where $P_{0}^j$ projects qubit $j$ onto the $|0>$ state
 
-The emulated sequences are going to be the same as before, an adiabatic and a quench. In both cases, 9 qubits arrayed in a 3x3 grid are used, so that the results can also be simulated in Pulser. We will check accuracy against two main tunable parameters in _EMU-MPS_:
+The emulated sequences are going to be the same as before, an adiabatic and a quench. In both cases, 9 qubits arrayed in a 3x3 grid are used, so that the results can also be simulated in Pulser. We will check accuracy against two main tunable parameters in EMU-MPS:
 
 - `precision`<sup>[[1]](../advanced/errors.md#truncation-of-the-state)</sup>: at each step, throw away components of the state whose sum weighs less that the specified precision.
-- time step `dt`: sampling time of the sequence.
+- `dt`: sampling time step of the sequence.
 
 The goal is to show that for qubit numbers accessible to Pulser, the results are identical up to good precision.
 
 <img src="../benchmark_plots/afm_state_fidelity.png"  width="49.7%">
 <img src="../benchmark_plots/quench_fidelity.png"  width="49.7%">
 
-Both sequences are emulated multiple times by varying both the precision and time step. Notice that any deviations from Pulser for the adiabatic sequence are impossible to detect at the scale of the graph for a wide range of emulation parameters. For larger qubit numbers, such as the 7x7 grid, the question of convergence is much subtler ([see here](../advanced/convergence.md)). Rather, what is interesting there, is that even for a 2d system, Emu-MPS correctly treats the Rydberg interaction, regardless of the [effective description of long-range interaction terms](../advanced/errors.md#effective-description-of-long-range-terms-in-the-hamiltonian) that Emu-MPS uses.
+Both sequences are emulated multiple times by varying both the precision and time step. Notice that any deviations from Pulser for the adiabatic sequence are impossible to detect at the scale of the graph for a wide range of emulation parameters. For larger qubit numbers, such as the 7x7 grid, the question of convergence is much subtler ([see here](../advanced/convergence.md)). Rather, what is interesting there, is that even for a 2d system, EMU-MPS correctly treats the Rydberg interaction, regardless of the [effective description of long-range interaction terms](../advanced/errors.md#effective-description-of-long-range-terms-in-the-hamiltonian) that EMU-MPS uses.
 
 For the quench sequence, agreement with Pulser is still good for all shown parameter combinations, with the possible exception of the yellow curve, which has a deviation of 1%. For the quench sequence, the energy and energy variance are conserved quantities, meaning that all variation therein come from errors. Even though the relative errors are small, it's instructive to analyze the sources of these errors. For example, we see that EMU-MPS incurs the biggest error at the start of the emulation, when the bond dimension is still small (the bond dimension starts at 1, and increases from there). For a time-constant Hamiltonian, all deviations in the mean and variance of the energy come from truncation, and as expected, improving the precision reduces the error in the energy variance ([see here](../advanced/errors.md)). Finally, as explained in error sources in TDVP ([see here](../advanced/errors.md#truncation-of-the-state)), we see that reducing $dt$ below a threshold (somewhere in the range of 1-5) causes a quick growth of the truncation errors, which requires improving the precision.
 
 The errors incurred by EMU-MPS can be contrasted with Pulser, which uses a generic ODE solver backend that does not take into account constants of the motion. Both the mean and variance of the energy exhibit a deviation from their initial value that is linear in the number of time-steps taken by the solver.
-
-[TODO: For a more in depth discussion change the plots to have the observables on the left column and difference respect to Pulser state vector on right column]

docs/benchmarks/index.md

@@ -1,7 +1,7 @@
 # EMU-MPS benchmarks
 
 All the benchmarks are run on a single NVIDIA A100 GPU of Pasqal's DGX-cluster and for best performance on heavy workloads we recommend using such setup.
-There, users should expect _EMU-MPS_ to emulate up to
+There, users should expect EMU-MPS to emulate up to
 
 - 30 atoms for **quenches**
 - 50 atoms for **adiabatic sequences**
@@ -19,20 +19,20 @@ These quantities are represented, in the following plots:
 <img src="../benchmarks/benchmark_plots/emumps_maxRSS_map.png"  width="49.7%">
 <img src="../benchmarks/benchmark_plots/emumps_runtime_map.png"  width="49.7%">
 
-The RSS plot (left) shows the memory cost of the emulation.
+The RSS plot (left) shows the peak memory cost of the emulation.
 It is expected to stay constant at fixed bond dimension and thus represent the total memory occupation of the emulation of a sequence.
 As evident, the emulator is mostly limited by the available memory (40 GB on NVIDIA A100), as it restricts the maximum number of qubits/bond dimension pair allowed.
 To get the total estimated runtime instead, one should simply multiply the time estimate in the timing plot (right) by the number of steps in the emulated sequence.
-Finally, given the technical nature of these estimates, which rely on some previous knowledge about [matrix product states](../advanced/mps/index.md) and the [TDVP](../advanced/tdvp.md) algorithm. We encourage anyone who might be interested into understanding how they are computed in the first place, to have a look at the [resource estimation](../advanced/resource_estimation.md) page in advanced topic section of this documentation.
+Finally, given the technical nature of these estimates, they rely on some previous knowledge about [matrix product states](../advanced/mps/index.md) and the [TDVP](../advanced/tdvp.md) algorithm. We encourage anyone who might be interested into the derivation, to have a look at the [resource estimation](../advanced/resource_estimation.md) page in advanced topic section of this documentation.
 
-While the simple resources estimate provided above allows to upper bound the memory/time cost of an emulation, a final very important remark has to be made. If during an emulation, the bond dimension reach a user-set maximum value (with the `max_bond_dim` argument), the accuracy of the subsequent results of the time evolution cannot be guaranteed anymore, as discussed [here](../advanced/convergence.md).
+While the simple resource estimation provided above allows to upper bound the memory/time cost of an emulation, a final very important remark has to be made. If during an emulation, the bond dimension reach a user-set maximum value (with the `max_bond_dim` argument), the accuracy of the subsequent results of the time evolution cannot be guaranteed anymore, as discussed [here](../advanced/convergence.md).
 
-Having sketched up the expected performance, in the next section, we make those statements more concrete providing more details about use-cases benchmarks.
+Having sketched up the expected performance, in the next section, we make those statements more concrete by providing more details about use-cases benchmarks.
 Concretely, we will discuss the relevant register/ pulse sequences and the performance metrics of choice.
 
 ## Use-case benchmarks
 
-Benchmark efforts, documented here, are meant to provide insights for _EMU-MPS_ users about
+Benchmark efforts, documented here, are meant to provide insights for EMU-MPS users about
 
 - **Performance**: runtime, memory usage, bond dimension as a function of qubit number ([see here](../advanced/mps/index.md#bond-dimension))
 - **Accuracy**: different precision levels as compared to state vector solvers
@@ -45,7 +45,7 @@ The benchmarks are ordered in subpages by general topic.
 - [Performance](../benchmarks/performance.md)
 - [Noise](../benchmarks/noise.md)
 
-The accuracy benchmarks compare results between emulators to create confidence in the results _EMU-MPS_ generates. The performance benchmarks exist to exhibit the runtime and memory consumption characteristics of _EMU-MPS_. Based on these, the reader should get a feel for what kind of parameters would be required to be able to run a given sequence in a given time. Note that this is independent of whether the emulation results are actually accurate ([see here](../advanced/convergence.md)). Finally, the noise page presents benchmarks regarding noisy simulations, focusing on effects specific to noise that are not already covered in the other pages.
+The accuracy benchmarks compare results between emulators to create confidence in the results EMU-MPS generates. The performance benchmarks exist to exhibit the runtime and memory consumption characteristics of EMU-MPS. Based on these, the reader should get a feel for what kind of parameters would be required to be able to run a given sequence in a given time. Note that this is independent of whether the emulation results are actually accurate ([see here](../advanced/convergence.md)). Finally, the noise page presents benchmarks regarding noisy simulations, focusing on effects specific to noise that are not already covered in the other pages.
 
 ## Sequences used
 
@@ -101,17 +101,17 @@ seq.add(simple_pulse, "ising")
 ```
 
 These two types of driving typically complement each other.
-Since the matrix product state approach in _EMU-MPS_ strives to minimize the stored information, keeping track of a single equilibrium state in adiabatic time evolution is typically easier. While this single state can be a complicated object itself, quenches, driving the system out of equilibrium, involve taking into account multiple excited states, and are typically computationally harder to emulate.
+Since the matrix product state approach in EMU-MPS strives to minimize the stored information, keeping track of a single equilibrium state in adiabatic time evolution is typically easier. While this single state can be a complicated object itself, quenches, driving the system out of equilibrium, involve taking into account multiple excited states, and are typically computationally harder to emulate.
 
 ## CPU/GPU hardware
 
-_EMU-MPS_ is built on top of [pytorch](https://pytorch.org/). Thus, it can run on most available CPUs and GPUs, from a laptop to a cluster. The presented benchmarks are run on an NVIDIA DGX cluster node, requesting the following resources
+EMU-MPS is built on top of [pytorch](https://pytorch.org/). Thus, it can run on most available CPUs and GPUs, from a laptop to a cluster. The presented benchmarks are run on an NVIDIA DGX cluster node, requesting the following resources
 
 - GPU: 1 NVIDIA A100 (40 GB)
 - CPU: 16 cores on AMD EPYC 7742
 
 Of course, performance will vary depending on the hardware.
 For this reason, if at any point of your work, performance becomes critical, we always recommend to use Pasqal's DGX cluster.
-If you intend to run _EMU-MPS_ on your laptop, for example, please be aware that the suggestion to use a GPU for heavier workloads might not be valid.
-In such case it is always good to check performance on a couple of runs, changing the _EMU-MPS_ config default values as documented in the [API](../api.md#mpsconfig).
+If you intend to run EMU-MPS on your laptop, for example, please be aware that the suggestion to use a GPU for heavier workloads might not be valid.
+In such case it is always good to check performance on a couple of runs, changing the EMU-MPS config default values as documented in the [API](../api.md#mpsconfig).
 In particular `num_devices_to_use = 0` will run the emulation on CPU, while `num_devices_to_use ≥ 1` on GPU/s.