dynamiqs 0.2.2__tar.gz → 0.2.3__tar.gz

dynamiqs-0.2.3/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing to Dynamiqs
+
+We warmly welcome all contributions. If you're a junior developer or physicist, you can start with a small utility function, and move on to bigger problems as you discover the library's internals. If you're more experienced and want to implement more advanced features, don't hesitate to [get in touch](https://github.com/dynamiqs/dynamiqs#lets-talk) to discuss what would suit you.
+
+To contribute efficiently, a few guidelines are compiled below.
+
+## 1. Requirements
+
+The project was written using Python 3.9+, you must have a compatible version of Python (i.e. >= 3.9) installed on your computer.
+
+## 2. Setup
+
+Clone the repository and dive in:
+
+```shell
+git clone git@github.com:dynamiqs/dynamiqs.git
+cd dynamiqs
+```
+
+To install the library with all its dependencies, as well as the developer dependencies:
+
+- **If you use `uv`**, just run:
+  ```shell
+  uv sync --extra dev
+  ```
+- **If you use `pip`**, we strongly recommend creating a virtual environment to install the project dependencies. You can then install the library in editable mode:
+  ```shell
+  pip install -e ".[dev]"
+  ```
+
+## 3. Workflow
+
+### Github flow
+
+We use the GitHub flow branch-based workflow to collaborate on the library. If you're unfamiliar with open-source development, you can follow the [GitHub flow tutorial](https://docs.github.com/en/get-started/using-github/github-flow). Briefly, to add a change you should: fork the repository, create a branch, make and commit your changes, create a pull request (PR), address review comments, and merge the PR.
+
+### Planning your change
+
+If you are planning a large change (more than one hundred lines of code), it is usually more efficient to discuss it with us beforehand. This way, we can agree on the API and the main logic. For structural or significant changes, we typically write and iterate on small RFCs (Requests for Comments). For large change, please separate the logical building blocks of your change into distinct pull requests as much as possible. Long PRs are harder to review, and breaking them down will make everyone's life easier.
+
+If the proposed change is necessary for your work and has not been reviewed within reasonable time (a few working days), don’t hesitate to ping the main developers directly on the PR.
+
+### Developer tools
+
+We use a variety of modern formatting and linting tools, as well as automated tests, to ensure high code quality and to identify bugs early in the development process. These tests can be run either together or individually using the `task` CLI tool, which is installed as part of the development dependencies.
+
+Typically you should ensure all tasks run smoothly before submitting a new PR:
+
+```shell
+task all
+```
+
+Here is a list of available tasks:
+
+```shell
+> task --list
+lint         lint the code (ruff)
+format       auto-format the code (ruff)
+codespell    check for misspellings (codespell)
+clean        clean the code (ruff + codespell)
+test         run the unit tests suite (pytest)
+doctest-code check code docstrings examples (doctest)
+doctest-docs check documentation examples (doctest)
+doctest      check all examples (doctest)
+docbuild     build the documentation website
+docserve     preview documentation website with hot-reloading
+all          run all tasks before a commit (ruff + codespell + pytest + doctest)
+ci           run all the CI checks
+```
+
+### Run tasks automatically before each commit
+
+Alternatively, you can use `pre-commit` to automatically run the cleaning tasks (ruff + codespell) before each commit:
+
+```shell
+pip install pre-commit
+pre-commit install
+```
+
+### Build the documentation
+
+The documentation is built using [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. MkDocs generates a static website based on the markdown files in the `docs/` directory.
+
+To preview the changes to the documentation as you edit the docstrings or the markdown files in `docs/`, we recommend starting a live preview server, which will automatically rebuild the website upon modifications:
+
+```shell
+task docserve
+```
+
+Open <http://localhost:8000/> in your web browser to preview the documentation website.
+
+You can build the static documentation website locally with:
+
+```shell
+task docbuild
+```
+
+This will create a `site/` directory with the contents of the documentation website. You can then simply open `site/index.html` in your web browser to view the documentation website.
+
+## 4. Style guide
+
+This project adheres to PEP 8 guidelines. The maximum line length is **88** characters, and we recommend setting this limit in your IDE. Generally, our automatic cleaning task (`task clean`) will address most basic styling issues. If you have any remaining doubts, you can follow the conventions used throughout the library by looking at various files.
+
+We strive to keep the codebase as maintainable, readable, and unified as possible. We would appreciate your help by following these guidelines in your next PR.
+
+### Writing a PR
+
+The main goal to keep in mind is that if someone reads a past PR, they should quickly gain a clear understanding of what the change was.
+
+- Use a lower case name for your branch name.
+- Choose a clear and precise title for your PR. We use the squash and merge strategy to incorporate changes, so the title of your PR will become the commit title in the `main` branch history. Refer to the [commit history of the `main` branch](https://github.com/dynamiqs/dynamiqs/commits/main/) for inspiration.
+- If, after multiple reviews and iterations, the content of the PR no longer corresponds to the original description, please update the description.
+
+### Adding a new function
+
+When writing your function:
+
+- Type all arguments of your function, and its return type.
+- When typing a public function, use `ArrayLike` for array inputs (and `jnp.asarray()` to convert to a proper array), and `Array` for array outputs. See [JAX typing best practices](https://jax.readthedocs.io/en/latest/jax.typing.html#jax-typing-best-practices).
+- Ensure you run `task docserve` to verify how the documentation for your function appears, and correct any issues with rendering.
+- To type an array shape, use `...` to denote possible batch dimensions, use `n` for the Hilbert space dimension.
+- To add an axis to an array, favor `[None, ...]` over `unsqueeze`.
+- Favor `(...).sum(0)` over `jnp.sum(..., 0)`.
+
+Make sure to add your function:
+
+1. to the `__all__` variable at the top of the file (this is how we control namespaces to have everything available under `dq.*`),
+2. to the `dynamiqs/mkdocs.yml` file (so it appears in the documentation and navigation),
+3. to the `dynamiqs/docs/python_api/index.md` file (so it appears on the Python API page, which lists all the functions of the library).
+
+### Writing a docstring
+
+We use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8.1-comments-in-doc-strings) (see examples [here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)) with a few quirks.
+
+- Headers can include (in this order and with these names): `Args`, `Returns`, `Raises`, `Examples`, `See also`.
+- You can use the admonitions (colored blocks in the documentation) `Note` and `Warning` if relevant.
+- Avoid using `The` in arguments description, for example change `x: The quantum state.` to `x: Quantum state.`.
+- Specify arguments type in `_(...)_` after the argument name and _only if it is necessary_. Adding a type can for example be useful to add a shape information for an array, or because the argument typing in the function signature is opaque.
+
+### Documentation
+
+- For internal links, use `[dq.Options][dynamiqs.Options]` for a class, `[dq.sesolve()][dynamiqs.sesolve]` for a function (explicitely include `()` in the function name), and `(doc page)(relative/path/to/file.md)` for another documentation page (note the parentheses instead of brackets).
+- If you want to add an icon somewhere, use one of the `:material-*` (search the list [here](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)).
+
+### Exceptions message
+
+- Use one or multiple sentences starting with a capital letter and ending with a period.
+- Use backticks ``` ` ``` to refer to a variable name or a function. Use `'` to refer to a string.
+- Many exceptions arise from incorrect argument input; they should typically follow the format: `"Argument ... must ..., but ..."`.
+
+Examples:
+
+```python
+raise ValueError(f'Argument `H` must have shape (n, n), but has shape H.shape={H.shape}.')
+raise ValueError(
+    "Argument `matmul_precision` should be a string 'low', 'high', or"
+    f" 'highest', but is '{matmul_precision}'."
+)
+```

{dynamiqs-0.2.2 → dynamiqs-0.2.3}/LICENSE

@@ -199,3 +199,6 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+This project also includes code derived from QuTiP, licensed under the BSD 3-Clause
+License. The BSD 3-Clause License can be found in the `NOTICE` file.

dynamiqs-0.2.3/NOTICE

@@ -0,0 +1,33 @@
+=======================================================================
+QuTiP's 3-Clause BSD License
+=======================================================================
+
+This project contains code derived from QuTiP, which is licensed under the BSD 3-Clause License. The original license is reproduced below:
+
+    Copyright (c) 2011 to 2022 inclusive, QuTiP developers and contributors.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification,
+    are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+    3. Neither the name of the copyright holder nor the names of its contributors
+    may be used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+    ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{dynamiqs-0.2.2 → dynamiqs-0.2.3}/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: dynamiqs
-Version: 0.2.2
+Version: 0.2.3
 Summary: High-performance quantum systems simulation with JAX (GPU-accelerated & differentiable solvers).
-Author-email: Pierre Guilmin <pierreguilmin@gmail.com>, Ronan Gautier <ron.gautier@gmail.com>, Adrien Bocquet <adrienbocquet38@gmail.com>, Elie Genois <elie.genois@usherbrooke.ca>
+Author-email: Pierre Guilmin <pierreguilmin@gmail.com>, Ronan Gautier <ron.gautier@gmail.com>, Adrien Bocquet <adrienbocquet38@gmail.com>, Elie Genois <elie.genois@usherbrooke.ca>, Daniel Weiss <daniel.kamrath.weiss@gmail.com>
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: Apache Software License
@@ -16,7 +16,7 @@ Requires-Dist: matplotlib
 Requires-Dist: tqdm
 Requires-Dist: jax<0.4.34
 Requires-Dist: jaxlib
-Requires-Dist: jaxtyping
+Requires-Dist: jaxtyping<=0.2.34
 Requires-Dist: diffrax>=0.5.1
 Requires-Dist: equinox
 Requires-Dist: pillow
@@ -24,7 +24,7 @@ Requires-Dist: cmasher>=1.8.0
 Requires-Dist: ipython
 Requires-Dist: tqdm
 Requires-Dist: taskipy ; extra == "dev"
-Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: ruff>=0.8 ; extra == "dev"
 Requires-Dist: codespell ; extra == "dev"
 Requires-Dist: pytest>=8.0 ; extra == "dev"
 Requires-Dist: pytest-sugar ; extra == "dev"
@@ -41,6 +41,7 @@ Requires-Dist: sybil>=6 ; extra == "dev"
 Requires-Dist: black ; extra == "dev"
 Requires-Dist: flit ; extra == "dev"
 Requires-Dist: mike ; extra == "dev"
+Requires-Dist: optax ; extra == "dev"
 Project-URL: Documentation, https://www.dynamiqs.org/
 Project-URL: Homepage, https://github.com/dynamiqs/dynamiqs
 Project-URL: Repository, https://github.com/dynamiqs/dynamiqs
@@ -50,15 +51,15 @@ Provides-Extra: dev
     <img alt="Dynamiqs logo" width="360" src="https://github.com/dynamiqs/dynamiqs/blob/main/docs/media/logo-typeface-darktype.png?raw=true">
 </h1>
 
-[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois)
+[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois), [D. Weiss](https://github.com/dkweiss31)
 
 [![ci](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml/badge.svg)](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml?query=branch%3Amain)  ![python version](https://img.shields.io/badge/python-3.9%2B-blue) [![chat](https://badgen.net/badge/icon/on%20slack?icon=slack&label=chat&color=orange)](https://join.slack.com/t/dynamiqs-org/shared_invite/zt-1z4mw08mo-qDLoNx19JBRtKzXlmlFYLA) [![license: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-yellow)](https://github.com/dynamiqs/dynamiqs/blob/main/LICENSE) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 High-performance quantum systems simulation with JAX.
 
-**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, and the stochastic master equation. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
+**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, the stochastic master equation, and others. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
 
-Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/python_api/index.html) for a list of all implemented functions.
+Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/stable/python_api/index.html) for a list of all implemented functions.
 
 The main features of **Dynamiqs** are:
 
@@ -69,7 +70,7 @@ The main features of **Dynamiqs** are:
 
 We hope that this library will prove useful to the community for e.g. simulation of large quantum systems, gradient-based parameter estimation or quantum optimal control. The library is designed for large-scale problems, but also runs efficiently on CPUs for smaller problems.
 
-⚠️ This library is under active development and while the APIs and solvers are still finding their footing, we're working hard to make it worth the wait. Check back soon for the grand opening!
+⚠️ This library is under active development and some APIs and solvers are still finding their footing. While most of the library is stable, new releases might introduce breaking changes.
 
 ## Installation
 
@@ -163,22 +164,22 @@ Gradient w.r.t. kappa : -3.3520
 Gradient w.r.t. alpha0: 1.0670
 ```
 
-ℹ️ On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
+ℹ️ On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{-i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
 
 $$
 \nabla_\theta\ \bar{n} = \begin{pmatrix}
-  \partial\bar{n} / \partial\omega \\
-  \partial\bar{n} / \partial\kappa \\
+  \partial\bar{n} / \partial\omega \\\\
+  \partial\bar{n} / \partial\kappa \\\\
   \partial\bar{n} / \partial\alpha_0
 \end{pmatrix}
 = \begin{pmatrix}
-  0\\
-  -\alpha_0^2 T e^{-\kappa T} \\
+  0 \\\\
+  -\alpha_0^2 T e^{-\kappa T} \\\\
   2 \alpha_0 e^{-\kappa T}
 \end{pmatrix}
 \approx \begin{pmatrix}
-  0.0 \\
-  -3.3520 \\
+  0.0 \\\\
+  -3.3520 \\\\
   1.0670
 \end{pmatrix}
 $$
@@ -251,11 +252,11 @@ If you have found this library useful in your academic research, you can cite:
 ```bibtex
 @unpublished{guilmin2024dynamiqs,
   title  = {Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems},
-  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois},
+  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois and Daniel Weiss},
   year   = {2024},
   url    = {https://github.com/dynamiqs/dynamiqs}
 }
 ```
 
-> P. Guilmin, R. Gautier, A. Bocquet, E. Genois. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.
+> P. Guilmin, R. Gautier, A. Bocquet, E. Genois, D. Weiss. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.
 

{dynamiqs-0.2.2 → dynamiqs-0.2.3}/README.md

@@ -6,15 +6,15 @@
   </picture>
 </h1>
 
-[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois)
+[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois), [D. Weiss](https://github.com/dkweiss31)
 
 [![ci](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml/badge.svg)](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml?query=branch%3Amain)  ![python version](https://img.shields.io/badge/python-3.9%2B-blue) [![chat](https://badgen.net/badge/icon/on%20slack?icon=slack&label=chat&color=orange)](https://join.slack.com/t/dynamiqs-org/shared_invite/zt-1z4mw08mo-qDLoNx19JBRtKzXlmlFYLA) [![license: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-yellow)](https://github.com/dynamiqs/dynamiqs/blob/main/LICENSE) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 High-performance quantum systems simulation with JAX.
 
-**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, and the stochastic master equation. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
+**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, the stochastic master equation, and others. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
 
-Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/python_api/index.html) for a list of all implemented functions.
+Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/stable/python_api/index.html) for a list of all implemented functions.
 
 The main features of **Dynamiqs** are:
 
@@ -26,7 +26,7 @@ The main features of **Dynamiqs** are:
 We hope that this library will prove useful to the community for e.g. simulation of large quantum systems, gradient-based parameter estimation or quantum optimal control. The library is designed for large-scale problems, but also runs efficiently on CPUs for smaller problems.
 
 > [!WARNING]
-> This library is under active development and while the APIs and solvers are still finding their footing, we're working hard to make it worth the wait. Check back soon for the grand opening!
+> This library is under active development and some APIs and solvers are still finding their footing. While most of the library is stable, new releases might introduce breaking changes.
 
 ## Installation
 
@@ -122,7 +122,7 @@ Gradient w.r.t. alpha0: 1.0670
 ```
 
 > [!Note]
-> On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
+> On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{-i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
 >
 > $$
 > \nabla_\theta\ \bar{n} = \begin{pmatrix}
@@ -210,10 +210,10 @@ If you have found this library useful in your academic research, you can cite:
 ```bibtex
 @unpublished{guilmin2024dynamiqs,
   title  = {Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems},
-  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois},
+  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois and Daniel Weiss},
   year   = {2024},
   url    = {https://github.com/dynamiqs/dynamiqs}
 }
 ```
 
-> P. Guilmin, R. Gautier, A. Bocquet, E. Genois. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.
+> P. Guilmin, R. Gautier, A. Bocquet, E. Genois, D. Weiss. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.

{dynamiqs-0.2.2 → dynamiqs-0.2.3}/README_PYPI.md

@@ -2,15 +2,15 @@
     <img alt="Dynamiqs logo" width="360" src="https://github.com/dynamiqs/dynamiqs/blob/main/docs/media/logo-typeface-darktype.png?raw=true">
 </h1>
 
-[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois)
+[P. Guilmin](https://github.com/pierreguilmin), [R. Gautier](https://github.com/gautierronan), [A. Bocquet](https://github.com/abocquet), [E. Genois](https://github.com/eliegenois), [D. Weiss](https://github.com/dkweiss31)
 
 [![ci](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml/badge.svg)](https://github.com/dynamiqs/dynamiqs/actions/workflows/ci.yml?query=branch%3Amain)  ![python version](https://img.shields.io/badge/python-3.9%2B-blue) [![chat](https://badgen.net/badge/icon/on%20slack?icon=slack&label=chat&color=orange)](https://join.slack.com/t/dynamiqs-org/shared_invite/zt-1z4mw08mo-qDLoNx19JBRtKzXlmlFYLA) [![license: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-yellow)](https://github.com/dynamiqs/dynamiqs/blob/main/LICENSE) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 High-performance quantum systems simulation with JAX.
 
-**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, and the stochastic master equation. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
+**Dynamiqs** is a Python library for **GPU-accelerated** and **differentiable** quantum simulations. Solvers are available for the Schrödinger equation, the Lindblad master equation, the stochastic master equation, and others. The library is built with [JAX](https://jax.readthedocs.io/en/latest/index.html) and the main solvers are based on [Diffrax](https://github.com/patrick-kidger/diffrax).
 
-Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/python_api/index.html) for a list of all implemented functions.
+Documentation is available on our website, <https://www.dynamiqs.org>; see the [Python API](https://www.dynamiqs.org/stable/python_api/index.html) for a list of all implemented functions.
 
 The main features of **Dynamiqs** are:
 
@@ -21,7 +21,7 @@ The main features of **Dynamiqs** are:
 
 We hope that this library will prove useful to the community for e.g. simulation of large quantum systems, gradient-based parameter estimation or quantum optimal control. The library is designed for large-scale problems, but also runs efficiently on CPUs for smaller problems.
 
-⚠️ This library is under active development and while the APIs and solvers are still finding their footing, we're working hard to make it worth the wait. Check back soon for the grand opening!
+⚠️ This library is under active development and some APIs and solvers are still finding their footing. While most of the library is stable, new releases might introduce breaking changes.
 
 ## Installation
 
@@ -115,22 +115,22 @@ Gradient w.r.t. kappa : -3.3520
 Gradient w.r.t. alpha0: 1.0670
 ```
 
-ℹ️ On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
+ℹ️ On this specific example, we can verify the result analytically. The state remains a coherent state at all time with complex amplitude $\alpha(t) = \alpha_0 e^{-\kappa t/2} e^{-i\omega t}$, and the final photon number is thus $\bar{n} = |\alpha(T)|^2 = \alpha_0^2 e^{-\kappa T}$. We can then compute the gradient with respect to the three parameters $\theta = (\omega, \kappa, \alpha_0)$:
 
 $$
 \nabla_\theta\ \bar{n} = \begin{pmatrix}
-  \partial\bar{n} / \partial\omega \\
-  \partial\bar{n} / \partial\kappa \\
+  \partial\bar{n} / \partial\omega \\\\
+  \partial\bar{n} / \partial\kappa \\\\
   \partial\bar{n} / \partial\alpha_0
 \end{pmatrix}
 = \begin{pmatrix}
-  0\\
-  -\alpha_0^2 T e^{-\kappa T} \\
+  0 \\\\
+  -\alpha_0^2 T e^{-\kappa T} \\\\
   2 \alpha_0 e^{-\kappa T}
 \end{pmatrix}
 \approx \begin{pmatrix}
-  0.0 \\
-  -3.3520 \\
+  0.0 \\\\
+  -3.3520 \\\\
   1.0670
 \end{pmatrix}
 $$
@@ -203,10 +203,10 @@ If you have found this library useful in your academic research, you can cite:
 ```bibtex
 @unpublished{guilmin2024dynamiqs,
   title  = {Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems},
-  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois},
+  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois and Daniel Weiss},
   year   = {2024},
   url    = {https://github.com/dynamiqs/dynamiqs}
 }
 ```
 
-> P. Guilmin, R. Gautier, A. Bocquet, E. Genois. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.
+> P. Guilmin, R. Gautier, A. Bocquet, E. Genois, D. Weiss. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.

{dynamiqs-0.2.2 → dynamiqs-0.2.3}/docs/community/citing.md

@@ -5,10 +5,10 @@ If you have found this library useful in your academic research, you can cite:
 ```bibtex
 @unpublished{guilmin2024dynamiqs,
   title  = {Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems},
-  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois},
+  author = {Pierre Guilmin and Ronan Gautier and Adrien Bocquet and {\'{E}}lie Genois and Daniel Weiss},
   year   = {2024},
   url    = {https://github.com/dynamiqs/dynamiqs}
 }
 ```
 
-> P. Guilmin, R. Gautier, A. Bocquet, E. Genois. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.
+> P. Guilmin, R. Gautier, A. Bocquet, E. Genois, D. Weiss. Dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024), in preparation.

dynamiqs-0.2.3/docs/community/contributing.md

@@ -0,0 +1,161 @@
+# Contributing to Dynamiqs
+
+We warmly welcome all contributions. If you're a junior developer or physicist, you can start with a small utility function, and move on to bigger problems as you discover the library's internals. If you're more experienced and want to implement more advanced features, don't hesitate to [get in touch](./lets-talk.md) to discuss what would suit you.
+
+To contribute efficiently, a few guidelines are compiled below.
+
+## 1. Requirements
+
+The project was written using Python 3.9+, you must have a compatible version of Python (i.e. >= 3.9) installed on your computer.
+
+## 2. Setup
+
+Clone the repository and dive in:
+
+```shell
+git clone git@github.com:dynamiqs/dynamiqs.git
+cd dynamiqs
+```
+
+To install the library with all its dependencies, as well as the developer dependencies:
+
+- **If you use `uv`**, just run:
+  ```shell
+  uv sync --extra dev
+  ```
+- **If you use `pip`**, we strongly recommend creating a virtual environment to install the project dependencies. You can then install the library in editable mode:
+  ```shell
+  pip install -e ".[dev]"
+  ```
+
+## 3. Workflow
+
+### Github flow
+
+We use the GitHub flow branch-based workflow to collaborate on the library. If you're unfamiliar with open-source development, you can follow the [GitHub flow tutorial](https://docs.github.com/en/get-started/using-github/github-flow) Briefly, to add a change you should: fork the repository, create a branch, make and commit your changes, create a pull request (PR), address review comments, and merge the PR.
+
+### Planning your change
+
+If you are planning a large change (more than one hundred lines of code), it is usually more efficient to discuss it with us beforehand. This way, we can agree on the API and the main logic. For structural or significant changes, we typically write and iterate on small RFCs (Requests for Comments). For large change, please separate the logical building blocks of your change into distinct pull requests as much as possible. Long PRs are harder to review, and breaking them down will make everyone's life easier.
+
+If the proposed change is necessary for your work and has not been reviewed within three days, don’t hesitate to ping the main developers directly on the PR.
+
+### Developer tools
+
+We use a variety of modern formatting and linting tools, as well as automated tests, to ensure high code quality and to identify bugs early in the development process. These tests can be run either together or individually using the `task` CLI tool, which is installed as part of the development dependencies.
+
+Typically you should ensure all tasks run smoothly before submitting a new PR:
+
+```shell
+task all
+```
+
+Here is a list of available tasks:
+
+```shell
+> task --list
+lint         lint the code (ruff)
+format       auto-format the code (ruff)
+codespell    check for misspellings (codespell)
+clean        clean the code (ruff + codespell)
+test         run the unit tests suite (pytest)
+doctest-code check code docstrings examples (doctest)
+doctest-docs check documentation examples (doctest)
+doctest      check all examples (doctest)
+docbuild     build the documentation website
+docserve     preview documentation website with hot-reloading
+all          run all tasks before a commit (ruff + codespell + pytest + doctest)
+ci           run all the CI checks
+```
+
+### Run tasks automatically before each commit
+
+Alternatively, you can use `pre-commit` to automatically run the cleaning tasks (ruff + codespell) before each commit:
+
+```shell
+pip install pre-commit
+pre-commit install
+```
+
+### Build the documentation
+
+The documentation is built using [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. MkDocs generates a static website based on the markdown files in the `docs/` directory.
+
+To preview the changes to the documentation as you edit the docstrings or the markdown files in `docs/`, we recommend starting a live preview server, which will automatically rebuild the website upon modifications:
+
+```shell
+task docserve
+```
+
+Open <http://localhost:8000/> in your web browser to preview the documentation website.
+
+You can build the static documentation website locally with:
+
+```shell
+task docbuild
+```
+
+This will create a `site/` directory with the contents of the documentation website. You can then simply open `site/index.html` in your web browser to view the documentation website.
+
+## 4. Style guide
+
+This project adheres to PEP 8 guidelines. The maximum line length is **88** characters, and we recommend setting this limit in your IDE. Generally, our automatic cleaning task (`task clean`) will address most basic styling issues. If you have any remaining doubts, you can follow the conventions used throughout the library by looking at various files.
+
+We strive to keep the codebase as maintainable, readable, and unified as possible. We would appreciate your help by following these guidelines in your next PR.
+
+### Writing a PR
+
+The main goal to keep in mind is that if someone reads a past PR, they should quickly gain a clear understanding of what the change was.
+
+- Use a lower case name for your branch name.
+- Choose a clear and precise title for your PR. We use the squash and merge strategy to incorporate changes, so the title of your PR will become the commit title in the `main` branch history. Refer to the [commit history of the `main` branch](https://github.com/dynamiqs/dynamiqs/commits/main/) for inspiration.
+- If, after multiple reviews and iterations, the content of the PR no longer corresponds to the original description, please update the description.
+
+### Adding a new function
+
+When writing your function:
+
+- Type all arguments of your function, and its return type.
+- When typing a public function, use `ArrayLike` for array inputs (and `jnp.asarray()` to convert to a proper array), and `Array` for array outputs. See [JAX typing best practices](https://jax.readthedocs.io/en/latest/jax.typing.html#jax-typing-best-practices).
+- Ensure you run `task docserve` to verify how the documentation for your function appears, and correct any issues with rendering.
+- To type an array shape, use `...` to denote possible batch dimensions, use `n` for the Hilbert space dimension.
+- To add an axis to an array, favor `[None, ...]` over `unsqueeze`.
+- Favor `(...).sum(0)` over `jnp.sum(..., 0)`.
+
+Make sure to add your function:
+
+1. to the `__all__` variable at the top of the file (this is how we control namespaces to have everything available under `dq.*`),
+2. to the `dynamiqs/mkdocs.yml` file (so it appears in the documentation and navigation),
+3. to the `dynamiqs/docs/python_api/index.md` file (so it appears on the Python API page, which lists all the functions of the library).
+
+### Writing a docstring
+
+We use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8.1-comments-in-doc-strings) (see examples [here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)) with a few quirks.
+
+- Headers can include (in this order and with these names): `Args`, `Returns`, `Raises`, `Examples`, `See also`.
+- You can use the admonitions (colored blocks in the documentation) `Note` and `Warning` if relevant.
+- Avoid using `The` in arguments description, for example change `x: The quantum state.` to `x: Quantum state.`.
+- Specify arguments type in `_(...)_` after the argument name and _only if it is necessary_. Adding a type can for example be useful to add a shape information for an array, or because the argument typing in the function signature is opaque.
+
+### Documentation
+
+- For internal links, use `[dq.Options][dynamiqs.Options]` for a class, `[dq.sesolve()][dynamiqs.sesolve]` for a function (explicitely include `()` in the function name), and `(doc page)(relative/path/to/file.md)` for another documentation page (note the parentheses instead of brackets).
+- If you want to add an icon somewhere, use one of the `:material-*` (search the list [here](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)).
+
+### Exceptions message
+
+- Use one or multiple sentences starting with a capital letter and ending with a period.
+- Use backticks ``` ` ``` to refer to a variable name or a function. Use `'` to refer to a string.
+- Many exceptions arise from incorrect argument input; they should typically follow the format: `"Argument ... must ..., but ..."`.
+
+Examples:
+
+<!-- skip: next -->
+
+```python
+raise ValueError(f'Argument `H` must have shape (n, n), but has shape H.shape={H.shape}.')
+raise ValueError(
+    "Argument `matmul_precision` should be a string 'low', 'high', or"
+    f" 'highest', but is '{matmul_precision}'."
+)
+```