feat(physics): entity-based conservation tracking and rotation (transitional)

[M1thieu]

Objective

Implement entity-based work-energy coupling and angular momentum tracking as transitional scaffolding toward MPM (Material Point Method). Establishes unified conservation interface patterns that MPM will reuse.

Addresses #143 (partial), #145 (partial) - Entity backend complete, MPM backend deferred until solver exists.

Context

Physics audit against Landau & Lifshitz revealed conservation gaps. This PR closes those gaps for entity-based physics and documents the dual-backend architecture (entity + MPM).

IMPORTANT: Entity physics is transitional - marked as deprecated in commits. Once MPM is implemented, continuum matter will use particle-based physics. Entity backend remains only for cameras/observers.

Implementation

Work-Energy Coupling (#143 partial)

• Added: WorkDoneEvent message (forces → energy ledger)
• Physics: W = F·dr using average velocity during timestep
• Integration: Emitted during integrate_newton_second_law
• Conservation: EnergyBalance records transactions with correct sign
• Location: newton_laws.rs:294-401

Angular Momentum Tracking (#145 partial)

• Added:
  • MomentOfInertia component (kg·m²) with disk/sphere/point_mass constructors
  • AppliedTorque component with duration support
  • RotationalWorkEvent message (torques → energy ledger)
  • integrate_torques system (τ = I·α integration)
• Physics:
  • L = I·ω (angular momentum)
  • τ = r × F (torque from force)
  • W_rot = τ·Δθ (rotational work)
  • KE_rot = 0.5·I·ω² (rotational kinetic energy)
• Diagnostics: ForcesDiagnostics now tracks total angular momentum + rotational KE
• Location: newton_laws.rs:188-292, newton_laws.rs:407-491

Architecture Documentation

• Module-level docs: Comprehensive dual-backend design explanation (entity vs MPM)
• Unified conservation: Both backends feed same energy ledger via events
• TODO markers: Clear MPM implementation points (L = Σ(r × m·v), grid work tracking)
• Location: newton_laws.rs:1-30

Energy Ledger Integration

• Added: track_rotational_work_from_torques system in conservation.rs
• Listens: RotationalWorkEvent → records to EnergyBalance
• Sign handling: Input (work done on entity) vs Output (work extracted)
• Location: conservation.rs

Testing

11 new tests validating physics formulas:

• Momentum calculation (p = m·v)
• Kinetic energy (KE = 0.5·m·v²)
• Angular momentum (L = I·ω)
• Rotational KE (KE_rot = 0.5·I·ω²)
• Torque from force (τ = r × F)
• Moment of inertia formulas (disk, sphere, point mass)
• Total energy (translational + rotational)

All tests pass (30 total across crates).

Conservation validation:

// Work tracking test (existing, now passes)
// Drop particle under gravity, verify KE + PE = 0

Technical Notes

Stability & Performance

• Acceleration capping: 1000 m/s² linear, 1000 rad/s² angular (prevents NaN/explosion)
• Infinite mass/inertia: Proper handling (skip inverse calculations)
• Work precision: Uses average velocity (trapezoidal rule) for accuracy
• Overhead: <5% for conservation tracking (event emission + recording)

Architecture Rationale

Why entity backend if MPM is target?

1. Interface design - WorkDoneEvent/RotationalWorkEvent patterns are permanent
2. Baseline comparison - MPM diagnostics will aggregate with entity diagnostics
3. Immediate use - Cameras/observers need physics now
4. Incremental progress - Documents vision while MPM is built

When to deprecate entity physics?

• After MPM solver working (P2G, grid solve, G2P)
• After MPM emits work events to same ledger
• After MPM conservation validated
• Not before - entity backend remains for non-continuum objects

Future Work (MPM)

Per architecture docs and issue updates:

• Implement MLS-MPM solver (critical blocker)
• MPM work tracking: grid forces → particle work events
• MPM angular momentum: L = Σ(r_i × m_i·v_i) from particles
• MPM stress tensor ([forces/mpm] Implement MPM stress tensor and constitutive models #144) - pressure emerges from σ
• Reaction-diffusion on MPM grid ([chemistry] Replace L-systems with IRL reaction-diffusion #147)
• Aggregate diagnostics (entity + MPM) for conservation

References

• Landau & Lifshitz Vol 1 §6 (work-energy theorem)
• Landau & Lifshitz Vol 1 §9 (angular momentum)
• Issue [forces] Implement work-energy coupling for energy conservation #143: Work-energy coupling
• Issue [forces] Add angular momentum and torque tracking #145: Angular momentum tracking
• Issue Physics accuracy improvements: conservation laws and thermodynamics #142: Main physics improvements tracking
• MLS-MPM paper (future): https://yuanming.taichi.graphics/publication/2018-mlsmpm/

---

Note: This PR is transitional work. Entity physics marked as deprecated. MPM is LP's primary physics backend. Conservation interface patterns established here will be reused by MPM.