SPhysics 0.6.0-dev

<p align="center"> <img src="src/code/SPhysics/icon.png" alt="SPhysics" width="50"/> </p>

SPhysics

Physics for .NET, written against generic math. Every formula is generic over the numeric type, so the same call site works for double, float, decimal or Half without overloads or casting. Builds on top of SMath.

Documentation

Full API reference, guides, and performance benchmarks are available on the Documentation Website.

Design

Generic over the number type. Constraints express the physics rather than a concrete type: a formula needing a square root asks for IRootFunctions<N>, one needing only addition asks for INumberBase<N>. Passing a type that cannot support the operation is a compile error.

Static and allocation free. There are no wrapper structs for quantities or vectors. Values are plain scalars and tuples, so they stay on the stack and interoperate with any other library. All entry points are static.

Names that read as the formula. Types are named after the quantity being computed, giving call sites like GravitationalForce.Outside(m1, m2, r) or KineticEnergy.Linear(m, v).

Contents

Setup

<PackageReference Include="SPhysics" Version="X.X.X" />

Replace X.X.X with the current version from NuGet. The package targets net8.0 and runs on any newer runtime.

Usage

Gravitation, with the numeric type inferred from the arguments:

using SPhysics;
using SPhysics.CelestialMechanics;

const double G = 6.67430e-11;

// Newton's law of universal gravitation between two point bodies
var force = GravitationalForce.Outside(mass1: 5.972e24, mass2: 7.342e22, distance: 3.844e8);

// Escape velocity from a spherically symmetric body of given mass and radius
var vEsc = EscapeVelocity.Eval(mass: 5.972e24, distance: 6.371e6, gravitationalConstant: G);

Energy and motion:

using SPhysics;

// Linear kinetic energy
var keLinear = KineticEnergy.Linear(mass: 1.5, velocity: 12.0);

// Spinning kinetic energy
var keSpin = KineticEnergy.Spinning(momentOfInertia: 0.4, angularVelocity: 3.0);

// Gravitational potential energy between two bodies
var epg = GravitationalEnergy.Eval(mass1: 5.972e24, mass2: 1.5, distance: 6.371e6);

N-body force accumulation into a stack allocated span:

using SPhysics;

const double G = 6.67430e-11;

Span<(double X, double Y, double Mass)> bodies = stackalloc (double, double, double)[]
{
    (0, 0, 5.972e24),
    (3.844e8, 0, 7.342e22),
    (1.496e11, 0, 1.989e30),
};

var (fx, fy) = GravitationalForce.Eval<double>(bodies, index: 0, gravitationConst: G);

Performance

NBodyGravity evaluates all pairs, O(n^2), in one of two kernels:

• Vectorized across the pairs: one Vector<T> evaluates 8 float or 4 double pairs at once with AVX2. The overloads over tuples copy the components into pooled spans first; NBodyGravity.Soa takes them in separate spans (structure of arrays) and skips the copies.
• Scalar, NBodyGravity.Scalar: pair by pair on the tuples, no copies.

Time of one evaluation, float bodies, a gravitational constant per body (NBodyGravityBenchmark, x64 with AVX2):

• The scalar kernel is faster below about 16 bodies; from there the vectorized one wins, 7x for thousands of bodies. The caller picks the kernel for its body count.
• The kernels differ in rounding. The vectorized one sums the pulls on a body in several lanes, so its rounding depends on the vector width: reproducible on one machine, not across machines with different vector widths. The scalar one is reproducible everywhere.
• VelocityVerlet.Soa advances the structure of arrays, bitwise identical to the tuple steps.

Contributing

Ideas, bug reports and pull requests are welcome. Open an issue to propose a change, or send a pull request directly.

License

Project is under MIT license.