# Physics in Parallel (PiP)
**Write the physics. Reuse the numerical machinery.**
Scientific software needs more than equations: numerical storage, random
sampling, spatial bookkeeping, particle state, and parallel execution all take
work. PiP supplies reusable Rust building blocks so you can spend more time on
your model and less time rebuilding that infrastructure.
## From numerical arrays to particle simulations
| Numerical containers | Tensors, matrices, and lists of vectors with explicit dense or sparse storage. |
| Reproducible randomness | Explicit RNG methods and seeds, sampling, and indexed generation where supported. |
| Spatial structure | Boundaries, square lattices, pair generation, and neighbor lists. |
| Particle dynamics | Canonical attributes, spring and power-law networks, integrators, thermostats, and observations. |
| Parallel numerical work | Operations using your active Rayon pool, participation limits, and internal SIMD dispatch. |
| Data interchange | Validated Serde representations and an optional NumPy conversion helper. |
Use just the numerical foundations, add the ready-made particle models, or opt
into advanced storage and generic engines. Your application owns its equations,
units, time loop, configuration, and saved results.
[See a complete simulation](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/3-first-simulation.md) ·
[Explore the API](https://docs.rs/physics_in_parallel/4.1.1-alpha/physics_in_parallel/) ·
[Browse examples](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/EXAMPLES.md)
## Give your AI assistant a smaller job
Describe the model, its shapes, boundary conditions, seeds, and numerical
constraints. An AI assistant can assemble documented PiP APIs instead of
inventing storage, sampling, or particle infrastructure. Reusing those APIs can
reduce generated code and the tokens spent explaining and repairing it.
Scientific choices still need your review.
**All AI assistants working with PiP must read
[docs/AGENTS.md](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/AGENTS.md) before proposing or changing an integration.**
It records API boundaries, numerical invariants, reproducibility requirements,
and validation expectations.
**Migrating an existing project? The instructions are already available:**
[the project migration procedure](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/AGENTS.md#migrate-an-existing-project-to-pip)
maps handwritten numerical infrastructure to PiP, preserves the physics, and
explains how to validate the transition. Start with one bounded component and
expand after its results agree with the baseline.
## Start here
Install the published package with an exact alpha pin:
```toml
[dependencies]
physics_in_parallel = "=4.1.1-alpha"
```
Rust **1.97 or newer** is required. The
[numbered guide](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/README.md) takes you from installation to a working
simulation, then into each numerical subsystem. Every chapter links to the next.
1. [Overview](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/1-overview.md)
2. [Installation](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/2-installation.md)
3. [Your first simulation](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/3-first-simulation.md)
4. [Tensors, matrices, and vectors](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/4-tensors-matrices-and-vectors.md)
5. [Randomness and sampling](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/5-randomness-and-sampling.md)
6. [Spaces, lattices, and pairs](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/6-spaces-lattices-and-pairs.md)
7. [Particle state](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/7-particle-state.md)
8. [Forces, integration, and thermostats](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/8-forces-integration-and-thermostats.md)
9. [Serialization and NumPy](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/9-serialization-and-numpy.md)
10. [Parallelism and performance](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/10-parallelism-and-performance.md)
11. [Advanced extensions](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/11-advanced-extensions.md)
12. [AI-assisted integration](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/guide/12-ai-assisted-integration.md)
## Performance you can inspect
PiP combines reusable output buffers, explicit storage choices, parallel work,
and runtime SIMD selection. The
[performance guide](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/PERFORMANCE.md),
[benchmark results](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/BENCHMARKS.md), and
[independent correctness checks](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/CORRECTNESS.md) explain the measured
behavior and numerical contracts. Choose settings against your actual workload.
## Alpha compatibility
**The 4.1 generation replaces the 3.x API.** Public APIs and serialized formats
may change between alpha releases; pin the exact version and review
[release migration notes](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/RELEASES.md) before upgrading old code or
data. Version **4.1.1-alpha is a documentation patch** with unchanged runtime
code, public API, and serialized formats from 4.1.0-alpha.
[Documentation index](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/README.md) ·
[Troubleshooting](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/docs/troubleshooting.md) ·
[License](https://github.com/dingyisun0101/Physics-in-Parallel/blob/v4.1.1-alpha/LICENSE)