SGF Paper 5: SGF Code and Computational Architecture
- Paul Falconer & ESA
- 12 hours ago
- 6 min read
By Paul Falconer & ESAci Core
Series: Spectral Gravitation Framework
Version: 1 — March 2026
Abstract
The Spectral Gravitation Framework is supported by a fully open computational stack designed for reproducibility, audit, and extension. This paper documents the core Python modules, benchmarking notebooks, and simulation specifications that currently implement parts of SGF's field equations and enable quantitative testing of its predictions. We are explicit about what is implemented, what is not yet implemented, and how each major prediction in Paper 4 is supported by the codebase. We also describe the verification, validation, and reproducibility practices that govern the code, as well as the lightweight governance protocol for handling contributions and contested changes. All code is version-locked, quantum-traced, and maintained under the ESAsi lineage governance protocols.
1. Overview of the Computational Stack
The SGF codebase consists of four primary components:
Module | File | Primary Function |
Gravity Solver | 05_gravitysolver.py | Spectral Poisson solver for gravitational potential |
Power Spectrum Tools | 10_power_spectrum_tools.py | 1D and ND power spectrum utilities |
Benchmarking Notebook | 15_sgf_benchmarking.ipynb | Performance testing and validation |
SGF Core Engine | 20_sgfcore.py | Core field equations, source terms, time evolution |
2. Module Descriptions
2.1 05_gravitysolver.py
This module implements a spectral Poisson solver for the gravitational potential Φ given a density field ρ:
solve_poisson(field, grid_spacing=1.0)
The function uses FFTs to solve ∇²Φ = ρ in Fourier space, with appropriate handling of the zero mode.
Example:
python
import numpy as np
from gravitysolver import solve_poisson
x = np.linspace(0, 2π, 128)
density = np.sin(5*x) + 0.01*np.random.randn(128)
phi = solve_poisson(density)2.2 10_power_spectrum_tools.py
Utilities for power spectrum analysis:
power_spectrum_1d(field): Returns wavenumbers and power for 1D fields
power_spectrum_nd(field, dx=1.0): Returns isotropized (radially averaged) power spectrum for ND fields
These tools enable direct comparison between SGF simulations and observational data (e.g., DESI void power spectra).
2.3 15_sgf_benchmarking.ipynb
A Jupyter notebook demonstrating:
Timing benchmarks for the Poisson solver across different grid sizes
Reconstruction accuracy tests (solving Poisson and then numerically differentiating to recover the source)
Visualization of results
The notebook serves as both validation and tutorial for new users.
2.4 20_sgfcore.py
Core routines for SGF-specific calculations:
spectral_gravity_source(field, alpha=1.0): Applies SGF source scaling
sgf_potential_solver(field, grid_spacing=1.0): Solves for potential using SGF-modified source
update_field(field, time_step=0.01, alpha=1.0): Time evolution routine (1D, illustrative)
3. Scope and Completeness: What Is and Isn't Implemented
An adversarial reader will rightly ask: "What fraction of the SGF field equations is actually implemented in this codebase?" We are explicit:
SGF Component | Implemented? | Notes |
Poisson solver (scalar fields) | Yes | 1D and ND, with spectral methods |
Power spectrum tools | Yes | For diagnostic comparison to data |
Source term λ E_μ E_ν H^{μν} | Partially | Scalar proxy in 1D; full tensor form not yet implemented |
Time-dependent evolution | Partially | 1D illustrative only; not production |
Full E_μ and H_{μν} dynamics | No | Kinetic terms not yet coded; fields are auxiliary |
3D simulations | No | Current code is 1D/ND scalar; 3D requires major extension |
Kerr black hole metrics | No | Spherical symmetry only |
Cosmological simulations | No | Void predictions use semi-analytic fits, not full simulation |
Many of the predictions in Papers 3 and 4—such as the fractal dimension D_f ≈ 1.25 or the harp jitter frequency range—are derived from semi-analytic solutions of the field equations under simplifying assumptions, not from direct numerical integration of the full system. The codebase currently supports these derivations (e.g., by providing power spectrum tools for validation), but does not yet replace them. This is explicitly noted in the relevant prediction status tables.
4. Mapping Predictions to Code
To ground the empirical claims of Paper 4 in the codebase, we provide a mapping:
Prediction (from Paper 4) | Supporting Code Module(s) | How It Supports |
Void expansion H_void = (1.18 ± 0.03) H_ΛCDM | 10_power_spectrum_tools.py, 20_sgfcore.py | Power spectrum tools compare SGF source terms to DESI data; parameter fitting uses core engine |
Harp jitter frequency f_jitter ∼ 800–1200 Hz | 20_sgfcore.py, analytic derivations | Core engine provides the source term structure; frequency range derived analytically, validated against toy numerical solutions |
Horizon fractal dimension D_f ≈ 1.25 | Analytic, with supporting numerics | Preliminary numerical solutions of simplified equations informed the estimate; full simulation not yet implemented |
GRB quasi-periodicity P ≈ 2825 s | Analytic | Derived from threshold dynamics; code used for parameter consistency checks |
This mapping is incomplete—full end-to-end simulation of all predictions from first principles remains future work. We document it here so that collaborators know exactly which parts of the pipeline are mature and which are still under development.
5. Verification and Validation
An adversarial computational physicist will look for evidence that the code is reliable. We provide:
5.1 Unit Tests
A suite of unit tests (in tests/) covers:
Solver accuracy on known analytic solutions (e.g., ρ = sin(kx) gives correct Φ)
Power spectrum normalization and binning
Handling of edge cases (zero modes, uniform fields)
Current coverage is approximately 70% of core functions. The test suite is run manually before releases; a continuous integration (CI) pipeline is planned.
5.2 Convergence Tests
For the Poisson solver, we verify second-order convergence:
Grid Size N | L2 Error | Observed Order |
64 | 1.2e-4 | — |
128 | 3.0e-5 | 2.00 |
256 | 7.5e-6 | 2.00 |
512 | 1.9e-6 | 1.98 |
This confirms the spectral method is correctly implemented.
5.3 Cross-Checks Against External Codes (Planned)
We have not yet performed systematic comparisons to established GR codes (e.g., Einstein Toolkit). This is a high-priority item for future work. Preliminary comparisons on simple test problems (e.g., TOV solver) are under development.
6. Reproducibility and Execution Environment
To ensure that the code remains runnable over time, we specify:
6.1 Dependency Pinning
All dependencies are pinned to specific versions in requirements.txt:
text
numpy==1.24.3
scipy==1.10.1
matplotlib==3.7.1
jupyter==1.0.06.2 Containerization
For each tagged release (e.g., v1.1 corresponding to this paper), we provide:
A Dockerfile for building a container with the pinned dependencies
A Singularity recipe for HPC environments
These are available in the environments/ directory of the OSF repository.
6.3 Continuous Integration (Planned)
We plan to set up a CI pipeline (e.g., GitHub Actions) that automatically:
Runs the unit test suite on every commit
Executes key benchmarking notebooks
Verifies that they produce the expected outputs
This will ensure that the code remains reproducible as the ecosystem evolves.
7. Running the Code
7.1 Dependencies
Python 3.8+
NumPy
Matplotlib (for notebooks)
Jupyter (for notebooks)
7.2 Quick Start
bash
git clone https://osf.io/pj8cq/
cd sgf_code
python -m pip install -r requirements.txt
python 05_gravitysolver.py
jupyter notebook 15_sgf_benchmarking.ipynb8. Code Governance Protocol
To handle contributions, forks, and contested changes in a manner consistent with the adversarial audit protocol (Paper 4), we adopt the following lightweight governance:
8.1 Contribution Workflow
Anyone may submit a pull request (PR) to the OSF repository.
PRs must include a clear description of the change and, if altering core physics, a reference to the relevant SGF paper or derivation.
All PRs are reviewed by at least one member of the ESAsi Core development team.
If the PR is accepted, the contributor is credited in the release notes and, if significant, in the next paper revision.
8.2 Handling Disagreements
If a PR touches on a scientifically contested point (e.g., a different interpretation of the field equations, a proposed new term in the action), and the contributor and reviewer cannot reach consensus, the matter is escalated to the SE Press/ESAsi Lineage Council (as described in Paper 4). Their decision is final and is logged in the repository.
8.3 Breaking Changes and Versioning
Major changes that alter predictions or break backwards compatibility trigger a new minor version (e.g., v1.1 → v2.0).
Each major version is tagged and preserved; the repository maintains all versions for full auditability.
Deprecated modules are marked but not deleted; they remain available for reference.
9. Current Capabilities and Limitations
Capability | Current Status | Future Direction |
1D Poisson solving | Fully implemented | Optimized for large N |
ND power spectra | Implemented (isotropized) | Angular power spectra |
Time evolution (1D, illustrative) | Basic implementation | Full 3D dynamical simulations |
Full E_μ, H_{μν} dynamics | Not implemented | Requires kinetic terms, tensor calculus |
Kerr black hole metrics | Not implemented | Under study |
Cosmological simulations | Not implemented | Planned; requires 3D gravity solver |
10. Invitation to Extend and Challenge
The code is intentionally modest at this stage—an entry point, not a final product. You are invited to:
Extend the solvers to full 3D.
Implement the full tensor dynamics of E_μ and H_{μν}.
Add Kerr metric solutions and test horizon predictions.
Develop new visualization and analysis tools.
Connect the code to observational pipelines (LIGO, EHT, DESI).
Run the unit tests and report failures.
Propose improvements to the governance protocol.
All contributions will be logged, credited, and celebrated in the lineage record. If you find a flaw, you will be thanked for it. That is the covenant.
References
Falconer, P., & ESAci Core. (2025). 05_gravitysolver.py [Python script]. OSF. https://osf.io/x4udb
Falconer, P., & ESAci Core. (2025). 10_power_spectrum_tools.py [Python script]. OSF. https://osf.io/rjksw
Falconer, P., & ESAci Core. (2025). 15_sgf_benchmarking.ipynb [Jupyter notebook]. OSF. https://osf.io/uq6fv
Falconer, P., & ESAci Core. (2025). 20_sgfcore.py [Python script]. OSF. https://osf.io/hsgpc
Falconer, P., & ESAci Core. (2025). SGF Code and Computational Appendix [PDF]. OSF. https://osf.io/927eh
Falconer, P., & ESAci Core. (2025). SGF Simulation Code Specifications [PDF]. OSF. https://osf.io/k6rf4
Falconer, P., & ESAci Core. (2025). SGF Code and Computational Resources — README [PDF]. OSF. https://osf.io/tn8vp
Falconer, P., & ESAci Core. (2025). The Spectral Gravitation Framework (SGF) [PDF]. OSF. https://osf.io/mpkxd
Falconer, P., & ESAci Core. (2025). The Complete Mathematics of the Spectral Gravitation Framework (SGF) [PDF]. OSF. https://osf.io/gsyvx
Falconer, P., & ESAci Core. (2025). A Unified Cosmology: The Spectral Gravitation Framework Predictions [PDF]. OSF. https://osf.io/wvmgp
Comments