RunFeemsSim 0.5.0__tar.gz → 0.7.0__tar.gz

{runfeemssim-0.5.0 → runfeemssim-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RunFeemsSim
-Version: 0.5.0
+Version: 0.7.0
 Summary: A library for running feems simulation
 Author-email: Kevin Koosup Yum <kevinkoosup.yum@gmail.com>
 License-Expression: Apache-2.0

{runfeemssim-0.5.0 → runfeemssim-0.7.0}/RunFeemsSim/machinery_calculation.py

@@ -290,6 +290,25 @@ class MachineryCalculation:
             fuel_option=fuel_option,
         )
 
+    def _set_boiler_steam_demand(self, steam_demand_kg_per_h: Optional[np.ndarray]) -> None:
+        """Set the boiler steam demand aligned to the simulation's integration intervals.
+
+        The number of integration points equals ``len(time_interval_s)``, which is one less
+        than the number of timestamps when the load is given as a timestamp series (the last
+        point is dropped, mirroring how the propulsion power is handled). The steam demand is
+        therefore truncated to the same number of points so the boiler fuel integration matches
+        the engine integration. No-op when the system has no boiler.
+        """
+        if self.system_feems.boiler is None:
+            return
+        n_points = len(np.atleast_1d(self.electric_system.time_interval_s))
+        if steam_demand_kg_per_h is None:
+            self.system_feems.boiler.steam_out_kg_per_h = np.zeros(n_points)
+        else:
+            self.system_feems.boiler.steam_out_kg_per_h = (
+                np.asarray(steam_demand_kg_per_h, dtype=float)[:n_points]
+            )
+
     def calculate_machinery_system_output_from_propulsion_power_time_series(
         self,
         *,
@@ -298,6 +317,7 @@ class MachineryCalculation:
         fuel_specified_by: FuelSpecifiedBy = FuelSpecifiedBy.IMO,
         ignore_power_balance: bool = False,
         fuel_option: Optional[FuelOption] = None,
+        steam_demand_kg_per_h: Optional[np.ndarray] = None,
     ) -> Union[FEEMSResult, FEEMSResultForMachinerySystem]:
         """
         Calculate the machinery system output from a time series of the propulsion power and
@@ -313,6 +333,8 @@ class MachineryCalculation:
             ignore_power_balance(bool): If True, the power balance calculation will be ignored.
             fuel_option(FuelOption): The fuel option to be used in the simulation. If None, the
                 default fuel option in the system will be used.
+            steam_demand_kg_per_h: Steam demand time series (kg/h). Must have the same length as
+                propulsion_power. If None and a boiler is attached, demand is treated as zero.
 
         Returns:
             The result of the calculation. FEEMSResult or FEEMSResultForMachinerySystem.
@@ -347,11 +369,19 @@ class MachineryCalculation:
                 f"The length of the auxiliary power({len(auxiliary_power_kw)}) must be 1"
                 f" or the same as the propulsion power ({len(propulsion_power)})"
             )
+        n_steps = len(propulsion_power)
+        if steam_demand_kg_per_h is not None:
+            if len(steam_demand_kg_per_h) != n_steps:
+                raise ValueError(
+                    f"The length of steam_demand_kg_per_h ({len(steam_demand_kg_per_h)}) must match "
+                    f"propulsion_power ({n_steps})."
+                )
 
         self._set_input_load_time_interval_from_propulsion_power_time_series(
             propulsion_power_time_series=propulsion_power,
             auxiliary_load_kw=auxiliary_power_kw,
         )
+        self._set_boiler_steam_demand(steam_demand_kg_per_h)
         return self._run_simulation(
             fuel_specified_by=fuel_specified_by,
             ignore_power_balance=ignore_power_balance,
@@ -368,6 +398,7 @@ class MachineryCalculation:
         fuel_specified_by: FuelSpecifiedBy = FuelSpecifiedBy.IMO,
         ignore_power_balance: bool = False,
         fuel_option: Optional[FuelOption] = None,
+        steam_demand_kg_per_h: Optional[np.ndarray] = None,
     ) -> Union[FEEMSResult, FEEMSResultForMachinerySystem]:
         """
         Calculate the machinery system output from statistics of the propulsion power.
@@ -377,6 +408,11 @@ class MachineryCalculation:
             ignore_power_balance(bool): If True, the power balance calculation will be ignored.
             fuel_option(FuelOption): The fuel option to be used in the simulation. If None, the
                 default fuel option in the system will be used.
+            steam_demand_kg_per_h: Steam demand time series (kg/h). Must have the same length as
+                the time series. Takes precedence over the boiler_steam_demand_kg_per_h carried by
+                the time_series proto; if None, that proto value is used instead (per-instance, or
+                the top-level constant when the per-instance values are all zero). If both are
+                absent and a boiler is attached, demand is treated as zero.
 
         Returns:
             The result of the simulation. FEEMSResult or FEEMSResultForMachinery system.
@@ -398,7 +434,25 @@ class MachineryCalculation:
             raise TypeError(
                 "time_series must be a TimeSeriesResult or TimeSeriesResultForMultiplePropulsors."
             )
-
+        n_steps = len(df)
+        if steam_demand_kg_per_h is not None:
+            if len(steam_demand_kg_per_h) != n_steps:
+                raise ValueError(
+                    f"The length of steam_demand_kg_per_h ({len(steam_demand_kg_per_h)}) must match "
+                    f"the time series ({n_steps})."
+                )
+        # The explicit steam_demand_kg_per_h argument takes precedence; otherwise fall back to the
+        # boiler_steam_demand_kg_per_h carried by the time-series proto (per-instance values, with a
+        # top-level constant fallback resolved by the converter).
+        steam_demand_from_proto = (
+            df["boiler_steam_demand_kg_per_h"].values
+            if "boiler_steam_demand_kg_per_h" in df.columns
+            else None
+        )
+        effective_steam_demand = (
+            steam_demand_kg_per_h if steam_demand_kg_per_h is not None else steam_demand_from_proto
+        )
+        self._set_boiler_steam_demand(effective_steam_demand)
         return self._run_simulation(
             fuel_specified_by=fuel_specified_by,
             ignore_power_balance=ignore_power_balance,
@@ -414,6 +468,7 @@ class MachineryCalculation:
         fuel_specified_by: FuelSpecifiedBy = FuelSpecifiedBy.IMO,
         ignore_power_balance: bool = False,
         fuel_option: Optional[FuelOption] = None,
+        steam_demand_kg_per_h: Optional[np.ndarray] = None,
     ) -> Union[FEEMSResult, FEEMSResultForMachinerySystem]:
         """
         Calculate the machinery system output from statistics of the propulsion power.
@@ -428,19 +483,32 @@ class MachineryCalculation:
             ignore_power_balance(bool): If True, the power balance calculation will be ignored.
             fuel_option(FuelOption): The fuel option to be used in the simulation. If None, the
                 default fuel option in the system will be used.
+            steam_demand_kg_per_h: Steam demand for each mode in kg/h. Must have the same length
+                as propulsion_power. If None and a boiler is attached, demand is treated as zero.
 
         Returns:
             The result of the simulation. FEEMSResult or FEEMSResultForMachinery system.
         """
+        n_steps = len(propulsion_power)
         if not np.isscalar(auxiliary_power_kw):
             assert (
-                len(propulsion_power) == len(auxiliary_power_kw) or len(auxiliary_power_kw) == 1
+                n_steps == len(auxiliary_power_kw) or len(auxiliary_power_kw) == 1
             ), "The length of the auxiliary power must be 1 or the same as the propulsion power"
+        if steam_demand_kg_per_h is not None:
+            if len(steam_demand_kg_per_h) != n_steps:
+                raise ValueError(
+                    f"The length of steam_demand_kg_per_h ({len(steam_demand_kg_per_h)}) must match "
+                    f"propulsion_power ({n_steps})."
+                )
         self._set_input_load_time_interval_from_propulsion_power_time_series(
             propulsion_power_time_series=pd.Series(data=propulsion_power, index=frequency),
             auxiliary_load_kw=auxiliary_power_kw,
             time_is_given_as_interval=True,
         )
+        # Time is given as intervals here, so there is no last-point truncation: the helper's
+        # alignment is a no-op (n_points == n_steps). Routed through the helper anyway to keep a
+        # single boiler-steam code path across all calculation methods.
+        self._set_boiler_steam_demand(steam_demand_kg_per_h)
         return self._run_simulation(
             fuel_specified_by=fuel_specified_by,
             ignore_power_balance=ignore_power_balance,

{runfeemssim-0.5.0 → runfeemssim-0.7.0}/RunFeemsSim.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RunFeemsSim
-Version: 0.5.0
+Version: 0.7.0
 Summary: A library for running feems simulation
 Author-email: Kevin Koosup Yum <kevinkoosup.yum@gmail.com>
 License-Expression: Apache-2.0

{runfeemssim-0.5.0 → runfeemssim-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "RunFeemsSim"
-version = "0.5.0"
+version = "0.7.0"
 description = "A library for running feems simulation"
 readme = "README.md"
 requires-python = ">=3.10"

{runfeemssim-0.5.0 → runfeemssim-0.7.0}/tests/test_machinery_calculation.py

@@ -13,6 +13,7 @@ from feems.components_model.component_mechanical import (
     COGAS,
     EngineMultiFuel,
     FuelCharacteristics,
+    SteamBoiler,
 )
 from feems.fuel import FuelOrigin, FuelSpecifiedBy, TypeFuel
 from feems.system_model import ElectricPowerSystem, FuelOption
@@ -20,6 +21,7 @@ from feems.types_for_feems import EngineCycleType, TypeComponent, TypePower
 from MachSysS.convert_to_feems import convert_proto_propulsion_system_to_feems
 from MachSysS.gymir_result_pb2 import (
     GymirResult,
+    PropulsionPowerInstance,
     PropulsionPowerInstanceForMultiplePropulsors,
     SimulationInstance,
     TimeSeriesResult,
@@ -461,3 +463,209 @@ def test_machinery_calculation_multifuel_coges():
         rtol=1e-6,
     ), "Explicit LNG option should match default"
 
+
+
+# --- Boiler steam demand carried through TimeSeriesResult ---------------------------------
+#
+# These tests cover boiler_steam_demand_kg_per_h on the TimeSeriesResult proto: the value is
+# read back by the converter and applied to the system boiler, producing boiler fuel/CO2 that
+# matches the equivalent table-mode path (calculate_..._from_propulsion_power_time_series with
+# the same steam_demand_kg_per_h array). Both paths use a timestamp series, so the last point is
+# dropped during integration; the helper that builds the proto and the table array shares the
+# same epochs/steam values, so they stay aligned.
+
+_BOILER_EPOCHS = [0, 60, 120, 180]
+_BOILER_PROPULSION_KW = [1500.0, 1600.0, 1700.0, 1800.0]
+_BOILER_AUX_KW = 200.0
+
+
+def _make_steam_boiler() -> SteamBoiler:
+    flat_eff = np.array([[0.25, 0.85], [0.50, 0.85], [0.75, 0.85], [1.00, 0.85]])
+    return SteamBoiler(
+        name="test boiler",
+        rated_steam_production_kg_per_h=10_000.0,
+        working_pressure_barg=6.0,
+        thermal_efficiency_curve=flat_eff,
+        fuel_type=TypeFuel.HFO,
+        fuel_origin=FuelOrigin.FOSSIL,
+        feed_water_temperature_c=80.0,
+        uid="boiler-uid-ts",
+    )
+
+
+def _build_boiler_machinery_calculation() -> MachineryCalculation:
+    """Fresh MachineryCalculation (electric system) with a standalone boiler attached.
+
+    A fresh instance is required per run because boiler.steam_out_kg_per_h is mutated in place.
+    """
+    package_dir = os.path.dirname(os.path.abspath(__file__))
+    path = os.path.join(package_dir, "system_proto.mss")
+    system_feems = convert_proto_propulsion_system_to_feems(retrieve_machinery_system_from_file(path))
+    system_feems.boiler = _make_steam_boiler()
+    return MachineryCalculation(feems_system=system_feems)
+
+
+def _table_mode_boiler_result(steam_demand_kg_per_h: np.ndarray):
+    series = pd.Series(index=_BOILER_EPOCHS, data=_BOILER_PROPULSION_KW)
+    return _build_boiler_machinery_calculation().calculate_machinery_system_output_from_propulsion_power_time_series(
+        propulsion_power=series,
+        auxiliary_power_kw=_BOILER_AUX_KW,
+        steam_demand_kg_per_h=steam_demand_kg_per_h,
+    )
+
+
+def test_time_series_result_per_instance_boiler_steam_matches_table_mode():
+    """AC1: per-timestep boiler_steam_demand_kg_per_h matches the table-mode path."""
+    steam = np.array([2000.0, 3000.0, 4000.0, 5000.0])
+    time_series = TimeSeriesResult(
+        propulsion_power_timeseries=[
+            PropulsionPowerInstance(
+                epoch_s=epoch,
+                propulsion_power_kw=prop,
+                auxiliary_power_kw=_BOILER_AUX_KW,
+                boiler_steam_demand_kg_per_h=s,
+            )
+            for epoch, prop, s in zip(_BOILER_EPOCHS, _BOILER_PROPULSION_KW, steam)
+        ],
+    )
+    res_proto = _build_boiler_machinery_calculation().calculate_machinery_system_output_from_time_series_result(
+        time_series=time_series
+    )
+    res_table = _table_mode_boiler_result(steam)
+
+    # Boiler actually ran (guards against a silently-zero comparison).
+    assert res_proto.fuel_consumption_boiler_total.total_fuel_consumption > 0
+    assert res_proto.steam_production_boiler_total_kg > 0
+    # Independent absolute check so a bug in the shared steam-alignment helper can't be hidden by
+    # the proto==table comparison (both route through it). The last timestamp is dropped, so the
+    # integrated steam is [2000, 3000, 4000] kg/h over three 60 s intervals = 9000/3600*60 = 150 kg.
+    assert np.isclose(res_proto.steam_production_boiler_total_kg, 150.0)
+    assert np.isclose(
+        res_proto.fuel_consumption_boiler_total.total_fuel_consumption,
+        res_table.fuel_consumption_boiler_total.total_fuel_consumption,
+    )
+    assert np.isclose(
+        res_proto.fuel_consumption_boiler_total.get_total_co2_emissions().tank_to_wake_kg_or_gco2eq_per_gfuel,
+        res_table.fuel_consumption_boiler_total.get_total_co2_emissions().tank_to_wake_kg_or_gco2eq_per_gfuel,
+    )
+    assert np.isclose(
+        res_proto.steam_production_boiler_total_kg,
+        res_table.steam_production_boiler_total_kg,
+    )
+
+
+def test_time_series_result_constant_boiler_steam_fallback():
+    """AC2: all-zero per-instance values + non-zero top-level constant behaves as a constant."""
+    constant = 3500.0
+    time_series = TimeSeriesResult(
+        propulsion_power_timeseries=[
+            PropulsionPowerInstance(
+                epoch_s=epoch,
+                propulsion_power_kw=prop,
+                auxiliary_power_kw=_BOILER_AUX_KW,
+                # boiler_steam_demand_kg_per_h left at 0 on every instance
+            )
+            for epoch, prop in zip(_BOILER_EPOCHS, _BOILER_PROPULSION_KW)
+        ],
+        boiler_steam_demand_kg_per_h=constant,
+    )
+    res_proto = _build_boiler_machinery_calculation().calculate_machinery_system_output_from_time_series_result(
+        time_series=time_series
+    )
+    res_table = _table_mode_boiler_result(np.full(len(_BOILER_EPOCHS), constant))
+
+    assert res_proto.fuel_consumption_boiler_total.total_fuel_consumption > 0
+    assert np.isclose(
+        res_proto.fuel_consumption_boiler_total.total_fuel_consumption,
+        res_table.fuel_consumption_boiler_total.total_fuel_consumption,
+    )
+    assert np.isclose(
+        res_proto.steam_production_boiler_total_kg,
+        res_table.steam_production_boiler_total_kg,
+    )
+
+
+def test_time_series_result_zero_boiler_steam_no_contribution():
+    """AC3: all fields zero produces zero boiler contribution (no regression)."""
+    time_series = TimeSeriesResult(
+        propulsion_power_timeseries=[
+            PropulsionPowerInstance(
+                epoch_s=epoch,
+                propulsion_power_kw=prop,
+                auxiliary_power_kw=_BOILER_AUX_KW,
+            )
+            for epoch, prop in zip(_BOILER_EPOCHS, _BOILER_PROPULSION_KW)
+        ],
+    )
+    res_proto = _build_boiler_machinery_calculation().calculate_machinery_system_output_from_time_series_result(
+        time_series=time_series
+    )
+    assert res_proto.fuel_consumption_boiler_total.total_fuel_consumption == 0.0
+    assert res_proto.steam_production_boiler_total_kg == 0.0
+
+
+def test_time_series_result_explicit_steam_demand_overrides_proto():
+    """The explicit steam_demand_kg_per_h argument takes precedence over the proto value."""
+    explicit = np.array([2000.0, 3000.0, 4000.0, 5000.0])
+    # Proto carries a different (constant) value that must be ignored when the arg is given.
+    time_series = TimeSeriesResult(
+        propulsion_power_timeseries=[
+            PropulsionPowerInstance(
+                epoch_s=epoch,
+                propulsion_power_kw=prop,
+                auxiliary_power_kw=_BOILER_AUX_KW,
+            )
+            for epoch, prop in zip(_BOILER_EPOCHS, _BOILER_PROPULSION_KW)
+        ],
+        boiler_steam_demand_kg_per_h=9999.0,
+    )
+    res_override = _build_boiler_machinery_calculation().calculate_machinery_system_output_from_time_series_result(
+        time_series=time_series,
+        steam_demand_kg_per_h=explicit,
+    )
+    res_table = _table_mode_boiler_result(explicit)
+    assert np.isclose(
+        res_override.fuel_consumption_boiler_total.total_fuel_consumption,
+        res_table.fuel_consumption_boiler_total.total_fuel_consumption,
+    )
+
+
+def test_time_series_result_multiple_propulsors_boiler_steam():
+    """Per-instance boiler steam is carried through the multi-propulsor time-series path.
+
+    The boiler depends only on steam demand and the integration intervals, not on how propulsion
+    power is split across drives, so the boiler fuel/steam must match the single-propulsor
+    table-mode result for the same epochs and steam profile.
+    """
+    steam = np.array([2000.0, 3000.0, 4000.0, 5000.0])
+    machinery_calculation = _build_boiler_machinery_calculation()
+    propulsor_names = [drive.name for drive in machinery_calculation.electric_system.propulsion_drives]
+    # Split the same total propulsion power equally across the drives.
+    per_drive_power = [[prop / len(propulsor_names)] * len(propulsor_names) for prop in _BOILER_PROPULSION_KW]
+    time_series = TimeSeriesResultForMultiplePropulsors(
+        propulsion_power_timeseries=[
+            PropulsionPowerInstanceForMultiplePropulsors(
+                epoch_s=epoch,
+                propulsion_power_kw=power_row,
+                auxiliary_power_kw=_BOILER_AUX_KW,
+                boiler_steam_demand_kg_per_h=s,
+            )
+            for epoch, power_row, s in zip(_BOILER_EPOCHS, per_drive_power, steam)
+        ],
+        propulsor_names=propulsor_names,
+    )
+    res_proto = machinery_calculation.calculate_machinery_system_output_from_time_series_result(
+        time_series=time_series
+    )
+    res_table = _table_mode_boiler_result(steam)
+
+    assert res_proto.fuel_consumption_boiler_total.total_fuel_consumption > 0
+    assert np.isclose(res_proto.steam_production_boiler_total_kg, 150.0)
+    assert np.isclose(
+        res_proto.fuel_consumption_boiler_total.total_fuel_consumption,
+        res_table.fuel_consumption_boiler_total.total_fuel_consumption,
+    )
+    assert np.isclose(
+        res_proto.steam_production_boiler_total_kg,
+        res_table.steam_production_boiler_total_kg,
+    )