mosaik-emissions 0.1.0__tar.gz → 1.0.0__tar.gz

mosaik_emissions-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+**/__pycache__
+dist
+.coverage
+coverage.xml
+pytest-*.xml
+uv.lock

{mosaik_emissions-0.1.0 → mosaik_emissions-1.0.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 mosaik development team
+Copyright (c) 2025 Danila Valko & mosaik development team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mosaik_emissions-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mosaik-emissions
+Version: 1.0.0
+Summary: Carbon emissions simulator for mosaik.
+Author-email: Danila Valko <mosaik@offis.de>
+License: MIT License
+        
+        Copyright (c) 2025 Danila Valko & mosaik development team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mosaik-api-v3<4,>=3.0.4
+Requires-Dist: numpy>=1.26.1
+Requires-Dist: pandas>=2.1.2
+Requires-Dist: rapidfuzz>=3.14.3
+Description-Content-Type: text/markdown
+
+This simulator implements CO₂-emissions calculations for a given [mosaik] scenario and power-unit configuration.
+
+> **Note:** This simulator is still a work in progress. Not all desired attributes are implemented yet. If you need support for a specific attribute, please open an [issue here].
+
+[mosaik]: https://mosaik.offis.de
+[issue here]: https://gitlab.com/mosaik/components/energy/mosaik-emissions/-/issues
+
+
+## Installation
+
+```python
+pip install mosaik-emissions
+```
+
+## Methodology and Usage
+
+CO₂ emissions are dynamically aggregated based on predefined power-unit characteristics.
+The following attributes are currently implemented:
+
+* P[MW] – power (input/output)
+* E[tCO₂eq] – total emissions (output)
+* I[tCO₂eq/MWh] – average carbon intensity (output)
+
+The basic calculation converts input power into estimated total carbon emissions by multiplying it with the designated carbon-intensity value (emission factor), typically expressed in gCO₂eq/kWh.
+
+If multiple inputs assigned with different carbon-intensity values, the resulting intensity is computed as a power-weighted average. While the average carbon intensity is always reported in tCO₂eq/MWh (numerically equivalent to gCO₂eq/kWh), total emissions take the simulation step size into account.
+
+The emission factor / carbon intensity is defined as part of the model parameters when simulator entities are created, as commonly done in a [mosaik] scenario.
+
+The available parameters depend on the selected data source. Several data sources are integrated (see the table below). For each data source, identified by an `id`, multiple filtering parameters may be used, such as reference year, country, state, fuel type, etc.
+
+| Source & Description | Parameters |
+|--------|------------|
+*id: "2006IPCC"* - [2006 IPCC Default Fuel Emission Factors](https://ghgprotocol.org/sites/default/files/2024-05/Emission_Factors_for_Cross_Sector_Tools_V2.0_0.xlsx) | **year**: 2006, **fuel**: [Crude oil, Natural gas, ..]
+*id: "OWD"* - [Our World in Data](https://ourworldindata.org/grapher/carbon-intensity-electricity), country average carbon intencity of electricity, yearly resolution | **year**: 1990-2023, **country_code**: [AFG, DNK, DEU, ..]
+*id: "CO2MAP"* - INATECH [CO2Map](https://co2map.de), carbon intensity in hourly resolution, estimates based on `production` and `consumption`  | **year**: 2020-2024, **country_code**: DEU, **state_code**: [BY, BB, SL, ..], **scope**: [prod, cons]
+*id: "EMAPS"* - [Electricity Maps](https://app.electricitymaps.com/datasets), carbon intensity in hourly resolution, `direct` and `lifecycle` estimates | **year**: 2021-2024, **country_code**: DEU, **scope**: [direct, lifecycle]
+
+
+Parameters are applied from the most specific to the least specific; the exact priority corresponds to the reversed column order of the respective data file (see the files in the `data` directory).
+
+
+### Usage example
+
+```python
+    emission_config = {
+        "id": "CO2MAP",
+        "country_code": "DEU",
+        "state_code": "BY",
+        "scope": "cons",
+    }
+    emission = world.start("EmissionSim").Emission(**emission_config)
+    const = world.start("Const").Const(value=5)
+    world.connect(const, emission, ("value", "P[MW]"))
+    world.connect(emission, csv_writer, "P[MW]")
+    world.connect(emission, csv_writer, "E[tCO₂eq]")
+    world.connect(emission, csv_writer, "I[tCO₂eq/MWh]")
+    world.run(until=1)
+```
+
+If the selected data source provides suitable (that matches the parameters) historical time series, the simulator will use them.
+If no appropriate time series are available or if manual configuration is preferred one may directly define the emission factor for a specific entity or provide a callable.
+
+### Manual configuration examples
+
+```python
+# Manual emission factor
+em.create(1, "Emission", **{
+    "emission_factor": 8.0,
+})
+```
+
+```python
+# Manual method
+def get_value(**kwargs):
+    print("print from a method call:", kwargs)
+    return 100.0
+
+em.create(1, "Emission", **{
+    "method": get_value,
+})
+```
+
+The `start` parameter sets the starting time for the time series, but the simulator will use the data point *nearest* to the reference `year`. If only one data point is available, it will be the sole result. If no reference year is specified, the year is taken from the `start` parameter. The default value of `start` is `"2020-01-01 00:00:00"`.
+
+A simple `multiplier` parameter is also available (default: `1.0`) and is applied to the resulting carbon-intensity value.
+
+## Custom Data
+
+### Data structure
+Data files can be extended or replaced, and additional sources may be added directly to the `data` directory as .csv or zip. To be automatically detected and merged with the internal database, each data file must follow the required column structure:
+
+```python
+datetime;carbon_intensity[gCO₂eq/kWh];id;year
+2020-01-01 00:00:00+00:00;651.0;CO2MAP;2020
+2020-01-01 01:00:00+00:00;679.0;CO2MAP;2020
+```
+
+* datetime – timeseries index
+* carbon_intensity[gCO₂eq/kWh] – intensity values (float)
+* id – data source identifier (str)
+* year – reference year (int)
+
+
+Any additional columns may follow. As long as the first three columns match this structure, the simulator will automatically read the file and incorporate it into the available data sources.
+
+Other columns, beyond the required first three, are interpreted as filtering parameters. These parameters are applied in reversed column order (i.e., the rightmost column has the highest priority). This allows you to filter data by fields such as fuel type, region, year, or any other metadata you include.
+
+If you introduce parameter columns that do not match the existing ones, you will also need to update the mosaik `meta` structure in `emission_simulator.py` accordingly so that the simulator can recognize these new parameters.
+
+### Other Usage
+
+If you only want to access carbon-intensity data or test whether a configuration and custom database work correctly, you can use the `get_stored_values` function. By default, it uses parameters that correspond directly to the data columns.
+
+```python
+em = Simulator()
+em.init()
+values = em.get_stored_values(**{
+    "id": "2006IPCC",
+    "fuel": "Natural gas",
+})
+print(values)
+assert str(values["intensity"].index[0]) == "2020-01-01 00:00:00+00:00"
+```
+
+
+## Citation
+
+#### APA-like format
+```tex
+Valko, D., Alsharif, S., & Tolk, D. (2024). An Open-Source Carbon Emissions Simulator for Smart Grid Co-Simulation Scenarios. European Simulation and Modelling Conference 2024 (ESM 2024), San Sebastian, Spain. https://doi.org/10.5281/zenodo.13984401
+```
+#### BibTeX format
+```tex
+@inproceedings{ValkoAlsharifTolk2024,
+title={An Open-Source Carbon Emissions Simulator for Smart Grid Co-Simulation Scenarios},
+author={Danila Valko and Sharaf Alsharif and Deborah Tolk},
+year={2024},
+pages={355-360},
+publisher={EUROSIS-ETI},
+booktitle={European Simulation and Modelling Conference 2024 (ESM 2024)},
+doi={10.5281/zenodo.13984401},
+}
+```
+
+## Sources and References
+
+* Ember - Yearly Electricity Data (2023); Ember - European Electricity Review (2022); Energy Institute - Statistical Review of World Energy (2023) – with major processing by Our World in Data. “Carbon intensity of electricity generation” [dataset]. Ember, “Yearly Electricity Data”; Ember, “European Electricity Review”; Energy Institute, “Statistical Review of World Energy” [original data]. Retrieved February 27, 2024 from https://ourworldindata.org/grapher/carbon-intensity-electricity
+
+* Hourly consumption-based CO2 emissions intensity in Germany / [co2map.de](https://co2map.de/), INATECH, University of Freiburg. Retrieved February 27, 2024 from https://api.co2map.de/docs

mosaik_emissions-1.0.0/README.md

@@ -0,0 +1,150 @@
+This simulator implements CO₂-emissions calculations for a given [mosaik] scenario and power-unit configuration.
+
+> **Note:** This simulator is still a work in progress. Not all desired attributes are implemented yet. If you need support for a specific attribute, please open an [issue here].
+
+[mosaik]: https://mosaik.offis.de
+[issue here]: https://gitlab.com/mosaik/components/energy/mosaik-emissions/-/issues
+
+
+## Installation
+
+```python
+pip install mosaik-emissions
+```
+
+## Methodology and Usage
+
+CO₂ emissions are dynamically aggregated based on predefined power-unit characteristics.
+The following attributes are currently implemented:
+
+* P[MW] – power (input/output)
+* E[tCO₂eq] – total emissions (output)
+* I[tCO₂eq/MWh] – average carbon intensity (output)
+
+The basic calculation converts input power into estimated total carbon emissions by multiplying it with the designated carbon-intensity value (emission factor), typically expressed in gCO₂eq/kWh.
+
+If multiple inputs assigned with different carbon-intensity values, the resulting intensity is computed as a power-weighted average. While the average carbon intensity is always reported in tCO₂eq/MWh (numerically equivalent to gCO₂eq/kWh), total emissions take the simulation step size into account.
+
+The emission factor / carbon intensity is defined as part of the model parameters when simulator entities are created, as commonly done in a [mosaik] scenario.
+
+The available parameters depend on the selected data source. Several data sources are integrated (see the table below). For each data source, identified by an `id`, multiple filtering parameters may be used, such as reference year, country, state, fuel type, etc.
+
+| Source & Description | Parameters |
+|--------|------------|
+*id: "2006IPCC"* - [2006 IPCC Default Fuel Emission Factors](https://ghgprotocol.org/sites/default/files/2024-05/Emission_Factors_for_Cross_Sector_Tools_V2.0_0.xlsx) | **year**: 2006, **fuel**: [Crude oil, Natural gas, ..]
+*id: "OWD"* - [Our World in Data](https://ourworldindata.org/grapher/carbon-intensity-electricity), country average carbon intencity of electricity, yearly resolution | **year**: 1990-2023, **country_code**: [AFG, DNK, DEU, ..]
+*id: "CO2MAP"* - INATECH [CO2Map](https://co2map.de), carbon intensity in hourly resolution, estimates based on `production` and `consumption`  | **year**: 2020-2024, **country_code**: DEU, **state_code**: [BY, BB, SL, ..], **scope**: [prod, cons]
+*id: "EMAPS"* - [Electricity Maps](https://app.electricitymaps.com/datasets), carbon intensity in hourly resolution, `direct` and `lifecycle` estimates | **year**: 2021-2024, **country_code**: DEU, **scope**: [direct, lifecycle]
+
+
+Parameters are applied from the most specific to the least specific; the exact priority corresponds to the reversed column order of the respective data file (see the files in the `data` directory).
+
+
+### Usage example
+
+```python
+    emission_config = {
+        "id": "CO2MAP",
+        "country_code": "DEU",
+        "state_code": "BY",
+        "scope": "cons",
+    }
+    emission = world.start("EmissionSim").Emission(**emission_config)
+    const = world.start("Const").Const(value=5)
+    world.connect(const, emission, ("value", "P[MW]"))
+    world.connect(emission, csv_writer, "P[MW]")
+    world.connect(emission, csv_writer, "E[tCO₂eq]")
+    world.connect(emission, csv_writer, "I[tCO₂eq/MWh]")
+    world.run(until=1)
+```
+
+If the selected data source provides suitable (that matches the parameters) historical time series, the simulator will use them.
+If no appropriate time series are available or if manual configuration is preferred one may directly define the emission factor for a specific entity or provide a callable.
+
+### Manual configuration examples
+
+```python
+# Manual emission factor
+em.create(1, "Emission", **{
+    "emission_factor": 8.0,
+})
+```
+
+```python
+# Manual method
+def get_value(**kwargs):
+    print("print from a method call:", kwargs)
+    return 100.0
+
+em.create(1, "Emission", **{
+    "method": get_value,
+})
+```
+
+The `start` parameter sets the starting time for the time series, but the simulator will use the data point *nearest* to the reference `year`. If only one data point is available, it will be the sole result. If no reference year is specified, the year is taken from the `start` parameter. The default value of `start` is `"2020-01-01 00:00:00"`.
+
+A simple `multiplier` parameter is also available (default: `1.0`) and is applied to the resulting carbon-intensity value.
+
+## Custom Data
+
+### Data structure
+Data files can be extended or replaced, and additional sources may be added directly to the `data` directory as .csv or zip. To be automatically detected and merged with the internal database, each data file must follow the required column structure:
+
+```python
+datetime;carbon_intensity[gCO₂eq/kWh];id;year
+2020-01-01 00:00:00+00:00;651.0;CO2MAP;2020
+2020-01-01 01:00:00+00:00;679.0;CO2MAP;2020
+```
+
+* datetime – timeseries index
+* carbon_intensity[gCO₂eq/kWh] – intensity values (float)
+* id – data source identifier (str)
+* year – reference year (int)
+
+
+Any additional columns may follow. As long as the first three columns match this structure, the simulator will automatically read the file and incorporate it into the available data sources.
+
+Other columns, beyond the required first three, are interpreted as filtering parameters. These parameters are applied in reversed column order (i.e., the rightmost column has the highest priority). This allows you to filter data by fields such as fuel type, region, year, or any other metadata you include.
+
+If you introduce parameter columns that do not match the existing ones, you will also need to update the mosaik `meta` structure in `emission_simulator.py` accordingly so that the simulator can recognize these new parameters.
+
+### Other Usage
+
+If you only want to access carbon-intensity data or test whether a configuration and custom database work correctly, you can use the `get_stored_values` function. By default, it uses parameters that correspond directly to the data columns.
+
+```python
+em = Simulator()
+em.init()
+values = em.get_stored_values(**{
+    "id": "2006IPCC",
+    "fuel": "Natural gas",
+})
+print(values)
+assert str(values["intensity"].index[0]) == "2020-01-01 00:00:00+00:00"
+```
+
+
+## Citation
+
+#### APA-like format
+```tex
+Valko, D., Alsharif, S., & Tolk, D. (2024). An Open-Source Carbon Emissions Simulator for Smart Grid Co-Simulation Scenarios. European Simulation and Modelling Conference 2024 (ESM 2024), San Sebastian, Spain. https://doi.org/10.5281/zenodo.13984401
+```
+#### BibTeX format
+```tex
+@inproceedings{ValkoAlsharifTolk2024,
+title={An Open-Source Carbon Emissions Simulator for Smart Grid Co-Simulation Scenarios},
+author={Danila Valko and Sharaf Alsharif and Deborah Tolk},
+year={2024},
+pages={355-360},
+publisher={EUROSIS-ETI},
+booktitle={European Simulation and Modelling Conference 2024 (ESM 2024)},
+doi={10.5281/zenodo.13984401},
+}
+```
+
+## Sources and References
+
+* Ember - Yearly Electricity Data (2023); Ember - European Electricity Review (2022); Energy Institute - Statistical Review of World Energy (2023) – with major processing by Our World in Data. “Carbon intensity of electricity generation” [dataset]. Ember, “Yearly Electricity Data”; Ember, “European Electricity Review”; Energy Institute, “Statistical Review of World Energy” [original data]. Retrieved February 27, 2024 from https://ourworldindata.org/grapher/carbon-intensity-electricity
+
+* Hourly consumption-based CO2 emissions intensity in Germany / [co2map.de](https://co2map.de/), INATECH, University of Freiburg. Retrieved February 27, 2024 from https://api.co2map.de/docs

mosaik_emissions-1.0.0/mosaik_components/emissions/__init__.py

@@ -0,0 +1,12 @@
+import mosaik_api_v3
+from mosaik_components.emissions.emission_simulator import Simulator
+
+__all__ = ["Simulator"]
+
+
+def main():
+    mosaik_api_v3.start_simulation(Simulator(), "run the emission simulator for mosaik")
+
+
+if __name__ == "__main__":
+    main()