final docs review before release. (#26)

* version bump for release

* fix mkdocs-jupyter version

* refresh getting_started notebook

* fix link in docs/notebooks/index

* fix gitlab links in contrimuting.md

* small fixes on benchmarks index accuracy and performance

* another small fix in benchmark/index

* update homepage with new readme

* emu-mps capitalization

* small fix typos

* fix index and readme

---------

Co-authored-by: stefano.grava <[email protected]>

README.md

@@ -4,7 +4,7 @@
   # Emu-MPS
 </div>
 
-**EMU-MPS** is a backend for the [Pulser low-level Quantum Programming toolkit](https://pulser.readthedocs.io). EMU-MPS lets you transparently run Quantum Algorithms on a simulated device, using GPU acceleration if available. More in depth, EMU-MPS is designed to **EMU**late the dynamics of programmable arrays of neutral atoms, with matrix product states (**MPS**). While benchmarking is incomplete as of this writing, early results suggest that this design makes EMU-MPS faster and more memory-efficient than previous generations of quantum emulators at running simulations with large numbers of qubits.
+**Emu-mps** is a backend for the [Pulser low-level Quantum Programming toolkit](https://pulser.readthedocs.io) that lets you run Quantum Algorithms on a simulated device, using GPU acceleration if available. More in depth, emu-mps is designed to **emu**late the dynamics of programmable arrays of neutral atoms, with matrix product states (**mps**). While benchmarking is incomplete as of this writing, early results suggest that this design makes emu-mps faster and more memory-efficient than previous generations of quantum emulators at running simulations with large numbers of qubits.
 
 ## Installation
 

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

@@ -1,10 +1,10 @@
 # How to Contribute
 
-We're grateful for your interest in participating in EMU-MPS! Please follow our guidelines to ensure a smooth contribution process.
+We're grateful for your interest in participating in emu-mps! Please follow our guidelines to ensure a smooth contribution process.
 
 ## 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>
@@ -35,7 +35,7 @@ git push --set-upstream origin <your initials>/<branch name>
 
 We recommend to use `hatch` for managing environments:
 
-To develop within EMU-MPS, use:
+To develop within emu-mps, use:
 ```shell
 pip install hatch
 hatch -v shell
@@ -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/advanced/config.md

@@ -1,6 +1,6 @@
 # Explanation of config values
 
-The following config values to EMU-MPS relate to the functioning of the tdvp algorithm used to evolve the quantum state in time, and will be explained in more detail below:
+The following config values to emu-mps relate to the functioning of the tdvp algorithm used to evolve the quantum state in time, and will be explained in more detail below:
 
 - dt
 - precision
@@ -10,7 +10,7 @@ The following config values to EMU-MPS relate to the functioning of the tdvp alg
 
 ## dt
 
-Emu-MPS assumes the Hamiltonian is piece-wise constant in time for intervals of `dt`. It then constructs the Hamiltonian by sampling the amplitude, detuning and phase of the pulse midway through the interval, and making a single Hamiltonian. The TDVP algorithm is then used to evolve the state by `dt`. There are two sources of error related to `dt`.
+Note that emu-mps assumes the Hamiltonian is piece-wise constant in time for intervals of `dt`. It then constructs the Hamiltonian by sampling the amplitude, detuning and phase of the pulse midway through the interval, and making a single Hamiltonian. The TDVP algorithm is then used to evolve the state by `dt`. There are two sources of error related to `dt`.
 
 - The discretization of the pulse
 - [TDVP](errors.md)
@@ -19,7 +19,7 @@ Both sources of error dictate that `dt` shall not be too small, but the function
 
 ## precision
 
-The 2-site TDVP algorithm used in EMU-MPS works by repeatedly time-evolving two neighbouring qubits in the MPS, and then truncating the result. Truncation is done by applying an [SVD](https://en.wikipedia.org/wiki/Singular_value_decomposition) to the matrix representing the 2-qubit subsystem.
+The 2-site TDVP algorithm used in emu-mps works by repeatedly time-evolving two neighbouring qubits in the MPS, and then truncating the result. Truncation is done by applying an [SVD](https://en.wikipedia.org/wiki/Singular_value_decomposition) to the matrix representing the 2-qubit subsystem.
 The singular values give much information about the state. Denote the singular values by $d_i$, and assume they are ordered in decreasing magnitude.
 Then the norm of the state will be $\sum_i d_i^2$ and the entanglement entropy between the left and right parts of the state will be $\sum_i d_i \log_2(d_i)$, for example.
 

docs/advanced/errors.md

@@ -1,6 +1,6 @@
 # An explanation of the sources of error in TDVP
 
-EMU-MPS uses a 2nd order 2-site time-dependent variational principle to compute the time evolution of the qubit registers ([see here](tdvp.md)).
+Emu-mps uses a 2nd order 2-site time-dependent variational principle to compute the time evolution of the qubit registers ([see here](tdvp.md)).
 There are four sources of error inherent in this algorithm ([see here](https://tensornetwork.org/mps/algorithms/timeevo/tdvp.html))
 
 - effective description of long-range terms in the Hamiltonian

docs/advanced/hamiltonian.md

@@ -8,7 +8,7 @@ $$
 where $H_i$ is the interaction term in the Hamiltonian.
 Values of $\Omega_j$ and $\Delta_j$ respectively represent the amplitude and the detuning of the driving field applied to the qubit $j$. Avoiding technical details we will refer to eigenstates of $H$ (and in particular to the ground state) as equilibrium states.
 
-Although the QPU currently only supports a Rydberg interaction, EMU-MPS supports both the Rydberg interaction term and the XY interaction.
+Although the QPU currently only supports a Rydberg interaction, emu-mps supports both the Rydberg interaction term and the XY interaction.
 
 The Rydberg interaction reads
 

docs/advanced/index.md

@@ -1,6 +1,6 @@
 #Advanced topics
 You have reached the advanced topics. Links to the individual pages discussing the various topics can be found in the sidebar to the left.
-The content here all relates to the inner workings of _EMU-MPS_ and is more conceptual in nature. You will not find information here about
+The content here all relates to the inner workings of emu-mps and is more conceptual in nature. You will not find information here about
 how to actually run a simulation, but rather
 
 - What Hamiltonian the emulator uses for time-evolution
@@ -11,4 +11,4 @@ how to actually run a simulation, but rather
 - How to determine whether your results are accurate
 - How to estimate the memory consumption and the runtime of a simulation in advance
 
-For the experienced user, this will help get the most out of _EMU-MPS_.
+For the experienced user, this will help get the most out of emu-mps.

docs/advanced/mps/index.md

@@ -1,7 +1,7 @@
 # The MPS representation of a state
-As opposed to state vector solvers (of the Master/Schrödinger equation), tensor network based approaches use adaptive data structures, which in the case of _EMU-MPS_ are called [matrix product state/operator (MPS/MPO)](http://tensornetwork.org/mps/). They are adaptive in the sense that the memory used to store such a state/operator does not only depend on the dimension of the state space, but also on the specific state you're trying to represent. In many relevant use cases, this makes representation more memory-efficient, which allows pushing for higher number of qubits compared to state vector solvers. However, it has the drawback that the cost of the simulation is less predictable since there is no _a priori_ method to know how much information is going to be relevant at the next step of the solver. The are configurable hard caps on memory consumption built into _EMU-MPS_ ([see here](../resource_estimation.md)), but when these are hit it becomes necessary to check for validity of the results ([see here](../convergence.md)).
+As opposed to state vector solvers (of the Master/Schrödinger equation), tensor network based approaches use adaptive data structures, which in the case of emu-mps are called [matrix product state/operator (MPS/MPO)](http://tensornetwork.org/mps/). They are adaptive in the sense that the memory used to store such a state/operator does not only depend on the dimension of the state space, but also on the specific state you're trying to represent. In many relevant use cases, this makes representation more memory-efficient, which allows pushing for higher number of qubits compared to state vector solvers. However, it has the drawback that the cost of the simulation is less predictable since there is no _a priori_ method to know how much information is going to be relevant at the next step of the solver. The are configurable hard caps on memory consumption built into emu-mps ([see here](../resource_estimation.md)), but when these are hit it becomes necessary to check for validity of the results ([see here](../convergence.md)).
 
-The take-home message is that a reasonable way to assess _EMU-MPS_ performance is by __benchmarking relevant and meaningful sequences/use-cases__ ([see here](../../benchmarks/index.md)).
+The take-home message is that a reasonable way to assess emu-mps performance is by __benchmarking relevant and meaningful sequences/use-cases__ ([see here](../../benchmarks/index.md)).
 
 ## Bond dimension
 Please, have a look at [http://tensornetwork.org/mps/](http://tensornetwork.org/mps/) for a more general introduction to matrix product states.

docs/advanced/noise.md

@@ -1,7 +1,7 @@
-# Noise Implementation in EMU-MPS
-To faithfully emulate the Pasqal QPU using EMU-MPS, we need to include noise effects, as these effects cannot be neglected in a real quantum system—they significantly impact the performance and fidelity of the QPU.
+# Noise Implementation in emu-mps
+To faithfully emulate the Pasqal QPU using emu-mps, we need to include noise effects, as these effects cannot be neglected in a real quantum system—they significantly impact the performance and fidelity of the QPU.
 
-In open quantum many-body systems, noise is typically expressed in terms of **mixed states** and **noise channels** using a **density matrix representation**. Similar to a state-vector emulator, EMU-MPS **only handles pure states**. Therefore, we implement noise using a higher order Monte Carlo method ([see here](https://www.phys.ens.psl.eu/~dalibard/publi3/osa_93.pdf)), where we evolve the system using an **effective Hamiltonian** and then apply a quantum jump at certain times. This method is probabilistic in the sense that it approximates the simulation of a mixed state using many non-deterministic pure state simulations.
+In open quantum many-body systems, noise is typically expressed in terms of **mixed states** and **noise channels** using a **density matrix representation**. Similar to a state-vector emulator, emu-mps **only handles pure states**. Therefore, we implement noise using a higher order Monte Carlo method ([see here](https://www.phys.ens.psl.eu/~dalibard/publi3/osa_93.pdf)), where we evolve the system using an **effective Hamiltonian** and then apply a quantum jump at certain times. This method is probabilistic in the sense that it approximates the simulation of a mixed state using many non-deterministic pure state simulations.
 
 ## Noise Types
 
@@ -13,10 +13,10 @@ Our implementation supports different types of noise:
 - **eff_noise**: general effective noise channel defined by the set of collapse operators **eff_noise_opers** and their corresponding rates **eff_noise_rates**.
 - **SPAM errors**: parameterized by **state_prep_error**, **p_false_pos** and **p_false_neg**.
 
- Users can refer to the [Pulser documentation](https://pulser.readthedocs.io/en/stable/tutorials/noisy_sim.html) for a detailed overview of the different noise models currently available. EMU-MPS currently does not support the **amplitude noise**, **Doppler noise** and **leakage**.
+ Users can refer to the [Pulser documentation](https://pulser.readthedocs.io/en/stable/tutorials/noisy_sim.html) for a detailed overview of the different noise models currently available. Currently, emu-mps does not support the **amplitude noise**, **Doppler noise** and **leakage**.
 
 ## Effective Hamiltonian
-The non-hermitian **effective Hamiltonian** used in noisy EMU-MPS simulations includes both the physical Hamiltonian $H_{physical}$, which governs the noiseless evolution of the system, and a term representing noise:
+The non-hermitian **effective Hamiltonian** used in noisy emu-mps simulations includes both the physical Hamiltonian $H_{physical}$, which governs the noiseless evolution of the system, and a term representing noise:
 
 $$
 H_{\text{eff}} = H_{\text{physical}} \ - \ \frac{i}{2} \sum_m L^{\dagger}_m L_m.

docs/advanced/resource_estimation.md

@@ -3,7 +3,7 @@ The presence of the `max_bond_dim` and `max_krylov_dim` [config](config.md) para
 ## Estimating the memory consumption of a simulation
 
 In this section we outline how to estimate the memory consumption of a simulation, for a given `max_bond_dim`, a Krylov subspace of size `max_krylov_dim`, and for $N$ being the number of qubits to be simulated.
-There are four contributions to the peak memory consumption of EMU-MPS that will be discussed in the next sections:
+There are four contributions to the peak memory consumption of emu-mps that will be discussed in the next sections:
 
 - the state
 - the baths
@@ -76,7 +76,7 @@ For different combinations of the number of atoms in a register $N$ and the fixe
 
 Finally, having established an estimate for the memory consumption, it makes sense to explore what are the available regimes of qubits/bond dimension can be reached for a given hardware capability.
 Since all heavy simulations will be run on an NVIDIA A100 (on Pasqal's DGX cluster), we have 40 GB of available memory.
-Therefore, above, we show (right image) the contour lines of the RSS estimate $m(N,\chi,k=30) < 40$ GB for particular useful values of the total memory, allowing to quickly estimate the memory footprint of an _EMU-MPS_ emulation.
+Therefore, above, we show (right image) the contour lines of the RSS estimate $m(N,\chi,k=30) < 40$ GB for particular useful values of the total memory, allowing to quickly estimate the memory footprint of an emu-mps emulation.
 
 ### An example
 
@@ -130,7 +130,7 @@ Below, we show the obtained results for different number of atoms in a register
 <img src="../../benchmarks/benchmark_plots/runtime_vs_N.png"  width="49.7%">
 <img src="../../benchmarks/benchmark_plots/runtime_vs_bond_dim.png"  width="49.7%">
 
-To wrap up, and to provide an useful tool for runtime estimation for _EMU-MPS_, the time to perform a **single**  time step in a sequence can be conveniently visualized (below) for both $N$ and $\chi$ on contour lines.
+To wrap up, and to provide an useful tool for runtime estimation for emu-mps, the time to perform a **single**  time step in a sequence can be conveniently visualized (below) for both $N$ and $\chi$ on contour lines.
 
 <img src="../../benchmarks/benchmark_plots/emumps_runtime_map.png"  width="49.7%">
 

docs/advanced/tdvp.md

@@ -1,6 +1,6 @@
 # Summary of the TDVP algorithm
 
-EMU-MPS uses a second order 2-site TDVP to compute the time-evolution of the system ([see here for details](https://tensornetwork.org/mps/algorithms/timeevo/tdvp.html)).
+Emu-mps uses a second order 2-site TDVP to compute the time-evolution of the system ([see here for details](https://tensornetwork.org/mps/algorithms/timeevo/tdvp.html)).
 Briefly, the algorithm repeatedly computes the time-evolution for 2 neighbouring qubits while truncating the resulting MPS to keep the state small. It does this by
 
 - evolving qubit 1 and 2 forwards in time by $dt/2$

docs/api.md

@@ -1,7 +1,7 @@
 # API specification
 
-The EMU-MPS api is based on a series of abstract base classes, which are intended to generalize into a backend independent API.
-Currently these classes are defined in EMU-MPS, and they will be documented here until they are moved into a more general location, probably pulser-core.
+The emu-mps api is based on a series of abstract base classes, which are intended to generalize into a backend independent API.
+Currently these classes are defined in emu-mps, and they will be documented here until they are moved into a more general location, probably pulser-core.
 While they are in this project, see the specification [here](base_classes.md).
 
 ## MPSBackend