Contributing to PyNitride¶

Getting started¶

To become a contributor, first fork the repository then follow the build-from-source instructions, except use your forked repository URL when cloning instead of the main repository URL.

Dependency management¶

The dependencies are defined by pyproject.toml and locked in requirements.txt.

To regenerate the locked dependencies after changing pyproject.toml, run:

pip-compile --no-strip-extras --no-annotate --no-allow-unsafe --no-header --extra dev -o requirements.txt pyproject.toml

(To update the dependencies to their latest versions, add an --upgrade flag, or e.g. --upgrade-package numpy to only upgrade a specific package.)

Then install the new dependencies with

pip install -r requirements.txt

Note that the CI Tests job checks that regenerating the locked dependencies from pyproject.toml matches the existing requirements.txt, so if you change pyproject.toml you must also regenerate requirements.txt. (This regeneration references the existing requirements.txt so it should not fail just because a newer version of a dependency was released.)

Tests¶

Tests include unit tests, literature value tests, and a set of example simulations that are run and compared to “golden” output files.

CI¶

The Tests workflow (.github/workflows/tests.yml) runs the unit tests and example tests on every push and pull request, and will fail if any of the tests fail.

Golden files¶

These golden files were generated by running the examples and saving the output, and are included in the repository in the tests/examples/goldens directory. When adding a new example, you should create a test function for it in test_examples.py (under tests/examples/) following the pattern of e.g. test_hemt_example().

Then to generate the golden file for a new example, you can simply run test_examples.py with the name of the example function, e.g. python test_examples.py test_hemt_example.

Documentation¶

The source files are in the docs/ and docs/manual/ directories. The root toctree is in docs/index.rst. You can add new pages to the manual by creating new .rst files in docs/manual/ and adding them to the toctree in docs/index.rst.

Building¶

The documentation is built using Sphinx, just run python docs/document.py, which will generate the API reference and build the HTML files in the docs/build/html/ directory.

Deploying documentation¶

Documentation (such as latest) is hosted on Read the Docs and rebuilds automatically on every push to main.

Distribution¶

Wheels¶

PyNitride contains Cython extensions and must be distributed as pre-built binary wheels. Wheels are built using cibuildwheel for the following platforms:

Runner	Wheel
`ubuntu-latest`	`manylinux_x86_64`
`ubuntu-24.04-arm`	`manylinux_aarch64`
`windows-latest`	`win_amd64`
`windows-11-arm`	`win_arm64`
`macos-latest`	`macosx_arm64`

The cibuildwheel configuration lives in pyproject.toml under [tool.cibuildwheel]. After building each wheel, cibuildwheel installs it into a fresh virtual environment and runs the full test suite to verify the wheel is functional.

CI¶

The Build Tests workflow (.github/workflows/build_tests.yml) runs on every push to, or pull request targeting, dev, main, or any release/** branch. It builds wheels for all five platforms and runs the tests inside each installed wheel.

Publishing to PyPI¶

The PyPI workflow (.github/workflows/pypi.yml) publishes to the PyNitride PyPI project when a tag of the form vX.X.X is pushed.

To cut a release:

Bump __version__ in src/pynitride/__init__.py to the intended version, e.g. "0.2.0".
Commit and push.
Tag the commit with the matching version and push the tag — the workflow enforces that the tag and __version__ agree:
```
git tag vX.Y.Z
git push origin vX.Y.Z
```

The workflow will build wheels for all five platforms and, once all builds pass, publish them to PyPI. To install from PyPI for verification:

pip install pynitride

Pull requests¶

When contributing to the project, please open a pull request from your fork with a clear description of the changes and why they are needed. Pull requests from forks should apply to the dev branch, not main! Once tested on dev, the changes can be merged into main by the maintainers.