Release v0.5.0 (#339)

Main Pulser features:
- Addition of buffer times for retargeting and phase jumps (#305)
- Output modulation (#312)
- `RegisterLayout` (#333)
- `MappableRegister` (#334)

Note: Extraordinarily merges changes dating back to v0.4 development to correct for that fact that v0.4.0 was merged to master in a squashed commit.

.flake8

@@ -1,15 +1,15 @@
 [flake8]
-exclude = ./build, ./docs
 docstring-convention = google
+exclude = ./build, ./docs
+extend-ignore =
+    # D105 Missing docstring in magic method
+    D105,
+    # E203 whitespace before ':' (for compliance with black)
+    E203,
 per-file-ignores =
   # D100 Missing docstring in public module
   # D103 Missing docstring in public function
   # F401 Module imported but unused
   pulser/tests/*: D100, D103
   __init__.py: F401
   setup.py: D100
-extend-ignore =
-    # D105 Missing docstring in magic method
-    D105,
-    # E203 whitespace before ':' (for compliance with black)
-    E203,

.github/workflows/ci.yml

@@ -32,8 +32,33 @@ jobs:
     steps:
       - name: Check out Pulser
         uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install black
+        run: |
+          python -m pip install --upgrade pip
+          pip install black
+          pip install 'black[jupyter]'
       - name: Check formatting with black
-        uses: psf/black@stable
+        run: black --check --diff .
+  isort:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out Pulser
+        uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install -r requirements.txt
+      - name: Check import sorting with isort
+        run: isort --check-only --diff .
   typing:
     runs-on: ubuntu-latest
     steps:
@@ -55,7 +80,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9, "3.10"]
     steps:
       - name: Check out Pulser
         uses: actions/checkout@v2

.mypy_script

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+mypy --config-file .mypy.ini

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 22.1.0
+    hooks:
+      - id: black-jupyter
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 4.0.1
+    hooks:
+      - id: flake8
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  # Calling mypy from a bash script, as I cannot figure out how to pass the
+  # .mypy.ini config file when using the hook at
+  # https://github.com/pre-commit/mirrors-mypy
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: ./.mypy_script
+        language: script

CONTRIBUTING.md

@@ -8,47 +8,55 @@ The steps to take will depend on what you want to do, but generally you'll want
 
 1. Do a quick search for keywords over the existing issues to ensure yours has not been added yet.
 2. If you can't find your issue already listed, create a new one. Please try to be as clear and detailed as possible in your description.
+
 - If you just want to give a suggestion or report a bug, that's already excellent and we thank you for it! Your issue will be listed and, hopefully, someone will take care of it at some point.
 - However, you may also want to be the one solving your issue, which would be even better! In these cases, you would proceed by preparing a [Pull Request](#making-a-pull-request).
 
-
 ## Making a Pull Request
 
 We're thrilled that you want to contribute to Pulser! For general contributions, we use a combination of two Git workflows: the [Forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) and the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). If you don't know what any of this means, don't worry, you should still be able to make your contribution just by following the instructions detailed below. Nonetheless, in a nutshell, this workflow will have you making a fork from the main Pulser repository and working off a branch from `develop` (**not** `master`). Thus, you'll start your branch from `develop` and end with a pull request that merges your branch back to `develop`. The only exception to this rule is when making a `hotfix`, but in these cases the Pulser development team will take care of it for you.
 
 Here are the steps you should follow to make your contribution:
 
 0. Fork the Pulser repository and add the main Pulser repository as the `upstream`. You only have to do this once and you do so by clicking the "Fork" button at the upper right corner of the [repo page](https://github.com/pasqal-io/Pulser). This will create a new GitHub repo at `https://github.com/USERNAME/Pulser`, where `USERNAME` is your GitHub ID. Then, `cd` into the folder where you would like to place your new fork and clone it by doing:
+
     ```bash
     git clone https://github.com/USERNAME/Pulser.git
     ```
+
     **Note**: `USERNAME` should be replaced by your own GitHub ID.
 
    Then, you'll want to go into the directory of your brand new Pulser fork and add the main Pulser repository as the `upstream` by running:
+
    ```bash
    git remote add upstream https://github.com/pasqal-io/Pulser.git
    ```
 
 1. Have the related issue assigned to you. We suggest that you work only on issues that have been assigned to you; by doing this, you make sure to be the only one working on this and we prevent everyone from doing duplicate work. If a related issue does not exist yet, consult the [section above](#reporting-a-bug-or-suggesting-a-feature) to see how to proceed.
 
 2. You'll want to create a new branch where you will do your changes. The starting point will be `upstream/develop`, which is where you'll ultimately merge your changes. Inside your fork's root folder, run:
+
     ```bash
     git fetch upstream
     git checkout -b branch-name-here upstream/develop
     ```
+
     This will create and checkout the new branch, where you will do your changes.
 
     **Note**: `branch-name-here` should be replaced by the name you'll give your branch. Try to be descriptive, pick a name that identifies your new feature.
 
 3. Do your work and commit the changes to this new branch. Try to make the first line of your commit messages short but informative; in case you want to go into more detail, you have the option to do so in the next lines.
 
 4. At this point, your branch might have drifted out of sync with Pulser's `develop` branch (the `upstream`). By running
+
     ```shell
     git pull upstream develop
     ```
+
    you will fetch the latest changes in `upstream/develop` and merge them with your working branch, at which point you'll have to solve any merge conflicts that may    arise. This will keep your working branch in sync with `upstream/develop`.
 
 5. Finally, you push your code to your local branch:
+
     ```bash
     git push origin branch-name-here
     ```
@@ -66,30 +74,64 @@ pip install -r requirements.txt
 ```
 
 - **Tests**: We use [`pytest`](https://docs.pytest.org/en/latest/) to run unit tests on our code. If your changes break existing tests, you'll have to update these tests accordingly. Additionally, we aim for 100% coverage over our code. Try to cover all the new lines of code with simple tests, which should be placed in the `Pulser/pulser/tests` folder. To run all tests and check coverage, run:
+
     ```bash
     pytest --cov pulser
     ```
+
     All lines that are not meant to be tested must be tagged with `# pragma: no cover`. Use it sparingly,
     every decision to leave a line uncovered must be well justified.
 
 - **Style**: We use [`flake8`](https://flake8.pycqa.org/en/latest/) and the `flake8-docstrings` extension to enforce PEP8 style guidelines. To lint your code with `flake8`, simply run:
+
     ```bash
     flake8 .
     ```
+
     To help you keep your code compliant with PEP8 guidelines effortlessly, we suggest you look into installing a linter for your text editor of choice.
 
-- **Format**: We use the [`black`](https://black.readthedocs.io/en/stable/index.html) auto-formatter to enforce a consistent style throughout the entire code base. It will also ensure your code is compliant with the formatting enforced by `flake8` for you. To automatically format your code with black, just run:
+- **Format**: We use the [`black`](https://black.readthedocs.io/en/stable/index.html) auto-formatter to enforce a consistent style throughout the entire code base, including the Jupyter notebooks (so make sure to install `black[jupyter]`). It will also ensure your code is compliant with the formatting enforced by `flake8` for you. To automatically format your code with black, just run:
+
     ```bash
     black .
     ```
+
     Note that some IDE's and text editors support plug-ins which auto-format your code with `black` upon saving, so you don't have to worry about code format at all.
 
-- **Type hints**: We use [mypy](http://mypy-lang.org/) to type check the code. Your code should have type
+- **Import sorting**: We use [`isort`](https://pycqa.github.io/isort/) to automatically sort all library imports. You can do the same by running:
+
+    ```bash
+    isort .
+    ```
+
+- **Type hints**: We use [`mypy`](http://mypy-lang.org/) to type check the code. Your code should have type
 annotations and pass the type checks from running:
+
     ```bash
     mypy
     ```
+
     In case `mypy` produces a false positive, you can ignore the respective line by adding the `# type: ignore` annotation.
 
     **Note**: Type hints for `numpy` have only been added in version 1.20. Make sure you have `numpy >= 1.20`
     installed before running the type checks.
+
+### Use `pre-commit` to automate CI checks
+
+[`pre-commit`](https://pre-commit.com/) is a tool to easily setup and manage [git hooks](https://git-scm.com/docs/githooks).
+
+Run
+
+```bash
+pre-commit install --hook-type pre-push
+```
+
+to install `black`, `isort`, `flake8` and `mypy` hooks in your local repository (at `.git/hooks/` by defaults)
+and run them automatically before any push to a remote git repository.
+If an issue is found by these tools, the git hook will abort the push. `black` and `isort` hooks may reformat guilty files.
+
+Disable the hooks with
+
+```bash
+pre-commit uninstall --hook-type pre-push
+```

README.md

@@ -2,9 +2,9 @@
 
 Pulser is a framework for composing, simulating and executing **pulse** sequences for neutral-atom quantum devices.
 
-**Documentation** for the [latest release](https://pypi.org/project/pulser/) of `pulser` is available at https://pulser.readthedocs.io (for the docs tracking the `develop` branch of this repository, visit https://pulser.readthedocs.io/en/latest instead).
+**Documentation** for the [latest release](https://pypi.org/project/pulser/) of `pulser` is available at <https://pulser.readthedocs.io> (for the docs tracking the `develop` branch of this repository, visit <https://pulser.readthedocs.io/en/latest> instead).
 
-The source code can be found at https://github.com/pasqal-io/Pulser.
+The source code can be found at <https://github.com/pasqal-io/Pulser>.
 
 ## Overview of Pulser
 
@@ -51,6 +51,7 @@ Then, you can do the following to run the test suite and report test coverage:
 ```bash
 pytest --cov pulser
 ```
+
 ## Contributing
 
 Want to contribute to Pulser? Great! See [How to Contribute][contributing] for information on how you can do so.

docs/source/intro_rydberg_blockade.ipynb

@@ -88,8 +88,10 @@
     "from pulser import Pulse\n",
     "from pulser.waveforms import RampWaveform, BlackmanWaveform\n",
     "\n",
-    "duration = 1000 # Typical: ~1 µsec\n",
-    "pulse = Pulse(BlackmanWaveform(duration, np.pi), RampWaveform(duration, -5., 10.), 0)\n",
+    "duration = 1000  # Typical: ~1 µsec\n",
+    "pulse = Pulse(\n",
+    "    BlackmanWaveform(duration, np.pi), RampWaveform(duration, -5.0, 10.0), 0\n",
+    ")\n",
     "pulse.draw()"
    ]
   },
@@ -131,18 +133,18 @@
    "source": [
     "from pulser import Sequence\n",
     "\n",
-    "reg = Register.rectangle(1, 2, spacing=8, prefix='atom')\n",
+    "reg = Register.rectangle(1, 2, spacing=8, prefix=\"atom\")\n",
     "reg.draw()\n",
     "\n",
-    "pi_pulse = Pulse.ConstantDetuning(BlackmanWaveform(duration, np.pi), 0., 0.)\n",
+    "pi_pulse = Pulse.ConstantDetuning(BlackmanWaveform(duration, np.pi), 0.0, 0.0)\n",
     "\n",
     "seq = Sequence(reg, Chadoq2)\n",
     "\n",
-    "seq.declare_channel('ryd','rydberg_local','atom0')\n",
+    "seq.declare_channel(\"ryd\", \"rydberg_local\", \"atom0\")\n",
     "\n",
-    "seq.add(pi_pulse,'ryd')\n",
-    "seq.target('atom1', 'ryd')\n",
-    "seq.add(pi_pulse,'ryd')\n",
+    "seq.add(pi_pulse, \"ryd\")\n",
+    "seq.target(\"atom1\", \"ryd\")\n",
+    "seq.add(pi_pulse, \"ryd\")\n",
     "\n",
     "seq.draw()"
    ]
@@ -199,25 +201,27 @@
     "data = []\n",
     "distances = np.linspace(6.5, 14, 7)\n",
     "\n",
-    "r = [1,0] # |r>\n",
-    "rr = np.kron(r,r) # |rr>\n",
+    "r = [1, 0]  # |r>\n",
+    "rr = np.kron(r, r)  # |rr>\n",
     "occup = [np.outer(rr, np.conj(rr))]  # |rr><rr|\n",
     "\n",
-    "for i,R in enumerate(distances):\n",
+    "for i, R in enumerate(distances):\n",
     "    # Atom Register and Device\n",
-    "    reg = Register.rectangle(1,2,spacing=R, prefix='atom')\n",
+    "    reg = Register.rectangle(1, 2, spacing=R, prefix=\"atom\")\n",
     "\n",
     "    # Pulse Sequence\n",
     "    seq = Sequence(reg, Chadoq2)\n",
-    "    seq.declare_channel('ryd','rydberg_local','atom0')\n",
-    "    seq.add(pi_pulse,'ryd')\n",
-    "    seq.target('atom1', 'ryd')\n",
-    "    seq.add(pi_pulse,'ryd')\n",
+    "    seq.declare_channel(\"ryd\", \"rydberg_local\", \"atom0\")\n",
+    "    seq.add(pi_pulse, \"ryd\")\n",
+    "    seq.target(\"atom1\", \"ryd\")\n",
+    "    seq.add(pi_pulse, \"ryd\")\n",
     "\n",
     "    sim = Simulation(seq)\n",
-    "    \n",
+    "\n",
     "    res = sim.run()  # Returns a SimulationResults instance\n",
-    "    data.append(res.expect(occup)[0]) # Get expectation value for the occupation operator\n",
+    "    data.append(\n",
+    "        res.expect(occup)[0]\n",
+    "    )  # Get expectation value for the occupation operator\n",
     "print(\"...Simulation Complete!\")"
    ]
   },
@@ -247,10 +251,10 @@
     }
    ],
    "source": [
-    "for i,R in enumerate(distances):\n",
-    "    plt.plot(data[i], label=f'R={R}')\n",
-    "    plt.xlabel('Time (ns)', fontsize=14)\n",
-    "    plt.ylabel(r'Occupation of $|rr\\rangle$', fontsize=14)\n",
+    "for i, R in enumerate(distances):\n",
+    "    plt.plot(data[i], label=f\"R={R}\")\n",
+    "    plt.xlabel(\"Time (ns)\", fontsize=14)\n",
+    "    plt.ylabel(r\"Occupation of $|rr\\rangle$\", fontsize=14)\n",
     "    plt.legend()"
    ]
   },

pulser/__init__.py

@@ -15,11 +15,7 @@
 """A pulse-level composer for neutral-atom quantum devices."""
 
 from pulser._version import __version__
-
 from pulser.pulse import Pulse
-
 from pulser.register import Register, Register3D
-
 from pulser.sequence import Sequence
-
 from pulser.simulation import Simulation