Repository navigation
Documentation restructure, demo regrouping, and lapse-tracked collapse analysis - #99
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No PyPIC3D runtime source changes. This PR touches docs/, demos/, one test, README.md, and CI/packaging config.
Documentation
einstein_maxwell.rst is split into two topic pages and deleted:
docs/dynamical_relativity.rst (new) — BSSN formulation and variable table, W conformal-factor convention, gauge conditions, the [metric] table with defaults, the six gravitational boundary codes and why they differ from the EM codes, Strang-split time integration, constraint diagnostics, and the curved-space work-energy theorem.
docs/dark_photon.rst (new) — the mass-eigenbasis derivation, field equations, staggering and update order, the Proca timestep limit that overrides the ordinary Courant path, dark_fieldN initial data, conducting-wall parities, PML behaviour, and energy diagnostics.
docs/solvers.rst becomes a short overview that links to both. pair_injection.md and distributed_cartesian.md convert to .rst and join the toctree (previously neither was reachable from the docs index). usage.rst, architecture.rst, tiling.rst, development.rst, and the README structure block are brought in line with the current layout — utilities/parameters.py, solvers/GR_yee/, solvers/dark_matter_yee/, relativity/metrics/, tests/distributed_tests/.
Demos
Regrouped into four solver families — standard_yee/, dark_matter/, static_metric_relativity/, dynamical_relativity/ — with demos.rst rewritten around that taxonomy and every invocation path updated. Adds Kerr orbits, Wald/Meissner, both dark-sector demos, and all four dynamical-relativity demos to the page, plus a BZ monopole figure. The BZ diagnostics output is renamed figure6_diagnostics.png → bz_monopole.png and its plot title drops the external paper reference.
Collapse analysis: track the lapse minimum
Both plot_analytical_comparison.py scripts previously assumed the star sat at the coordinate origin and read the ray from rint(-origin/spacing). They now load the full lapse mesh, locate the 3D minimum with nanargmin, print its index and coordinates, and take the positive-x ray from there — so the comparison follows the collapse centre instead of a fixed grid point. Radius is reported relative to that origin.
Two correctness fixes ride along in the charged-star script:
f_RN is evaluated only on the exterior mask, so the R = 0 cell no longer divides by zero.
The trumpet turning-point guard moves from np.argmin(R) to the outward_branch scan the neutral OS script already used. Because the new radial grid starts at exactly r = 0, R[0] is exactly 0 and argmin was pinned to index 0, silently disabling the guard; the analytic RN curve could then be drawn across the inner branch of the trumpet and double back on itself.
CI and packaging
New Documentation workflow building with -W --keep-going, so a broken cross-reference or malformed heading fails CI instead of degrading the published docs.
Read the Docs moves Python 3.8 → 3.12; sphinx-autobuild added to docs/requirements.in.
pyproject.toml declares requires-python = ">=3.9", matching the existing build matrix.
.coveragerc source corrected from the non-existent PyPIC3D/PyPIC3D to PyPIC3D, and the stale PyPIC3D/tests/* omit dropped.
.gitignore updated for the new demo nesting (demos///data/, demos///outputs/) plus docs/_build/.
Test
bssn_parameters_test.py drops the assertions that non-periodic field and particle boundaries are rejected, and asserts the open-wall configuration initialises instead. Both collapse demos run constant field walls with absorbing particle walls, so the old assertions no longer described supported behaviour.
Verification
python -m sphinx -b html -W --keep-going docs docs/_build/html → build succeeded, exit 0, zero warnings.
tests.code_tests.bssn_parameters_test → 13 tests, OK.
Every demo path, config, and script named in demos.rst and the README exists; every :doc: target resolves; every referenced image is present.
The outward_branch fix checked on a synthetic trumpet profile: argmin returned 0 while outward_branch returned the true fold index, and the old mask admitted an above-horizon inner-branch cell that the new one excludes.