This file tells coding agents how to work in the HyPyP repository. It is deliberately short and contains only facts that are stable today. HyPyP is a Python library for hyperscanning analysis: it computes inter-brain connectivity and related statistics on EEG and fNIRS recordings of pairs of participants. Its results end up in scientific publications, so a silent change in a computed value is the most serious defect a contribution can introduce.
The project uses uv with a committed lock file and requires Python 3.11 or later. Install the development environment from the repository root:
uv sync --group devThe accelerated backends are optional extras and are not installed by default. Add them only when the task needs them: --extra numba, --extra torch, --extra metal (Apple Silicon only) and --extra cupy (NVIDIA CUDA 12 only).
uv run python -m pytest tests/Tests for a backend that is not installed are skipped, not failed. A green run without the extras therefore says nothing about the Numba, torch, Metal or CUDA code paths; say so when you report a result, and report the number of skipped tests along with the number that passed.
When a change may alter a computed value, write an independent reference test first and see it fail, then make the fix. An independent reference is a value obtained without the code under test: a closed-form result on a synthetic signal, or a different trusted implementation. A test that only checks the shape of an output, or that compares one HyPyP backend with another, is not a reference test.
Do not change a formula, a default parameter, a normalisation or a sign convention on your own judgement. These are choices of scientific method. Describe the problem, cite the literature, and leave the decision to a maintainer.
Keep a pull request to one subject, and state in its description whether it changes any numerical result.
Do not edit uv.lock by hand; change pyproject.toml and let uv lock regenerate it. Do not edit docs/requirements.txt by hand either: it is generated by update_docs_requirements.sh. Do not add a dependency without asking.
Do not modify the sample data in hypyp/data/ and tests/data/, and do not add recordings of real participants to the repository.
The fNIRS code under hypyp/fnirs/ and the Shiny dashboards under hypyp/shiny/ have their own maintainer and an open draft pull request. Ask before changing them.
Releases, tags and publication to PyPI are done by a maintainer with a dedicated procedure. Do not bump the version, create a tag or publish.