Documentation

.github/CONTRIBUTING.md

@@ -1,50 +1,176 @@
-
 # Contributing to **Cooper**
 
+We encourage contributions to **Cooper**.
 
-We want to make contributing to **Cooper** as easy and transparent as
-possible.
+Some things that we would like to see in the future, but have not yet had time to implement, are:
 
+- More tutorials showing how to use **Cooper** in non-deep learning applications.
 
-## Building
+## How to contribute
 
-Using `pip`, you can install the package in development mode by running:
+Please follow these steps to contribute:
 
-```sh
-pip install --editable ".[dev]"
-```
+1. If you plan to contribute new features, please first open an issue and discuss the feature with us.
 
-## Testing
+2. Fork the **Cooper** repository by clicking the **Fork** button on the
+   [repository page](http://www.github.com/cooper-org/cooper). This creates
+   a copy of the **Cooper** repository in your own account.
 
-We test the package using `pytest`, which you can run locally by typing
+3. Install Python >= 3.9 locally in order to run tests.
 
-```sh
-pytest tests
-```
+4. `pip` installing your fork from source. This allows you to modify the code
+   and immediately test it out:
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/cooper
+    cd cooper
+    pip install --editable .  # Without tests.
+    pip install --editable '.[test]'  # Matches test environment.
+    pip install --editable '.[dev]'  # Matches development environment.
+    pip install --editable '.[notebooks]'  # Install dependencies for running notebooks.
+    pip install --editable '.[docs]'  # Used to generate the documentation.
+    pip install --editable '.[dev, docs]'  # Install all dependencies.
+    ```
+
+5. Add the **Cooper** repo as an upstream remote, so you can use it to sync your
+   changes.
+
+   ```bash
+   git remote add upstream https://www.github.com/cooper-org/cooper
+   ```
+
+6. Create a branch where you will develop from:
+
+   ```bash
+   git checkout -b name-of-change
+   ```
+
+7. Make sure your code passes **Cooper**'s lint and type checks, by running the following from
+   the top of the repository:
+
+   ```bash
+   pip install pre-commit
+   pre-commit run --all
+   ```
+
+8. Make sure the tests pass by running the following command from the top of
+   the repository:
+
+   ```bash
+   pytest tests
+   ```
+
+   **Cooper**'s pipeline tests can take a while to run, so if you know the specific test file that covers your changes, you can limit the tests to that; for example:
 
-## Pull Requests
+   ```bash
+   pytest tests/multipliers/test_explicit_multipliers.py
+   ```
 
-We actively welcome your pull requests.
+   You can narrow the tests further by using the `pytest -k` flag to match particular test
+   names:
 
-1. Fork the repo and create your branch from `master`.
-2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
-4. Ensure the test suite passes.
-5. Make sure your code lints.
+   ```bash
+   pytest tests/test_cmp.py -k test_cmp_state_dict
+   ```
 
+9. Once you are satisfied with your change, create a commit as follows (
+   [how to write a commit message](https://chris.beams.io/posts/git-commit/)):
+
+    ```bash
+    git add file1.py file2.py ...
+    git commit -m "Your commit message"
+    ```
+
+   Then sync your code with the main repo:
+
+    ```bash
+    git fetch upstream
+    git rebase upstream/main
+    ```
+
+   Finally, push your commit on your development branch and create a remote
+   branch in your fork that you can use to create a pull request from:
+
+    ```bash
+    git push --set-upstream origin name-of-change
+    ```
+
+10. Create a pull request from the **Cooper** repository and send it for review. The pull request should be aimed at the `dev` branch.
+
+If you have any questions, please feel free to ask in the issue you opened, or reach out via our [Discord server](https://discord.gg/Aq5PjH8m6E).
 
 ## Issues
 
 We use GitHub issues to track public bugs. Please ensure your description is
 clear and has sufficient instructions to be able to reproduce the issue.
 
-## Coding Style
+## Code Style
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting, formatting and import sorting. We ask for type hints for all code committed to **Cooper** and check for compliance with [mypy](https://mypy.readthedocs.io/).
+The CI system should check this when you submit your pull requests.
+The easiest way to run these checks locally is via the
+[pre-commit](https://pre-commit.com/) framework:
+
+```bash
+pip install pre-commit
+pre-commit run --all-files
+```
+
+## Update notebooks
+
+We use [jupytext](https://jupytext.readthedocs.io/) to maintain two synced copies of the notebooks
+in `docs/source/notebooks`: one in `ipynb` format, and one in `md` format. The advantage of the former
+is that it can be opened and executed directly in Colab; the advantage of the latter is that
+it makes it much easier to track diffs within version control.
+
+```bash
+pip install jupytext==1.16.4
+jupytext --sync docs/source/notebooks/new_tutorial.ipynb
+```
+
+The jupytext version should match that specified in
+[.pre-commit-config.yaml](https://github.com/cooper-org/cooper/blob/master/.pre-commit-config.yaml).
+
+To check that the markdown and ipynb files are properly synced, you may use the
+[pre-commit](https://pre-commit.com/) framework to perform the same check used
+by the GitHub CI:
+
+```bash
+pip install pre-commit
+pre-commit run jupytext --all-files
+```
+
+## Update documentation
+
+To rebuild the documentation, install several packages:
+
+```
+pip install -e '.[docs]'
+```
+
+And then run:
+
+```
+sphinx-build -b html docs/source docs/source/build/html -j auto
+```
+
+This can take a long time because it executes many of the notebooks in the documentation source;
+if you'd prefer to build the docs without executing the notebooks, you can run:
+
+```
+sphinx-build -b html -D nb_execution_mode=off docs/source docs/source/build/html -j auto
+```
+
+You can then see the generated documentation in `docs/source/build/html/index.html`.
+
+The `-j auto` option controls the parallelism of the build. You can use a number
+in place of `auto` to control how many CPU cores to use.
 
-We use `ruff` for linting, formatting and import sorting. We ask for type hints for all code committed to **Cooper** and check
-for compliance with `mypy`. The CI system should check of this when you submit
-your pull requests.
 
 ## License
 
 By contributing to **Cooper**, you agree that your contributions will be
 licensed under the LICENSE file in the root directory of this source tree.
+
+## Acknowledgements
+
+This CONTRIBUTING.md file is based on the one from [JAX](https://jax.readthedocs.io/en/latest/contributing.html).

.github/workflows/ci.yaml

@@ -5,6 +5,14 @@ on:
   push:
     branches: [ master ]
 
+concurrency:
+  # github.workflow: name of the workflow
+  # github.event.pull_request.number || github.ref: pull request number or branch name if not a pull request
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+
+  # Cancel in-progress runs when a new workflow with the same group name is triggered
+  cancel-in-progress: true
+
 jobs:
   ci:
     runs-on: ubuntu-latest
@@ -24,12 +32,13 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.10"
+          cache: "pip"
 
       - name: Pre-commit checks
         uses: pre-commit/action@v3.0.1
 
       - name: Install package & dependencies
-        run: pip install --editable '.[dev, docs, tests, examples]'
+        run: pip install '.[tests]'
 
       - name: Launch tests & generate coverage report
         run: coverage run -m pytest tests
@@ -39,6 +48,10 @@ jobs:
         uses: py-cov-action/python-coverage-comment-action@v3
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # If the coverage percentage is above or equal to this value, the badge will be green.
+          MINIMUM_GREEN: 90
+          # If the coverage percentage is below this value, the badge will be red.
+          MINIMUM_ORANGE: 80
 
       - name: Store Pull Request comment to be posted
         uses: actions/upload-artifact@v4

.github/workflows/coverage.yaml

@@ -22,9 +22,12 @@ jobs:
       # artifact that contains the comment to be published
       actions: read
     steps:
-
       - name: Post comment
         uses: py-cov-action/python-coverage-comment-action@v3
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}
+          # If the coverage percentage is above or equal to this value, the badge will be green.
+          MINIMUM_GREEN: 90
+          # If the coverage percentage is below this value, the badge will be red.
+          MINIMUM_ORANGE: 80

.github/workflows/publish.yaml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
   push:
     tags:
-      - v.**
+      - 'v[0-9]+\.[0-9]+\.[0-9]+'
 
 jobs:
   publish:

.github/workflows/test.yaml

@@ -0,0 +1,48 @@
+name: Run tests
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+concurrency:
+  # github.workflow: name of the workflow
+  # github.event.pull_request.number || github.ref: pull request number or branch name if not a pull request
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+
+  # Cancel in-progress runs when a new workflow with the same group name is triggered
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.9", "3.10", "3.11" ]
+        TORCH_VERSION: [ "1.13.1", "2.0.1", "2.1.2", "2.2.2", "2.3.1", "2.4.0" ]
+        include:
+          - python-version: "3.12"
+            TORCH_VERSION: "2.4.0"
+        exclude:
+          - python-version: "3.11"
+            TORCH_VERSION: "1.13.1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies and PyTorch ${{ matrix.TORCH_VERSION }}
+        run: |
+          pip install --upgrade pip
+          pip install torch==${{ matrix.TORCH_VERSION }} '.[tests]'
+
+      - name: Launch tests
+        # Only run the unit tests, not the pipeline tests.
+        # Pipeline tests are too expensive to run for every python/PyTorch version.
+        # However, they are run as part the coverage job in the CI workflow
+        run: pytest --ignore=tests/pipeline tests

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
         files: \.py$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.6
+    rev: v0.6.1
     hooks:
       - id: ruff
         types_or: [ python, pyi, jupyter ]
@@ -28,7 +28,7 @@ repos:
         types_or: [ python, pyi, jupyter ]
 
   - repo: https://github.com/mwouts/jupytext
-    rev: v1.16.3
+    rev: v1.16.4
     hooks:
       - id: jupytext
         files: docs/source/notebooks

CITATION.cff

@@ -7,6 +7,8 @@ authors:
       given-names: "Juan"
     - family-names: "Hashemizadeh"
       given-names: "Meraj"
-title: "Cooper: a toolkit for Lagrangian-based constrained optimization"
-date-released: 2022-03-15
+    - family-names: "Lacoste-Julien"
+      given-names: "Simon"
+title: "Cooper: A Library for Constrained Optimization in Deep Learning"
+date-released: 2024-09-01
 url: "https://github.com/cooper-org/cooper"

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022, The Cooper Developers
+Copyright (c) 2024, The Cooper Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal