alexisrx96/physure

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.