maxffarrell's picture
Release experimental Transition Foundation Model v0.1 with reproducible source and validation
1baf215 verified
Raw History Blame Contribute Delete
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)