Skip to content

Contributing

This page is for contributors of this library. To use PtyLab, see Installation.

Contributing follows three steps: set up a local copy, make your changes with tests, and submit a pull request.

1. Set up

Fork and clone

Fork PtyLab/PtyLab.py on GitHub, then clone your fork and add the original repository as upstream:

git clone git@github.com:<your-username>/PtyLab.py.git
cd PtyLab.py
git remote add upstream https://github.com/PtyLab/PtyLab.py.git

Use https://github.com/<your-username>/PtyLab.py.git instead if you have not set up SSH keys for GitHub.

Work on a new branch created from the latest main:

git fetch upstream
git switch -c my-feature upstream/main

Install

Install the project with uv. uv sync creates a virtual environment and always includes the development tools (pytest, ruff); add the extras for your machine:

uv sync --all-extras                  # Linux/Windows with an NVIDIA GPU, or macOS

This installs all extras: CuPy for CUDA 12 (gpu) and the Qt viewer (gui).

uv sync --all-extras --no-extra gpu   # Linux/Windows without a GPU: skips CuPy

This installs the same extras without CuPy.

Either command creates a .venv in the project root; select it in your IDE or run source .venv/bin/activate. uv sync removes any extra you leave out, so reuse the same flags on every sync.

Check whether CuPy detects the GPU with:

uv run ptylab check gpu

2. Make changes

Avoid breaking changes to the public API. If one is unavoidable, keep the old name working and emit a DeprecationWarning that names the replacement (see pcPIE in PtyLab/Engines/mPIE.py).

Code style

Format the files you changed with ruff:

uv run ruff format path/to/changed_file.py

Tests

Add tests for new implementations and run the suite with:

uv run pytest tests

Tests that need an unavailable dependency are skipped, for example the CUDA tests on a machine without a GPU. Check the skipped count in the summary to see what did not run.

Documentation

Documentation changes are deployed automatically once a pull request is merged into main. Check them locally first:

uv run --group docs zensical serve

Then open http://127.0.0.1:8000 in your browser. The page reloads when you save a change.

Write maths in LaTeX between $...$ (inline) or $$...$$ (display), and draw diagrams in a ```mermaid code block.

Tutorials

Each tutorial is a Python script tutorial_<name>.py in docs/tutorials/scripts/, split into cells by # %% lines. If you add or change any of these scripts, re-render the tutorials with:

uv run ptylab docs render              # every tutorial whose script is new or changed

For rendering just a specific one, even if its script did not change (for example, after changing the code it uses):

uv run ptylab docs render <tutorial-name> # single tutorial (with or without .py)

This runs the script and saves the page and its figures in docs/tutorials/ (<tutorial-name>.md and <tutorial-name>_files/), which should be committed as well. The .ipynb it also writes there is not committed. In the end, run uv run ptylab docs check, which reports pages that are out of date and tutorials missing from the index or the nav, as CI does.

New feature, such as an engine or a constraint? Please add a tutorial for it. List it in docs/tutorials/index.md and in the nav of mkdocs.yml.

3. Submit a pull request

Using LLMs

You may use LLMs to generate code, as long as the pull request:

  • is of reasonable size,
  • contains well-written code,
  • is logically self-contained, addressing one feature or fix,
  • adds appropriate tests for new functions.

By opening a pull request, you confirm that you understand all of the code in it. Very large pull requests will be closed, with a request to resubmit them as smaller, logically separate pull requests.

Opening the pull request

Push your branch to your fork and open a pull request against main of PtyLab/PtyLab.py:

git push -u origin my-feature

GitHub fills the description with the pull request template. Fill in each section rather than replacing it: why the change is needed, how it was tested (a demo figure or screenshot helps), and any notes such as deprecations or changed reconstruction results. Keep the description short: list the changes per file as brief bullet points in simple words. Preferably write it yourself. If an LLM drafts it, edit it until it is easy to read, without unnecessary length or jargon.

If main has moved on in the meantime, update your branch with git fetch upstream and git rebase upstream/main.