# Physics Kernels
This document covers the **kernel layer** of `deep_causality_physics` — the pure, stateless,
domain-specific computations and the type-safe quantity wrappers built around them.
For the **theory layer** (Gauge Theories on a shared topological backend) see
[README_GAUGE_THEORIES.md](./README_GAUGE_THEORIES.md).
For the project overview see [README.md](./README.md).
---
## Domains
Kernels live under `src/kernels/<domain>/`. Each domain ships pure computation kernels, monadic
wrappers (`wrappers.rs`), and domain-specific quantity newtypes (`quantities.rs`). The table below
lists the source files (excluding `mod.rs`, `quantities.rs`, and `wrappers.rs`) shipped under each
domain and a short description of what each one covers.
| Domain | Source files | Coverage |
|---|---|---|
| **Astro** | `mechanics` | Schwarzschild radius, orbital velocity, escape velocity, gravitational redshift. |
| **Chronometric** | `solve_gm`, `wrapper` | Inverts the J2-corrected weak-field 1PN clock equation (Bjerhammar 1975, Vermeer 1983) to recover $GM_\oplus$ and the derived planetary mass from satellite clock time-dilation measurements. `CentralBody` (gravity-model parameters), `SpaceTimeCoordinate` (clock + kinematic state), `solve_gm_analytical`. |
| **Condensed** | `moire`, `phase`, `qgt` | Twistronics (Bistritzer–MacDonald moiré Hamiltonian), phase-field models (Ginzburg–Landau, Cahn–Hilliard), Quantum Geometric Tensor. |
| **Dynamics** | `estimation`, `kinematics` | Classical mechanics (Newton's laws, kinematics), state estimation (Kalman filters), Euler integration. |
| **Electromagnetism (`em`)** | `fields`, `forces`, `solver` | Maxwell's equations, Lorentz force, Poynting vectors, gauge fields via Geometric Algebra. |
| **Fluids** | `boundary_layer`, `coherent_structures`, `compressible`, `constitutive`, `dimensionless`, `governing`, `ideal_flow`, `kinematics`, `mechanics`, `turbulence` | Full Navier–Stokes surface: continuity / momentum / energy RHS, Newtonian and power-law stress, kinematics (S, Ω, vorticity, CPC invariants), 18 dimensionless numbers, turbulence quantities (TKE, ε, Kolmogorov scales, Reynolds stress, Boussinesq), coherent-structure detectors (Q, Δ, λ₂, swirling strength), compressible thermodynamics (speed of sound, isentropic stagnation, entropy production), wall functions, ideal-flow primitives (Bernoulli, stream function, circulation, Kutta–Joukowski). |
| **Materials** | `mechanics` | Stress, strain, Hooke's law, Young's modulus, thermal expansion. |
| **MHD** | `grmhd`, `ideal`, `plasma`, `resistive` | Alfvén waves, magnetic pressure, ideal induction on manifolds, General Relativistic MHD with manifold-based current computation, plasma parameters. |
| **Nuclear** | `lund`, `pdg`, `physics`, `qcd` | Binding energy, radioactive decay, PDG particle database, **Lund String Fragmentation** for QCD hadronization. |
| **Photonics** | `beam`, `diffraction`, `polarization`, `ray` | Ray optics, polarization calculus, Gaussian beam optics, diffraction. |
| **Quantum** | `gates`, `gates_haruna`, `mechanics` | Wavefunctions, operators, gates, expectation values; Haruna's Gauge Field gates. |
| **Relativity** | `gravity`, `spacetime` | Special and General Relativity: spacetime intervals, time dilation, Einstein tensor, geodesic deviation. |
| **Thermodynamics** | `stats` | Statistical mechanics: entropy, Carnot efficiency, ideal gas law, heat diffusion. |
| **Waves** | `general` | Doppler effect, wave speed, frequency/wavelength relations. |
---
## Architecture
Kernels are organized in four layers:
1. **Kernels (`kernels/<domain>/mechanics.rs`, `kernels/<domain>/gravity.rs`, etc.)** — Pure
functions that perform the raw physical computations. They operate on `CausalTensor`,
`CausalMultiVector`, `Manifold`, or primitive types. Stateless, side-effect free.
*Example*: `klein_gordon_kernel` computes $(\Delta + m^2)\psi$.
2. **Wrappers (`kernels/<domain>/wrappers.rs`)** — Monadic wrappers that lift kernels into the
`PropagatingEffect` monad. They allow physics functions to be directly embedded into
`CausalEffect` functions within a DeepCausality graph.
*Example*: `apply_gate` wraps `apply_gate_kernel` to validly propagate state changes in the
causal graph.
3. **Quantities (`kernels/<domain>/quantities.rs`, `units::*`)** — Newtype wrappers
(`Speed`, `Mass`, `Temperature`, `FourMomentum`, `Hadron`, …) that enforce physical invariants
(e.g. mass cannot be negative) and type safety. **Every wrapper is generic over
`R: RealField`**, so the same code runs at `f32`, `f64`, `DoubleFloat`, or any other field that
implements `RealField`.
4. **Metric Types** — Re-exports from `deep_causality_metric` for sign-convention handling
(`LorentzianMetric`, `EastCoastMetric`, `WestCoastMetric`, `PhysicsMetric`).
---
## When to use kernels vs. theories
* **Kernels for Isolation**: If you need to solve a specific equation (e.g., `schwarzschild_radius`,
`lorentz_force`, `cahn_hilliard_flux`) in isolation, use the standalone kernels. They are pure
functions, stateless, and efficient.
* **Theories for Frameworks**: If you are working within a full physical theory (General Relativity,
Electroweak Theory, etc.), use the Physics Theories modules under `src/theories/`. See
[README_GAUGE_THEORIES.md](./README_GAUGE_THEORIES.md).
---
## Examples
### Relativistic Dynamics
```rust
use deep_causality_physics::{spacetime_interval, time_dilation_angle};
use deep_causality_multivector::{CausalMultiVector, Metric};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// 1. Define Spacetime Events using Geometric Algebra
// Minkowski Metric (+---) for 4D spacetime
let metric = Metric::Minkowski(4);
// Event A at origin
let event_a = CausalMultiVector::<f64>::new(vec![0.0; 16], metric).unwrap();
// Event B at (t=10, x=5, y=0, z=0)
let mut data_b = vec![0.0; 16];
data_b[1] = 10.0; // Time basis
data_b[2] = 5.0; // X basis
let event_b = CausalMultiVector::<f64>::new(data_b, metric).unwrap();
// 2. Compute Spacetime Interval (Wrapper returns PropagatingEffect)
let interval_effect = spacetime_interval(&event_b, &metric);
if let Ok(s2) = interval_effect.value().clone().into_value() {
println!("Spacetime Interval s^2: {}", s2);
}
Ok(())
}
```
### Chronometric GM Recovery
```rust
use deep_causality_physics::{CentralBody, SpaceTimeCoordinate, solve_gm_analytical};
fn main() {
// Two space-time coordinate samples (position in ECI, inertial velocity,
// IGS clock bias and drift rate). In practice these come from preprocessed
// satellite broadcast clock + SP3 orbit data.
let coord_a: SpaceTimeCoordinate<f64> = /* ... */;
let coord_b: SpaceTimeCoordinate<f64> = /* ... */;
// Earth parameters: JGM-3 J2 with WGS-84 equatorial radius. The struct
// pairs J2 with its reference radius — they are only meaningful together.
let body = CentralBody::EARTH_JGM3;
// Wrapper returns PropagatingEffect<f64> for use in causaloid graphs.
let effect = solve_gm_analytical(&coord_a, &coord_b, &body);
// → recovered GM in m³/s²; divide by NEWTONIAN_CONSTANT_OF_GRAVITATION
// to get Earth's mass in kg.
}
```
A complete worked example processing one full GPS week of Galileo broadcast clock data
(satellite E14) is in [`examples/chronometric_examples/gm_recovery`](../examples/chronometric_examples/gm_recovery).
It demonstrates the framework's `CausalMonad` bind chain end-to-end and recovers
$GM_\oplus$ and Earth's mass to ~0.2% relative error against published JGM-3 / IERS 2010
references — *the planet weighed by clock time-dilation alone.*
### Lund String Fragmentation (QCD Hadronization)
```rust
use deep_causality_physics::{FourMomentum, LundParameters, lund_string_fragmentation_kernel};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Configure Lund parameters (defaults tuned to LEP e+e- data)
let params = LundParameters::default();
// Define a quark-antiquark string (e.g., from e+e- → qq̄)
// Quark moving in +z, antiquark in -z
let quark = FourMomentum::<f64>::new(50.0, 0.0, 0.0, 50.0);
let antiquark = FourMomentum::<f64>::new(50.0, 0.0, 0.0, -50.0);
let endpoints = vec![(quark, antiquark)];
// Fragment the string into hadrons
let mut rng = deep_causality_rand::rng();
let hadrons = lund_string_fragmentation_kernel(&endpoints, ¶ms, &mut rng)?;
println!("Produced {} hadrons:", hadrons.len());
for h in &hadrons {
println!(" PDG ID: {}, Energy: {:.2} GeV", h.pdg_id(), h.energy());
}
Ok(())
}
```
More example code is in the [examples folder](../examples/physics_examples).
---
## Precision
Every kernel and every quantity wrapper in this crate is generic over `R: RealField`. Pick the
precision at the call site:
```rust
use deep_causality_physics::Mass;
use deep_causality_num::DoubleFloat;
let m_fast: Mass<f32> = Mass::new(5.0_f32).unwrap(); // games / viz
let m_std: Mass<f64> = Mass::new(5.0_f64).unwrap(); // engineering default
let m_hi: Mass<DoubleFloat> = Mass::new(DoubleFloat::from(5.0)).unwrap(); // cosmology
```
The single carve-out is physical constants under `src/constants/` and the PDG quark-mass constants
in `kernels/nuclear/pdg.rs`. Those stay declared as `pub const X: f64 = literal` and the consumer
converts at the call site via `R::from_f64(SPEED_OF_LIGHT)`. Rationale: the values themselves do not
benefit from precision-parametricity (exact-defined CODATA constants fit in `f64` exactly; measured
constants have measurement uncertainty far below `f64` precision).