# alexisrx96/physure architecture

> Architecture diagram of the GitHub repository alexisrx96/physure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexisrx96/physure
- Repository: https://github.com/alexisrx96/physure

## Overview

#### Purpose and entry points
Physure is a unit-aware scientific-computing platform centered on a Rust engine for dimensional correctness and uncertainty propagation. It is delivered independently as:
- Rust library: `physure-core/src/lib.rs`
- Python package and CLI: `physure-python/physure/__init__.py`, `physure-python/physure/__main__.py`
- PHS DSL binary: `physure-cli/src/main.rs`
- JVM/JNI package: `physure-java/src/main/java/com/physure/NativeEngine.java`
- PHS language server: `physure-lsp/src/main.rs`

The Cargo workspace root (`Cargo.toml`) coordinates Rust packages.

#### Shared physics engine
`physure-core` is the authoritative implementation; frontends should translate into its model rather than duplicate dimensional or uncertainty logic.
- Quantities and equations: `physure-core/src/quantity.rs`, `physure-core/src/equation.rs`
- Unit definitions, parsing, conversion, and registry: `physure-core/src/units/mod.rs`, `physure-core/src/units/parser.rs`, `physure-core/src/units/registry.rs`
- Rational dimensions and numerical primitives: `physure-core/src/math/dimension_vector.rs`, `physure-core/src/linalg.rs`

The core accepts values plus units, validates compatible arithmetic, computes resultant dimensions/conversions, and returns typed quantities or domain errors.

#### Uncertainty and covariance pipeline
Uncertainty is a first-class execution path coupled to quantity operations. Correlation lineage is represented in a sparse covariance store, then propagation behavior is selected by mode/model.
- Sparse covariance storage and pruning: `physure-core/src/covariance/store.rs`, `physure-core/src/covariance/pruning.rs`
- Models and propagation modes: `physure-core/src/uncertainty/mod.rs`, `physure-core/src/uncertainty/gaussian.rs`, `physure-core/src/uncertainty/monte_carlo.rs`
- Higher-order and alternative numerical support: `physure-core/src/math/hessian_propagation.rs`, `physure-core/src/uncertainty/unscented.rs`

This boundary keeps correlated uncertainty semantics consistent across Rust, Python, PHS, and Java.

#### Python application and compute backends
The Python package provides the primary ergonomic API, domain objects, startup/configuration, and optional integrations. It bridges to Rust through the native extension at `physure-python/src/lib.rs`.
- Factory/context/services: `physure-python/physure/application/factories.py`, `physure-python/physure/application/context.py`, `physure-python/physure/application/startup.py`
- Measurement-domain API: `physure-python/physure/domain/measurement/quantity.py`, `physure-python/physure/domain/measurement/system.py`
- Dispatchable execution backends: `physure-python/physure/backends/core_backend.py`, `physure-python/physure/backends/numpy_backend.py`, `physure-python/physure/backends/torch_backend.py`

Optional NumPy, PyTorch, JAX, pandas, SymPy, and chemistry integrations remain outside the core domain boundary.

#### JIT and symbolic execution
For compiled ML workloads, tracing validates units before execution and delegates runtime array operations to selected tensor backends.
- JIT tracing: `physure-python/physure/_jit/tracer.py`
- Backend dispatch/autograd contracts: `physure-python/physure/core/dispatcher.py`, `physure-python/physure/core/autograd.py`
- Native/symbolic expression graph: `physure-python/physure/domain/symbolic/native.py`, `physure-python/physure/domain/symbolic/graph.py`

The intended flow is Python function → trace-time quantity/dimension validation → raw JAX or PyTorch compiled execution, avoiding per-operation unit overhead.

#### PHS language, CLI, and editor boundary
PHS is a standalone language layer over the shared physics semantics. The script engine owns language parsing, resolution, interpretation, symbolic operations, and source generation.
- Grammar/front end: `physure-script/src/phs.pest`, `physure-script/src/lexer.rs`, `physure-script/src/parser.rs`
- Runtime and resolution: `physure-script/src/interpreter.rs`, `physure-script/src/resolver.rs`
- Transpilers: `physure-script/src/codegen/python.rs`, `physure-script/src/codegen/rust.rs`, `physure-script/src/codegen/java.rs`

`physure-cli` exposes this through batch/REPL/TUI/web/report interfaces (`physure-cli/src/main.rs`, `physure-cli/src/tui.rs`, `physure-cli/src/web.rs`); `physure-lsp` supplies editor protocol support.

#### Runtime and release surface
Material runtimes are Rust, CPython via PyO3/native wheels, JVM through JNI, and optional NumPy/PyTorch/JAX ecosystems. Arrow serialization is implemented in `physure-core/src/covariance/arrow.rs` and `physure-core/src/serialization.rs`. Separate GitHub workflows publish the core, Python/CLI, and Java artifacts: `.github/workflows/core-release.yml`, `.github/workflows/release.yml`, `.github/workflows/java-release.yml`.

Main entry points: [`physure-core/src/lib.rs`](https://github.com/alexisrx96/physure/blob/main/physure-core/src/lib.rs) (physure-core), [`physure-script/src/parser.rs`](https://github.com/alexisrx96/physure/blob/main/physure-script/src/parser.rs) (PHS script engine), [`physure-core/src/quantity.rs`](https://github.com/alexisrx96/physure/blob/main/physure-core/src/quantity.rs) (Quantities & equations), [`physure-python/physure/_jit/tracer.py`](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/_jit/tracer.py) (JIT tracing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Rust physics engine"]
  node_core{{"physure-core<br/>Rust library<br/>[lib.rs]"}}
  node_quantities["Quantities &amp; equations<br/>core domain<br/>[quantity.rs]"]
  node_units["Units &amp; registry<br/>unit system<br/>[mod.rs]"]
  node_dimensions["Dimensions &amp; linalg<br/>math primitives"]
  node_covariance[("Sparse covariance<br/>correlation store<br/>[store.rs]")]
  node_uncertainty["Uncertainty propagation<br/>propagation models<br/>[mod.rs]"]
  node_serialization["Arrow serialization<br/>data interchange<br/>[arrow.rs]"]
end

subgraph group_python["Python runtime"]
  node_python_api["Python package &amp; CLI<br/>CPython API<br/>[__init__.py]"]
  node_python_app["Application services<br/>factory/context<br/>[factories.py]"]
  node_measurements["Measurement domain<br/>Python domain API<br/>[quantity.py]"]
  node_pyo3["Native extension<br/>PyO3 bridge<br/>[lib.rs]"]
  node_backends["Compute backends<br/>backend dispatch<br/>[core_backend.py]"]
  node_jit["JIT tracing<br/>compiled ML path<br/>[tracer.py]"]
  node_symbolic["Symbolic graph<br/>expression graph<br/>[graph.py]"]
end

subgraph group_phs["PHS language tooling"]
  node_phs_engine{{"PHS script engine<br/>language runtime<br/>[parser.rs]"}}
  node_transpilers["PHS transpilers<br/>code generation<br/>[python.rs]"]
  node_phs_cli["PHS CLI<br/>DSL binary<br/>[main.rs]"]
  node_lsp["PHS language server<br/>editor protocol<br/>[main.rs]"]
end

subgraph group_jvm["JVM integration"]
  node_jni["JVM/JNI package<br/>Java native bridge<br/>[NativeEngine.java]"]
end

node_workspace["Cargo workspace<br/>[Cargo.toml]"]

node_workspace -->|"builds"| node_core
node_workspace -->|"builds"| node_phs_engine
node_workspace -->|"builds"| node_phs_cli
node_core -->|"implements"| node_quantities
node_core -->|"implements"| node_units
node_core -->|"uses"| node_dimensions
node_quantities -->|"validates with"| node_units
node_quantities -->|"propagates through"| node_uncertainty
node_uncertainty -->|"tracks correlations"| node_covariance
node_core -->|"serializes"| node_serialization
node_python_api -->|"initializes"| node_python_app
node_python_app -->|"exposes"| node_measurements
node_measurements -->|"uses native semantics"| node_pyo3
node_pyo3 -->|"calls"| node_core
node_python_api -->|"dispatches"| node_backends
node_jit -->|"builds"| node_symbolic
node_jit -->|"runs compiled tensors"| node_backends
node_jit -.->|"validates dimensions"| node_quantities
node_phs_engine -->|"uses shared semantics"| node_core
node_phs_engine -->|"generates targets"| node_transpilers
node_phs_cli -->|"executes"| node_phs_engine
node_lsp -->|"analyzes"| node_phs_engine
node_jni -->|"invokes via JNI"| node_core

click node_workspace "https://github.com/alexisrx96/physure/blob/main/Cargo.toml"
click node_core "https://github.com/alexisrx96/physure/blob/main/physure-core/src/lib.rs"
click node_quantities "https://github.com/alexisrx96/physure/blob/main/physure-core/src/quantity.rs"
click node_units "https://github.com/alexisrx96/physure/blob/main/physure-core/src/units/mod.rs"
click node_dimensions "https://github.com/alexisrx96/physure/blob/main/physure-core/src/math/dimension_vector.rs"
click node_covariance "https://github.com/alexisrx96/physure/blob/main/physure-core/src/covariance/store.rs"
click node_uncertainty "https://github.com/alexisrx96/physure/blob/main/physure-core/src/uncertainty/mod.rs"
click node_serialization "https://github.com/alexisrx96/physure/blob/main/physure-core/src/covariance/arrow.rs"
click node_python_api "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/__init__.py"
click node_python_app "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/application/factories.py"
click node_measurements "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/domain/measurement/quantity.py"
click node_pyo3 "https://github.com/alexisrx96/physure/blob/main/physure-python/src/lib.rs"
click node_backends "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/backends/core_backend.py"
click node_jit "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/_jit/tracer.py"
click node_symbolic "https://github.com/alexisrx96/physure/blob/main/physure-python/physure/domain/symbolic/graph.py"
click node_phs_engine "https://github.com/alexisrx96/physure/blob/main/physure-script/src/parser.rs"
click node_transpilers "https://github.com/alexisrx96/physure/blob/main/physure-script/src/codegen/python.rs"
click node_phs_cli "https://github.com/alexisrx96/physure/blob/main/physure-cli/src/main.rs"
click node_lsp "https://github.com/alexisrx96/physure/blob/main/physure-lsp/src/main.rs"
click node_jni "https://github.com/alexisrx96/physure/blob/main/physure-java/src/main/java/com/physure/NativeEngine.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core,node_quantities,node_units,node_dimensions,node_covariance,node_uncertainty,node_serialization toneBlue
class node_python_api,node_python_app,node_measurements,node_pyo3,node_backends,node_jit,node_symbolic toneAmber
class node_phs_engine,node_transpilers,node_phs_cli,node_lsp toneMint
class node_jni toneRose
class node_workspace toneNeutral
```

## Components

### Rust physics engine

Authoritative dimensional and uncertainty semantics.

- [physure-core](https://github.com/alexisrx96/physure/blob/main/physure-core/src/lib.rs): Rust library · Shared typed quantity engine. · `physure-core/src/lib.rs`
- [Quantities & equations](https://github.com/alexisrx96/physure/blob/main/physure-core/src/quantity.rs): core domain · `physure-core/src/quantity.rs`
- [Units & registry](https://github.com/alexisrx96/physure/blob/main/physure-core/src/units/mod.rs): unit system · Parses, converts, and registers units. · `physure-core/src/units/mod.rs`
- [Dimensions & linalg](https://github.com/alexisrx96/physure/blob/main/physure-core/src/math/dimension_vector.rs): math primitives · `physure-core/src/math/dimension_vector.rs`
- [Sparse covariance](https://github.com/alexisrx96/physure/blob/main/physure-core/src/covariance/store.rs): correlation store · Preserves correlation lineage and pruning. · `physure-core/src/covariance/store.rs`
- [Uncertainty propagation](https://github.com/alexisrx96/physure/blob/main/physure-core/src/uncertainty/mod.rs): propagation models · Selects Gaussian, Monte Carlo, and alternative propagation. · `physure-core/src/uncertainty/mod.rs`
- [Arrow serialization](https://github.com/alexisrx96/physure/blob/main/physure-core/src/covariance/arrow.rs): data interchange · `physure-core/src/covariance/arrow.rs`

### Python runtime

Ergonomic API, native bridge, and accelerated execution.

- [Python package & CLI](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/__init__.py): CPython API · Primary ergonomic user surface. · `physure-python/physure/__init__.py`
- [Application services](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/application/factories.py): factory/context · Initializes domain services and configuration. · `physure-python/physure/application/factories.py`
- [Measurement domain](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/domain/measurement/quantity.py): Python domain API · `physure-python/physure/domain/measurement/quantity.py`
- [Native extension](https://github.com/alexisrx96/physure/blob/main/physure-python/src/lib.rs): PyO3 bridge · Bridges CPython calls into Rust. · `physure-python/src/lib.rs`
- [Compute backends](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/backends/core_backend.py): backend dispatch · Selects core, NumPy, or Torch execution. · `physure-python/physure/backends/core_backend.py`
- [JIT tracing](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/_jit/tracer.py): compiled ML path · Validates dimensions before tensor compilation. · `physure-python/physure/_jit/tracer.py`
- [Symbolic graph](https://github.com/alexisrx96/physure/blob/main/physure-python/physure/domain/symbolic/graph.py): expression graph · `physure-python/physure/domain/symbolic/graph.py`

### PHS language tooling

Standalone DSL, user interfaces, and editor support.

- [PHS script engine](https://github.com/alexisrx96/physure/blob/main/physure-script/src/parser.rs): language runtime · Parses, resolves, interprets, and generates PHS programs. · `physure-script/src/parser.rs`
- [PHS transpilers](https://github.com/alexisrx96/physure/blob/main/physure-script/src/codegen/python.rs): code generation · Generates Python, Rust, and Java targets. · `physure-script/src/codegen/python.rs`
- [PHS CLI](https://github.com/alexisrx96/physure/blob/main/physure-cli/src/main.rs): DSL binary · Provides batch, REPL, TUI, web, and report interfaces. · `physure-cli/src/main.rs`
- [PHS language server](https://github.com/alexisrx96/physure/blob/main/physure-lsp/src/main.rs): editor protocol · `physure-lsp/src/main.rs`

### JVM integration

- [JVM/JNI package](https://github.com/alexisrx96/physure/blob/main/physure-java/src/main/java/com/physure/NativeEngine.java): Java native bridge · `physure-java/src/main/java/com/physure/NativeEngine.java`

### Other components

- [Cargo workspace](https://github.com/alexisrx96/physure/blob/main/Cargo.toml): workspace · Coordinates Rust packages. · `Cargo.toml`

## Connections

- Cargo workspace → physure-core: builds
- Cargo workspace → PHS script engine: builds
- Cargo workspace → PHS CLI: builds
- physure-core → Quantities & equations: implements
- physure-core → Units & registry: implements
- physure-core → Dimensions & linalg: uses
- Quantities & equations → Units & registry: validates with
- Quantities & equations → Uncertainty propagation: propagates through
- Uncertainty propagation → Sparse covariance: tracks correlations
- physure-core → Arrow serialization: serializes
- Python package & CLI → Application services: initializes
- Application services → Measurement domain: exposes
- Measurement domain → Native extension: uses native semantics
- Native extension → physure-core: calls
- Python package & CLI → Compute backends: dispatches
- JIT tracing → Symbolic graph: builds
- JIT tracing → Compute backends: runs compiled tensors
- JIT tracing → Quantities & equations: validates dimensions
- PHS script engine → physure-core: uses shared semantics
- PHS script engine → PHS transpilers: generates targets
- PHS CLI → PHS script engine: executes
- PHS language server → PHS script engine: analyzes
- JVM/JNI package → physure-core: invokes via JNI