Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (137 loc) · 6.9 KB

CONTRIBUTING.md

File metadata and controls

178 lines (137 loc) · 6.9 KB
Raw

Contributing to quantem.widget

Thank you for contributing. Changes may come from a scientist working directly, from a scientist collaborating with a coding agent, or from an agent preparing work for human review. Everyone follows the same scientific and review standards.

quantem.widget combines Python APIs, React frontends, saved notebook state, standalone HTML, and GPU-backed scientific workflows. A useful contribution keeps the parts it touches consistent and gives reviewers enough evidence to understand what changed.

Start with a focused change

Use one small branch for one issue or documentation goal. Describe the user problem before the implementation, and keep unrelated experiments or cleanup out of the branch.

Adding a new widget, or a refactor that other widgets will import, starts with an issue or a maintainer discussion. A bug fix or a feature that stays inside one existing widget can go straight to a pull request. The two classes are in the pull request guide.

Reuse existing tutorial inputs in the public bobleesj/quantem-data dataset: viewer collections live under widget/, while shared image and diffraction inputs stay under haadf/ and 4dstem/. A new tutorial does not need another copy of an existing input. Keep scientific data, minimal data cards and numerical metadata on Hugging Face; notebooks, Python helpers, models and result reports belong in their owning source repositories. The dataset card records contribution requirements and provenance. The GitHub loader workflow is in Contribute tutorial data.

Once review begins, do not force-push. Add follow-up commits so GitHub preserves inline comments and the reviewer can inspect only the changes since their last visit. The project squash-merges completed work.

For Git and GitHub introductions, see ophusgroup/dev.

Set up the project

Create a dedicated Conda environment:

conda create --name live-env --channel conda-forge python=3.14 nodejs=22 pip
conda activate live-env

The DirectPtycho source migration requires the matching quantem.gpu source candidate, 0.0.1rc18.dev0 or newer in the rc18 series. These development versions are source candidates, not published releases. Install the paired backend first, then this widget checkout, so the environment cannot select an older backend without the direct reconstruction API. For a fresh paired checkout, run the following from a parent workspace directory. Both repositories use the oct-24-direct-iterative-api branch; their main branches do not yet contain this candidate API. Existing clones should switch to that same branch first.

git clone --branch oct-24-direct-iterative-api https://github.com/bobleesj/quantem.gpu.git
git clone --branch oct-24-direct-iterative-api https://github.com/bobleesj/quantem.widget.git
cd quantem.widget
pip install -e '../quantem.gpu[cuda]'   # use [mps] on Apple silicon
pip install -e '.[cuda]'              # use [mps] on Apple silicon
npm ci
QUANTEM_GPU_SRC=../quantem.gpu/src npm run build

Conventional direct ptychography remains available on CUDA and MPS. The regularized phase and complex methods currently require CUDA and do not run in standalone exports.

For documentation work:

pip install -r docs/requirements.txt

Check your change

Run the smallest checks that cover what you changed. For Python changes, run:

pytest -q

For frontend work, use the development build while editing and make a final production build before review:

npm run dev
npm run build

The build copies quantem.gpu's WebGPU science kernels into the bundles, so it needs a quantem.gpu source. It takes, in order: QUANTEM_GPU_SRC (the src directory of a quantem.gpu checkout at the commit in gpu-ref.txt), the quantem.gpu installed in the Python named by PYTHON, a quantem.gpu checkout beside this repository (../quantem.gpu, said in one line), and the quantem.gpu installed in python. For example:

QUANTEM_GPU_SRC=../quantem.gpu/src npm run build
PYTHON="$(which python)" npm run build      # quantem.gpu installed in this environment

Set QUANTEM_GPU_SRC for the npm command only: quantem core reads every QUANTEM_* environment variable as its configuration, and an exported one makes a docs-environment test fail.

If you changed frontend logic, also run the focused checks:

npm run typecheck
npm test

You do not need to memorize a separate command for every widget. The pull-request template routes each type of change to the relevant checks, and the release guide documents the release-level gates.

Use the pull-request template

The PR template is intentionally thorough. It is a shared review contract for humans and coding agents, not a requirement to keep every checkbox in every PR. Keep the core checklist and only the expandable sections relevant to your change; delete the rest.

The structured verification fields—tests, user workflow, data shape and dtype, backend, timing, and evidence artifacts—make scientific claims reproducible. They also give agents and automation enough metadata to select checks, detect missing evidence, and prepare a review without guessing about the experiment. A human reviewer should still be able to understand the completed template without reading agent logs.

Preserve scientific behavior

  • Use NumPy-style docstrings and modern Python type hints for public APIs.
  • Present positions to users in (row, col) order and name physical units.
  • Add helpful errors with a corrective next step when invalid input could produce a scientifically wrong result.
  • Do not silently crop, bin, downsample, quantize, or substitute a backend.
  • Test the workflow a scientist actually uses, not only an internal helper.
  • For interactive changes, drive the UI and report the data shape, dtype, backend, and observed responsiveness.

See the widget UI protocol, performance guide, and HTML export reference for the detailed contracts.

Commit durable files only

Commit source, tests, and public documentation. Do not commit generated HTML, documentation builds, node_modules, local screenshots, private notebooks or data, machine paths, browser profiles, or AppleDouble ._* metadata.

Before committing, inspect the exact scope:

git status --short
git diff --stat

Use a short, single-line Conventional Commit-style message such as:

feat: add calibrated image export
fix: stabilize Show2D resize handle
docs: clarify HTML export guidance

Releases

Release candidates have additional packaging, browser, and TestPyPI gates. Follow the release guide before creating a widget-v* tag.