Release experimental Transition Foundation Model v0.1 with reproducible source and validation
1baf215 verified Download tfm/simulators/physics.py from maxffarrell/transition-foundation-model: direct link, hf CLI and curl.
- Browser
- Download file 11 kB
-
https://huggingface.co/maxffarrell/transition-foundation-model/resolve/main/tfm/simulators/physics.py
- Command line
-
hf download hf://maxffarrell/transition-foundation-model/tfm/simulators/physics.py
-
curl -L -o physics.py https://huggingface.co/maxffarrell/transition-foundation-model/resolve/main/tfm/simulators/physics.py
11 kB
| """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) | |