Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ Each check actually run, as `command → result`, and any human review or
independent reference used to judge correctness. Then a `Not verified:` line
for anything not checked, and why.

- [ ] `python -m flake8 polyphys projects`
- [ ] `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate projects`
- [ ] `python -m pytest polyphys README.md projects --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'`
- [ ] `python -m flake8 polyphys`
- [ ] `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate`
- [ ] `python -m pytest polyphys README.md --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'`
- [ ] `python -m build` if packaging metadata, package data, or package layout changed
- [ ] `python -m sphinx -W -b html docs/source docs/_build` if `docs/source/` changed
- [ ] `CHANGELOG.md` has an entry under `[Unreleased]`, or this pull request needs none (`CONTRIBUTING.md`, "Changelog")
Expand Down
10 changes: 5 additions & 5 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:
python -m pip install flake8

- name: Run flake8
run: flake8 polyphys projects
run: flake8 polyphys

typecheck:
name: Type-check
Expand All @@ -59,7 +59,7 @@ jobs:
python -m pip install -e .[dev]

- name: Run mypy
run: mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate projects
run: mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate

test:
name: Test Python ${{ matrix.python-version }}
Expand Down Expand Up @@ -94,7 +94,7 @@ jobs:
# tests, which cannot run here, out of the measured set; the
# MDAnalysis job below measures them.
run: |
pytest polyphys README.md projects \
pytest polyphys README.md \
--cov=polyphys \
--cov-config=.coveragerc-no-mda \
--cov-report=term-missing \
Expand Down Expand Up @@ -143,7 +143,7 @@ jobs:
# report with the matrix jobs', which leave the probe layer out; the
# floor stays on the matrix job.
run: |
pytest polyphys README.md projects \
pytest polyphys README.md \
--cov=polyphys \
--cov-report=term-missing \
--cov-report=xml \
Expand Down Expand Up @@ -200,7 +200,7 @@ jobs:
# Without MDAnalysis, like the matrix jobs, and without coverage:
# this job checks the floors, and it uploads no coverage report.
run: |
.venv/bin/python -m pytest polyphys README.md projects \
.venv/bin/python -m pytest polyphys README.md \
--doctest-modules \
--doctest-glob="README.md"

Expand Down
8 changes: 3 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ commit it, and never copy its contents into a tracked file.
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Install | `python -m pip install -e '.[dev,viz]'`; add the `mda` extra for the probe tests and `docs` for the docs build |
| Build | `python -m build` |
| Run all tests | `python -m pytest polyphys README.md projects --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'` |
| Run all tests | `python -m pytest polyphys README.md --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'` |
| Run one test | `python -m pytest polyphys/tests/manage/test_parser.py::<test name>` |
| Lint | `python -m flake8 polyphys projects` |
| Type-check | `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate projects` |
| Lint | `python -m flake8 polyphys` |
| Type-check | `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate` |
| Docs | `python -m sphinx -W -b html docs/source docs/_build` |
| Full pre-commit gate | Lint, type-check, and all tests; add the build after a packaging change and the docs build when `docs/source/` changed |

Expand Down Expand Up @@ -58,7 +58,6 @@ PolyPhys/
polyphys/probe/ core, chain_size, binders, histograms, pairs: per-frame observables read from LAMMPS trajectories with MDAnalysis (the mda extra)
polyphys/viz/ colors, helpers: color lists and matplotlib helpers for the studies' figures (the viz extra)
polyphys/tests/ tests for analyze/, manage/, probe/, simulate/, viz/, packaging, the docs pages, and the shared fixtures
projects/ one folder per study: its ProjectSpec, ProbeSpec, and analysis tables; not installed
docs/source/ Sphinx sources
README.md user guide; its examples run as doctests
AI-POLICY.md AI policy, for contributors
Expand Down Expand Up @@ -161,7 +160,6 @@ your role in each tier. Change both in the same commit.
| `polyphys/probe/` | Supervised | Draft against acceptance criteria the maintainer set; every line is read. |
| `polyphys/viz/` | Supervised | Draft against acceptance criteria the maintainer set; every line is read. |
| `polyphys/tests/`, `.github/workflows/`, `pyproject.toml` | Supervised | Draft against acceptance criteria the maintainer set; every line is read. |
| `projects/` | Supervised | Draft a study's spec from the research code's values; every line is read. |
| `docs/` | Supervised | Draft against acceptance criteria the maintainer set; every line is read. |

- A path not listed is Supervised: draft against acceptance criteria the
Expand Down
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ deprecation is listed under "Changed" and starts with `**Deprecated:**`.
- Rate every part of the repository as Supervised in the AI tier tables of `README.md` and `AGENTS.md`: AI drafts and the maintainer reads every line, as the 1.0 code, tests, workflows, and documentation were made ([#269](https://github.com/amirhs1/PolyPhys/issues/269), [#271](https://github.com/amirhs1/PolyPhys/pull/271))
- Say on the front page of the documentation, and in the README, what the research code is: the maintainer's private repository PolyPhys was migrated from, which nothing in PolyPhys needs; call it the research code, not SciOps or the research repository, in the study specs, the tests, and the design decisions; and name its functions instead of its files and their line ranges in the study specs and their tests ([#272](https://github.com/amirhs1/PolyPhys/pull/272))
- Install PolyPhys from conda-forge, where it is published from 1.0.0, on the installation pages, with `mdanalysis` and `matplotlib-base` alongside it for the probe and viz layers, instead of installing it with pip into a conda environment ([#236](https://github.com/amirhs1/PolyPhys/issues/236))
- Move the four published studies' parsers, specs, and tests from `projects/` to the companion repository [polyphys-lab](https://github.com/amirhs1/polyphys-lab), where each installs as `polyphys_lab.<study>`, together with the probe, pipeline, and viz tests that run a study's specs on real frames or compare with the research code; PolyPhys's tests no longer import any study, and the `ImportError` of a moved study parser now names its `polyphys_lab` module ([#275](https://github.com/amirhs1/PolyPhys/issues/275))
- Take the parser of `benchmarks/organizer_timing.py` as `--parser <module>:<class>`, such as `polyphys_lab.trans_foci_cub.parser:TransFociCub`, instead of a study folder in `projects/` ([#275](https://github.com/amirhs1/PolyPhys/issues/275))
- Retire the `projects` area from `CONTRIBUTING.md`, "Names", and the `projects/` rows of the tier tables in `README.md` and `AGENTS.md` ([#275](https://github.com/amirhs1/PolyPhys/issues/275))

### Added

Expand Down
9 changes: 4 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@ Run these from the repository root before opening a pull request:

| Check | Command |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lint | `python -m flake8 polyphys projects` |
| Type-check | `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate projects` |
| All tests | `python -m pytest polyphys README.md projects --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'` |
| Lint | `python -m flake8 polyphys` |
| Type-check | `python -m mypy polyphys/analyze polyphys/manage polyphys/probe polyphys/simulate` |
| All tests | `python -m pytest polyphys README.md --cov=polyphys --cov-report=term-missing --cov-report=xml --doctest-modules --doctest-glob='README.md'` |
| One test | `python -m pytest polyphys/tests/manage/test_parser.py::<test name>` |
| Package build | `python -m build`, after a packaging change |
| Documentation build | `python -m sphinx -W -b html docs/source docs/_build`, when `docs/source/` changed |
Expand Down Expand Up @@ -109,7 +109,7 @@ part of the repository. A commit's scope is its area, and the labels are

```text
types: feat fix docs test refactor chore release question
areas: analyze manage simulate probe viz projects packaging guide ci agents deps
areas: analyze manage simulate probe viz packaging guide ci agents deps
```

| Type | Means |
Expand All @@ -130,7 +130,6 @@ areas: analyze manage simulate probe viz projects packaging guide ci agents deps
| `simulate` | `polyphys/simulate/`, `polyphys/tests/simulate/` |
| `probe` | `polyphys/probe/`, `polyphys/tests/probe/` |
| `viz` | `polyphys/viz/`, `polyphys/tests/viz/` |
| `projects` | `projects/`: the studies' specs, drivers, and tests, outside the package |
| `packaging` | `pyproject.toml`, `polyphys/__version__.py`, `polyphys/tests/test_packaging.py`, `CITATION.cff`, `AUTHORS.rst` |
| `guide` | `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `SECURITY.md`, `docs/`, `.github/ISSUE_TEMPLATE/` |
| `ci` | `.github/workflows/`, `.github/dependabot.yml` |
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,8 @@ details. `probe` needs the `mda` extra and `viz.helpers` the `viz` extra.

The package ships no study's parser: each study declares its own
`ParserBase` subclass in its own folder. The parsers of the maintainer's
published studies are in `projects/`, outside the installed package.
published studies are in the companion repository
[polyphys-lab](https://github.com/amirhs1/polyphys-lab).

## Documentation

Expand Down Expand Up @@ -238,7 +239,8 @@ layer's tests run on Python 3.14 with MDAnalysis.
The Python examples above run as doctests in the test suite.

A study _uses_ PolyPhys from outside the package rather than extending it:
its parser and its specs live in its own folder, as `projects/` shows.
its parser and its specs live in its own folder, as
[polyphys-lab](https://github.com/amirhs1/polyphys-lab) shows.

PolyPhys was migrated from the maintainer's private research code, which the
documentation, docstrings, and tests call _the research code_; the
Expand Down Expand Up @@ -279,7 +281,6 @@ records the checks or human review applied to each part:
| `polyphys/probe/` | Supervised | CI: flake8, mypy; pytest with doctests on Python 3.14 with MDAnalysis installed; maintainer review of every line |
| `polyphys/viz/` | Supervised | CI: flake8, pytest with doctests on Python 3.11–3.14 with matplotlib installed; maintainer review of every line |
| `polyphys/tests/`, `.github/workflows/`, `pyproject.toml` | Supervised | CI on every pull request: lint, type-check, tests, docs build, package build; maintainer review of every line |
| `projects/` | Supervised | CI: flake8, mypy, pytest of each spec against its parser and the research code's values; maintainer review of every line |
| `docs/` | Supervised | CI: Sphinx build with warnings as errors for `docs/source/`; maintainer review of every line |

Nothing that handles security, credentials, private data, or published results,
Expand Down
33 changes: 17 additions & 16 deletions benchmarks/organizer_timing.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,12 @@

Usage
=====
Run from a checkout or an environment where ``polyphys`` imports::
Run from a checkout or an environment where ``polyphys`` and the study's
parser import::

python benchmarks/organizer_timing.py <probe_dir> \\
--parser trans_foci_cub --group bug --prop gyrTMon \\
--relation tseries --repeats 5
--parser polyphys_lab.trans_foci_cub.parser:TransFociCub \\
--group bug --prop gyrTMon --relation tseries --repeats 5

``<probe_dir>`` is the probe directory of one space, as
:func:`~polyphys.analyze.pipeline.reduce_space` takes it; ``--hierarchy``
Expand Down Expand Up @@ -89,7 +90,6 @@
import time
import tracemalloc
from collections import Counter
from pathlib import Path
from typing import Any, Callable, Sequence

import numpy as np
Expand Down Expand Up @@ -274,16 +274,16 @@ def residual(end_to_end: dict[str, float],
return end_to_end['median_s'] - sum(p['median_s'] for p in parts)


def _study_parser(study: str) -> type:
"""Return the parser class that ``projects/<study>/parser.py``
exports, the only class in its ``__all__``; ``projects/`` is not an
installed package, so its folder is put on the import path."""
projects = Path(__file__).resolve().parents[1] / 'projects'
if str(projects) not in sys.path:
sys.path.insert(0, str(projects))
module = importlib.import_module(f'{study}.parser')
(name,) = module.__all__
parser: type = getattr(module, name)
def _study_parser(target: str) -> type:
"""Return the parser class that `target`, ``<module>:<class>``, names,
such as ``polyphys_lab.trans_foci_cub.parser:TransFociCub``; the module
must be importable."""
module_name, sep, class_name = target.partition(':')
if not sep or not module_name or not class_name:
raise SystemExit(
f"--parser takes '<module>:<class>', not {target!r}")
module = importlib.import_module(module_name)
parser: type = getattr(module, class_name)
return parser


Expand Down Expand Up @@ -504,8 +504,9 @@ def main(argv: Sequence[str] | None = None) -> None:
'Prints timings and counts only; writes nothing.')
cli.add_argument('probe_dir', help='the probe directory of one space')
cli.add_argument('--parser', required=True,
help="study folder in projects/ whose parser.py "
"reads the names, such as 'trans_foci_cub'")
help="the parser class that reads the names, as "
"'<module>:<class>', such as "
"'polyphys_lab.trans_foci_cub.parser:TransFociCub'")
cli.add_argument('--group', required=True, help="particle group, 'bug'")
cli.add_argument('--prop', required=True,
help="property in the file names, such as 'gyrTMon'")
Expand Down
8 changes: 8 additions & 0 deletions docs/source/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,14 @@ public; importing one now fails as for any name the module never
defined. The package's own tests and examples use made-up parsers in
`polyphys.tests.synthetic`.

**The companion repository.** On 2026-11-08 the maintainer decided that
PolyPhys stands alone: the package and its tests do not refer to the
studies. In 1.1.0 the `projects/` folder moved to the companion repository
[polyphys-lab](https://github.com/amirhs1/polyphys-lab) (amirhs1/PolyPhys#275), where each study is a
folder installed as `polyphys_lab.<study>`, with the tests that run its
specs on real frames. The lab depends on a released PolyPhys, never the
reverse.

[^adorf2018]: C. S. Adorf, P. M. Dodd, V. Ramasubramani, and S. C. Glotzer,
"Simple data and workflow management with the signac framework,"
*Comput. Mater. Sci.* **146**, 220–229 (2018),
Expand Down
Loading