Physics Standard Library
Relevant source files
The following files were used as context for generating this wiki page:
The Physics Standard Library (deep_causality_physics) is a comprehensive collection of modular, type-safe, and composable computation kernels designed for high-fidelity theoretical physics and scientific engineering. It serves as a "Logic Layer" within the deep_causality ecosystem, integrating specialized physics formulas with the framework's causal reasoning capabilities. The library covers diverse domains including Quantum Mechanics, Electromagnetism, General Relativity, and Thermodynamics, providing a standardized foundation for complex multi-physics simulations.
Sources: openspec/changes/archive/physics.md, website/web/src/content/blog/en/announcement-physics-crate.md
Dual-Layer Architecture
The library is built on a dual-layer architecture designed to balance High-Performance Computing (HPC) requirements with the traceability required for causal analysis. This structure allows researchers to prototype in the causal layer and transition to the kernel layer for production runs without rewriting logic.
Layer Definitions
- Kernel Layer (The Compute): Consists of standalone, pure math functions named with a
_kernelsuffix. These functions are stack-based,no_stdcompatible, and SIMD-friendly to maximize performance and CPU cache locality. They return standard RustResult<T, E>or primitive types. - Causal Layer (The Graph): Wraps kernels in monadic structures, specifically
PropagatingEffect<T>. This layer provides total observability, including logging, historical tracking, and error propagation through theCausalMonad.
Sources: openspec/changes/archive/physics_v1_review.md:12-25, openspec/changes/archive/physics_final_review.md:14-20
Architecture Flow
The following diagram illustrates how data flows from pure mathematical kernels into the causal framework.
Type Safety and Invariants
To prevent unphysical states (such as negative mass), the library utilizes the Newtype pattern with private fields. This ensures that physical quantities can only be instantiated through validated constructors.
Quantity Implementation Pattern
| Component | Description |
|---|---|
| Private Field | Prevents direct manipulation of the underlying f64. |
new() | Validates physical invariants (e.g., Mass > 0) and returns Result. |
new_unchecked() | Bypasses validation for performance-critical paths; used when inputs are proven valid upstream. |
value() | Returns the underlying primitive value for calculations. |
Sources: openspec/changes/archive/physics_v1_review.md:27-40, openspec/changes/archive/physics.md:113-140
Domain Modules
The library is organized into specialized modules representing different branches of physics.
Quantum Mechanics (quantum)
Focuses on Hilbert Space operations and quantum logic. It consolidates quantum gates and operators, often implemented for HilbertState from the multivector crate.
- Key Operations:
born_probability,expectation_value,apply_gate,commutator. - Constants: Planck constant, Reduced Planck constant.
Sources: openspec/changes/archive/physics.md:162-167, 246-270
Electromagnetism (electromagnetism)
Implements Maxwell's equations and plasma forces using Geometric Algebra.
- Key Operations:
lorentz_force,maxwell_gradient,lorenz_gauge,poynting_vector. - Constants: Speed of light, Vacuum magnetic permeability, Vacuum electric permittivity.
Sources: openspec/changes/archive/physics.md:169-174, 272-282
Relativity (relativity)
Covers General Relativity and spacetime metrics, utilizing tensor and multivector dependencies.
- Key Operations:
spacetime_interval,einstein_tensor,geodesic_deviation,time_dilation_angle. - Sign Conventions: Supports both West Coast (+---) and East Coast (-+++) metrics via the
deep_causality_metricintegration.
Sources: openspec/changes/archive/physics.md:284-294, openspec/changes/archive/physics_update.md:38-55
Gauge Theories
Provides specialized implementations for fundamental forces:
- QED: U(1) gauge theory.
- Weak Force: SU(2) theory including generators and propagators.
- Electroweak: SU(2)×U(1) theory covering Higgs mechanism and symmetry breaking.
Sources: openspec/changes/archive/physics_gauge_theories_review.md:12-30
Physical Constants (CODATA 2022)
The library centralizes standardized physical constants to prevent "magic numbers" and discrepancies across implementations.
| Constant | Symbol | Value (SI Units) |
|---|---|---|
| Speed of Light | $c$ | 299,792,458.0 |
| Planck Constant | $h$ | 6.626,070,15e-34 |
| Boltzmann Constant | $k_B$ | 1.380,649e-23 |
| Gravitational Constant | $G$ | 6.674,30e-11 |
| Elementary Charge | $e$ | 1.602,176,634e-19 |
Sources: openspec/changes/archive/physics.md:204-230, openspec/changes/archive/physics_v1_review.md:42-49
Multi-Physics Pipelines
The library enables the composition of heterogeneous physics domains into a single causal pipeline. This is facilitated by the shared Higher-Order Abstract Functional Trait (HAFT) foundation, allowing data (e.g., Tensors, MultiVectors) to flow between modules without manual transformation code.
Pipeline Sequence Diagram
This diagram shows a typical multi-physics simulation where data flows between Quantum Field Theory (QFT), Hadronization, and Thermodynamics.
Error Handling
The specialized PhysicsError enum captures domain-specific invariant violations and integrates with the generic CausalityError.
- Fundamental:
PhysicalInvariantBroken,DimensionMismatch. - Relativistic:
CausalityViolation,MetricSingularity. - Thermodynamics:
ZeroKelvinViolation,EntropyViolation. - Numerical:
Singularity,NumericalInstability.
Sources: openspec/changes/archive/physics.md:232-243, openspec/changes/archive/physics_update.md:160-175
Summary
The Physics Standard Library provides the rigorous mathematical backbone for the deep_causality framework. By enforcing physical invariants through type safety and offering a dual-layer API for both performance and observability, it enables developers to build complex, multi-domain simulations that are both computationally efficient and causally traceable.