Universal Physics Tensor Framework

Computational framework for exploring unified physics through tensor formalism

Vision

Modern physics is fragmented across scales and domains: quantum mechanics governs the microscopic, general relativity explains the cosmic, and statistical mechanics bridges between them. Each regime has its own mathematics, assumptions, and approximations. What if we could represent all of physics in a single mathematical object?

The Universal Physics Tensor Framework (UPTF) proposes a rank-6 tensor Π living in a product space of:

• Scale (quantum → mesoscopic → classical → cosmological)
• Force (gravitational, electromagnetic, weak, strong, emergent)
• Symmetry (Poincaré, gauge, conformal, supersymmetry ('susy' in code))
• Information (von Neumann, Shannon, Kolmogorov, quantum discord)
• Dimension (dimensional analysis constraints)
• Topology (topological invariants)

This framework provides a computational laboratory for exploring:

• Bridge equations connecting different physical regimes
• Emergence of macroscopic laws from microscopic interactions
• Information-geometry connections between computation and spacetime
• Unification patterns across seemingly disparate phenomena

Important Context

I am not a physicist by trade. I'm a systems engineer specializing in Test Program Set development for defense avionics. This project applies engineering systems thinking to theoretical physics questions.

Think of this as:

• A computational framework for exploring ideas
• An engineering approach to organizing physical knowledge
• A collaboration platform inviting physicists to validate/improve
• NOT claiming to have "solved" or "unified" physics
• NOT peer-reviewed theoretical physics (yet)

Physicists: Your expertise is welcomed and needed! Please contribute validation, corrections, and improvements.

Quick Start

npm install universal-physics-tensor
npx upt help

The npm package ships dist/, bin/, this README and the licence. The documentation and the examples live in the GitHub repository. From a clone, Bun is the package manager (package.json pins [email protected]). Node does not install it: corepack prepare [email protected] --activate fails with Unsupported package manager specification. Install that Bun from https://bun.sh/install, then bun install and bun run build. On a machine that has Node and not Bun, the clone path is npm install, npm run build, then node bin/upt.mjs <command>.

The library requires the published @danielsimonjr/mathts-* packages. There is no second parser. MathTS accepts factorial, erf, gamma(), and juxtaposition such as 2pi. A bare e is the elementary charge, E is energy, and Euler's number is only exp(x), for example exp(1). The name euler is refused. upt eval --debug names the parser. upt version stays a bare semver line. @viz-js/viz (upt map --format=svg) stays an optional peer.

First five minutes

npx upt eval "2*pi*sqrt(1/9.81)"
npx upt derive period:time length:length gravity:acceleration --formula "2*pi*sqrt(length/gravity)"
npx upt explain hawking-temperature mass=1Msun
npx upt evaluate be-63 mu_e=2
npx upt search pendulum

upt eval "2*pi*sqrt(1/9.81)" prints the small-angle period of a 1 m pendulum, in seconds:

2.0060666807106475

upt derive recovers the dimensionless prefactor of that formula (2π) and names the canonical entry:

  dimensionally determined up to a constant:  period ∝ length^0.5·gravity^-0.5
  formula dimension: [time]  ✓ homogeneous, matches target
  formula MATCHES the dimensional form — recovered prefactor ≈ 6.2832e+0
  ✓ agrees with CE-pendulum-period (Pendulum period), prefactor included: yours/canonical = 1 at 3 fixed points

upt explain hawking-temperature mass=1Msun recovers 6.1684e-8 by the two routes of BE-42. upt evaluate be-63 mu_e=2 prints M_Ch_solar = 1.4558683960704613 for an ideal degenerate gas with M_sun = 1.989e30 kg. upt search pendulum names the commands that open the pendulum records. Every flag of every command is in docs/CLI.md.

Commands

30 commands: 28 registered, plus help and version.

Evaluate and check

| Command | What it does | |---|---| | audit | Derive every bridge equation by dimensions and sort derived, coefficient unset, decoy, not a monomial, and open. | | derive (dim) | Derive the dimensional form of your own equation and, with --formula, the prefactor. | | eval (calc) | Evaluate a scalar formula. A bare e is the elementary charge; Euler's number is exp(x). | | evaluate | Evaluate a closed-form bridge or an applied case, with units on every input. | | metric (curvature) | Print Christoffel symbols and curvature scalars for one exact metric. | | symbolic (compose-symbolic) | Compose the symbolic forms of the registered bridge chains. |

Explore bridges and the atlas

| Command | What it does | |---|---| | atlas | Show one atlas bridge with its relation, regime, bound, witnesses, and formal reference. | | canonical (laws) | List the canonical-equation registry, its fidelity, and the coverage gap. | | explain | Show how the graph determines a quantity, or say that it does not cover that name. | | map (linkage) | Show how equations link, or where your own equation lands on that graph. | | path | Show the bridge chain between two models and whether a bound is claimed there. | | recover (recovery, validate) | Classify each bridge-to-canonical link as restates, recovers, or dimensional-only. | | regime | Report where a family's models are valid, violated, or unknown. | | search | Find a bridge, equation, model, quantity, case, or regime by the words in its record. |

Discovery and probes

| Command | What it does | |---|---| | axes (axis-audit) | Report which tensor classification axes gate the discovery funnel. | | candidates (propose) | Propose same-dimension links between clusters for physicist review. | | connectors (orphans) | Find same-dimension identifications that would pull an isolated bridge into the core. | | discover (discovery) | Vet quantity identifications and rank them promising, inert, or contradictory. | | frontier | Print null results and missing connections as two lists, neither of them a score. | | ground | Show which falsifiers ran on one discovery candidate, and which abstained. | | predict (predictions) | Rank empty regime cells as undiscovered-connection hypotheses. | | priority (prioritize, triage) | Triage speculative bridges by structural decidability, not by credibility. | | probe | Search expressions and residuals. This is not upt discover. |

Data and confrontation

| Command | What it does | |---|---| | confront | Run the committed predicted-versus-observed confrontations. | | coverage (grounding) | Count catalog bridges by empirical grounding tier. | | retrieve | Search the atlas for a claim. --embed asks a local Ollama model and does not accept that order. | | testplan | Print the measurement plan stored on a confrontation or an applied case. |

Utilities

| Command | What it does | |---|---| | help | Show every command, or one command's usage and flags. upt help statuses defines the status words. | | version | Print the installed package version as one semver line. | | chain | Name the internal chain orchestrator and exit 2. It does not run it. |

Global options

| Option | Default | What it does | |---|---|---| | --help | | Show this command list, or upt help <command> for one command. -h is the same. upt <command> --help prints that command. | | --version | | Print the package version as one semver line and exit. -v and upt version are the same. Neither takes --json. | | --json | | Write a JSON envelope to stdout instead of the text report. | | --record | | Run the following command unchanged and append one JSONL entry to FILE: arguments, stdout, stderr, exit code, versions, and hashes. A failed run is recorded too. | | --replay | | Re-run every entry of FILE and report reproduced, differs, or not replayable. Takes no command. --json after it selects the JSON report. Exit 0 when every entry is reproduced and unchanged, 3 when any differs, 1 otherwise. | | --show-record | | Print FILE as a transcript and run nothing. Takes no command. --json after it selects the JSON report. |

upt <command> --help prints that command. An unknown flag exits 2 and names the flag. docs/CLI.md is the flag reference: every command, every flag, one example each. cli/README.md keeps the exit-code and input-syntax notes. docs/architecture/PHYSICS_MAP.md is the rendered map (upt map --format=mermaid|dot|svg).

Installation

npm install universal-physics-tensor

Or install directly from GitHub:

# Clone and build locally
git clone https://github.com/danielsimonjr/universal-physics-tensor.git
cd universal-physics-tensor
npm install
npm run build

import { UniversalTensor } from 'universal-physics-tensor';
import type { PhysicalLaw, BridgeEquation } from 'universal-physics-tensor';

// Create a tensor instance
const tensor = new UniversalTensor({
  rank: 3, // Start simple
  scales: ['quantum', 'classical'],
  forces: ['electromagnetic', 'gravitational'],
});

// Register a known law (e.g., Schrödinger equation)
const schrodinger: PhysicalLaw = {
  id: 'schrodinger',
  name: 'Schrödinger Equation',
  equation: 'iℏ ∂ψ/∂t = Ĥψ',
  scales: ['quantum'],
  forces: ['electromagnetic'],
  symmetries: ['poincare'], // strictly Galilean for non-relativistic Schrödinger; 'poincare' used as placeholder (no 'galilean' in current Symmetry type)
  confidence: 1.0,
};
tensor.addLaw(schrodinger);

// Query laws applicable to the quantum regime
const quantumLaws = tensor.queryLaws({ scale: 'quantum' });
console.log(quantumLaws.map(l => l.name));

Note: evaluateRelation(id, bindings) is the public evaluation. A sourced number is { kind: 'value', value, dimension }. An unset coefficient is { kind: 'unset', formula } and is not a number. evaluateRelation('be-42', { mass: 1.989e30 }) is the Hawking temperature. evaluateRelation('be-16', { temperature: 300 }) is k_B T ln 2. The formal spec (Parts I–III) defines the underlying physics and AST encodings.

Core Concepts

The Universal Tensor

The tensor Π is decomposed (classified) into three components:

Π = L + B + E

Where:

• L (Laws): Known physics on the diagonal (QM, GR, SM, etc.)
• B (Bridges): Off-diagonal equations connecting regimes
• E (Emergence): Higher-order correlations producing emergent phenomena

Note on notation: the "+" here denotes disjoint union of catalog entries (each tensor slot holds content of exactly one category), not algebraic addition. The type system enforces this disjointness via the Cell discriminated union in src/core/cell.ts; UniversalTensor.populatedCells() is the canonical way to enumerate the populated catalog as typed Cell values. See also Part I §1.2 for the spec-level treatment. Different slots may hold quantities of different physical dimensions (e.g., a Lagrangian density and a decoherence rate) and cannot be summed numerically.

Bridge Equations

Bridge equations connect different physical regimes:

Quantum ↔ Classical:

• Decoherence Master Equation
• Mesoscopic Coherence Length

Information ↔ Geometry:

• Einstein trace reduction
• Holographic Quantum Error Correction

Microscopic ↔ Macroscopic:

• Universal Emergence Equation
• Complexity-Entropy Production Relation

Parts I–II of the formal specification write up the cross-domain bridges; a standard bridge is a catalog record and has no specification heading. The authoritative current catalog is the versioned, schema-checked JSON file data/bridge-catalog.json; its id range and counts are the generated Bridge catalog row of the Development Status table below. Part III covers algorithmic implementation.

Composing Bridges (v0.8.0)

Bridges are edges in a typed quantity graph, and compatible edges compose — with an exact dimensional check at the junction, validity domains carried through, and confidence demoted to the weakest link:

import { CATALOG_GRAPH, composeEdges, M_SUN_KG } from 'universal-physics-tensor';

const edge = (id: string) => CATALOG_GRAPH.find((e) => e.id === id)!;

// Hawking temperature (M → T_H) ∘ Landauer bound (T → E_min)
const erasureCost = composeEdges(edge('be-42'), edge('be-16'));
erasureCost.evaluate({ mass: M_SUN_KG }); // ≈ 5.9e-31 J — E_min(M) = ℏc³ln2/(8πGM)
erasureCost.confidence;                   // 'highly-speculative' (min of the operands)

GM_SUN_SI is the IAU 2015 nominal solar gravitational parameter, 1.3271244e20 m³/s². It is not G_SI * M_SUN_SI. parseUnit, convertValue, and UnitError read a number with a unit:

import { GM_SUN_SI, convertValue } from 'universal-physics-tensor';

GM_SUN_SI;                    // 1.3271244e20
convertValue('25degC', 'K'); // { value: 298.15, given: 'degC', affine: 'celsius' }

That derived relation — the minimum erasure cost at a black-hole horizon — is the framework's first derived (rather than encoded) literature-anchored result, pre-registered before implementation and pinned to relErr ≤ 10⁻¹² (see Part IX and docs/planning/v0.8.0-Design.md). A computable membership criterion (a bridge's endpoint quantities must differ in regime) now adjudicates the catalog — 152 bridges · 5 not-a-bridge · 3 unadjudicated — with rejections recorded in a reviewable negative catalog (src/bridges/rejected.ts).

Since v0.12, composition is also symbolic (composeSymbolic): bridges may carry an optional symbolic ExprNode form, and composing two of them substitutes one AST into the other's junction, dimensionally validated and numerically evaluable — not just a chained numeric closure. The composed form can be folded by MathTS simplify (optional peer), so CT-1 reduces to ℏc³ln2/(8πGM) with k_B cancelled. See upt symbolic --simplify.

Documentation

Formal Specification

Complete theoretical foundation of the Universal Physics Tensor Framework — see the specification index for the full reader's map and the spec revision history for how the documents evolved.

• Part I: Foundation & Mathematical Framework - Tensor structure, Π = L + B + E decomposition, Bridge Equations 11-20
• Part II: Extended Bridge Equation Catalog - Bridge Equations 21-54 across condensed matter, quantum biology, emergent spacetime
• Part III: Computational Implementation - Algorithms, information-theoretic bounds, ML integration
• Part IV: Validation & Implications - Experimental pathways, philosophical implications, applications
• Part V: Advanced Mathematics & Protocols - Category theory extensions, validation protocols, algorithmic analysis
• Part VI: Deployment & Governance - Implementation strategies, applications, governance frameworks
• Supplements - Part VII: Tensor Algebra · Part VIII: Metric Layer · Part IX: Composition · Part X: Curvature & Field Equations · Part XI: Proposed Equations (non-normative; machine-derived identity consequences, unadjudicated)

Planning & Development

• ROADMAP.md - Strategic direction: from bridge catalog to a verified, regime-aware physics atlas (phased, with exit criteria)
• Development Plan - Phased implementation roadmap
• Implementation Plan - Technical architecture
• System Requirements - Functional requirements

Architecture

Grounded in a real parse of the code. Every authored document ends with a ## Verification block, and repo_map.py check fails when a claim in one stops matching the source.

• Overview - What this is, what it does, how it is laid out
• Architecture - Why it is built this way; principles and key decisions
• Components - Each module, with real signatures
• Data Flow - How a request travels end to end
• API Reference - The public surface, per export
• File Inventory - Every tracked file, by zone and disposition
• Test Coverage - What is tested and what is not (generated)
• Dependency Graph - Who imports whom (generated)
• Unused Analysis - Files and exports with no importer (generated)
• Duplicate Symbols - Names defined in more than one file
• Physics Map - The bridge catalog as a map

Regenerate the three generated reports with npm run docs:deps; do not edit them by hand. The docs-fresh CI job fails if what is committed differs from a fresh generation.

Code Documentation

• Examples - Usage examples and code samples
• Documentation Index - Complete documentation guide

Benchmarks

UPT ships benchmark infrastructure via Vitest bench:

npm run bench        # interactive run (median, p99, ops/sec)
npm run bench:ci     # verbose run for CI log capture

Baseline results are recorded in docs/architecture/benchmarks.md. These are correctness-first baselines, not optimization targets. Comparative analysis has since landed: v0.6.0's BR-2 christoffelFn flat-array refactor delivered a measured 5-6× RK4 geodesic-integrator speedup (see CHANGELOG).

Development Status

The current version is recorded in package.json and on npm; release chronology lives in the CHANGELOG. This README deliberately carries no version number and no release-by-release counts — both drift, and nothing gates this file. It said v0.44.1 while the package was at 0.44.3.

The current machine-checked state is:

| Surface | Current state | |---|---| | Bridge catalog | 160 entries (BE-11…170): 124 established, 33 speculative, 3 highly speculative; the JSON artifact is freshness-tested against the TypeScript registry | | Empirical spine | 19 committed confrontations, exposed through upt confront with rigor/caveat metadata | | Composition layer | 158 bridge edges plus the canonical L-layer graph; dimensional, symbolic, discovery, consequence, and visualization tooling | | Canonical reference layer | 109 canonical equations used as the non-speculative answer-key layer for bridge recovery/linkage | | Architecture | Generated dependency graph reports 0 circular dependencies. The unused-analysis report lists 0 files and 77 exports with no importer. Both reports are regenerated by bun run docs:deps, and the docs-fresh job fails when they are stale | | Quality gates | Build, strict source+test TypeScript checks, full Vitest suite, active-plan audit, package-content smoke test, and nightly long-horizon GL4/Shapiro accuracy tests | | Formal references | 10 atlas bridges derive formally-proved from a reviewed lean4-physjs reference. 16 catalog equations carry a counted reference and do not light that tag. 119 state the catalogued equation, kind bridge; the catalog path passes that reference, so catalog evidence and edge evidence include formally-proved, except an unadjudicated row, which stays proposed. 3 carry a cross-check and 3 carry a property. Each kind is the PhysJS manifest entry's own field. Nested statements are not second references. The pin and the split are NOTES.md |

The project is engineering-complete for its stated goal: it is a computational laboratory and falsification/review instrument, not a claim that physics itself is complete or unified. New physics claims remain reviewable hypotheses and require external evidence/domain review before promotion.

Remaining frontier (not code-completion blockers)

• Physics-curation decisions and literature validation are tracked as bounded contributor tasks in CONTRIBUTING.md.
• Longer-horizon production ideas are explicitly non-blocking and live in docs/planning/Future-Production-Hardening.md.
• Historical implementation plans are preserved as records; the live code-completion ledger is ACTIVE.md and is what npm run audit:plans gates.

Contributing

See CONTRIBUTING.md — it lists bounded, no-code-required physics-review tasks (catalog adjudications, encoding checks against the literature, quantity-identification reviews) plus the dev quick-start, and explains the JSON catalog review surface.

Contributions are welcome, especially from:

• Physicists - Validate equations, suggest corrections, add physics insights
• Mathematicians - Verify formalism, improve rigor, suggest optimizations
• Engineers - Improve architecture, add features, optimize performance
• Educators - Create examples, improve documentation, develop tutorials

Background & Philosophy

This project emerged from a simple question: "If I had to design a test program set for all of physics, how would I structure it?"

In Test Program Set (TPS) development for avionics, we create systems that:

• Interface across multiple domains (hardware, software, physics)
• Bridge different measurement scales (micro to macro)
• Maintain consistency across transformations
• Enable diagnostic troubleshooting

The same systems thinking applies to physics:

• Known laws = verified test procedures (diagonal elements)
• Bridge equations = interface adapters (off-diagonal elements)
• Emergence = higher-order system behaviors (correlations)
• Validation = experimental data matching (consistency checks)

This is an engineer's approach to theoretical physics — systematic, organized, and open to collaboration with domain experts.

License

Code: MIT License - see LICENSE. Exported atlas data (data/atlas/): CC BY 4.0 - see LICENSE-DATA.

Author

Daniel Simon Jr.

• Systems Engineer specializing in Test Program Set Development
• Electrical Engineering, University of Texas at Dallas
• Currently: Senior Test Engineer, Lockheed Martin
• Interests: Integrating Philosophy, Science, and Technology

Connect:

• GitHub: @danielsimonjr
• LinkedIn: danielsimonjr
• Substack: Simon Says!
• Website: danielsimonjr.github.io/resume

Acknowledgments

This work builds on the shoulders of giants:

• Tensor formalism from differential geometry
• Bridge equations inspired by effective field theory
• Information-theoretic insights from quantum information theory
• Emergence concepts from condensed matter physics
• Systems thinking from engineering practice

Disclaimer: This is an exploratory computational framework, not peer-reviewed physics research. All results should be validated against experimental data and theoretical physics literature. Collaboration with professional physicists is actively sought to improve accuracy and rigor.