Merge pull request erematorg#139 from M1thieu/dev

Energy Perception & Physics Stability

Author: M1thieu

.gitignore

@@ -28,17 +28,13 @@ Thumbs.db
 *.temp
 *.log
 /tmp
+.claude/
+CLAUDE.md
 
 # Environment files
 .env
 .env.local
 .env.*.local
 
 # Application save files
-save.json
-
-# MCP and Serena files
-.mcp.json
-.serena/
-.claude/
-CLAUDE.md
+save.json

Cargo.toml

@@ -12,6 +12,7 @@ members = [
     "crates/forces",
     "crates/information",
     "crates/matter",
+    "crates/utils",
 ]
 
 # Enable a small amount of optimization in the dev profile.
@@ -29,6 +30,7 @@ energy = { path = "crates/energy" }
 forces = { path = "crates/forces" }
 information = { path = "crates/information" }
 matter = { path = "crates/matter" }
+utils = { path = "crates/utils" }
 
 bevy = { version = "0.17", features = ["dynamic_linking"] }
 

crates/energy/Cargo.toml

@@ -6,3 +6,4 @@ description = "Core systems governing how energy manifests, transforms and flows
 
 [dependencies]
 bevy = "0.17"
+utils = { path = "../utils" }

crates/energy/README.md

@@ -1,3 +1,12 @@
 # Energy
 
-Energy conservation, thermodynamics, electromagnetism, and wave mechanics for LP physics simulations.
+Energy conservation, thermodynamics, electromagnetism, and wave mechanics for LP physics simulations.
+
+## Scope and units
+- Tracks energy in joules via an accounting ledger; conservation is enforced where modeled.
+- Thermodynamics, EM, and waves modules are present but remain partial scaffolds.
+- Uses consistent sim units (SI-style); couple to time/space steps used by the broader sim.
+
+## Not yet implemented
+- **Wave/EM energy accounting**: Wave damping exists but not coupled to energy ledger; EM fields exist but no work/energy tracking.
+- **EOS, convection, latent heat, phase transitions**: Deferred to matter/MPM coupling (see tmp/GD/Systems_Overview.md).

crates/energy/src/conservation.rs

@@ -231,6 +231,33 @@ pub fn conversion_efficiency(energy_input: f32, energy_output: f32) -> f32 {
     }
 }
 
+/// Optional resource to monitor energy drift over time (diagnostic only, not enforced)
+#[derive(Resource, Debug)]
+pub struct EnergyDriftMonitor {
+    pub initial_energy: f32,
+    pub tolerance: f32,
+}
+
+impl EnergyDriftMonitor {
+    pub fn new(initial_energy: f32, tolerance: f32) -> Self {
+        Self {
+            initial_energy,
+            tolerance,
+        }
+    }
+
+    /// Check if current energy has drifted beyond tolerance
+    /// Returns Some(drift) if drift exceeds tolerance, None otherwise
+    pub fn check_drift(&self, current_energy: f32) -> Option<f32> {
+        let drift = (current_energy - self.initial_energy).abs();
+        if drift > self.tolerance {
+            Some(drift)
+        } else {
+            None
+        }
+    }
+}
+
 /// Plugin to manage energy conservation systems
 pub struct EnergyConservationPlugin;
 
@@ -249,3 +276,92 @@ impl Plugin for EnergyConservationPlugin {
             .add_message::<EnergyTransferEvent>();
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_ledger_arithmetic() {
+        // Test that net_energy_change = total_input - total_output
+        let mut ledger = EnergyAccountingLedger::default();
+
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Input,
+            amount: 100.0,
+            source: None,
+            destination: None,
+            timestamp: 0.0,
+            transfer_rate: 0.0,
+            duration: 0.0,
+        });
+
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Output,
+            amount: 30.0,
+            source: None,
+            destination: None,
+            timestamp: 0.0,
+            transfer_rate: 0.0,
+            duration: 0.0,
+        });
+
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Input,
+            amount: 50.0,
+            source: None,
+            destination: None,
+            timestamp: 0.0,
+            transfer_rate: 0.0,
+            duration: 0.0,
+        });
+
+        assert_eq!(ledger.total_input, 150.0);
+        assert_eq!(ledger.total_output, 30.0);
+        assert_eq!(ledger.net_energy_change(), 120.0);
+    }
+
+    #[test]
+    fn test_current_flux_sums_active_rates() {
+        // Test that current_flux sums transfer rates correctly
+        let mut ledger = EnergyAccountingLedger::default();
+
+        let current_time = 10.0;
+
+        // Add active transfer (within time window)
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Input,
+            amount: 50.0,
+            source: None,
+            destination: None,
+            timestamp: 9.5,
+            transfer_rate: 10.0, // W
+            duration: 1.0,
+        });
+
+        // Add another active transfer
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Input,
+            amount: 30.0,
+            source: None,
+            destination: None,
+            timestamp: 9.8,
+            transfer_rate: 5.0, // W
+            duration: 0.5,
+        });
+
+        // Add old transfer (outside time window)
+        ledger.record_transaction(EnergyTransaction {
+            transaction_type: TransactionType::Input,
+            amount: 100.0,
+            source: None,
+            destination: None,
+            timestamp: 5.0,
+            transfer_rate: 20.0, // W
+            duration: 2.0,
+        });
+
+        let flux = ledger.current_flux(current_time, 1.0);
+        assert_eq!(flux, 15.0, "Expected sum of active rates: 10.0 + 5.0");
+    }
+}

crates/energy/src/electromagnetism/mod.rs

@@ -3,6 +3,8 @@ pub mod interactions;
 
 use bevy::prelude::*;
 
+// NOTE: Charge is NOT conserved; EM is quasi-static (no charge continuity equation).
+// Ref: .claude/skills/lp-physics-chem-invariants/references/em.md
 pub struct ElectromagnetismPlugin;
 
 impl Plugin for ElectromagnetismPlugin {

crates/energy/src/lib.rs

@@ -114,8 +114,8 @@ pub mod prelude {
 
     pub use crate::conservation::{
         EnergyAccountingLedger, EnergyConservationPlugin, EnergyConservationTracker,
-        EnergyQuantity, EnergyTransaction, EnergyTransferEvent, EnergyType, TransactionType,
-        conversion_efficiency, verify_conservation,
+        EnergyDriftMonitor, EnergyQuantity, EnergyTransaction, EnergyTransferEvent, EnergyType,
+        TransactionType, conversion_efficiency, verify_conservation,
     };
 
     pub use crate::electromagnetism::prelude::*;

crates/energy/src/thermodynamics/entropy.rs

@@ -7,6 +7,7 @@ pub struct Entropy {
     /// Entropy in J/K
     pub value: f32,
 }
+// NOTE: No systems currently update Entropy in the world; helper functions return ΔS but callers must apply them.
 
 impl Entropy {
     pub fn new(value: f32) -> Self {

crates/energy/src/thermodynamics/equilibrium.rs

@@ -28,17 +28,17 @@ pub struct ThermalProperties {
 }
 
 /// Check if two systems are in thermal equilibrium
+/// Zeroth Law: Equilibrium means equal temperature (within tolerance)
 pub fn is_in_equilibrium(
     temp_a: f32,
     temp_b: f32,
-    props_a: &ThermalProperties,
-    props_b: &ThermalProperties,
+    _props_a: &ThermalProperties,
+    _props_b: &ThermalProperties,
     tolerance: f32,
 ) -> bool {
-    // Weighted equilibrium considers both temperature and thermal properties
-    let weighted_diff =
-        (temp_a - temp_b).abs() / (1.0 + (props_a.thermal_mass * props_b.thermal_mass).sqrt());
-    weighted_diff <= tolerance
+    // Zeroth Law: Thermal equilibrium is defined purely by temperature equality
+    // Thermal mass affects TIME to reach equilibrium, not the definition of equilibrium itself
+    (temp_a - temp_b).abs() <= tolerance
 }
 
 pub fn equilibrium_time_estimate(

crates/energy/src/thermodynamics/mod.rs

@@ -16,26 +16,11 @@ pub struct ThermodynamicsPlugin;
 
 impl Plugin for ThermodynamicsPlugin {
     fn build(&self, app: &mut App) {
-        app.register_type::<thermal::Temperature>()
-            .register_type::<thermal::ThermalConductivity>()
-            .register_type::<thermal::ThermalDiffusivity>()
+        app.add_plugins(thermal::ThermalSystemPlugin)
             .register_type::<entropy::Entropy>()
             .register_type::<entropy::Reversibility>()
             .register_type::<equilibrium::ThermalEquilibrium>()
-            .register_type::<equilibrium::PhaseState>()
-            .add_message::<thermal::ThermalTransferEvent>()
-            .configure_sets(
-                Update,
-                (
-                    ThermodynamicsSet::ThermalTransfer,
-                    ThermodynamicsSet::Equilibrium,
-                )
-                    .chain(),
-            )
-            .add_systems(
-                Update,
-                thermal::calculate_thermal_transfer.in_set(ThermodynamicsSet::ThermalTransfer),
-            );
+            .register_type::<equilibrium::PhaseState>();
     }
 }
 
@@ -50,6 +35,7 @@ pub mod prelude {
         validate_equilibrium_group_consistency,
     };
     pub use super::thermal::{
-        Temperature, ThermalConductivity, ThermalDiffusivity, thermal_utils::heat_conduction,
+        Temperature, ThermalConductivity, ThermalDiffusivity, HeatCapacity,
+        thermal_utils::heat_conduction,
     };
 }