Static and auditable

Programming and
reproducibility

A result is useful only when its chain from scientific statement to formula, code, input, test, output and version can be inspected.

{ }

Run and regenerate the portal

Local static server

cd ssz-research-portal
python3 -m http.server 8000
# open http://127.0.0.1:8000/

A server is needed because browsers normally block JSON fetches from file://.

Research indexes and checks

python3 scripts/inventory_files.py
python3 scripts/build_catalogs.py
python3 scripts/build_deep_catalogs.py
python3 scripts/build_evaluations.py
node scripts/test_browser_physics.mjs
python3 scripts/validate_content.py
python3 scripts/check_links.py
python3 scripts/check_secrets.py

Archive and TeX policy: archives are catalogued but not unpacked. Existing TeX sources may be read as research sources; mathematics is published as accessible HTML/MathJax, with no TeX build pipeline or TeX output.

One environment per repository

Reproduce the declared version—not an accidental workstation

The documentation repositories favour isolated environments, editable local installs during development, and repository-specific dependency files. There is no honest universal command: each project’s branch, model lock and dependency lock take precedence over this portal’s general guidance.

1 · Identify

Record URL, branch, commit, release or model lock, operating system and runtime. A later green run must not rewrite an earlier captured snapshot.

2 · Isolate

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Use pinned project metadata when present. Never install missing packages silently inside a result script.

3 · Preserve

Store command, exit code, duration, dependency versions, input checksums, seed, tolerances and output paths. Mark an unclean tree explicitly.

Version rule: the current all-tests snapshot records Python 3.12, while individual repositories document other supported versions. Repository-specific locks are authoritative.

Derived from the metric and documentation repositories

Programming rules

Names and domains

Use explicit names such as xi_strong, xi_weak, dilation and normalized x=r/r_s. Document every branch domain and endpoint convention.

Units

Keep SI at public interfaces, label dimensionless ratios and test dimensions. Convert to plot units only at presentation boundaries.

Constants

Centralise G, c, φ and reference masses. Do not silently redefine r_s, swap Ξ branches or change D.

Functions and documentation

Type public functions; document physical scope, units, assumptions and failure modes. Separate model equations, approximations, fit routines and plotting.

Errors and logs

Fail clearly on invalid domains, missing provenance or unit mismatch. Logs record version, parameters and input identity without secrets.

Plots

Label quantities and units, identify metric branch and reference model, display uncertainty and state what the figure does not establish.

Numerical precision and tolerances

Precision follows the question

Use ordinary binary floating point for well-conditioned plots, higher precision for differences near machine resolution and symbolic algebra for endpoint identities, limits and curvature expressions.

Predeclare tolerances

A tolerance must follow from analytic truncation, floating-point propagation, solver convergence or measurement uncertainty—not adjustment until a test passes.

assert abs(xi_strong(1) - 0.801711847...) < declared_tolerance
assert xi_weak(10) == 0.05 within declared numerical tolerance
assert value, slope and curvature match at x=1.8 and x=2.2
assert superseded claims are rejected by publication gates

Core, external and derived layers

Data provenance and anti-circular analysis

The metric can be tested without observational downloads; empirical pipelines cannot. Keep source observations, immutable snapshots, processed tables and plotted summaries distinct.

Layer	Required record	Rule
Core analytic	formula version, domain, constants, precision	No network dependency; compare against symbolic limits and branch locks.
External observation	provider, query, retrieval date, licence, checksum	A missing catalogue is SKIP or dependency failure—not a physics failure.
Processed data	source checksum, code commit, filters, exclusions	Never overwrite raw data; document every transformation.
Derived result	model, parameters, uncertainty, residual definition	Preserve machine-readable output beside figure and prose interpretation.

Avoid circular validation

Do not tune parameters on an observation and present the same observation as an independent prediction. Separate calibration, validation and held-out evaluation; disclose reused priors and reference-model products.

Determinism

Record seeds, sampling algorithm, thread count and numerical backend. For nondeterministic solvers, report distributions or uncertainty intervals rather than a privileged run.

Do not add unlike units

Test and execution status semantics

A pytest case, script, analysis phase, exporter, log and result file are different evidence units. Captured run summaries remain separate from the searchable artefact catalogue.

Status	Meaning	Does not mean
PASS_EXACT	Identity or locked value met its declared tolerance.	The physical model is empirically confirmed.
PASS_UNCERTAINTY	Difference lies inside a predeclared numerical or observational uncertainty.	A competing model is excluded.
WARN / EXPLORATORY	Run completed but scope or threshold prevents a binary claim.	A passed hypothesis test.
FAIL	Assertion, collection, dependency or physical criterion failed; subtype is retained.	Automatically a falsification of SSZ.
SKIP / XFAIL	A prerequisite was absent or an incomplete path was declared.	Evidence that the feature works.

Counting rule: report execution unit and snapshot date. The 1,296-pass run is a historical twelve-repository execution subset. The current complete catalogue contains 9,300 records, 5,294 unique repository/test definitions and 9,216 repository/file/test identities across 28 test-bearing repositories. Catalogue coverage is never silently converted into PASS outcomes.

Mandatory provenance chain

Claim

Formula + scope

Code + inputs

Test + result + commit

Layer	Minimum record	Failure prevented
Claim	category, wording, epistemic status	overclaiming
Formula	variables, units, domain, approximation	method misuse
Implementation	repository, file, function, commit	untraceable number
Data	origin, licence, checksum, preprocessing	silent replacement
Test	command, environment, expected/actual/tolerance	irreproducible PASS
Result	output file, uncertainty, limitations	result promotion

Release process

Freeze canonical formula, branch and claim locks; preserve superseded claims separately.
Record repository URL, commit, clean/dirty status, runtime and dependency lock.
Verify input checksums, licence and retrieval metadata.
Regenerate inventories, deep catalogues and evaluation snapshots.
Run analytic, unit, integration, regression and observational checks; retain SKIP and failure reasons.
Review tolerances and reject post-hoc adjustment.
Run content validation, browser interaction checks, link checking and secret scanning.
Review P0 wording, central divergence, coordinate/local distinctions and observational caveats.
Commit on a non-destructive branch and deploy the exact reviewed commit.
Verify public subpath assets and interactions; record deployment commit and time.

Security and data hygiene

Never publish

Tokens, environment files, private remotes, authenticated URLs, absolute personal paths, SSH material, browser-side credentials or raw diagnostic dumps containing secrets.

Public metadata only

Remote metadata is fetched locally and transformed into safe static JSON. The published browser never receives or requires a token.