"""Randomized, constrained physical systems with reproducible common-noise snapshots. Controls are power (kW) or valve/pump fractions, elapsed time is minutes. The thermal integrator uses <=1-minute steps; tank and charge balance are exact. """ import copy import numpy as np from tfm.data.schema import FIELD_INDEX, FIELD_SPECS, NUM_FIELDS, SCHEMAS, role_fields class PhysicalSimulator: def __init__(self, family, seed): if family not in SCHEMAS: raise ValueError(f"Unknown family {family!r}; choose {tuple(SCHEMAS)}") self.family = family self.seed = int(seed) self.rng = np.random.default_rng(seed) self.schema = list(SCHEMAS[family]) r = self.rng if family == "thermal": two_node = bool(r.random() < 0.65) self.parameters = { "two_node": two_node, "air_capacity": r.uniform(0.5, 3), "mass_capacity": r.uniform(3, 20), "envelope_conductance": r.uniform(0.08, 0.4), "mass_conductance": r.uniform(0.2, 1.2), "hvac_efficiency": r.uniform(0.8, 1.1), "process_noise_std": r.uniform(0.005, 0.025), "max_heating_power": r.uniform(4, 15), "max_cooling_power": r.uniform(3, 14), } if not two_node: self.schema.remove("mass_temp") self.state = np.array([r.uniform(18, 26)] * (2 if two_node else 1) + [0.0]) elif family == "tank": capacity = r.uniform(2, 20) self.parameters = { "capacity": capacity, "leakage_rate": r.uniform(0.002, 0.025), "inlet_efficiency": r.uniform(0.9, 1), "process_noise_std": r.uniform(0.001, 0.008), } self.parameters.update( max_pump_flow=r.uniform(2, 8), valve_coefficient=r.uniform(0.4, 1.2), heat_loss=r.uniform(0.005, 0.03), pressure_head=r.uniform(60, 160), ) self.state = np.array([r.uniform(0.2, 0.8) * capacity, r.uniform(12, 24), 0.0, 0.0]) else: self.parameters = { "capacity_kwh": r.uniform(5, 60), "charge_efficiency": r.uniform(0.90, 0.99), "discharge_efficiency": r.uniform(0.90, 0.99), "self_discharge": r.uniform(0.0001, 0.001), "thermal_capacity": r.uniform(0.1, 0.7), "thermal_conductance": r.uniform(0.03, 0.15), "resistance_loss": r.uniform(0.015, 0.06), "process_noise_std": r.uniform(0.0001, 0.0005), } self.parameters.update( nominal_voltage=r.uniform(24, 52), internal_resistance=r.uniform(0.01, 0.08) ) soc = r.uniform(0.2, 0.8) self.state = np.array( [soc, r.uniform(18, 30), self.parameters["nominal_voltage"] * (0.9 + 0.2 * soc)] ) self.step_count = 0 def _compact(self, values, role): names = role_fields(self.schema, role) if isinstance(values, dict): if set(values) != set(names): raise ValueError(f"{role} dictionary must contain exactly {names}") a = np.array([values[n] for n in names], dtype=float) else: a = np.asarray(values, dtype=float) if a.shape == (NUM_FIELDS,): a = a[[FIELD_INDEX[n] for n in names]] if a.shape != (len(names),) or not np.isfinite(a).all(): raise ValueError(f"{role} must be finite compact {names} or canonical vector") if role == "action": bounds = [ (FIELD_SPECS[FIELD_INDEX[n]].minimum, FIELD_SPECS[FIELD_INDEX[n]].maximum) for n in names ] if any(not low <= value <= high for value, (low, high) in zip(a, bounds)): raise ValueError(f"Control outside public actuator bounds: {names}") return a def step(self, action, exogenous, dt_minutes=15): if not np.isfinite(dt_minutes) or not 0 < dt_minutes <= 1440: raise ValueError("dt_minutes must be in (0,1440]") a, e = self._compact(action, "action"), self._compact(exogenous, "exogenous") p = self.parameters dt = dt_minutes / 60 # A fixed draw per state/step allows counterfactual branches to share disturbances. noise = self.rng.normal(size=len(self.state)) * p["process_noise_std"] * np.sqrt(dt) if self.family == "thermal": power = np.clip(a[0], -p["max_cooling_power"], p["max_heating_power"]) outside, solar, occupants = e outside, solar, occupants = ( np.clip(outside, -30, 60), np.clip(solar, 0, 5), np.clip(occupants, 0, 3), ) n = int(np.ceil(dt_minutes)) h = dt / n for _ in range(n): air = self.state[0] flux = ( p["envelope_conductance"] * (outside - air) + p["hvac_efficiency"] * power + solar + occupants ) if p["two_node"]: mass_flux = p["mass_conductance"] * (self.state[1] - air) self.state[:2] += h * np.array( [(flux + mass_flux) / p["air_capacity"], -mass_flux / p["mass_capacity"]] ) else: self.state[0] += h * flux / p["air_capacity"] self.state[:-1] = np.clip(self.state[:-1] + noise[:-1], -30, 70) self.state[-1] += abs(power) * dt elif self.family == "tank": valve, pump = np.clip(a, 0, 1) demand, inlet_temp = np.clip(e[0], 0, 10), np.clip(e[1], -5, 60) incoming = pump * p["max_pump_flow"] * p["inlet_efficiency"] outgoing = min(demand * valve * p["valve_coefficient"], self.state[0] / dt + incoming) rate = incoming - outgoing decay = np.exp(-p["leakage_rate"] * dt) level = self.state[0] * decay + rate * (1 - decay) / p["leakage_rate"] old_level = self.state[0] self.state[0] = np.clip(level + noise[0], 0, p["capacity"]) mixing = 1 - np.exp(-incoming * dt / max(old_level, 0.05)) self.state[1] = np.clip( self.state[1] + mixing * (inlet_temp - self.state[1]) + p["heat_loss"] * dt * (20 - self.state[1]) + noise[1], -5, 80, ) self.state[2] = max(0.0, outgoing) self.state[3] = np.clip( p["pressure_head"] * pump**2 + 9.81 * self.state[0] / p["capacity"], 0, 300 ) else: power = np.clip(a[0], -20, 20) ambient = np.clip(e[0], -30, 60) thermal_derating = np.clip(1 - 0.002 * abs(self.state[1] - 25), 0.75, 1.0) resistance_factor = ( 1 + 0.018 * max(0.0, 25 - self.state[1]) + 0.006 * max(0.0, self.state[1] - 40) ) resistance_derating = 1 + p["resistance_loss"] * resistance_factor charge_efficiency = p["charge_efficiency"] * thermal_derating / resistance_derating discharge_efficiency = p["discharge_efficiency"] * thermal_derating / resistance_derating charge = power * charge_efficiency if power >= 0 else power / discharge_efficiency soc = np.clip( self.state[0] * (1 - p["self_discharge"] * dt) + charge * dt / p["capacity_kwh"] + noise[0], 0, 1, ) # At charge boundaries only accepted energy produces resistive heating. soc_without_charge = self.state[0] * (1 - p["self_discharge"] * dt) stored_change = max(0.0, abs(soc - soc_without_charge) - abs(noise[0])) * p["capacity_kwh"] / dt accepted = min( abs(power), stored_change / charge_efficiency if power >= 0 else stored_change * discharge_efficiency, ) decay = np.exp(-p["thermal_conductance"] * dt / p["thermal_capacity"]) conversion_loss = ( accepted * (1 - charge_efficiency) if power >= 0 else accepted * (1 / discharge_efficiency - 1) ) heat = conversion_loss # all electrical conversion loss becomes heat; no double counting equilibrium = ambient + heat / p["thermal_conductance"] temp = equilibrium + (self.state[1] - equilibrium) * decay + noise[1] voltage = ( p["nominal_voltage"] * (0.9 + 0.2 * soc) + power * 1000 / p["nominal_voltage"] * p["internal_resistance"] * resistance_factor ) self.state = np.array([soc, np.clip(temp, -30, 80), np.clip(voltage, 10, 70)]) self.step_count += 1 return self.state.copy() def snapshot(self): return { "version": 1, "family": self.family, "seed": self.seed, "parameters": copy.deepcopy(self.parameters), "schema": list(self.schema), "state": self.state.copy(), "rng_state": copy.deepcopy(self.rng.bit_generator.state), "step_count": self.step_count, } def restore(self, snapshot): if snapshot.get("version") != 1: raise ValueError("Unsupported simulator snapshot version") if snapshot["family"] != self.family or snapshot["schema"] != self.schema: raise ValueError("Snapshot belongs to a different simulator schema") state = np.asarray(snapshot["state"], dtype=float) if state.shape != self.state.shape or not np.isfinite(state).all(): raise ValueError("Snapshot state must match finite simulator state shape") restored_rng = np.random.default_rng() restored_rng.bit_generator.state = copy.deepcopy(snapshot["rng_state"]) self.parameters = copy.deepcopy(snapshot["parameters"]) self.state = state.copy() self.rng = restored_rng self.seed = snapshot["seed"] self.step_count = snapshot["step_count"] def make_simulator(family, seed): return PhysicalSimulator(family, seed) def counterfactual_rollout(simulator, snapshot, actions, exogenous, dt_minutes=15): """Replay a branch from a snapshot; preserve caller state and noise stream.""" if len(actions) != len(exogenous): raise ValueError("Actions and exogenous must have identical lengths") original = simulator.snapshot() try: simulator.restore(snapshot) states = [simulator.state.copy()] states.extend(simulator.step(a, e, dt_minutes) for a, e in zip(actions, exogenous)) return np.asarray(states) finally: simulator.restore(original)