Source code for x2power.models
"""Immutable inputs and interval-integrated outputs with units in field names."""
from dataclasses import asdict, dataclass, field, fields
from typing import Any
from x2power.utilities.validation import fraction, number
[docs]
@dataclass(frozen=True)
class SolidFeedstock:
"""Mass over one interval. Moisture is wet-basis; LHV is per kg dry matter."""
mass_kg: float
moisture_fraction: float
dry_lhv_mj_per_kg: float
def __post_init__(self) -> None:
number("mass_kg", self.mass_kg)
fraction("moisture_fraction", self.moisture_fraction)
number("dry_lhv_mj_per_kg", self.dry_lhv_mj_per_kg, strict=True)
@property
def dry_mass_kg(self) -> float:
return self.mass_kg * (1 - self.moisture_fraction)
@property
def water_mass_kg(self) -> float:
return self.mass_kg * self.moisture_fraction
@property
def chemical_energy_kwh(self) -> float:
return self.dry_mass_kg * self.dry_lhv_mj_per_kg / 3.6
[docs]
@dataclass(frozen=True)
class Generator:
"""Constant LHV-basis efficiencies; rating is gross electrical power."""
electrical_efficiency: float
heat_recovery_efficiency: float = 0.0
rated_power_kw: float | None = None
def __post_init__(self) -> None:
fraction("electrical_efficiency", self.electrical_efficiency, positive=True)
fraction("heat_recovery_efficiency", self.heat_recovery_efficiency)
if self.electrical_efficiency + self.heat_recovery_efficiency > 1.0:
raise ValueError("Electrical and recovered-heat efficiencies must sum to <= 1")
if self.rated_power_kw is not None:
number("rated_power_kw", self.rated_power_kw)
[docs]
@dataclass(frozen=True)
class AuxiliaryLoads:
"""Standing load applies throughout the interval, including generator outages."""
fixed_power_kw: float = 0.0
electricity_fraction_of_gross: float = 0.0
process_electricity_kwh: float = 0.0
electric_heater_efficiency: float = 1.0
process_heat_usable_fraction: float = 1.0
def __post_init__(self) -> None:
number("fixed_power_kw", self.fixed_power_kw)
fraction("electricity_fraction_of_gross", self.electricity_fraction_of_gross)
number("process_electricity_kwh", self.process_electricity_kwh)
fraction("electric_heater_efficiency", self.electric_heater_efficiency, positive=True)
fraction("process_heat_usable_fraction", self.process_heat_usable_fraction)
[docs]
@dataclass(frozen=True)
class PowerResult:
"""Energy ledger at the generator boundary, plus explicit plant electrical loads."""
duration_h: float
fuel_energy_available_kwh: float
fuel_energy_used_kwh: float
unused_fuel_energy_kwh: float
gross_electricity_kwh: float
recovered_heat_kwh: float
generator_loss_kwh: float
process_heat_demand_kwh: float
heat_to_process_kwh: float
surplus_heat_kwh: float
electric_heating_kwh: float
auxiliary_electricity_kwh: float
net_electricity_kwh: float
balance_residual_kwh: float
def __post_init__(self) -> None:
for item in fields(self):
number(item.name, getattr(self, item.name), minimum=float("-inf"))
number("duration_h", self.duration_h, strict=True)
number("net_power_kw", self.net_power_kw, minimum=float("-inf"))
if self.net_electrical_efficiency is not None:
number(
"net_electrical_efficiency", self.net_electrical_efficiency, minimum=float("-inf")
)
@property
def net_power_kw(self) -> float:
return self.net_electricity_kwh / self.duration_h
@property
def net_electrical_efficiency(self) -> float | None:
"""Net electricity / available fuel energy; undefined for zero fuel."""
if self.fuel_energy_available_kwh == 0:
return None
return self.net_electricity_kwh / self.fuel_energy_available_kwh
[docs]
@dataclass(frozen=True)
class SimulationResult:
route: str
power: PowerResult
metrics: dict[str, float] = field(default_factory=dict)
def __post_init__(self) -> None:
for key, value in self.metrics.items():
number(key, value, minimum=float("-inf"))
[docs]
def to_dict(self) -> dict[str, Any]:
result = asdict(self)
result["power"]["net_power_kw"] = self.power.net_power_kw
result["power"]["net_electrical_efficiency"] = self.power.net_electrical_efficiency
return result