Skip to content

Documentation restructure, demo regrouping, and lapse-tracked collapse analysis - #99

Merged
cwoolfo1 merged 12 commits into
uwplasma:mainfrom
cwoolfo1:main
Nov 18, 2026
Merged

cwoolfo1 merged 12 commits into
uwplasma:mainfrom
cwoolfo1:main

Conversation

@cwoolfo1

Copy link
Copy Markdown
Member

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.

@cwoolfo1
cwoolfo1 merged commit b1075cc into uwplasma:main Nov 18, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant