release v0.5.0 (#265)

# Release 0.5.0

### New features

* Optimization callback functionalities has been improved. A dedicated
`Callback` class is added which
is able to access the optimizer, the cost function, the parameters as
well as gradients, during the
optimization. In addition, multiple callbacks can be specified. This
opens up the endless possiblities
of customizing the the optimization progress with schedulers, trackers,
heuristics, tricks, etc.
  [(#219)](#219)

* Tensorboard-based optimization tracking is added as a builtin
`Callback` class: `TensorboardCallback`.
It can automatically track costs as well as all trainable parameters
during optimization in realtime.
  Tensorboard can be most conveniently viewed from VScode.
  [(#219)](#219)

  ```python
  import numpy as np
  from mrmustard.training import Optimizer, TensorboardCallback

  def cost_fn():
      ...
  
  def as_dB(cost):
      delta = np.sqrt(np.log(1 / (abs(cost) ** 2)) / (2 * np.pi))
      cost_dB = -10 * np.log10(delta**2)
      return cost_dB

  tb_cb = TensorboardCallback(cost_converter=as_dB, track_grads=True)

  opt = Optimizer(euclidean_lr = 0.001);
opt.minimize(cost_fn, max_steps=200, by_optimizing=[...],
callbacks=tb_cb)

# Logs will be stored in `tb_cb.logdir` which defaults to
`./tb_logdir/...` but can be customized.
# VScode can be used to open the Tensorboard frontend for live
monitoring.
# Or, in command line: `tensorboard --logdir={tb_cb.logdir}` and open
link in browser.
  ```

* Gaussian states support a `bargmann` method for returning the bargmann
representation.
  [(#235)](#235)

* The `ket` method of `State` now supports new keyword arguments
`max_prob` and `max_photons`.
Use them to speed-up the filling of a ket array up to a certain
probability or *total* photon number.
  [(#235)](#235)

  ```python
  from mrmustard.lab import Gaussian

# Fills the ket array up to 99% probability or up to the |0,3>, |1,2>,
|2,1>, |3,0> subspace, whichever is reached first.
# The array has the autocutoff shape, unless the cutoffs are specified
explicitly.
  ket = Gaussian(2).ket(max_prob=0.99, max_photons=3)
  ```

* Gaussian transformations support a `bargmann` method for returning the
bargmann representation.
  [(#239)](#239)

* BSGate.U now supports method='vanilla' (default) and 'schwinger'
(slower, but stable to any cutoff)
  [(#248)](#248)

### Breaking Changes

* The previous `callback` argument to `Optimizer.minimize` is now
`callbacks` since we can now pass
  multiple callbacks to it.
  [(#219)](#219)

* The `opt_history` attribute of `Optimizer` does not have the
placeholder at the beginning anymore.
  [(#235)](#235)

### Improvements

* The math module now has a submodule `lattice` for constructing
recurrence relation strategies in the Fock lattice.
There are a few predefined strategies in
`mrmustard.math.lattice.strategies`.
  [(#235)](#235)

* Gradients in the Fock lattice are now computed using the
vector-jacobian product.
This saves a lot of memory and speeds up the optimization process by
roughly 4x.
  [(#235)](#235)

* Tests of the compact_fock module now use hypothesis.
  [(#235)](#235)

* Faster implementation of the fock representation of `BSgate`, `Sgate`
and `SqueezedVacuum`, ranging from 5x to 50x.
  [(#239)](#239)

* More robust implementation of cutoffs for States.
[(#239)](#239)

* Dependencies and versioning are now managed using Poetry.
[(#257)](#257)

### Bug fixes

* Fixed a bug that would make two progress bars appear during an
optimization
  [(#235)](#235)

* The displacement of the dual of an operation had the wrong sign
  [(#239)](#239)

* When projecting a Gaussian state onto a Fock state, the upper limit of
the autocutoff now respect the Fock projection.
  [(#246)](#246)

* Fixed a bug for the algorithms that allow faster PNR sampling from
Gaussian circuits using density matrices. When the
cutoff of the first detector is equal to 1, the resulting density matrix
is now correct.

### Documentation

### Contributors
[Filippo Miatto](https://github.com/ziofil), [Zeyue
Niu](https://github.com/zeyueN),
[Robbe De Prins](https://github.com/rdprins), [Gabriele
Gullì](https://github.com/ggulli),
[Richard A. Wolf](https://github.com/ryk-wolf)

---------

Co-authored-by: Sebastián Duque Mesa <[email protected]>
Co-authored-by: JacobHast <[email protected]>
Co-authored-by: elib20 <[email protected]>
Co-authored-by: Luke Helt <[email protected]>
Co-authored-by: zeyueN <[email protected]>
Co-authored-by: Robbe De Prins <[email protected]>
Co-authored-by: Robbe De Prins (UGent-imec) <[email protected]>
Co-authored-by: Yuan <[email protected]>
Co-authored-by: Ryk <[email protected]>
Co-authored-by: Gabriele Gullì <[email protected]>

.devcontainer/Dockerfile

@@ -36,6 +36,8 @@ RUN sh -c "$(wget -nv -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/mast
 
 # upgrade pip and install package manager
 RUN python -m pip install --no-cache-dir --upgrade pip
+RUN pip install --no-cache-dir poetry==1.4.0
+RUN poetry config virtualenvs.create false
 
 ### TEAR DOWN IMAGE SETUP ###
 # switch back to dialog for any ad-hoc use of apt-get

.devcontainer/post-install.sh

@@ -1,8 +1,3 @@
 #! /bin/zsh
 
-pip install --no-cache-dir -r requirements.txt
-pip install --no-cache-dir -r requirements-dev.txt
-pip install --no-cache-dir -r doc/requirements.txt
-pip install ray
-pip install pylint
-pip install -e .
+poetry install --all-extras --with dev,doc

.github/CHANGELOG.md

@@ -1,3 +1,115 @@
+# Release 0.5.0
+
+### New features
+
+* Optimization callback functionalities has been improved. A dedicated `Callback` class is added which
+  is able to access the optimizer, the cost function, the parameters as well as gradients, during the
+  optimization. In addition, multiple callbacks can be specified. This opens up the endless possiblities
+  of customizing the the optimization progress with schedulers, trackers, heuristics, tricks, etc.
+  [(#219)](https://github.com/XanaduAI/MrMustard/pull/219)
+
+* Tensorboard-based optimization tracking is added as a builtin `Callback` class: `TensorboardCallback`.
+  It can automatically track costs as well as all trainable parameters during optimization in realtime.
+  Tensorboard can be most conveniently viewed from VScode.
+  [(#219)](https://github.com/XanaduAI/MrMustard/pull/219)
+
+  ```python
+  import numpy as np
+  from mrmustard.training import Optimizer, TensorboardCallback
+
+  def cost_fn():
+      ...
+
+  def as_dB(cost):
+      delta = np.sqrt(np.log(1 / (abs(cost) ** 2)) / (2 * np.pi))
+      cost_dB = -10 * np.log10(delta**2)
+      return cost_dB
+
+  tb_cb = TensorboardCallback(cost_converter=as_dB, track_grads=True)
+
+  opt = Optimizer(euclidean_lr = 0.001);
+  opt.minimize(cost_fn, max_steps=200, by_optimizing=[...], callbacks=tb_cb)
+
+  # Logs will be stored in `tb_cb.logdir` which defaults to `./tb_logdir/...` but can be customized.
+  # VScode can be used to open the Tensorboard frontend for live monitoring.
+  # Or, in command line: `tensorboard --logdir={tb_cb.logdir}` and open link in browser.
+  ```
+
+* Gaussian states support a `bargmann` method for returning the bargmann representation. 
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+* The `ket` method of `State` now supports new keyword arguments `max_prob` and `max_photons`.
+  Use them to speed-up the filling of a ket array up to a certain probability or *total* photon number.
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+  ```python
+  from mrmustard.lab import Gaussian
+
+  # Fills the ket array up to 99% probability or up to the |0,3>, |1,2>, |2,1>, |3,0> subspace, whichever is reached first.
+  # The array has the autocutoff shape, unless the cutoffs are specified explicitly.
+  ket = Gaussian(2).ket(max_prob=0.99, max_photons=3)
+  ```
+
+* Gaussian transformations support a `bargmann` method for returning the bargmann representation. 
+  [(#239)](https://github.com/XanaduAI/MrMustard/pull/239)
+
+* BSGate.U now supports method='vanilla' (default) and 'schwinger' (slower, but stable to any cutoff)
+  [(#248)](https://github.com/XanaduAI/MrMustard/pull/248)
+
+### Breaking Changes
+
+* The previous `callback` argument to `Optimizer.minimize` is now `callbacks` since we can now pass
+  multiple callbacks to it.
+  [(#219)](https://github.com/XanaduAI/MrMustard/pull/219)
+
+* The `opt_history` attribute of `Optimizer` does not have the placeholder at the beginning anymore.
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+### Improvements
+
+* The math module now has a submodule `lattice` for constructing recurrence relation strategies in the Fock lattice.
+  There are a few predefined strategies in `mrmustard.math.lattice.strategies`.
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+* Gradients in the Fock lattice are now computed using the vector-jacobian product.
+  This saves a lot of memory and speeds up the optimization process by roughly 4x.
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+* Tests of the compact_fock module now use hypothesis.
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+* Faster implementation of the fock representation of `BSgate`, `Sgate` and `SqueezedVacuum`, ranging from 5x to 50x.
+  [(#239)](https://github.com/XanaduAI/MrMustard/pull/239)
+
+* More robust implementation of cutoffs for States.
+[(#239)](https://github.com/XanaduAI/MrMustard/pull/239)
+
+* Dependencies and versioning are now managed using Poetry.
+[(#257)](https://github.com/XanaduAI/MrMustard/pull/257)
+
+### Bug fixes
+
+* Fixed a bug that would make two progress bars appear during an optimization
+  [(#235)](https://github.com/XanaduAI/MrMustard/pull/235)
+
+* The displacement of the dual of an operation had the wrong sign
+  [(#239)](https://github.com/XanaduAI/MrMustard/pull/239)
+
+* When projecting a Gaussian state onto a Fock state, the upper limit of the autocutoff now respect the Fock projection.
+  [(#246)](https://github.com/XanaduAI/MrMustard/pull/246)
+
+* Fixed a bug for the algorithms that allow faster PNR sampling from Gaussian circuits using density matrices. When the 
+cutoff of the first detector is equal to 1, the resulting density matrix is now correct.
+
+### Documentation
+
+### Contributors
+[Filippo Miatto](https://github.com/ziofil), [Zeyue Niu](https://github.com/zeyueN), 
+[Robbe De Prins](https://github.com/rdprins), [Gabriele Gullì](https://github.com/ggulli),
+[Richard A. Wolf](https://github.com/ryk-wolf)
+
+---
+
 # Release 0.4.1
 
 ### New features
@@ -23,8 +135,9 @@
 ### Contributors
 [Filippo Miatto](https://github.com/ziofil), [Sebastian Duque Mesa](https://github.com/sduquemesa)
 
+---
 
-# Release 0.4.0
+# Release 0.4.0 (current release)
 
 ### New features
 

.github/workflows/builds.yml

@@ -1,4 +1,4 @@
-name: builds
+name: Build package
 on:
   push:
     branches:
@@ -12,37 +12,37 @@ jobs:
     runs-on: ubuntu-latest
     env:
       HYPOTHESIS_PROFILE: ci
-
     strategy:
       fail-fast: false
       matrix:
         python-version: ['3.9', '3.10']
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.python-version }}
+      cancel-in-progress: true
 
     steps:
-      - name: Cancel Previous Runs
-        uses: styfle/[email protected]
-        with:
-          access_token: ${{ github.token }}
-
-      - uses: actions/checkout@v3
+      - name: Checkout repo
+        uses: actions/checkout@v3
 
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Build and install Mr Mustard
         run: |
-          python -m pip install --upgrade pip wheel
-          python setup.py bdist_wheel
+          python -m pip install --no-cache-dir --upgrade pip
+          pip install --no-cache-dir poetry==1.4.0
+          poetry config virtualenvs.create false
+          poetry build
           pip install dist/mrmustard*.whl
+          # Move to 'src' to properly test only installed package
+          # https://docs.pytest.org/en/7.1.x/explanation/goodpractices.html#tests-outside-application-code
+          mkdir src
+          mv mrmustard src
 
-      - name: Install test dependencies
-        run: |
-          pip install -r requirements.txt
-          pip install -r requirements-dev.txt
-          pip install wheel pytest pytest-cov pytest-mock hypothesis --upgrade
+      - name: Install only test dependencies
+        run: poetry install --no-root --extras "ray" --with dev
 
       - name: Run tests
-        run: |
-          python -m pytest tests -p no:warnings --tb=native
+        run: python -m pytest tests -p no:warnings --tb=native

.github/workflows/tests.yml

@@ -4,35 +4,38 @@ on:
     branches:
       - develop
   pull_request:
+    paths:
+      - '.github/workflows/tests.yml'
+      - 'mrmustard/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'poetry.lock'
+      - 'pytest.ini'
 
 jobs:
   pytest:
     runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     env:
       HYPOTHESIS_PROFILE: ci
 
     steps:
-      - name: Cancel Previous Runs
-        uses: styfle/[email protected]
-        with:
-          access_token: ${{ github.token }}
-
-      - uses: actions/checkout@v3
+      - name: Checkout repo
+        uses: actions/checkout@v3
 
-      - name: Setup python ${{ matrix.python-version }}
+      - name: Setup python
         uses: actions/setup-python@v4
         with:
           python-version: '3.9'
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install -r requirements-dev.txt
-          pip install wheel pytest pytest-cov --upgrade
-          pip install .[ray]
-          # python setup.py bdist_wheel
-          # pip install dist/*.whl
+          python -m pip install --no-cache-dir --upgrade pip
+          pip install --no-cache-dir poetry==1.4.0
+          poetry config virtualenvs.create false
+          poetry install --extras "ray" --with dev
 
       - name: Run tests
         run: python -m pytest tests --cov=mrmustard --cov-report=term-missing --cov-report=xml -p no:warnings --tb=native

.github/workflows/upload.yml

@@ -10,7 +10,8 @@ jobs:
       HYPOTHESIS_PROFILE: ci
 
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout repo
+        uses: actions/checkout@v3
 
       - name: Set up Python
         uses: actions/setup-python@v4
@@ -19,21 +20,24 @@ jobs:
 
       - name: Build and install Mr Mustard
         run: |
-          python -m pip install --upgrade pip wheel
-          python setup.py bdist_wheel
+          python -m pip install --no-cache-dir --upgrade pip
+          pip install --no-cache-dir poetry==1.4.0
+          poetry config virtualenvs.create false
+          poetry build
           pip install dist/mrmustard*.whl
+          # Move to 'src' to properly test only installed package
+          # https://docs.pytest.org/en/7.1.x/explanation/goodpractices.html#tests-outside-application-code
+          mkdir src
+          mv mrmustard src
 
-      - name: Install test dependencies
-        run: |
-          pip install -r requirements.txt
-          pip install wheel pytest pytest-cov pytest-mock hypothesis --upgrade
+      - name: Install only test dependencies
+        run: poetry install --no-root --extras "ray" --with dev
 
       - name: Run tests
-        run: |
-          python -m pytest tests -p no:warnings --tb=native
+        run: python -m pytest tests -p no:warnings --tb=native
 
       - name: Publish
-        uses: pypa/gh-action-pypi-publish@master
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
           password: ${{ secrets.PIPY_TOKEN }}

.readthedocs.yml

@@ -6,6 +6,11 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.9"
+  jobs:
+    post_install:
+      - pip install --no-cache-dir poetry==1.4.0
+      - poetry config virtualenvs.create false
+      - poetry install --with doc
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -16,9 +21,5 @@ sphinx:
 #    - pdf
 
 # Optionally declare the Python requirements required to build your docs
-python:
-   install:
-   - requirements: doc/requirements.txt
-   - method: pip
-     path: .
-   system_packages: true
+# python:
+#    install: