diff --git a/.gitattributes b/.gitattributes
deleted file mode 100644
index 22bb492b..00000000
--- a/.gitattributes
+++ /dev/null
@@ -1 +0,0 @@
-gerrychain/_version.py export-subst
diff --git a/.github/workflows/docs-pr-check.yml b/.github/workflows/docs-pr-check.yml
deleted file mode 100644
index c4e9da32..00000000
--- a/.github/workflows/docs-pr-check.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-name: "Pull Request Docs Check"
-
-on:
- pull_request:
-
-jobs:
- docs:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
-
- - name: Set up Python
- uses: actions/setup-python@v5
- with:
- python-version: "3.11"
-
- - name: Set up uv
- uses: astral-sh/setup-uv@v4
-
- - name: Build docs
- run: make docs
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c86d2e8b..c24aea75 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,6 +1,7 @@
-name: "Publish Docs"
+name: "Docs"
on:
+ pull_request:
push:
branches:
- main
@@ -8,42 +9,25 @@ on:
jobs:
docs:
runs-on: ubuntu-latest
-
steps:
- - name: Checkout repository
- uses: actions/checkout@v4
+ - uses: actions/checkout@v4
- - name: Install uv
- run: |
- curl -LsSf https://astral.sh/uv/install.sh | sh
- echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+ # uv manages its own interpreter (UV_MANAGED_PYTHON=1 in the Makefile).
+ - name: Set up uv
+ uses: astral-sh/setup-uv@v4
- - name: Build documentation with Makefile
- env:
- PYTHON_VERSION: "3.11"
- run: |
- uv python install "$PYTHON_VERSION"
- make docs PYTHON_VERSION="$PYTHON_VERSION"
+ - name: Build docs (warnings are errors)
+ run: make docs
- - name: Clone gh-pages branch
- run: |
- git clone --branch gh-pages --single-branch \
- "https://github.com/${{ github.repository }}.git" gh-pages
- rm -rf gh-pages/*
- cp -r docs/_build/* gh-pages/
+ - name: Run documentation snippet tests
+ run: make docs-test
- - name: Commit documentation changes
- run: |
- cd gh-pages
- touch .nojekyll
- git config --local user.email "action@github.com"
- git config --local user.name "GitHub Action"
- git add .
- git commit -m "Update documentation" || echo "No changes to commit"
+ - name: Upload built site
+ uses: actions/upload-artifact@v4
+ with:
+ name: docs
+ path: docs/_build
- - name: Push changes
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- cd gh-pages
- git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" gh-pages
+ # ADD THIS BACK IN LATER -- SOME LINKS WILL NOT RESOLVE RIGHT NOW
+ # - name: Check external links
+ # run: make docs-linkcheck
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..a2a98e95
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,188 @@
+name: Release GerryChain
+
+on:
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: Release tag, for example v1.0.0
+ type: string
+ required: true
+ upload_to:
+ description: Upload destination
+ type: choice
+ required: true
+ default: testpypi
+ options: [testpypi, pypi]
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build and test distributions
+ runs-on: ubuntu-latest
+ outputs:
+ version: ${{ steps.release.outputs.version }}
+ steps:
+ - name: Check out release tag
+ uses: actions/checkout@v7
+ with:
+ ref: ${{ inputs.tag }}
+ fetch-depth: 0
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+ with:
+ version: "0.12.1"
+
+ - name: Install Python
+ run: uv python install 3.13
+
+ - name: Validate release tag
+ id: release
+ env:
+ RELEASE_TAG: ${{ inputs.tag }}
+ run: |
+ if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
+ echo "Dispatch this workflow from the main branch, not $GITHUB_REF_NAME."
+ exit 1
+ fi
+ project_version="$(uv version --short)"
+ if [[ "$RELEASE_TAG" != "v$project_version" ]]; then
+ echo "Tag $RELEASE_TAG does not match project version $project_version."
+ exit 1
+ fi
+ if ! git show-ref --verify --quiet "refs/tags/$RELEASE_TAG"; then
+ echo "$RELEASE_TAG is not a tag in this repository."
+ exit 1
+ fi
+ git fetch --no-tags origin main
+ if ! git merge-base --is-ancestor HEAD origin/main; then
+ echo "The tagged commit is not on the main branch."
+ exit 1
+ fi
+ echo "version=$project_version" >> "$GITHUB_OUTPUT"
+ echo "RELEASE_VERSION=$project_version" >> "$GITHUB_ENV"
+
+ - name: Run tests
+ run: uv run --locked pytest
+
+ - name: Build distributions
+ run: uv build
+
+ - name: Smoke test wheel
+ run: >-
+ uv run --isolated --no-project --with dist/*.whl python -c
+ 'import os; from importlib.metadata import version;
+ from gerrychain.examples import gerrymandria;
+ assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+ assert len(gerrymandria().nodes) == 64'
+
+ - name: Smoke test source distribution
+ run: >-
+ uv run --isolated --no-project --with dist/*.tar.gz python -c
+ 'import os; from importlib.metadata import version;
+ from gerrychain.examples import gerrymandria;
+ assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+ assert len(gerrymandria().nodes) == 64'
+
+ - name: Upload distributions
+ uses: actions/upload-artifact@v7
+ with:
+ name: distributions
+ path: dist/
+ if-no-files-found: error
+
+ testpypi:
+ name: Publish and verify on TestPyPI
+ needs: build
+ runs-on: ubuntu-latest
+ environment:
+ name: testpypi
+ url: https://test.pypi.org/project/gerrychain/
+ permissions:
+ contents: read
+ id-token: write
+ env:
+ RELEASE_VERSION: ${{ needs.build.outputs.version }}
+ steps:
+ - name: Install uv
+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+ with:
+ version: "0.12.1"
+
+ - name: Install Python
+ run: uv python install 3.13
+
+ - name: Download distributions
+ uses: actions/download-artifact@v8
+ with:
+ name: distributions
+ path: dist/
+
+ - name: Publish to TestPyPI
+ run: >-
+ uv publish --trusted-publishing always
+ --publish-url https://test.pypi.org/legacy/
+ --check-url https://test.pypi.org/simple/
+ dist/*
+
+ - name: Install dependencies from PyPI
+ run: |
+ uv venv --python 3.13 "$RUNNER_TEMP/testpypi-venv"
+ uv pip install --python "$RUNNER_TEMP/testpypi-venv/bin/python" dist/*.whl
+
+ - name: Install wheel from TestPyPI
+ run: |
+ for attempt in {1..10}; do
+ if uv pip install \
+ --python "$RUNNER_TEMP/testpypi-venv/bin/python" \
+ --reinstall-package gerrychain \
+ --no-deps \
+ --default-index https://test.pypi.org/simple/ \
+ "gerrychain==$RELEASE_VERSION"; then
+ exit 0
+ fi
+ if [[ "$attempt" == 10 ]]; then
+ echo "TestPyPI did not make gerrychain $RELEASE_VERSION available in time."
+ exit 1
+ fi
+ sleep 15
+ done
+
+ - name: Smoke test TestPyPI installation
+ run: >-
+ "$RUNNER_TEMP/testpypi-venv/bin/python" -c
+ 'import os; from importlib.metadata import version;
+ from gerrychain.examples import gerrymandria;
+ assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+ assert len(gerrymandria().nodes) == 64'
+
+ pypi:
+ name: Publish to PyPI
+ needs: [build, testpypi]
+ if: ${{ inputs.upload_to == 'pypi' }}
+ runs-on: ubuntu-latest
+ environment:
+ name: pypi
+ url: https://pypi.org/project/gerrychain/
+ permissions:
+ contents: read
+ id-token: write
+ steps:
+ - name: Install uv
+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+ with:
+ version: "0.12.1"
+
+ - name: Download distributions
+ uses: actions/download-artifact@v8
+ with:
+ name: distributions
+ path: dist/
+
+ - name: Publish to PyPI
+ run: >-
+ uv publish --trusted-publishing always
+ --check-url https://pypi.org/simple/
+ dist/*
diff --git a/.gitignore b/.gitignore
index b566efbf..dc18757f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,6 +59,7 @@ coverage.xml
# Sphinx documentation
docs/_build/
+docs/_generated/
_build
# PyBuilder
@@ -87,3 +88,15 @@ TODO.md
# Environment items
.env
.envrc
+
+# Profiling data
+*.prof
+docs/jupyter_execute/
+
+# Sample data copied next to a tutorial so it can be run interactively from docs/user/.
+# The committed copy lives in docs/_static/ and is staged automatically by
+# docs/_refresh_notebooks.py, so this local duplicate must never be committed.
+docs/user/PA_VTDs.json
+
+# Written by docs/user/data.ipynb when it runs; not a source file.
+docs/user/PA_output.jsonl
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index accbf12c..a8e30fc9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,13 @@
repos:
- repo: local
hooks:
+ - id: clear-notebook-outputs
+ name: Clear notebook outputs
+ entry: >-
+ uv run --no-default-groups --group docs-exec
+ python docs/_clear_notebook_outputs.py
+ language: system
+ files: ^docs/user/.*\.ipynb$
- id: make-format
name: Run `make check` (format + lint)
entry: make check
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..3524cc23
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,176 @@
+## [v1.0.0] - August 2026
+
+### Added
+
+#### Markov chains (module: chain)
+* Added ability to incrementally configure the chain.
+
+ You can explicitly set class attributes, such as: `chain.initial_partition = ...`.
+
+ Functions to add constraints and updaters:
+
+ * add_constraint()
+ * add_constraints()
+ * add_updater()
+ * add_updaters()
+
+ Function to check whether a chain is fully configured:
+
+ * check_valid()
+
+#### Graphs (module: graph)
+* Added methods to query and access the embedded NetworkX/RustworkX graph.
+
+ * is_nx_graph()
+ * is_rx_graph()
+ * get_nx_graph()
+ * get_rx_graph()
+
+* Added methods for converting between GerryChain, NetworkX, and RustworkX graphs, and to create an empty graph.
+
+ * from_networkx()
+ * from_rustworkx()
+ * from_null_networkx()
+ * to_networkx_graph()
+
+* Added methods to translate node_ids between NetworkX and RustworkX and between parent graphs and subgraphs - to deal with the differences between the way NetworkX and RustworkX implement node_ids.
+
+ * original_nx_node_id_for_internal_node_id()
+ * internal_node_id_for_original_nx_node_id()
+ * get_nx_to_rx_node_id_map()
+ * translate_subgraph_node_ids_for_set_of_nodes()
+ * original_nx_node_ids_for_list()
+ * original_nx_node_ids_for_set()
+ * translate_subgraph_node_ids_for_flips()
+
+* Added methods to handle the fact that in RustworkX, edges are different from edge_ids. In both NetworkX and RustworkX, an edge is a tuple of node_ids. In NetworkX, there is no difference between an edge and an edge_id, but in RustworkX an edge_id is an integer.
+
+ * get_edge_id_from_edge()
+ * get_edge_from_edge_id()
+
+#### Examples (module: examples)
+
+* Added `gerrymandria()`, which returns the fictional 8x8 grid graph used in the User Guide.
+
+#### Partitions (module: partition)
+
+* Added `Partition.assignment_vector()` and `Assignment.to_vector()`.
+
+#### Proposals (module: proposals)
+
+* Added new names for legacy functions. The new names adhere to the naming convention for creating proposal functions, "build_xxx_proposal_fn". Note that the legacy functions continue to exist.
+
+ * build_any_node_flip_proposal_fn() == propose_any_node_flip()
+ * build_random_flip_proposal_fn() == propose_random_flip()
+ * build_flip_every_district_proposal_fn() == propose_flip_every_district()
+ * build_chunk_flip_proposal_fn() == propose_chunk_flip()
+ * build_slow_reversible_proposal_fn() == slow_reversible_propose()
+ * build_slow_reversible_bi_proposal_fn() == slow_reversible_propose_bi()
+
+#### ReCom proposals (module: proposals)
+* Changed the ReCom class to be a namespace that defines the five variants of recom that were discussed in the article, "Spanning Tree Methods for Sampling Graph Partitions":
+
+ * A = cut_edges_mst()
+ * B = district_pairs_mst()
+ * C = cut_edges_ust()
+ * D = district_pairs_ust()
+ * R = reversible()
+
+* Added convenience functions to create recom proposal functions:
+
+ * build_recom_proposal_fn()
+ * build_reversible_recom_proposal_fn()
+
+#### Multi-member ReCom (module: proposals)
+
+* Added functions and the MultiMemberReCom class to support multi-member ReCom. These new functions and the MultiMemberReCom class mirror the routines and class for standard ReCom:
+
+ * multi_member_recom()
+ * build_multi_member_recom_proposal_fn()
+ * epsilon_tree_bipartition_multi_member()
+ * class MultiMemberReCom
+ * cut_edges_mst()
+ * district_pairs_mst()
+ * cut_edges_ust()
+ * district_pairs_ust()
+
+#### Constraints for multi-member ReCom (module: constraints)
+
+* Added a new constraint to support multi-member ReCom
+
+ * within_percent_of_ideal_population_per_member()
+
+### Changed
+
+#### Graphs
+
+* `gerrychain.Graph` no longer subclasses `networkx.Graph`. Node and edge data access has changed.
+ See the [v1.0 migration guide](docs/topics/v1p0p0_migration_guide.md).
+
+* Changed the way to access node and edge data
+
+ * To access node data, use: my_graph.node_data(...node_id...)
+ * To access edge data, use: my_graph.edge_data(...edge_id...)
+
+* GerryChain now uses independent random number generators configured through `rng=`. See the
+ [reproducibility guide](docs/topics/reproducibility.md).
+
+#### Renamed public parameters
+
+* Parameters accepting functions now generally have names that use the _fn suffix:
+
+ This is only an issue for function calls using named parameters.
+
+ An example of this is the renaming of "proposal" to "proposal_fn" in the constructor for a MarkovChain object:
+
+ Old:
+ ```
+ my_chain = MarkovChain(
+ proposal = my_proposal,
+ ...
+ )
+ ```
+ New:
+ ```
+ my_chain = MarkovChain(
+ proposal_fn = my_proposal,
+ ...
+ )
+ ```
+### Removed
+
+#### Removed the pre-1.0 NetworkX-derived Graph interface.
+
+* `gerrychain.Graph` is no longer a subclass of `networkx.Graph`. See the
+ [v1.0 migration guide](docs/topics/v1p0p0_migration_guide.md) for replacement graph operations.
+
+#### Removed the old instantiable and callable ReCom interface.
+
+* The old ReCom class was instantiable and callable. It has been replaced with a namespace that
+ defines functions that generate proposal functions. See
+ [The `ReCom` Namespace](docs/topics/v1p0p0_migration_guide.md#the-recom-namespace) for details.
+
+#### Other removals
+
+* `MarkovChain` is now an iterable rather than an iterator. Create an iterator with
+ `chain_iterator = iter(chain)`, then call `next(chain_iterator)` instead of `next(chain)`.
+
+* Removed `gerrychain.__version__`. Use `importlib.metadata.version("gerrychain")` to read the
+ installed package version.
+
+### Deprecated
+
+#### Pre-1.0 callback signatures
+
+* Legacy proposal, acceptance, spanning-tree, bipartition, balanced-edge-cut, cut-choice, and
+ initial-partition callbacks remain temporarily supported with warnings. This includes callbacks
+ that do not accept `rng=`.
+
+ For more details see the [reproducibility guide](docs/topics/reproducibility.md).
+
+#### Legacy parameter names
+
+* The legacy parameter names listed above remain temporarily supported with warnings.
+
+* `create_grid_graph()` remains available as a deprecated compatibility shim. There is no public
+ `create_grid_nx_graph()` function.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 783324ea..7f3f19bb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,88 +1,284 @@
# Contributing to GerryChain
-Thank you for your interest in contributing to GerryChain! If you decide to
-participate, use this document as a guide for how to go about it. These are not
-strict rules; break them when appropriate.
+Thanks for your interest in contributing to GerryChain! Contributions of all sizes are welcome,
+including bug reports, documentation improvements, tests, examples, and new features.
-## How can I contribute?
+If you are planning anything larger than a small bug fix or documentation change, please contact
+`code@mggg.org` before you start coding. The maintainers can help you align the work with the
+current roadmap and target branch.
-### Reporting bugs
+## Ways to contribute
-If you find a bug while using any tools in this repository, consider creating a
-[GitHub issue](https://github.com/mggg/GerryChain/issues) documenting the
-problem. Be sure to be detailed. Explain what you did, what you expected to
-happen, and what actually happened.
+- Report bugs or confusing behavior.
+- Improve or expand documentation and tutorials.
+- Add tests for uncovered behavior or regressions.
+- Fix bugs, performance problems, or edge cases.
+- Propose or implement new proposals, constraints, updaters, metrics, or graph features.
-### Updating documentation
+Please search the [issue tracker](https://github.com/mggg/GerryChain/issues) before opening a new
+issue. A useful bug report explains what you did, what you expected, what happened instead, and
+includes a minimal example when possible.
-If you find any documentation that is lacking or in error, submit a pull
-request that updates it. Be sure to follow the [documentation
-styleguide](#documentation-styleguide).
+## Development setup
-### Suggesting enhancements
+GerryChain uses:
-If you have ideas for additional features, consider creating a [GitHub
-issue](https://github.com/mggg/GerryChain/issues) documenting the desired
-feature. Be sure to be detailed. Explain what the tool currently does (or does
-not do), what you would like it to do, and how this benefits users.
+- [uv](https://docs.astral.sh/uv/) for Python and dependency management
+- Make for common development commands
+- [Ruff](https://docs.astral.sh/ruff/) for formatting and linting
+- [ty](https://github.com/astral-sh/ty) and
+ [Pyright](https://github.com/microsoft/pyright) for type checking
+- [pytest](https://docs.pytest.org/) for tests
+- [pre-commit](https://pre-commit.com/) for local quality checks
+- [Sphinx](https://www.sphinx-doc.org/) and [MyST](https://myst-parser.readthedocs.io/) for docs
-### Contributing code (pull requests)
+Recommended setup:
-The main way to contribute code to the project is via GitHub pull requests
-(PRs). To create a pull request, see the [GitHub
-docs](https://help.github.com/articles/creating-a-pull-request/). Be detailed
-in the description of your pull request. Explain what your proposed changes do,
-and reference any relevant issues.
+1. Install `uv`.
+2. Fork and clone the repository.
+3. From the repository root, run `make setup`.
-Be sure to follow the [style guides](#style-guides) for code and documentation.
+`make setup` installs a managed Python 3.11 environment, syncs every dependency group, and
+installs the pre-commit hooks.
-## Style Guides
+If you already have `uv` installed and prefer to run the steps directly, the equivalent setup is:
-### Git commit messages
+```bash
+uv python install 3.11
+UV_MANAGED_PYTHON=1 uv sync --python 3.11 --all-groups
+uv run pre-commit install
+```
-When writing git commit messages, use the following guidelines:
+## Contributor workflow
-- Use the present tense ("Update documentation", not "Updated documentation")
-- Use the imperative mood ("Fix import", not "Fixes import")
-- Limit first line to 72 characters
+1. Fork the repository and clone your fork locally.
+2. Create a descriptive branch from the current target branch.
+3. Keep the change focused. Do not bundle unrelated refactors into the same pull request.
+4. Add or update tests for behavior changes.
+5. Update public documentation when behavior or APIs change.
+6. Run the relevant checks locally.
+7. Open a pull request that explains the problem, your approach, and how you tested it.
-For further guidelines, see [this
-gist](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53).
+If you are unsure which branch to target, ask the maintainers before opening the pull request.
-### Python styleguide
+### Branch naming
-The recommended styleguide is
-[PEP8](https://www.python.org/dev/peps/pep-0008/), the Python standard. Using
-the source code linter [flake8](http://flake8.pycqa.org/en/latest/) will
-automatically scan your source code for compliance with PEP8.
+Use descriptive branch names such as:
-Below are some highlights of PEP8, but refer to the standard itself for full
-details.
+- `fix/recom-region-reselection`
+- `feat/add-compactness-updater`
+- `docs/update-contributing-guide`
-- Use 4 spaces per indentation level.
+## Running checks locally
-- Use spaces, not tabs.
+The preferred Make targets are:
-- Limit lines to 100 characters at maximum.
+```bash
+make format
+make lint
+make type-check
+make test
+make test-all
+make precommit
+```
-- Avoid extraneous whitespace, such as in the following situations:
+`make lint` runs Ruff and both type checkers, so a separate `make type-check` is only needed when
+you want to run the type checkers by themselves. `make test-all` includes tests marked as slow.
- - `f(x)`, not `f( x )`.
- - `array[x]`, not `array[ x ]`.
- - `if x == 1: print(x)`, not `if x == 1 : print(x)`.
+To run a specific test file through Make:
-- _Do_ use whitespace around arithmetic operators:
+```bash
+make test TEST_PATHS=tests/test_tree.py
+```
- - `2 + 2`, not `2+2`
- - `x / y`, not `x/y`.
+You can also pass pytest options directly:
-- Write comments as complete sentences with correct punctuation and grammar.
+```bash
+uv run pytest tests/test_tree.py -k bipartition
+uv run pytest tests --runslow
+uv run pytest tests --cov=gerrychain --cov-report=term-missing
+```
-- Write docstrings in
- [reStructuredText](http://docutils.sourceforge.net/rst.html) and in
- accordance with [PEP257](https://www.python.org/dev/peps/pep-0257/).
+Before opening a pull request, also verify that the lockfile is current:
- - Docstrings are scanned by
- [Sphinx](http://www.sphinx-doc.org/en/master/index.html) to autogenerate
- documentation on our [documentation
- site](http://gerrychain.readthedocs.io/en/latest/).
+```bash
+uv lock --check
+```
+
+## Pull request expectations
+
+Before opening a pull request, make sure that:
+
+- the change is scoped to a single topic;
+- code, tests, and docs are updated together when needed;
+- new behavior and regressions are covered by tests;
+- formatting, linting, and type checks pass locally;
+- slow tests relevant to the change pass; and
+- the description explains the user-facing impact and notable tradeoffs.
+
+Small, focused pull requests are much easier to review and merge than large mixed changes.
+
+## Code style guidelines
+
+GerryChain requires Python 3.11 or later. Follow the current conventions below and avoid
+style-only churn in files unrelated to your change.
+
+- Follow the repository tooling first. Ruff defines formatting and baseline lint rules.
+- Keep lines at or below 100 characters.
+- Add type annotations for function parameters and return values.
+- Prefer modern type syntax, such as `str | None` instead of `Optional[str]`.
+- Match the import style and structure of the surrounding module.
+- Use descriptive `snake_case` names for variables and functions, `PascalCase` for classes, and
+ `UPPER_SNAKE_CASE` for module-level constants.
+- Keep functions focused and put validation or obvious guard clauses near the top.
+- Prefer straightforward control flow and targeted helpers over unnecessary abstraction.
+- Preserve useful docstrings and comments when editing older code.
+- Use comments sparingly and reserve them for invariants, non-obvious reasoning, or domain context.
+
+### Docstrings
+
+Public classes, functions, and methods should use the repository's Google-style docstrings. Keep
+docstrings at or below 100 characters per line and document contracts, defaults, and failure modes.
+
+```python
+def population_deviation(population: int, ideal: int) -> float:
+ """Return a district's relative population deviation from the ideal.
+
+ Args:
+ population (int): District population.
+ ideal (int): Ideal district population.
+
+ Returns:
+ float: Relative deviation from the ideal population.
+
+ Raises:
+ ValueError: If the ideal population is not positive.
+ """
+ if ideal <= 0:
+ raise ValueError("ideal must be positive")
+ return (population - ideal) / ideal
+```
+
+Use `Args`, `Returns`, and `Raises` when they add information. Add examples when they clarify
+non-obvious behavior, not simply to repeat the signature.
+
+## Testing guidelines
+
+Tests are required for behavior changes.
+
+- Add tests under `tests/` near the existing tests for the same module or feature.
+- Cover successful behavior, expected failures, and natural edge cases.
+- When checking exceptions, verify useful error text with `pytest.raises(..., match=...)`.
+- Mark tests that take longer than about ten seconds with `@pytest.mark.slow`.
+- Pass an explicit seed or `random.Random` instance in tests involving randomness.
+- Do not rely on `PYTHONHASHSEED` or unordered container iteration for reproducibility.
+- When changing shared graph behavior, exercise both NetworkX and RustworkX backends when relevant.
+
+The test suite enables GerryChain's runtime integrity checks automatically. Production code should
+not assume that those optional checks are enabled.
+
+## Documentation guidelines
+
+If your change affects public behavior, update the relevant documentation with the code. This may
+include:
+
+- docstrings under `gerrychain/`;
+- narrative Markdown under `docs/`;
+- tutorial notebooks under `docs/user/`;
+- API reference pages under `docs/api/`; or
+- examples and links in `README.md`.
+
+### Notebook-first workflow
+
+Tutorial notebooks under `docs/user/` are the source of truth. Commit them without outputs so
+reviews contain only source changes. The pre-commit hook clears outputs and execution counts from
+changed notebooks automatically.
+
+The docs build reuses outputs when the notebook source matches the ignored MyST-NB cache under
+`docs/_build/`. New or changed notebooks execute in temporary directories with the example
+datasets staged. To populate that cache for one notebook without building the site, run:
+
+```bash
+make docs-cache-notebooks NOTEBOOKS=docs/user/recom.ipynb
+```
+
+Omit `NOTEBOOKS` to execute every tutorial:
+
+```bash
+make docs-cache-notebooks
+```
+
+### Building and previewing docs
+
+Build the complete site with warnings treated as errors:
+
+```bash
+make docs
+```
+
+The generated site is written to `docs/_build/`. To serve it locally with automatic rebuilding:
+
+```bash
+make docs-serve
+```
+
+To force notebook re-execution before a build or preview, set `FRESH=1`. This also works with
+`docs` and `docs-cache-notebooks`:
+
+```bash
+make docs-serve FRESH=1
+```
+
+### Testing docs
+
+Execute Python snippets from Markdown, RST, and `README.md`:
+
+```bash
+make docs-test
+```
+
+Blocks that cannot run independently must provide a reason:
+
+```md
+
+```
+
+Shared setup blocks use:
+
+```md
+
+```
+
+A page whose blocks are all illustrative fragments can opt out wholesale, with the marker placed
+just under the title:
+
+```md
+
+```
+
+Snippet failures report the original documentation filename and line number. The docs build fails
+if a notebook cannot execute, and the test suite rejects notebooks containing committed outputs.
+
+Check external links manually with:
+
+```bash
+make docs-linkcheck
+```
+
+Pull requests and pushes to `main` execute the notebooks, build the site, run snippet checks, and
+upload the built site as a workflow artifact. Read the Docs publishes the site. External link
+checking is temporarily manual while the reorganized pages are unpublished.
+
+Documentation dependencies are split into `docs` for building and serving the site and
+`docs-exec` for executing notebooks and snippets. The Make targets select the appropriate group.
+
+## Community guidelines
+
+This project follows the Contributor Covenant Code of Conduct. By participating, you agree to
+follow the expectations in the
+[Code of Conduct](https://github.com/mggg/GerryChain/blob/main/CODE_OF_CONDUCT.md).
+
+## Questions
+
+If anything in the contribution process is unclear, contact `code@mggg.org`. Thanks for helping
+make GerryChain better!
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 00000000..fc492939
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1 @@
+include CHANGELOG.md
diff --git a/Makefile b/Makefile
index 09fa33b3..172eb6c4 100644
--- a/Makefile
+++ b/Makefile
@@ -4,8 +4,16 @@ PYTHON_VERSION = 3.11
VENV_DIR ?= .venv
PKG ?= gerrychain
TEST_PATHS ?= tests
+TYPECHECK_PATHS ?= $(PKG) $(TEST_PATHS)
+DOCS_PY_PATHS ?= docs/conf.py docs/_clear_notebook_outputs.py \
+ docs/_refresh_notebooks.py docs/generate_recom_assets.py
+# Tutorial notebooks. Ruff formats the code cells; it ignores the Markdown files alongside them.
+NOTEBOOK_PATHS ?= docs/user
+DOCS_CACHE_FLAGS = $(if $(filter 1,$(FRESH)),--force)
+export UV_MANAGED_PYTHON = 1
-.PHONY: help setup install install-docs test lint format precommit docs clean
+.PHONY: help check_prereq setup install install-docs check test test-all type-check format lint \
+ precommit docs docs-serve docs-test docs-linkcheck docs-cache-notebooks docs-recom-assets clean
help:
@echo "Available targets:"
@@ -13,10 +21,18 @@ help:
@echo " install - Install the package"
@echo " install-docs - Install documentation dependencies"
@echo " test - Run the test suite"
- @echo " lint - Run code linters"
+ @echo " test-all - Run the test suite including slow tests"
+ @echo " lint - Run Ruff and both type checkers"
+ @echo " type-check - Run ty, then Pyright"
@echo " format - Format the codebase"
@echo " precommit - Run pre-commit hooks"
- @echo " docs - Build the documentation"
+ @echo " docs - Build the documentation (warnings are errors)"
+ @echo " docs-serve - Serve the documentation locally with live reload"
+ @echo " docs-test - Execute the Python code blocks in the documentation"
+ @echo " docs-linkcheck - Check external links in the documentation"
+ @echo " docs-cache-notebooks - Execute user-guide notebooks into the ignored docs cache"
+ @echo " Set FRESH=1 with a docs target to rebuild notebook outputs"
+ @echo " docs-recom-assets - Regenerate the static Gerrymandria images used by recom.ipynb"
@echo " clean - Clean build artifacts"
@@ -34,9 +50,7 @@ setup: check_prereq
@echo
uv python install $(PYTHON_VERSION)
@echo "Creating virtual environment and installing dev dependencies..."
- uv sync --python $(PYTHON_VERSION)
- uv sync --all-groups
- uv pip install -e .
+ uv sync --python $(PYTHON_VERSION) --all-groups
uv run pre-commit install
@echo ""
@echo "Development environment setup complete!"
@@ -44,13 +58,10 @@ setup: check_prereq
install: check_prereq
@echo "Installing GerryChain package..."
uv sync --python $(PYTHON_VERSION)
- uv pip install -e .
install-docs: check_prereq
- @echo "Installing GerryChain package with all just the documentation dependencies..."
- uv sync --python $(PYTHON_VERSION)
- uv sync --group docs
- uv pip install -e .
+ @echo "Installing documentation and notebook execution dependencies..."
+ uv sync --python $(PYTHON_VERSION) --no-default-groups --group docs --group docs-exec
check:
$(MAKE) format
@@ -58,29 +69,62 @@ check:
test:
@echo "Running test suite..."
- PYTHONHASHSEED=0 uv run pytest -v $(TEST_PATHS)
+ uv run pytest -v $(TEST_PATHS)
+
+test-all:
+ @echo "Running test suite (including slow tests)..."
+ uv run pytest -v --runslow $(TEST_PATHS)
-# Add this in later
-# type-check:
-# @echo "Running type checking with mypy..."
-# uv run mypy $(PKG) ${TEST_PATHS}
+type-check:
+ @echo "Running fast type checking with ty..."
+ uv run --group dev ty check $(TYPECHECK_PATHS)
+ @echo "Running thorough type checking with Pyright..."
+ uv run --group dev pyright $(TYPECHECK_PATHS)
format:
- @echo "Formatting codebase with black..."
- uv run isort $(PKG) $(TEST_PATHS)
- uv run black $(PKG) $(TEST_PATHS)
+ @echo "Formatting codebase with Ruff..."
+ uv run ruff format $(PKG) $(TEST_PATHS) $(DOCS_PY_PATHS) $(NOTEBOOK_PATHS)
-lint:
- @echo "Running linters (ruff)..."
- uv run ruff check $(PKG) $(TEST_PATHS)
+lint:
+ @echo "Running Ruff..."
+ uv run ruff check $(PKG) $(TEST_PATHS) $(DOCS_PY_PATHS)
+ $(MAKE) type-check
precommit:
@echo "Running pre-commit hooks..."
uv run pre-commit run --all-files
-docs: install-docs
+docs: docs-cache-notebooks
@echo "Building documentation..."
- uv run sphinx-build -b dirhtml docs/ docs/_build
+ uv run --no-default-groups --group docs --group docs-exec sphinx-build -E -a -W --keep-going \
+ -b dirhtml docs/ docs/_build
+
+docs-serve: docs-cache-notebooks
+ @echo "Serving documentation with live reload..."
+ uv run --no-default-groups --group docs --group docs-exec \
+ sphinx-autobuild -b dirhtml docs/ docs/_build
+
+docs-linkcheck: docs-cache-notebooks
+ @echo "Checking documentation links..."
+ uv run --no-default-groups --group docs --group docs-exec \
+ sphinx-build -E -a -W --keep-going \
+ -b linkcheck docs/ docs/_build/linkcheck
+
+# Selects the docs-exec group explicitly so it does not rely on uv's implicit dev group.
+docs-test:
+ @echo "Executing documentation code snippets..."
+ uv run --no-default-groups --group docs --group docs-exec pytest -v --rundocs \
+ tests/test_docs_snippets.py
+
+docs-cache-notebooks: install-docs
+ @echo "Caching user-guide notebook outputs..."
+ uv run --no-default-groups --group docs --group docs-exec \
+ python docs/_refresh_notebooks.py $(DOCS_CACHE_FLAGS) $(NOTEBOOKS)
+
+docs-recom-assets: install-docs
+ @echo "Regenerating static Gerrymandria images..."
+ uv run --no-default-groups --group docs --group docs-exec \
+ python docs/generate_recom_assets.py
clean:
@echo "Cleaning build artifacts..."
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..b920f3a7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,165 @@
+# GerryChain
+
+[![Code Coverage][coverage-badge]][coverage]
+[![Documentation Status][docs-badge]][docs]
+[![PyPI Package][pypi-badge]][pypi]
+
+GerryChain is a Python library for building ensembles of districting plans using [Markov chain Monte
+Carlo](https://en.wikipedia.org/wiki/Markov_chain_Monte_Carlo). It is developed and maintained by
+the [Metric Geometry and Gerrymandering Group](https://www.mggg.org/) and our network of volunteers.
+It is distributed under the [3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).
+
+The basic workflow is to start with the geometry of an initial plan and generate a large collection
+of sample plans for comparison. Usually, we will constrain these sampled plans in such a way that
+they perform at least as well as the initial plan according to traditional districting principles,
+such as population balance or compactness. Comparing the initial plan to the ensemble provides
+quantitative tools for measuring whether or not it is an outlier among the sampled plans.
+
+## Getting started
+
+See our [Getting started guide](https://gerrychain.readthedocs.io/en/latest/user/quickstart/) for
+the basics of using GerryChain.
+
+We also highly recommend the resources prepared by Daryl R. DeFord of MGGG for the 2019 MIT IAP
+course [Computational Approaches for Political
+Redistricting](https://people.csail.mit.edu/ddeford//CAPR.php).
+
+## Useful links
+
+- [Documentation](https://gerrychain.readthedocs.io/en/latest/)
+- [Bug reports and feature requests](https://github.com/mggg/gerrychain/issues)
+- [Contributions welcome!](https://github.com/mggg/gerrychain/pulls)
+
+## Installation
+
+### Supported Python Versions
+
+The current version of GerryChain requires Python 3.11 or newer.
+
+If you do not have one of these versions installed on you machine, we recommend that you go to the
+[Python website](https://www.python.org/downloads/) and download the installer for one of these
+versions.[^1]
+
+#### A Note for Windows Users
+
+> If you are using Windows and are new to Python, we recommend that you still install Python using
+> the installation package available on the Python website. There are several versions of Python
+> available on the Windows Store, but they can be... finicky, and experience seems to suggest that
+> downloadable available on the Python website produce better results.
+>
+> In addition, we recommend that you install the [Windows
+> Terminal](https://apps.microsoft.com/detail/9n0dx20hk701) from the Microsoft Store. It is still
+> possible to use PowerShell or the Command Prompt, but Windows Terminal tends to be more beginner
+> friendly and allows for a greater range of utility than the natively installed terminal options
+> (for example, it allows for you to install the more recent version of PowerShell, [PowerShell
+> 7](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell), and for
+> the use of the Linux Subsystem for Windows).
+
+### Setting Up a Virtual Environment
+
+Once Python is installed on your system, you will want to open the terminal and navigate to the
+working directory of your project. Here are some brief instructions for doing so on different
+systems:
+
+- **MacOS**: To open the terminal, you will likely want to use the Spotlight Search (the magnifying
+ glass in the top right corner of your screen) to find the "Terminal" application (you can also
+ access Spotlight Search by pressing "Command (⌘) + Space"). Once you have the terminal open, type
+ `cd` followed by the path to your working directory. For example, if you are working on a project
+ called `my_project` in your `Documents` folder, you may access by typing the command
+
+ ```console
+ cd ~/Documents/my_project
+ ```
+
+ into the terminal (here the `~` is a shortcut for your home directory). If you do not know what
+ your working directory is, you can find it by navigating to the desired folder in your file
+ explorer, and clicking on "Get Info". The path will be labeled "Where" and from there you can copy
+ the path to your clipboard and paste it in the terminal.
+
+- **Linux**: Most Linux distributions have the keyboard shortcut `Ctrl + Alt + T` set to open the
+ terminal. From there you may navigate to your working directory by typing `cd` followed by the
+ path to your working directory. For example, if you are working on a project called `my_project`
+ in your `Documents` folder, you may access this via the command
+
+ ```console
+ cd ~/Documents/my_project
+ ```
+
+ (here the `~` is a shortcut for your home directory). If you do not know what your working
+ directory is, you can find it by navigating to the desired folder in your file explorer, and
+ clicking on "Properties". The path will be labeled "Location" and from there you can copy the path
+ to your clipboard and paste it in the terminal (to paste in the terminal in Linux, you will need
+ to use the keyboard shortcut `Ctrl + Shift + V` instead of `Ctrl + V`).
+
+- **Windows**: Open the Windows Terminal and type `cd` followed by the path to your working
+ directory. For example, if you are working on a project called `my_project` in your `Documents`
+ folder, you may access this by typing the command
+
+ ```console
+ cd ~\Documents\my_project
+ ```
+
+ into the terminal (here the `~` is a shortcut for your home directory). If you do not know what
+ your working directory is, you can find it by navigating to the desired folder in your file
+ explorer, and clicking on "Properties". The path will be labeled "Location" and from there you can
+ copy the path to your clipboard and paste it in the terminal.
+
+Once you have navigated to your working directory, you will want to set up a virtual environment.
+This is a way of isolating the Python packages you install for this project from the packages you
+have installed globally on your system. This is useful because it allows you to install different
+versions of packages for different projects without worrying about compatibility issues. To set up a
+virtual environment, type the following command into the terminal:
+
+```console
+python -m venv .venv
+```
+
+This will create a virtual environment in your working directory which you can see if you list all
+the files in your working directory via the command `ls -a` (`dir` on Windows). Now we need to
+activate the virtual environment. To do this, type the following command into the terminal:
+
+- **Windows**: `.venv\Scripts\activate`
+- **MacOS/Linux**: `source .venv/bin/activate`
+
+You should now see `(.venv)` at the beginning of your terminal prompt now. This indicates that you
+are in the virtual environment, and are now ready to install GerryChain.
+
+To install GerryChain from [PyPI](https://pypi.org/), run `pip install gerrychain` from the command
+line.
+
+GerryChain's GIS functions, such as computing adjacencies or reading in shapefiles, work out of the
+box: `geopandas` and `shapely` are installed alongside GerryChain, so there is no separate `[geo]`
+extra to install.
+
+> **Note**
+> If you plan on following through the tutorials present within the remainder of this documentation,
+> you will also need to install `matplotlib` from [PyPI](https://pypi.org/). This can also be
+> accomplished with a simple invocation of `pip install matplotlib` from the command line.
+
+### Making a Run Reproducible
+
+Each `MarkovChain` owns an independent random number generator, so making a run reproducible takes
+one line: pass an integer seed or `random.Random` instance with `MarkovChain(..., rng=2024)`. Random
+initial assignments and standalone tree operations accept the same `rng` keyword.
+
+Note that `random.seed` from the standard library does **not** affect GerryChain, and that chain
+trajectories do not depend on the `PYTHONHASHSEED` environment variable (older versions of
+GerryChain required pinning it, but that is no longer necessary).
+
+> **A note on Jupyter**
+>
+> If you are using a Jupyter notebook, install `ipykernel` in your virtual environment along with
+> either `jupyter notebook` or `jupyterlab`. Then run `jupyter notebook` or `jupyter lab` from your
+> working directory while the virtual environment is active. This opens Jupyter in your default
+> browser.
+
+[^1]: Of course, if you are using a Linux system, you will either need to use your system's package
+ manager or install from source. You may also find luck installing Python directly from the
+ package manager if you find installing from source to be troublesome.
+
+[coverage-badge]: https://codecov.io/gh/mggg/GerryChain/branch/main/graph/badge.svg
+[coverage]: https://codecov.io/gh/mggg/GerryChain
+[docs-badge]: https://readthedocs.org/projects/gerrychain/badge/?version=latest
+[docs]: https://gerrychain.readthedocs.io/en/latest
+[pypi-badge]: https://badge.fury.io/py/gerrychain.svg
+[pypi]: https://pypi.org/project/gerrychain/
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 7feb0258..00000000
--- a/README.rst
+++ /dev/null
@@ -1,314 +0,0 @@
-==========
-GerryChain
-==========
-
-.. image:: https://circleci.com/gh/mggg/GerryChain.svg?style=svg
- :target: https://circleci.com/gh/mggg/GerryChain
- :alt: Build Status
-.. image:: https://codecov.io/gh/mggg/GerryChain/branch/master/graph/badge.svg
- :target: https://codecov.io/gh/mggg/GerryChain
- :alt: Code Coverage
-.. image:: https://readthedocs.org/projects/gerrychain/badge/?version=latest
- :target: https://gerrychain.readthedocs.io/en/latest
- :alt: Documentation Status
-.. image:: https://badge.fury.io/py/gerrychain.svg
- :target: https://pypi.org/project/gerrychain/
- :alt: PyPI Package
-
-GerryChain is a Python library for building ensembles of districting plans
-using `Markov chain Monte Carlo`_. It is developed and maintained by the
-`Metric Geometry and Gerrymandering Group`_ and our network of volunteers.
-It is distributed under the `3-Clause BSD License`_.
-
-The basic workflow is to start with the geometry of an initial plan and
-generate a large collection of sample plans for comparison. Usually, we
-will constrain these sampled plans in such a way that they perform at
-least as well as the initial plan according to traditional districting
-principles, such as population balance or compactness. Comparing the
-initial plan to the ensemble provides quantitative tools for measuring
-whether or not it is an outlier among the sampled plans.
-
-.. _`Voting Rights Data Institute`: http://gerrydata.org/
-.. _chain: https://github.com/gerrymandr/cfp_mcmc
-.. _`Markov chain Monte Carlo`: https://en.wikipedia.org/wiki/Markov_chain_Monte_Carlo
-.. _`Metric Geometry and Gerrymandering Group`: https://www.mggg.org/
-.. _`3-Clause BSD License`: https://opensource.org/licenses/BSD-3-Clause
-
-
-Getting started
-===============
-
-See our `Getting started guide`_ for the basics of using GerryChain.
-
-.. _`Getting started guide`: https://gerrychain.readthedocs.io/en/latest/user/quickstart/
-
-We also highly recommend the resources prepared by Daryl R. DeFord of MGGG
-for the 2019 MIT IAP course `Computational Approaches for Political Redistricting`_.
-
-.. _`Computational Approaches for Political Redistricting`: https://people.csail.mit.edu/ddeford//CAPR.php
-
-
-Useful links
-============
-
-- `Documentation`_
-- `Bug reports and feature requests`_
-- `Contributions welcome!`_
-
-.. _`Documentation`: https://gerrychain.readthedocs.io/en/latest/
-.. _`Bug reports and feature requests`: https://github.com/mggg/gerrychain/issues
-.. _`Contributions welcome!`: https://github.com/mggg/gerrychain/pulls
-
-
-Installation
-============
-
-Supported Python Versions
--------------------------
-
-The most recent version of GerryChain (as of April 2024) supports
-
-- Python 3.9
-- Python 3.10
-- Python 3.11
-
-If you do not have one of these versions installed on you machine, we
-recommend that you go to the
-`Python website `_ and
-download the installer for one of these versions. [1]_
-
-A Note for Windows Users
-++++++++++++++++++++++++
-
- If you are using Windows and are new to Python, we recommend that you
- still install Python using the installation package available on
- the Python website. There are several versions of Python available
- on the Windows Store, but they can be... finicky, and experience seems
- to suggest that downloadable available on the Python website produce
- better results.
-
- In addition, we recommend that you install the
- `Windows Terminal `_
- from the Microsoft Store. It is still possible to use PowerShell or
- the Command Prompt, but Windows Terminal tends to be more beginner
- friendly and allows for a greater range of utility than the natively
- installed terminal options (for example, it allows for you to install
- the more recent version of PowerShell,
- `PowerShell 7 `_,
- and for the use of the Linux Subsystem for Windows).
-
-
-Setting Up a Virtual Environment
---------------------------------
-
-Once Python is installed on your system, you will want to open the terminal
-and navigate to the working directory of your project. Here are some brief
-instructions for doing so on different systems:
-
-- **MacOS**: To open the terminal, you will likely want to use the
- Spotlight Search (the magnifying glass in the top right corner of
- your screen) to find the "Terminal" application (you can also access
- Spotlight Search by pressing "Command (⌘) + Space"). Once you have
- the terminal open, type ``cd`` followed by the path to your working
- directory. For example, if you are working on a project called
- ``my_project`` in your ``Documents`` folder, you may access by typing
- the command
-
- .. code-block:: console
-
- cd ~/Documents/my_project
-
- into the terminal (here the ``~`` is a shortcut for your home directory).
- If you do not know what your working directory is, you can find it by
- navigating to the desired folder in your file explorer, and clicking
- on "Get Info". The path will be labeled "Where" and from there you
- can copy the path to your clipboard and paste it in the terminal.
-
-
-- **Linux**: Most Linux distributions have the keyboard shortcut
- ``Ctrl + Alt + T`` set to open the terminal. From there you may navigate
- to your working directory by typing ``cd`` followed by the path to your
- working directory. For example, if you are working on a project called
- ``my_project`` in your ``Documents`` folder, you may access this via
- the command
-
- .. code-block:: console
-
- cd ~/Documents/my_project
-
- (here the ``~`` is a shortcut for your home directory). If you do not
- know what your working directory is, you can find it by navigating to
- the desired folder in your file explorer, and clicking on "Properties".
- The path will be labeled "Location" and from there you can copy the path
- to your clipboard and paste it in the terminal (to paste in the terminal
- in Linux, you will need to use the keyboard shortcut ``Ctrl + Shift + V``
- instead of ``Ctrl + V``).
-
-- **Windows**: Open the Windows Terminal and type ``cd`` followed by the
- path to your working directory. For example, if you are working on a
- project called ``my_project`` in your ``Documents`` folder, you may
- access this by typing the command
-
- .. code-block:: console
-
- cd ~\Documents\my_project
-
- into the terminal (here the ``~`` is a shortcut for your home directory).
- If you do not know what your working directory is,
- you can find it by navigating to the desired folder in your file
- explorer, and clicking on "Properties". The path will be labeled
- "Location" and from there you can copy the path to your clipboard
- and paste it in the terminal.
-
-
-Once you have navigated to your working directory, you will want to
-set up a virtual environment. This is a way of isolating the Python
-packages you install for this project from the packages you have
-installed globally on your system. This is useful because it allows
-you to install different versions of packages for different projects
-without worrying about compatibility issues. To set up a virtual
-environment, type the following command into the terminal:
-
-.. code-block:: console
-
- python -m venv .venv
-
-This will create a virtual environment in your working directory which
-you can see if you list all the files in your working directory via
-the command ``ls -a`` (``dir`` on Windows). Now we need to activate the
-virtual environment. To do this, type the following command into the
-terminal:
-
-- **Windows**: ``.venv\Scripts\activate``
-- **MacOS/Linux**: ``source .venv/bin/activate``
-
-You should now see ``(.venv)`` at the beginning of your terminal prompt
-now. This indicates that you are in the virtual environment, and are now
-ready to install GerryChain.
-
-To install GerryChain from PyPI_, run ``pip install gerrychain`` from
-the command line.
-
-If you plan on using GerryChain's GIS functions, such as computing
-adjacencies or reading in shapefiles, then run
-``pip install gerrychain[geo]`` from the command line.
-
-This approach sometimes fails due to compatibility issues between our
-different Python GIS dependencies, like ``geopandas``, ``pyproj``,
-``fiona``, and ``shapely``. If you run into this issue, try installing
-the dependencies using the `geo_settings.txt `_
-file. To do this, run ``pip install -r geo_settings.txt`` from the
-command line.
-
-.. note::
-
- If you plan on following through the tutorials present within the
- remainder of this documentation, you will also need to install
- ``matplotlib`` from PyPI_. This can also be accomplished with
- a simple invocation of ``pip install matplotlib`` from the command
- line.
-
-.. _PyPI: https://pypi.org/
-.. [1] Of course, if you are using a Linux system, you will either need to use your
- system's package manager or install from source. You may also find luck installing
- Python directly from the package manager if you find installing from source to be
- troublesome.
-
-Making an Environment Reproducible
-----------------------------------
-
-If you are working on a project wherein you would like to ensure
-particular runs are reproducible, it is necessary to invoke
-
-- **MacOS/Linux**: ``export PYTHONHASHSEED=0``
-- **Windows**:
-
- - PowerShell ``$env:PYTHONHASHSEED=0``
- - Command Prompt ``set PYTHONHASHSEED=0``
-
-before running your code. This will ensure that the hash seed is deterministic
-which is important for the replication of spanning trees across your runs. If you
-would prefer to not have to do this every time, then you need to modify the
-activation script for the virtual environment. Again, this is different depending
-on your operating system:
-
-- **MacOS/Linux**: Open the file ``.venv/bin/activate`` located in your working
- directory using your favorite text editor
- and add the line ``export PYTHONHASHSEED=0`` after the ``export PATH`` command.
- So you should see something like::
-
- _OLD_VIRTUAL_PATH="$PATH"
- PATH="$VIRTUAL_ENV/Scripts:$PATH"
- export PATH
-
- export PYTHONHASHSEED=0
-
- Then, verify that the hash seed is set to 0 in your Python environment by
- running ``python`` from the command line and typing
- ``import os; print(os.environ['PYTHONHASHSEED'])``.
-
-- **Windows**: To be safe, you will need to modify 3 files within your virtual
- environment:
-
- - ``.venv\Scripts\activate``: Add the line ``export PYTHONHASHSEED=0`` after
- the ``export PATH`` command. So you should see something like::
-
- _OLD_VIRTUAL_PATH="$PATH"
- PATH="$VIRTUAL_ENV/Scripts:$PATH"
- export PATH
-
- export PYTHONHASHSEED=0
-
- - ``.venv\Scripts\activate.bat``: Add the line ``set PYTHONHASHSEED=0`` to the
- end of the file. So you should see something like::
-
- if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH%
- if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH%
-
- set PATH=%VIRTUAL_ENV%\Scripts;%PATH%
- rem set VIRTUAL_ENV_PROMPT=(.venv)
- set PYTHONHASHSEED=0
-
- - ``.venv\Scripts\Activate.ps1``: Add the line ``$env:PYTHONHASHSEED=0`` to the
- end of the before the signature block. So you should see something like::
-
- # Add the venv to the PATH
- Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH
- $Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH"
-
- $env:PYTHONHASHSEED=0
-
- # SIG # Begin signature block
-
-After you have made these changes, verify that the hash seed is set to 0 in your
-Python environment by running ``python`` from the command line and typing
-``import os; print(os.environ['PYTHONHASHSEED'])`` in the Python prompt.
-
-.. admonition:: A Note on Jupyter
- :class: note
-
- If you are using a jupyter notebook, you will need to make sure that you have
- installed the ``ipykernel`` package in your virtual environment as well as
- either ``jypyternotebook`` or ``jupyterlab``. To install these packages, run
- ``pip install `` from the command line. Then, to use the virtual
- python environment in your jupyter notebook, you need to invoke
-
- .. code-block:: console
-
- jupyter notebook
-
- or
-
- .. code-block:: console
-
- jupyter lab
-
- from the command line of your working directory *while your virtual environment
- is activated*. This will open a jupyter notebook in your default browser. You may
- then check that the hash seed is set to 0 by running the following code in a cell
- of your notebook:
-
- .. code-block:: python
-
- import os
- print(os.environ['PYTHONHASHSEED'])
diff --git a/benchmarks/benchmark_recom.py b/benchmarks/benchmark_recom.py
new file mode 100644
index 00000000..d98674d8
--- /dev/null
+++ b/benchmarks/benchmark_recom.py
@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+"""Benchmark GerryChain ReCom throughput, optionally comparing versions.
+
+Subcommands:
+
+ run Run the benchmark in the *current* environment and report ms/step.
+ This is also the worker that `compare` invokes under the hood.
+
+ compare Run the benchmark against one or more targets, each in an isolated
+ environment (via `uv`), and print a comparison table. Targets:
+
+ local this checkout's dev environment (working tree,
+ including uncommitted changes)
+ pypi: a released version, e.g. pypi:0.3.2
+ git:[ any commit/branch/tag of this repo, e.g.
+ git:main, git:3f2e9e9, git:v0.3.1. Uses the
+ *committed* state of the ref - the working tree
+ is not consulted.
+
+Each benchmark runs the chain once per seed: `--num-seeds` consecutive seeds
+starting at `--seed`, times `--repeats`, with up to `--jobs` seeds running in
+parallel (the chain itself is single-threaded, so parallel seeds on a
+many-core machine contend only mildly). Results are aggregated as
+min / median / max ms-per-step over all runs; `compare` computes the speedup
+column from the medians.
+
+Examples:
+
+ # Quick timing of the working tree (5 seeds, 5 parallel jobs by default):
+ uv run python benchmarks/benchmark_recom.py run --steps 250
+
+ # Working tree vs. the commit you branched from vs. the last release:
+ uv run python benchmarks/benchmark_recom.py compare local git:main pypi:0.3.2
+
+ # Did my last commit help? (committed HEAD vs. its parent)
+ uv run python benchmarks/benchmark_recom.py compare git:HEAD git:HEAD~1 --steps 500
+
+ # Watch a single run with a progress bar:
+ uv run python benchmarks/benchmark_recom.py run --num-seeds 1 --progress
+
+ # Profile the working tree to find hotspots (forces sequential execution and
+ # inflates timings; don't use the ms/step from a profiled run for comparisons):
+ uv run python benchmarks/benchmark_recom.py run --num-seeds 1 --steps 250 --profile
+
+The first target listed is the baseline for the speedup column. Isolated targets are resolved with
+`uv run --no-project`, executed from a temp directory so the repo's `gerrychain/` package directory
+cannot shadow the installed version. All targets must support the high-level API used here
+(`Graph.from_json`, `Partition.from_random_assignment`, `recom`, `MarkovChain`, `updaters.Tally`),
+which is stable from 0.3.x onward.
+
+Note on RNG: by default a fresh base seed is drawn each invocation and printed; pass --seed to pin
+it. Within a `compare`, every target gets the same seeds either way - though different gerrychain
+versions consume the RNG streams differently, so they will not walk the same chains. This measures
+throughput, not output equivalence. GerryChain owns its RNGs, so a pinned seed is reproducible
+without also pinning Python's hash seed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+TOP_DIR = SCRIPT_DIR.parent
+RESULT_MARKER = "@@RESULT "
+DEFAULT_GRAPH = SCRIPT_DIR / "graphs" / "hard_graph.json"
+MAX_NUMPY_SEED = 2**32 - 1
+
+
+def positive_int(value: str) -> int:
+ parsed = int(value)
+ if parsed <= 0:
+ raise argparse.ArgumentTypeError("must be a positive integer")
+ return parsed
+
+
+def numpy_seed(value: str) -> int:
+ parsed = int(value)
+ if not 0 <= parsed <= MAX_NUMPY_SEED:
+ raise argparse.ArgumentTypeError(f"must be between 0 and {MAX_NUMPY_SEED}")
+ return parsed
+
+
+# --------------------------------------------------------------------------
+# worker: run the benchmark in whatever environment we were launched into
+# --------------------------------------------------------------------------
+
+# (graph, args, progress) for _run_one_seed. Forked pool workers inherit it from the
+# parent; spawned pool workers (Windows/macOS default) build it via _init_pool_worker.
+_WORKER_STATE: tuple | None = None
+
+
+def _init_pool_worker(args: argparse.Namespace) -> None:
+ """Build _WORKER_STATE in a spawned pool worker, which inherits nothing from the
+ parent and so must load the graph itself."""
+ global _WORKER_STATE
+
+ from gerrychain import Graph
+
+ _WORKER_STATE = (Graph.from_json(args.graph), args, False)
+
+
+def _run_one_seed(seed: int) -> dict:
+ """Run the chain for one seed. Must stay module-level so forked pool
+ workers can call it; reads the graph from _WORKER_STATE."""
+ import random
+ from functools import partial
+
+ import numpy as np
+
+ from gerrychain import MarkovChain, Partition, accept, updaters
+ from gerrychain.proposals import recom
+
+ graph, args, progress = _WORKER_STATE
+
+ profiler = None
+ if args.profile:
+ import cProfile
+
+ profiler = cProfile.Profile()
+
+ build_s: list[float] = []
+ times_s: list[float] = []
+ for _ in range(args.repeats):
+ random.seed(seed)
+ np.random.seed(seed)
+ rng = random.Random(seed)
+
+ t0 = time.perf_counter()
+ initial_kwargs = {
+ "graph": graph,
+ "n_parts": args.parts,
+ "epsilon": args.epsilon,
+ "pop_col": args.pop_col,
+ "updaters": {"population": updaters.Tally(args.pop_col, alias="population")},
+ }
+ if "rng" in inspect.signature(Partition.from_random_assignment).parameters:
+ initial_kwargs["rng"] = rng
+ initial = Partition.from_random_assignment(**initial_kwargs)
+ build_s.append(time.perf_counter() - t0)
+
+ ideal = sum(initial["population"].values()) / len(initial)
+ proposal_fn = partial(
+ recom,
+ pop_col=args.pop_col,
+ pop_target=ideal,
+ epsilon=args.epsilon,
+ node_repeats=0,
+ )
+ chain_params = inspect.signature(MarkovChain).parameters
+ # Older gerrychain versions call these proposal, accept, and initial_state.
+ chain_kwargs = {
+ ("proposal_fn" if "proposal_fn" in chain_params else "proposal"): proposal_fn,
+ "constraints": [],
+ ("acceptance_fn" if "acceptance_fn" in chain_params else "accept"): (
+ accept.always_accept
+ ),
+ ("initial_partition" if "initial_partition" in chain_params else "initial_state"): (
+ initial
+ ),
+ "total_steps": args.steps,
+ }
+ if "rng" in chain_params:
+ chain_kwargs["rng"] = rng
+ chain = MarkovChain(**chain_kwargs)
+ steps_iter = chain.with_progress_bar() if progress else chain
+
+ if profiler is not None:
+ profiler.enable()
+ t0 = time.perf_counter()
+ for _ in steps_iter:
+ pass
+ elapsed = time.perf_counter() - t0
+ if profiler is not None:
+ profiler.disable()
+ times_s.append(elapsed)
+
+ result = {"seed": seed, "build_s": build_s, "times_s": times_s}
+ if profiler is not None:
+ out = Path(args.out)
+ if args.num_seeds > 1:
+ out = out.with_name(f"{out.stem}_seed{seed}{out.suffix}")
+ profiler.dump_stats(str(out))
+ result["profile_out"] = str(out)
+ return result
+
+
+def _print_seed_result(result: dict, steps: int) -> None:
+ build = sum(result["build_s"]) / len(result["build_s"])
+ per_repeat = ", ".join(f"{t / steps * 1000:.3f}" for t in result["times_s"])
+ print(
+ f"seed {result['seed']}: initial partition {build:.2f}s, ms/step per repeat: {per_repeat}",
+ flush=True,
+ )
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+ # Defer imports because this environment is set by the orchestrator and may be different for
+ # each worker process.
+ import importlib.metadata
+ import random
+ import statistics
+
+ import gerrychain
+ from gerrychain import Graph
+
+ global _WORKER_STATE
+
+ try:
+ version = importlib.metadata.version("gerrychain")
+ except importlib.metadata.PackageNotFoundError:
+ version = getattr(gerrychain, "__version__", "unknown")
+ print(f"gerrychain {version} from {gerrychain.__file__}", flush=True)
+
+ base_seed = args.seed
+ if base_seed is None:
+ base_seed = random.randrange(2**31)
+ print(
+ f"base seed drawn randomly: {base_seed} (pass --seed {base_seed} to reproduce)",
+ flush=True,
+ )
+ if base_seed + args.num_seeds - 1 > MAX_NUMPY_SEED:
+ raise SystemExit(
+ f"--seed plus --num-seeds exceeds numpy's maximum seed value ({MAX_NUMPY_SEED})"
+ )
+ seeds = [base_seed + i for i in range(args.num_seeds)]
+ jobs = max(1, min(args.jobs, len(seeds)))
+ progress = args.progress
+ if args.profile and jobs > 1:
+ print("note: --profile forces sequential execution (--jobs 1)", flush=True)
+ jobs = 1
+ if progress and (jobs > 1 or len(seeds) > 1):
+ print("note: --progress only applies to a single sequential seed; ignoring", flush=True)
+ progress = False
+
+ graph = Graph.from_json(args.graph)
+ print(
+ f"graph={Path(args.graph).name} nodes={len(graph.nodes)} "
+ f"parts={args.parts} epsilon={args.epsilon} "
+ f"steps={args.steps} pop_col={args.pop_col} "
+ f"seeds={seeds[0]}..{seeds[-1]} repeats={args.repeats} jobs={jobs}",
+ flush=True,
+ )
+
+ _WORKER_STATE = (graph, args, progress)
+ seed_results: list[dict] = []
+ if jobs == 1:
+ for seed in seeds:
+ result = _run_one_seed(seed)
+ seed_results.append(result)
+ _print_seed_result(result, args.steps)
+ else:
+ import multiprocessing
+
+ start_methods = multiprocessing.get_all_start_methods()
+ method = args.start_method
+ if method == "auto":
+ # prefer fork (children inherit the already-loaded graph); Windows has no
+ # fork, so fall back to spawn with a per-worker graph load
+ method = "fork" if "fork" in start_methods else "spawn"
+ elif method not in start_methods:
+ raise SystemExit(
+ f"multiprocessing start method {method!r} is not available on this platform "
+ f"(available: {', '.join(start_methods)})"
+ )
+ ctx = multiprocessing.get_context(method)
+ if method == "fork":
+ pool = ctx.Pool(processes=jobs)
+ else:
+ pool = ctx.Pool(processes=jobs, initializer=_init_pool_worker, initargs=(args,))
+ with pool:
+ for result in pool.imap_unordered(_run_one_seed, seeds):
+ seed_results.append(result)
+ _print_seed_result(result, args.steps)
+ seed_results.sort(key=lambda r: r["seed"])
+
+ if args.profile:
+ import pstats
+
+ for result in seed_results:
+ print(f"\nprofile for seed {result['seed']} written to {result['profile_out']}")
+ st = pstats.Stats(result["profile_out"])
+ print("\n==== by cumulative time ====")
+ st.sort_stats("cumulative").print_stats(30)
+ print("\n==== by total (self) time ====")
+ st.sort_stats("tottime").print_stats(30)
+
+ all_ms = [t / args.steps * 1000 for r in seed_results for t in r["times_s"]]
+ ms_stats = {
+ "min": min(all_ms),
+ "median": statistics.median(all_ms),
+ "max": max(all_ms),
+ }
+ print(
+ f"\nms/step over {len(all_ms)} run(s): min {ms_stats['min']:.3f}, "
+ f"median {ms_stats['median']:.3f}, max {ms_stats['max']:.3f}",
+ flush=True,
+ )
+
+ result = {
+ "version": version,
+ "module_file": gerrychain.__file__,
+ "graph": str(Path(args.graph).resolve()),
+ "steps": args.steps,
+ "seeds": seeds,
+ "repeats": args.repeats,
+ "jobs": jobs,
+ "ms_per_step": ms_stats,
+ "per_seed": seed_results,
+ "profiled": bool(args.profile),
+ }
+ print(RESULT_MARKER + json.dumps(result), flush=True)
+
+
+# --------------------------------------------------------------------------
+# orchestrator: run the worker against several targets and compare
+# --------------------------------------------------------------------------
+
+
+def target_command(target: str, python_version: str) -> tuple[str, list[str]]:
+ """Map a target spec to (display label, command prefix ending in a python)."""
+ if target == "local":
+ return "local (working tree)", [sys.executable]
+ if target.startswith("pypi:"):
+ version = target[len("pypi:") :]
+ spec = f"gerrychain=={version}"
+ label = f"pypi:{version}"
+ elif target.startswith("git:"):
+ ref = target[len("git:") :]
+ sha = subprocess.run(
+ ["git", "rev-parse", ref],
+ cwd=TOP_DIR,
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout.strip()
+ # as_uri() instead of an f-string so Windows paths (C:\...) form a valid file URL
+ spec = f"gerrychain @ git+{TOP_DIR.as_uri()}@{sha}"
+ label = f"git:{ref} ({sha[:9]})"
+ else:
+ raise SystemExit(
+ f"unknown target {target!r}: expected 'local', 'pypi:', or 'git:]['"
+ )
+ prefix = [
+ "uv",
+ "run",
+ "--no-project",
+ "--python",
+ python_version,
+ "--with",
+ spec,
+ "python",
+ ]
+ return label, prefix
+
+
+def cmd_compare(args: argparse.Namespace) -> None:
+ import random
+
+ base_seed = args.seed
+ if base_seed is None:
+ base_seed = random.randrange(2**31)
+ print(
+ f"base seed drawn randomly: {base_seed} - every target gets the same seeds "
+ f"(pass --seed {base_seed} to reproduce)",
+ flush=True,
+ )
+
+ script = str(Path(__file__).resolve())
+ worker_args = [
+ "run",
+ "--graph",
+ str(Path(args.graph).resolve()),
+ "--parts",
+ str(args.parts),
+ "--epsilon",
+ str(args.epsilon),
+ "--steps",
+ str(args.steps),
+ "--seed",
+ str(base_seed),
+ "--num-seeds",
+ str(args.num_seeds),
+ "--jobs",
+ str(args.jobs),
+ "--repeats",
+ str(args.repeats),
+ "--pop-col",
+ args.pop_col,
+ "--start-method",
+ args.start_method,
+ ]
+
+ results: list[tuple[str, dict | None]] = []
+ # Run from a temp dir so the repo's gerrychain/ dir can't shadow installs.
+ with tempfile.TemporaryDirectory() as tmpdir:
+ for target in args.targets:
+ label, prefix = target_command(target, args.python)
+ print(f"\n=== {label} ===", flush=True)
+ proc = subprocess.Popen(
+ prefix + [script] + worker_args,
+ cwd=tmpdir,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ text=True,
+ )
+ result = None
+ assert proc.stdout is not None
+ for line in proc.stdout:
+ if line.startswith(RESULT_MARKER):
+ result = json.loads(line[len(RESULT_MARKER) :])
+ else:
+ print(" " + line.rstrip(), flush=True)
+ proc.wait()
+ if proc.returncode != 0 or result is None:
+ print(f" FAILED (exit code {proc.returncode})", flush=True)
+ results.append((label, None))
+ else:
+ results.append((label, result))
+
+ baseline = next((r for _, r in results if r is not None), None)
+ width = max((len(label) for label, _ in results), default=0)
+ print(
+ f"\n==== summary: graph={Path(args.graph).name}, "
+ f"{args.num_seeds} seed(s) x {args.repeats} repeat(s) from seed {base_seed}, "
+ f"{args.steps} steps, parts={args.parts}, epsilon={args.epsilon}, "
+ f"jobs={args.jobs} ===="
+ )
+ for label, result in results:
+ if result is None:
+ print(f"{label:<{width}} FAILED")
+ continue
+ ms = result["ms_per_step"]
+ if result is baseline:
+ note = "(baseline)"
+ else:
+ note = f"({baseline['ms_per_step']['median'] / ms['median']:.2f}x baseline speed)"
+ print(
+ f"{label:<{width}} median {ms['median']:9.3f} ms/step "
+ f"[min {ms['min']:9.3f}, max {ms['max']:9.3f}] "
+ f"gerrychain {result['version']:<10} {note}"
+ )
+
+ if any(result is None for _, result in results):
+ sys.exit(1)
+
+
+# --------------------------------------------------------------------------
+
+
+def add_benchmark_options(parser: argparse.ArgumentParser) -> None:
+ parser.add_argument(
+ "--graph",
+ default=str(DEFAULT_GRAPH),
+ help=f"dual graph JSON to run on (default: {DEFAULT_GRAPH})",
+ )
+ parser.add_argument("--pop-col", default="TOTPOP", help="population column (default: TOTPOP)")
+ parser.add_argument(
+ "--parts", type=positive_int, default=6, help="number of districts (default: 6)"
+ )
+ parser.add_argument(
+ "--epsilon", type=float, default=0.01, help="population deviation (default: 0.01)"
+ )
+ parser.add_argument(
+ "--steps", type=positive_int, default=250, help="chain steps per run (default: 250)"
+ )
+ parser.add_argument(
+ "--seed",
+ type=numpy_seed,
+ default=None,
+ help="base random/numpy seed; consecutive seeds count up from it "
+ "(default: drawn randomly and printed so the run can be reproduced)",
+ )
+ parser.add_argument(
+ "--num-seeds",
+ type=positive_int,
+ default=5,
+ help="number of consecutive seeds, starting at --seed (default: 5)",
+ )
+ parser.add_argument(
+ "--jobs",
+ type=positive_int,
+ default=5,
+ help="max seeds to run in parallel; each chain is single-threaded (default: 5)",
+ )
+ parser.add_argument(
+ "--repeats",
+ type=positive_int,
+ default=1,
+ help="timed repeats per seed (same trajectory re-run; default: 1)",
+ )
+ parser.add_argument(
+ "--start-method",
+ choices=["auto", "fork", "spawn"],
+ default="auto",
+ help="multiprocessing start method for parallel seeds (default: auto - "
+ "fork where available, else spawn)",
+ )
+
+
+def main() -> None:
+ ap = argparse.ArgumentParser(
+ description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+ )
+ sub = ap.add_subparsers(dest="command", required=True)
+
+ run_p = sub.add_parser("run", help="benchmark the current environment")
+ add_benchmark_options(run_p)
+ run_p.add_argument(
+ "--progress",
+ action="store_true",
+ help="show a chain progress bar (single sequential seed only)",
+ )
+ run_p.add_argument(
+ "--profile",
+ action="store_true",
+ help="also cProfile the chain (forces sequential execution; inflates timings)",
+ )
+ run_p.add_argument(
+ "--out", default=str(SCRIPT_DIR / "recom_profile.prof"), help="profile output path"
+ )
+ run_p.set_defaults(func=cmd_run)
+
+ cmp_p = sub.add_parser("compare", help="benchmark several targets and compare")
+ cmp_p.add_argument(
+ "targets",
+ nargs="+",
+ help="targets: 'local', 'pypi:', 'git:]