# PF Simulation r28: portable numerical relativity

PF now includes its own **portable vacuum BSSN solver**. It evolves numerical
spacetime fields inside the normal Python research environment, without Cactus,
WSL, a Linux compiler, MATLAB or a native Einstein Toolkit executable. The new
backend is named `portable_relativity`; the existing external Einstein Toolkit
backend remains separately named `numerical_relativity`.

This is a limited independent implementation of published Einstein-equation
evolution equations. It is **not a complete replica of Einstein Toolkit**, a
Cactus-compatible implementation, or a replacement for its astrophysical suite.
The implementation and numerical checks ran on Linux with Python 3.12. A real
Windows execution was not available for this release's validation evidence.

## Start on Windows

Use the regular research installation described in `R27_INSTALLATION_GUIDE.md`:

1. Extract the entire release into a new writable folder.
2. With 64-bit Python 3.12 available, run `setup_research_worker.bat`.
3. Run `Launch_PF_Research.bat`, which selects the research interpreter for
   `PF_Simulation_GUI.pyw`.
4. Select one of the **PF portable vacuum BSSN** research presets.

The portable studies need no WSL installation. Directly double-clicking
`PF_Simulation_GUI.pyw` still follows the Windows file association; the research
launcher explicitly selects the required environment. The core-only Python 3.8
installation does not gain these numerical research dependencies automatically.

From a terminal in the extracted PF folder, the canonical study can also run as:

```bat
.venv_research\Scripts\python.exe run_research_integrations.py --config configs_r28\research_portable_gauge_wave.json --output results_portable_gauge
```

On Linux, use the same arguments with `.venv_research/bin/python`. Choose a new
output folder for each run. The result includes reports, source and input hashes,
raw numerical fields and publication-ready static figures.

## Available studies

| Preset | What it actually executes | Additional scientific dependency |
| --- | --- | --- |
| `research_portable_minkowski.json` | Evolves flat vacuum data and checks the fixed point | NumPy, plus ordinary reporting dependencies |
| `research_portable_gauge_wave.json` | Evolves a periodic gauge wave at three resolutions and checks errors and convergence | NumPy, plus ordinary reporting dependencies |
| `research_portable_gauge_wave_link.json` | Evolves the same metric, integrates a null link through the numerical metric and evaluates a fixed illustrative receiver mode | SciPy and QuTiP in the existing research environment |

These configurations are in `configs_r28`. The GUI and SaaS use the same
`portable_relativity` backend and bounded input schema. The normal research
worker can execute it; a native Cactus worker is unnecessary. An operator must
deploy the updated code and declared research dependencies for an existing SaaS
installation to expose the new presets.

Public studies have spatial dependence only along x, periodic boundaries, zero
shift and harmonic lapse. The tensor core has three spatial indices and has
additional short axis/polarization tests, but the release does not qualify general
three-dimensional astrophysical evolution.

## Method and published sources

The solver advances the conformal metric, conformal extrinsic curvature, trace K,
conformal factor, independent conformal connection and lapse. It uses fourth-order
centered spatial differences and classical RK4 time integration. Algebraic
determinant and trace constraints are projected at RK stages; the Hamiltonian and
momentum constraints are measured, not replaced with zero.

The evolution follows the vacuum, zero-shift specialization of
[Baumgarte and Shapiro, Physical Review D 59, 024007](https://arxiv.org/pdf/gr-qc/9810065v1),
equations 14–24 and harmonic slicing equation 31. PF's discretization differs from
the time integrator used in that paper, and its published pulse figures are not
claimed reproduced.

The benchmark family follows
[Alcubierre et al., Classical and Quantum Gravity 21, 589](https://arxiv.org/pdf/gr-qc/0305023v1).
The consistent gauge and extrinsic-curvature signs are taken from Appendix A.2/A.3
of [Babiuc et al., Classical and Quantum Gravity 25, 125012](https://arxiv.org/pdf/0709.3559v3).
For the gauge test, PF uses

`H = 1 - A sin(2 pi (x-t)/L)`, `gamma_xx = H`, `alpha = sqrt(H)`,
`K_xx = -pi A cos(2 pi (x-t)/L)/(L sqrt(H))`.

Analytic fields initialize the benchmark and provide reference comparisons. They
are not used to advance the numerical state or populate its subsequent fields.
The gauge wave is flat spacetime in changing coordinates; it is not physical
gravitational radiation or an Earth gravity model.

## Reproduce the numerical qualification

The canonical qualification uses **A=0.01, L=1, t=1 and N=32/64/128**, with requested
CFL 0.25. The solver conservatively selects a slightly smaller timestep and records
the actual timestep and step count. Fields use geometric units G=c=1. Grid points
are unique periodic nodes; the reported L2-style errors are coordinate RMS values
`sqrt(mean(error**2))`, not unnormalized sums or proper-volume norms.

Run the separate evaluator with the research interpreter:

```bat
.venv_research\Scripts\python.exe release_tools\validate_r28_portable.py --output results_portable_independent
.venv_research\Scripts\python.exe -m unittest test_r28_portable_science -v
```

The evaluator defines its own exact solution and computes physical ADM constraint
residuals with Fourier derivatives and the Christoffel definition of Ricci. It
does not reuse the production BSSN diagnostics. It also reads and verifies the
hashes of the actual r27 Cactus/McLachlan HDF5 fields under
`validation_r27/native_install`. This is a comparison with **recorded native
execution**, not a fresh native solver run. The two implementations are compared
to the same continuum solution; discretization identity is not asserted.

Acceptance criteria are implementation verification thresholds established during
development and fixed before the final release run. They are not a preregistered
physical experiment or independent external certification. The evaluator requires:

- Better than order 3.5 refinement for metric, lapse and extrinsic-curvature RMS
  errors, and for both recorded native errors and inter-code differences.
- Portable/native maximum field differences below `1e-7*(32/N)^3` and native
  maximum exact errors below `1e-5*(32/N)^3.5`.
- Decreasing independent physical Hamiltonian and momentum residuals, with fine
  RMS residuals below `1e-5`.
- Correct initial fields, actual nontrivial evolution and finite saved errors.

The scientific tests additionally check the extrinsic-curvature sign, a 3D
Minkowski fixed point, a manufactured curved metric with nonzero constraints,
off-diagonal small-amplitude wave polarization and response to perturbed initial
data while the analytic-reference function is disabled.

The packaged independent evidence is
`validation_r28/independent/portable_validation.json`, with numerical NPZ fields.
Its source hashes bind the executed solver, evaluator, scientific tests and source
catalog. `research_sources_r28/portable_relativity_sources.json` records exact
paper versions, retrieval hashes and the scope of each citation. Changing source
files requires fresh evidence; a previously passing report is not automatically
current for edited code.

## Numerical fields, figures and reports

Each resolution saves `diagnostics.csv`, `metric_line.npz`, its metadata,
`extrinsic_curvature.npz`, and `final_bssn_state.npz`. These retain measured metric,
lapse, extrinsic curvature, final conformal fields and constraint histories.
The method and convergence JSON files record the parameters and interpretation.

Studies produce final-field comparisons, a spacetime plot, constraint histories
and, when multiple resolutions are requested, a convergence figure in PNG, SVG
and PDF. The research runner also writes HTML/Markdown/JSON reports and an
artifact evidence manifest. Verify an executed study with:

```bat
.venv_research\Scripts\python.exe run_research_integrations.py --verify results_portable_gauge --compare-source
```

The link study uses the numerically evolved metric and saved actual integration
times. Its fixed clocks and illustrative Gaussian receiver test the integration
pipeline. They do not establish measured satellite performance, intrinsic quantum
decoherence or a commercial advantage.

## Scope that still requires the external toolkit

The portable implementation does not supply adaptive mesh refinement, MPI,
black-hole mergers, puncture gauge, hydrodynamics/GRMHD, matter initial-data
solvers, horizon finding, general outer boundaries, arbitrary Cactus thorns or the
toolkit's complete gravitational-wave extraction suite. Existing kuibit analysis
of compatible real ET outputs remains a separate capability.

One crossing at small amplitude does not reproduce the published 1000-crossing
endurance campaign, the revised A=0.5 stress test or establish long-term nonlinear
stability. User-modified parameters receive measured diagnostics and consistency
checks; they do not inherit the canonical benchmark qualification. Experimental
accuracy and stronger commercial claims remain unassessed outcomes.