Source code for x2power.methods.biogas_plant

"""Mixed-feed CSTR, gas inventory and CHP simulation; see docs/biogas_plants.md.

The first-order substrate pools are a reduced-order approximation, not ADM1.
Temperature is maintained by recovered heat and unlimited electric backup heat.
Gas dispatch uses each interval's average production; use short operating intervals.
"""

from collections.abc import Sequence
from dataclasses import asdict, dataclass
from math import exp, expm1, fsum
from typing import Any

from x2power.methods.generation import generate_power
from x2power.models import AuxiliaryLoads, Generator, PowerResult
from x2power.utilities.validation import fraction, number


[docs] @dataclass(frozen=True) class DigesterFeedstock: """Continuous wet feed; methane yield is per kg of degradable VS destroyed. ``total_solids_fraction`` is wet basis; ``volatile_solids_fraction_ts`` is relative to total solids. ``biodegradable_vs_fraction`` partitions incoming VS into degradable and inert pools. Rate constants apply at the declared digester temperature and require calibration. Gas volumes are dry at 0 C, 101325 Pa. """ name: str wet_mass_kg_per_day: float total_solids_fraction: float volatile_solids_fraction_ts: float biodegradable_vs_fraction: float methane_yield_nm3_per_kg_vs_destroyed: float decay_rate_per_day: float density_kg_per_m3: float = 1000.0 dry_lhv_mj_per_kg: float = 18.0 def __post_init__(self) -> None: if not isinstance(self.name, str) or not self.name.strip(): raise ValueError("Feedstock name must be non-empty") for key in ( "wet_mass_kg_per_day", "methane_yield_nm3_per_kg_vs_destroyed", "decay_rate_per_day", ): number(key, getattr(self, key)) for key in ( "total_solids_fraction", "volatile_solids_fraction_ts", "biodegradable_vs_fraction", ): fraction(key, getattr(self, key)) number("density_kg_per_m3", self.density_kg_per_m3, strict=True) number("dry_lhv_mj_per_kg", self.dry_lhv_mj_per_kg, strict=True) @property def vs_kg_per_day(self) -> float: return ( self.wet_mass_kg_per_day * self.total_solids_fraction * self.volatile_solids_fraction_ts )
[docs] @dataclass(frozen=True) class ContinuousDigester: """One perfectly mixed working volume; no solids retention or liquid recycle. HRT and OLR limits only produce diagnostic flags; they are not inhibition kinetics or universal operating recommendations. Heat loss is UA * delta T. """ working_volume_m3: float temperature_c: float = 37.0 heat_loss_kw_per_k: float = 0.0 feed_heat_capacity_kj_per_kg_k: float = 4.18 minimum_hrt_days: float | None = None maximum_olr_kg_vs_m3_day: float | None = None def __post_init__(self) -> None: number("working_volume_m3", self.working_volume_m3, strict=True) number("temperature_c", self.temperature_c, minimum=-273.15, strict=True) number("heat_loss_kw_per_k", self.heat_loss_kw_per_k) number("feed_heat_capacity_kj_per_kg_k", self.feed_heat_capacity_kj_per_kg_k, strict=True) for key in ("minimum_hrt_days", "maximum_olr_kg_vs_m3_day"): if getattr(self, key) is not None: number(key, getattr(self, key), strict=True)
[docs] @dataclass(frozen=True) class BiogasPlant: """Plant parameters shared across intervals, without third-party dependencies. Storage capacity is dry normal biogas volume, not geometric membrane volume. Generator rating is mandatory and gross electrical. Fixed loads and mixing persist during outages. Treatment electricity applies to all captured gas. """ feedstocks: tuple[DigesterFeedstock, ...] digester: ContinuousDigester generator: Generator gas_storage_capacity_nm3: float = 0.0 methane_fraction: float = 0.6 capture_fraction: float = 0.98 methane_lhv_kwh_per_nm3: float = 9.94 fixed_auxiliary_power_kw: float = 0.0 mixing_power_w_per_m3: float = 0.0 feed_preparation_kwh_per_tonne: float = 0.0 gas_treatment_kwh_per_nm3: float = 0.0 electric_heater_efficiency: float = 1.0 def __post_init__(self) -> None: if not isinstance(self.feedstocks, tuple) or not self.feedstocks: raise ValueError("feedstocks must be a non-empty tuple") if len({feed.name for feed in self.feedstocks}) != len(self.feedstocks): raise ValueError("Feedstock names must be unique") if self.generator.rated_power_kw is None: raise ValueError("Plant generator requires rated_power_kw") for key in ( "gas_storage_capacity_nm3", "fixed_auxiliary_power_kw", "mixing_power_w_per_m3", "feed_preparation_kwh_per_tonne", "gas_treatment_kwh_per_nm3", ): number(key, getattr(self, key)) fraction("methane_fraction", self.methane_fraction, positive=True) fraction("capture_fraction", self.capture_fraction) fraction("electric_heater_efficiency", self.electric_heater_efficiency, positive=True) number("methane_lhv_kwh_per_nm3", self.methane_lhv_kwh_per_nm3, strict=True) for feed in self.feedstocks: potential = ( feed.volatile_solids_fraction_ts * feed.biodegradable_vs_fraction * feed.methane_yield_nm3_per_kg_vs_destroyed * self.methane_lhv_kwh_per_nm3 ) if potential > feed.dry_lhv_mj_per_kg / 3.6 + 1e-9: raise ValueError(f"Methane potential exceeds dry feedstock LHV: {feed.name}")
[docs] @dataclass(frozen=True) class PlantInterval: """Constant inputs over one interval; multipliers follow feedstock tuple order. Empty multipliers use all base rates. Availability is an equivalent capacity derating within the interval; resolve actual outages as separate 0/1 intervals. The CHP follows its setpoint, regardless of external electrical/thermal demand. """ duration_h: float = 1.0 feed_multipliers: tuple[float, ...] = () generator_availability: float = 1.0 generator_setpoint_fraction: float = 1.0 feed_temperature_c: float = 15.0 ambient_temperature_c: float = 15.0 site_electricity_demand_kw: float = 0.0 site_heat_demand_kw: float = 0.0 def __post_init__(self) -> None: number("duration_h", self.duration_h, strict=True) if not isinstance(self.feed_multipliers, tuple): raise ValueError("feed_multipliers must be a tuple") for value in self.feed_multipliers: number("feed_multiplier", value) fraction("generator_availability", self.generator_availability) fraction("generator_setpoint_fraction", self.generator_setpoint_fraction) for key in ("feed_temperature_c", "ambient_temperature_c"): number(key, getattr(self, key), minimum=-273.15, strict=True) number("site_electricity_demand_kw", self.site_electricity_demand_kw) number("site_heat_demand_kw", self.site_heat_demand_kw)
[docs] @dataclass(frozen=True) class PlantState: """Inventory passed between calls for the same unchanged plant configuration.""" feedstock_names: tuple[str, ...] degradable_vs_kg: tuple[float, ...] inert_vs_kg: tuple[float, ...] stored_biogas_nm3: float = 0.0 def __post_init__(self) -> None: for values in (self.feedstock_names, self.degradable_vs_kg, self.inert_vs_kg): if not isinstance(values, tuple): raise ValueError("State pools and names must be tuples") if not (len(self.feedstock_names) == len(self.degradable_vs_kg) == len(self.inert_vs_kg)): raise ValueError("State pool lengths must match feedstock names") for value in self.degradable_vs_kg + self.inert_vs_kg: number("VS inventory", value) number("stored_biogas_nm3", self.stored_biogas_nm3)
[docs] @dataclass(frozen=True) class PlantResult: """One interval ledger and end state; no digestate nutrient or full mass balance.""" power: PowerResult state: PlantState metrics: dict[str, float | None] flags: tuple[str, ...] = ()
[docs] def to_dict(self) -> dict[str, Any]: return asdict(self)
def _flows(plant: BiogasPlant, interval: PlantInterval) -> tuple[list[float], float, float]: multipliers = interval.feed_multipliers or (1.0,) * len(plant.feedstocks) if len(multipliers) != len(plant.feedstocks): raise ValueError("feed_multipliers must match the plant feedstock count") wet = [ feed.wet_mass_kg_per_day * scale for feed, scale in zip(plant.feedstocks, multipliers, strict=True) ] flow = fsum( mass / feed.density_kg_per_m3 for mass, feed in zip(wet, plant.feedstocks, strict=True) ) return wet, flow, flow / plant.digester.working_volume_m3
[docs] def initial_plant_state( plant: BiogasPlant, *, interval: PlantInterval | None = None, steady_state: bool = True, stored_biogas_nm3: float = 0.0, ) -> PlantState: """Initialize pools at constant-feed equilibrium or at zero VS inventory. Zero VS means an already full, warm liquid volume with no substrate inventory, not a prediction of microbial startup or digester filling. Gas defaults to zero. """ number("stored_biogas_nm3", stored_biogas_nm3) if stored_biogas_nm3 > plant.gas_storage_capacity_nm3: raise ValueError("Initial biogas exceeds storage capacity") wet, _, dilution = _flows(plant, interval or PlantInterval()) degradable, inert = [], [] for feed, mass in zip(plant.feedstocks, wet, strict=True): vs = mass * feed.total_solids_fraction * feed.volatile_solids_fraction_ts rate = feed.decay_rate_per_day + dilution degradable.append( vs * feed.biodegradable_vs_fraction / rate if steady_state and rate > 0 else 0.0 ) inert.append( vs * (1 - feed.biodegradable_vs_fraction) / dilution if steady_state and dilution > 0 else 0.0 ) return PlantState( tuple(f.name for f in plant.feedstocks), tuple(degradable), tuple(inert), stored_biogas_nm3 )
def _pool(initial: float, inflow: float, rate: float, days: float) -> tuple[float, float]: """Exact nonnegative solution and integrated removal for dM/dt = inflow-rate*M.""" if rate == 0: return initial + inflow * days, 0.0 x = rate * days removed_fraction = -expm1(-x) # Stable integral of newly arriving substrate when x approaches zero. q = ( x * (0.5 + x * (-1 / 6 + x * (1 / 24 - x / 120))) if x < 1e-4 else (1 - removed_fraction / x) ) remaining = initial * exp(-x) + inflow * days * (removed_fraction / x) removed = initial * removed_fraction + inflow * days * q return remaining, removed
[docs] def simulate_biogas_plant( plant: BiogasPlant, intervals: Sequence[PlantInterval], *, initial_state: PlantState | None = None, ) -> list[PlantResult]: """Integrate feed pools, dispatch captured gas and close electrical/heat ledgers. Without an explicit state, start at equilibrium for the first interval's feed rates with an empty gas holder. No automatic inhibition or temperature correction is applied to decay rates. Gas exceeding holder capacity is sent to an unlimited ideal flare. Flared gas volume is not an estimate of methane emitted to air. """ if not intervals: raise ValueError("Supply at least one plant interval") state = initial_state or initial_plant_state(plant, interval=intervals[0]) if state.feedstock_names != tuple(f.name for f in plant.feedstocks): raise ValueError("State feedstock names/order must match the plant") if state.stored_biogas_nm3 > plant.gas_storage_capacity_nm3: raise ValueError("Initial biogas exceeds storage capacity") results = [] for interval in intervals: result = _step(plant, interval, state) results.append(result) state = result.state return results
def _step(plant: BiogasPlant, interval: PlantInterval, state: PlantState) -> PlantResult: wet, flow, dilution = _flows(plant, interval) days = interval.duration_h / 24 vs_fed = destroyed = vs_out = methane = 0.0 degradable, inert = [], [] for i, (feed, mass) in enumerate(zip(plant.feedstocks, wet, strict=True)): vs_rate = mass * feed.total_solids_fraction * feed.volatile_solids_fraction_ts vs_fed += vs_rate * days rate = feed.decay_rate_per_day + dilution end, removed = _pool( state.degradable_vs_kg[i], vs_rate * feed.biodegradable_vs_fraction, rate, days ) reacted = removed * feed.decay_rate_per_day / rate if rate else 0.0 inert_end, inert_out = _pool( state.inert_vs_kg[i], vs_rate * (1 - feed.biodegradable_vs_fraction), dilution, days ) degradable.append(end) inert.append(inert_end) destroyed += reacted vs_out += (removed * dilution / rate if rate else 0.0) + inert_out methane += reacted * feed.methane_yield_nm3_per_kg_vs_destroyed produced = methane / plant.methane_fraction captured = produced * plant.capture_fraction available = state.stored_biogas_nm3 + captured lhv = plant.methane_fraction * plant.methane_lhv_kwh_per_nm3 rating = plant.generator.rated_power_kw assert rating is not None # enforced by BiogasPlant target = ( rating * interval.generator_setpoint_fraction * interval.generator_availability * interval.duration_h / plant.generator.electrical_efficiency / lhv ) used = min(available, target) stored = min(plant.gas_storage_capacity_nm3, max(0.0, available - used)) flared = max(0.0, available - used - stored) wet_mass = fsum(wet) * days digester = plant.digester feed_heat = ( wet_mass * digester.feed_heat_capacity_kj_per_kg_k * max(0.0, digester.temperature_c - interval.feed_temperature_c) / 3600 ) vessel_heat = ( digester.heat_loss_kw_per_k * max(0.0, digester.temperature_c - interval.ambient_temperature_c) * interval.duration_h ) auxiliary = AuxiliaryLoads( fixed_power_kw=( plant.fixed_auxiliary_power_kw + plant.mixing_power_w_per_m3 * digester.working_volume_m3 / 1000 ), process_electricity_kwh=( wet_mass / 1000 * plant.feed_preparation_kwh_per_tonne + captured * plant.gas_treatment_kwh_per_nm3 ), electric_heater_efficiency=plant.electric_heater_efficiency, ) power = generate_power( used * lhv, plant.generator, duration_h=interval.duration_h, process_heat_kwh=feed_heat + vessel_heat, auxiliaries=auxiliary, ) site_demand = interval.site_electricity_demand_kw * interval.duration_h grid_net = power.net_electricity_kwh - site_demand heat_demand = interval.site_heat_demand_kw * interval.duration_h useful_heat = min(power.surplus_heat_kwh, heat_demand) hrt = 1 / dilution if dilution > 0 else None olr = vs_fed / days / digester.working_volume_m3 flags = [] if ( hrt is not None and digester.minimum_hrt_days is not None and hrt < digester.minimum_hrt_days ): flags.append("hrt_below_configured_minimum") if digester.maximum_olr_kg_vs_m3_day is not None and olr > digester.maximum_olr_kg_vs_m3_day: flags.append("olr_above_configured_maximum") new_state = PlantState(state.feedstock_names, tuple(degradable), tuple(inert), stored) metrics = { "wet_feed_kg": wet_mass, "influent_volume_m3": flow * days, "hydraulic_retention_days": hrt, "organic_loading_kg_vs_m3_day": olr, "volatile_solids_fed_kg": vs_fed, "volatile_solids_destroyed_kg": destroyed, "effluent_volatile_solids_kg": vs_out, "vs_balance_residual_kg": ( fsum(state.degradable_vs_kg + state.inert_vs_kg) + vs_fed - destroyed - vs_out - fsum(degradable + inert) ), "methane_produced_nm3": methane, "methane_not_captured_nm3": methane * (1 - plant.capture_fraction), "biogas_produced_nm3": produced, "biogas_captured_nm3": captured, "biogas_to_chp_nm3": used, "biogas_flared_nm3": flared, "initial_stored_biogas_nm3": state.stored_biogas_nm3, "stored_biogas_nm3": stored, "gas_balance_residual_nm3": available - used - stored - flared, "feed_heating_kwh": feed_heat, "vessel_heat_loss_kwh": vessel_heat, "site_electricity_demand_kwh": site_demand, "grid_import_kwh": max(0.0, -grid_net), "grid_export_kwh": max(0.0, grid_net), "site_heat_demand_kwh": heat_demand, "heat_delivered_to_site_kwh": useful_heat, "unserved_site_heat_kwh": heat_demand - useful_heat, "rejected_heat_kwh": power.surplus_heat_kwh - useful_heat, } for key, value in metrics.items(): if value is not None: number(key, value, minimum=float("-inf")) return PlantResult(power, new_state, metrics, tuple(flags))