Crate rust_physics_engine 

A zero-dependency library for physics, mathematics and engineering computation.

What this is for

Every routine here is written so that something about it can be checked: against a closed form, against a conservation law, against an independent implementation of the same quantity, or against an exact identity over integers. A test that only asserts a function ran is not evidence. Where a result is approximate its error has a stated bound derived from the method; where it is exact the assertion uses ==.

That principle decides the shape of the API. Solvers return Result rather than panicking on non-convergence, so a caller can tell “did not converge” from “converged to this”. Functions validate their arguments, and the guards are written !(x > 0.0) rather than x <= 0.0 so that NaN is rejected too. Physical constants come from one table, math::constants, and the values fixed by the 2019 SI redefinition are exact.

Finding your way around

The crate is wide – 71 top-level modules. docs/MODULE_MAP.md in the repository is a generated map of every module with its size and summary. The rough shape:

Area	Modules
Numeric primitives	core, math, linalg, numerical, special
Exact and symbolic	exact, discrete, graph, codes
Classical physics	classical, gravitation, solid_mechanics, continuum_mechanics, resonance
Thermal and statistical	thermodynamics, statistical_mechanics, radiation
Electromagnetic	electromagnetism, electronics, rf, photonics, plasma, magnetohydrodynamics
Waves and signals	waves, optics, acoustics, transforms, dsp, signal_processing, audio
Fluids	fluids, cfd, fluid_instabilities, propulsion
Modern physics	relativity, general_relativity, quantum, particle_physics, nuclear, neutronics
Space	astrophysics
PDE solvers	fem, sim, fields, vector_calculus
Life and chemistry	chemistry, biophysics
Probability and data	statistics, stochastic, monte_carlo, information_theory, learn
Decisions	optimization, finance
Geometry	geometry, curves, trigonometry, quaternion, manifold, spatial, mesh
Patterns	fractals, patterns, nonlinear
Reference and utility	units, materials, color_science, control_systems, atmosphere, geophysics, error

Conventions

Units are SI unless a function’s documentation says otherwise, and angles are radians. units converts, and units::quantity carries dimensions in the type so that adding a velocity to a time is an error rather than a number.

f64 throughout, except where exactness is the point: exact works over arbitrary-precision integers and rationals, and units::dimensional computes null spaces over exact::rational::Rational because a group of quantities is exactly dimensionless or it is not.

Randomness comes from monte_carlo::Rng, a linear congruential generator that returns its raw state. The low bits therefore have a short period, so use monte_carlo::Rng::below for any small-integer draw rather than next_u64() % n.

Example

use rust_physics_engine::units::quantity::{Dim, Quantity};

let v = Quantity::new(3.0, Dim::new(1, 0, -1, 0, 0, 0, 0)); // m/s
let t = Quantity::new(2.0, Dim::TIME);
assert_eq!(v.mul(&t).unwrap().dim, Dim::LENGTH);  // exactly a length
assert!(v.add(&t).is_err());                      // and not a time

Modules

acoustics

Room acoustics, psychoacoustic scales, and musical pitch.

astrophysics

Astrodynamics and astrophysics.

atmosphere

The standard atmosphere, humidity, and near-surface wind.

audio

Audio synthesis, analysis, effects, and I/O.

biophysics

Biophysics: the elementary membrane, transport and mechanics relations here, with the population-scale models in submodules.

cfd

Computational fluid dynamics: staggered grids, advection schemes, and (in later modules) incompressible solvers, shallow water, SPH, LBM, level sets, and turbulence models.

chemistry

Reaction kinetics, chemical thermodynamics and electrochemistry.

classical

Newtonian mechanics: kinematics, dynamics, and the harmonic oscillator.

codes

Error detection, error correction, compression, and the arithmetic cryptography is built on.

color_science

Colour: the standard spaces, the transforms between them, and perceptual measures.

continuum_mechanics

Stress and strain as tensors, and the yield criteria built on them.

control_systems

Linear control: system response, stability margins and PID tuning.

core

Pure numeric building blocks: compensated summation, forward-mode automatic differentiation, and interval arithmetic.

curves

Plane curves: conics, Bézier curves, and parametric families.

discrete

Discrete mathematics: primes and factorization, elementary and analytic number theory, counting and enumeration, integer partitions, integer sequences, and union-find.

dsp

Digital signal processing: window functions, FIR/IIR filter design, resampling, and phase utilities.

electromagnetism

Classical electromagnetism, from Coulomb’s law to radiating dipoles.

electronics

Semiconductor device physics.

error

Error types shared by the numerical solvers.

exact

Exact arithmetic: arbitrary-precision integers, exact rationals, arbitrary-precision binary floating point, polynomials, and continued fractions.

fem

Finite elements, finite-difference time domain, and spectral methods.

fields

Uniform-grid scalar fields.

finance

Quantitative finance: derivative pricing, interest rates, portfolio construction and risk measurement.

fluid_instabilities

When a fluid configuration stops being stable, and how fast it comes apart.

fluids

Fluid statics and single-phase flow.

fractals

Fractals: escape-time sets, attractors, automata and noise.

general_relativity

General relativity: black holes and cosmology.

geometry

Areas, volumes and surface areas of the standard shapes.

geophysics

The solid Earth: gravity, seismology, and heat.

graph

Graphs: representation and structure, shortest paths, network flow, matchings, spectral graph theory, colouring, and drawing.

gravitation

Newtonian gravity and two-body orbits.

information_theory

Shannon information: entropy, divergence, and channel capacity.

learn

Learning algorithms, written to be read rather than to be fast.

linalg

Dense and sparse linear algebra.

magnetohydrodynamics

Magnetohydrodynamics: a conducting fluid and the field frozen into it.

manifold

Manifolds and higher-dimensional geometry: generic n-dimensional vectors and tensors, metric-driven curvature, and (in later modules) geodesics, Lie groups, constant-curvature spaces, polytopes, Clifford algebras, embeddings, discrete exterior calculus, and spacetimes.

materials

Reference property tables.

math

Vectors and the crate’s table of physical constants.

mesh

Indexed triangle meshes: construction, mass properties, cleanup, spatial queries, and OBJ/STL interchange.

monte_carlo

Monte Carlo methods and the random number generator behind them.

neutronics

Reactor physics: criticality, neutron diffusion, and shielding.

nonlinear

Chaos in low-dimensional systems.

nuclear

Radioactive decay, nuclear binding, and dosimetry.

numerical

Numerical methods: quadrature, root finding, ODE solvers, and interpolation. Submodules are re-exported so historical paths such as crate::numerical::trapezoid keep working.

optics

Geometric and wave optics.

optimization

Optimization: continuous, combinatorial, and strategic.

particle_physics

Relativistic kinematics and scattering for particle collisions.

patterns

Geometric patterns: polygon algorithms, sampling distributions, phyllotaxis, tilings, symmetry groups, packings, space-filling curves, polyhedra, aperiodic tilings, and knots.

photonics

Laser beams, optical fibre, and interferometry.

plasma

Plasma parameters: the characteristic lengths, frequencies and speeds.

propulsion

Rocket propulsion and impulsive orbital transfers.

quantum

Quantum mechanics: the elementary relations here, with the wavefunction machinery and the Schrodinger solvers in submodules.

quaternion

Unit quaternions for 3-D rotation.

radiation

Thermal radiation and radiative transfer.

relativity

Special relativity.

resonance

Resonance and vibration: single and coupled oscillators, acoustic and electromagnetic cavities, nonlinear resonance, and structural dynamics.

rf

Radio-frequency engineering: links, lines and noise.

signal_processing

Time-domain signal operations and test waveforms.

sim

Time-stepping simulation engines.

solid_mechanics

Strength of materials: stress, strain, elastic constants and beams.

spatial

Spatial data structures, transforms, geometric primitives, and queries.

special

Special functions: error function family, gamma family, and beta functions.

statistical_mechanics

Statistical mechanics: the elementary relations here, with lattice models and Monte Carlo in submodules.

statistics

Statistics: descriptive measures, probability distributions, and Fourier utilities. Submodules are re-exported so historical paths such as crate::statistics::mean keep working.

stochastic

Stochastic processes: Markov chains, Markov chain Monte Carlo, and hidden state models.

thermodynamics

Thermodynamics: gases, heat transfer, cycles and phase change.

transforms

Discrete transforms: FFT (any length), DCT/DST, STFT, wavelets, Hilbert, Laplace inversion, Radon, and spectral estimation.

trigonometry

Triangle solving, trigonometric identities, and hyperbolic functions.

units

Unit conversions, dimensional analysis and the CODATA constants.

vector_calculus

Vector calculus operators and field theory for physics grids.

waves

Wave propagation: mechanical, acoustic and seismic.