eta-components 1.0.0

Components for modeling industrial production sites

ETA Components

This is a component library for the mathematical modeling of industrial production sites. Currently it provides models for energy converters, such as CHPs, absorption chillers and energy storages, networks to connect these components to and basic models to mock energy sources and sinks.

The energy converter models are largely based on Baumgärtner (2020): "Optimization of low-carbon energy systems from industrial to national scale" p. 128 ff.

Modeling backend (Linopy-only)

eta-components constructs linear / mixed-integer linear models using Linopy + xarray (vectorized, labelled-array model construction). The modeling backend is Linopy-only (no Pyomo fallback).

Components

• A large variety of energy converters:
  • AbsorptionChiller,
  • GasBoiler and ElectrodeBoiler,
  • Chp,
  • AirWaterCompressionChiller and WaterWaterCompressionChiller,
  • DryCooler,
  • ParallelHX and CounterCurrentHX,
  • AirWaterHeatPump and WaterWaterHeatPump and
  • HeatStorage and ColdStorage.
• Networks to enforce energy balance across all connected components:
  • Gas, Hydrogen
  • Electrical (AC/DC variants)
  • HeatingFluid, CoolingFluid
• Environments to provide access to shared parameters:
  • AmbientEnvironment.
• Traders to buy and sell energy across the system's boundaries:
  • SimpleBuyer and SimpleSeller.
• Mock models for fixed energy sources and sinks, such as waste heat sources or cooling demands:
  • SimpleHeatingSource / SimpleHeatingSink
  • SimpleCoolingSource / SimpleCoolingSink
  • SimpleElectricitySource / SimpleElectricitySink
• System orchestration:
  • BasicSystem (Linopy-only)

Features

• On/off operating decisions for all converters.
• Part-load efficiency for all converters.
• Buying decisions for all converters.
• Objective construction via an objective-term registry (e.g. StaticCost, Emissions).
• Plotting of each network's energy production and consumption.
• Indices not only for time steps but also for typical periods and stochastic samples.

What's not implemented yet

• Investment and maintenance cost for all converters.
• Continuous sizing of all converters.
• Sellers and buyers for cooling energy.
  • At the moment these must be implemented with buyers or sellers, respectively (because of negative heat flow).
• Variable temperatures for the networks à la Thermal Dependencies paper.
• Framework for bilevel problems.
• Starting cost, ramp limits and maximum starts per time for relevant equipments.
• Measures for increasing efficiency.
• Material data models for production processes.

Requirements

• Python 3.11 or higher
• A MILP/LP solver supported by Linopy (recommended: HiGHS via highspy)

Installation

To install the project along with its development dependencies, execute the following command:

poetry install

Optionally install the git hooks:

poetry run pre-commit install

Run tests with:

poetry run pytest

Usage

The entire system is modeled as energy flows, thus no volume flows are explicitly implemented. Each converter, trader or energy source or sink must be connected to its corresponding network(s). The networks then enforce an energy balance across all connected components so that energy production and consumption match for each time step. The energy flows are implemented in a thermodynamic contex with each network as the system's boundary. Thus, inlet energy is positive and outlet energy is negative.

E.g. a gas boiler has a negative gas consumption (because it flows out of the gas network) and a positive heat production (because it flows into the heating network). The same goes for electrical energy. Attention is required when using cooling producers or consumers, as cooling producers move heat out of the cooling network (negative production) and cooling consumers move heat into the network (positive consumption).

Quick start

import eta_components.milp_component_library as mcl
from eta_components.milp_component_library.units.base_unit import BaseStandaloneUnit


class DispatchGenerator(BaseStandaloneUnit):
    """Toy generator with linear marginal cost."""

    def __init__(
        self,
        name: str,
        data: dict,
        system: mcl.systems.BasicSystem,
        *,
        electrical_network: mcl.networks.Electrical,
    ):
        self._net = electrical_network
        super().__init__(name, data, system)

    def build(self) -> None:
        idx = self.system.index
        p = self.system.add_variable(
            f"{self.name}__p",
            dims=("year", "period", "time"),
            coords={d: idx.coords[d].values for d in ("year", "period", "time")},
            lower=0,
        )
        self.vars["p"] = p
        self._net.register_unit(self, p, mcl.networks.PowerSign.POSITIVE)
        self.system.add_objective_term(
            f"{self.name}__opex",
            p * float(self.data.get("marginal_cost", 1.0)),
            kind="opex",
        )

    def unregister(self) -> None:
        self._net.unregister_unit(self)
        self.system.unregister_unit(self)

    @property
    def time_step_cost(self):
        return 0

    @property
    def annual_cost(self):
        return 0

    @property
    def onetime_cost(self):
        return 0

    @property
    def emissions(self):
        return 0


sys = mcl.systems.BasicSystem(n_years=1, n_periods=2, n_time_steps=3, step_length=5 * 60)
el = mcl.networks.Electrical("electrical", {}, sys)

# Fixed demand profile: consumption is negative by convention.
demand = {
    (1, 1, 1): -5,
    (1, 1, 2): -4,
    (1, 1, 3): -6,
    (1, 2, 1): -3,
    (1, 2, 2): -2,
    (1, 2, 3): -5,
}
_ = mcl.sources_sinks.SimpleElectricitySink("demand", {"P_in": demand}, sys, electrical_network=el)
_ = DispatchGenerator("gen", {"marginal_cost": 2.0}, sys, electrical_network=el)

sys.set_objective(mcl.objectives.StaticCost("cost", {"sense": "minimize", "weights": 1}, sys))
results = sys.solve(solver="highs", options={"time_limit_s": 30})
print(results.solve_info)
print(results.vars)

Key concepts in this Linopy-first workflow:

• Indexing: system.index defines canonical coordinates for ("year", "period", "time"). Parameters and variables are represented as xarray.DataArray-like objects aligned to these dims. See docs/indexing_and_parameters.md.
• Extension points: build your own variables/constraints using system.add_variable(...) and system.add_constraints(...). For objectives, register terms with system.add_objective_term(...) and use an objective like StaticCost.
• Networks: networks enforce a vectorized power balance (sum of registered power expressions equals zero).

For a longer quickstart, see docs/quickstart_linopy.md. For solver configuration, see docs/solver_options.md.

Example

There are examples in the folder examples/.

License

Refer to the LICENSE file distributed with this package.

Adding dependencies

Adding dependencies to the project can be done via

poetry add <package-name>@latest