documentation for industry rules

scripts/build_ammonia_production.py

@@ -4,6 +4,21 @@
 # SPDX-License-Identifier: MIT
 """
 Build historical annual ammonia production per country in ktonNH3/a.
+
+Inputs
+-------
+
+- ``data/bundle-sector/myb1-2017-nitro.xls``
+
+Outputs
+-------
+
+- ``resources/ammonia_production.csv``
+
+Description
+-------
+
+This functions takes data from the `Minerals Yearbook <https://www.usgs.gov/centers/national-minerals-information-center/nitrogen-statistics-and-information>`_ (June 2024) published by the US Geological Survey (USGS) and the National Minerals Information Center and extracts the annual ammonia production per country in ktonN/a. The data is converted to ktonNH3/a.
 """
 
 import country_converter as coco

scripts/build_industrial_distribution_key.py

@@ -4,6 +4,37 @@
 # SPDX-License-Identifier: MIT
 """
 Build spatial distribution of industries from Hotmaps database.
+
+Inputs
+-------
+
+- ``resources/regions_onshore_elec_s{simpl}_{clusters}.geojson``
+- ``resources/pop_layout_elec_s{simpl}_{clusters}.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_distribution_key_elec_s{simpl}_{clusters}.csv``
+
+Description
+-------
+
+This rule uses the `Hotmaps database <https://gitlab.com/hotmaps/industrial_sites/industrial_sites_Industrial_Database>`. After removing entries without valid locations, it assigns each industrial site to a bus region based on its location.
+Then, it calculates the nodal distribution key for each sector based on the emissions of the industrial sites in each region. This leads to a distribution key of 1 if there is only one bus per country and <1 if there are multiple buses per country. The sum over buses of one country is 1.
+
+The following subcategories of industry are considered:
+- Iron and steel
+- Cement
+- Refineries
+- Paper and printing
+- Chemical industry
+- Glass
+- Non-ferrous metals
+- Non-metallic mineral products
+- Other non-classified
+Furthermore, the population distribution is added
+- Population
+
 """
 
 import logging

scripts/build_industrial_energy_demand_per_country_today.py

@@ -4,6 +4,61 @@
 # SPDX-License-Identifier: MIT
 """
 Build industrial energy demand per country.
+
+Inputs
+-------
+
+- ``data/bundle/jrc-idees-2015``
+- ``industrial_production_per_country.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_energy_demand_per_country_today.csv``
+
+Description
+-------
+
+This rule uses the industrial_production_per_country.csv file and the JRC-IDEES data to derive an energy demand per country and sector. If the country is not in the EU28, an average energy demand depending on the production volume is derived.
+For each country and each subcategory of
+
+- Alumina production
+- Aluminium - primary production
+- Aluminium - secondary production
+- Ammonia
+- Cement
+- Ceramics & other NMM
+- Chlorine
+- Electric arc
+- Food, beverages and tobacco
+- Glass production
+- HVC
+- Integrated steelworks
+- Machinery Equipment
+- Methanol
+- Other Industrial Sectors
+- Other chemicals
+- Other non-ferrous metals
+- Paper production
+- Pharmaceutical products etc.
+- Printing and media reproduction
+- Pulp production
+- Textiles and leather
+- Transport Equipment
+- Wood and wood products
+
+the output file contains the energy demand in TWh/a for the following carriers
+
+- biomass
+- electricity
+- gas
+- heat
+- hydrogen
+- liquid
+- other
+- solid
+- waste
+
 """
 
 import multiprocessing as mp

scripts/build_industrial_energy_demand_per_node.py

@@ -4,6 +4,36 @@
 # SPDX-License-Identifier: MIT
 """
 Build industrial energy demand per model region.
+
+Inputs
+------
+
+- ``resources/industrial_energy_demand_today_elec_s{simpl}_{clusters}.csv``
+- ``resources/industry_sector_ratios_{planning_horizons}.csv``
+- ``resources/industrial_production_elec_s{simpl}_{clusters}_{planning_horizons}.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_energy_demand_elec_s{simpl}_{clusters}_{planning_horizons}.csv``
+
+Description
+-------
+This rule aggregates the energy demand of the industrial sectors per model region.
+For each bus, the following carriers are considered:
+- electricity
+- coal
+- coke
+- solid biomass
+- methane
+- hydrogen
+- low-temperature heat
+- naphtha
+- ammonia
+- process emission
+- process emission from feedstock
+
+which can later be used as values for the industry load.
 """
 
 import pandas as pd

scripts/build_industrial_energy_demand_per_node_today.py

@@ -4,6 +4,25 @@
 # SPDX-License-Identifier: MIT
 """
 Build industrial energy demand per model region.
+
+Inputs
+-------
+
+- ``resources/industrial_distribution_key_elec_s{simpl}_{clusters}.csv``
+- ``resources/industrial_energy_demand_per_country_today.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_energy_demand_per_node_today_elec_s{simpl}_{clusters}.csv``
+
+Description
+-------
+
+This rule maps the industrial energy demand per country `industrial_energy_demand_per_country_today.csv` to each bus region.
+The energy demand per country is multiplied by the mapping value from the file ``industrial_distribution_key_elec_s{simpl}_{clusters}.csv`` between 0 and 1 to get the industrial energy demand per bus.
+
+The unit of the energy demand is TWh/a.
 """
 
 from itertools import product

scripts/build_industrial_production_per_country.py

@@ -3,7 +3,63 @@
 #
 # SPDX-License-Identifier: MIT
 """
-Build industrial production per country.
+This rule builds the historical industrial production per country.
+
+Relevant Settings
+-----------------
+
+.. code:: yaml
+
+    countries:
+..
+
+Inputs
+-------
+- ``resources/ammonia_production.csv``
+- ``data/bundle-sector/jrc-idees-2015``
+- ``data/eurostat``
+
+Outputs
+-------
+
+- ``resources/industrial_production_per_country.csv``
+
+Description
+-------
+
+The industrial production is taken from the `JRC-IDEES <https://joint-research-centre.ec.europa.eu/potencia-policy-oriented-tool-energy-and-climate-change-impact-assessment/jrc-idees_en)>`.
+This dataset provides detailed information about the consumption of energy for various processes.
+If the country is not part of the EU28, the energy consumption in the industrial sectors is taken from the `Eurostat <https://ec.europa.eu/eurostat/de/data/database>` dataset. The industrial production is calculated for the year specified in the config["industry"]["reference_year"].
+
+The ammonia production is provided by the rule `build_ammonia_production <https://pypsa-eur.readthedocs.io/en/latest/sector.html#module-build_ammonia_production>`. Since Switzerland is not part of the EU28 nor reported by eurostat, the energy consumption in the industrial sectors is taken from the `BFE <https://www.bfe.admin.ch/bfe/de/home/versorgung/statistik-und-geodaten/energiestatistiken/energieverbrauch-nach-verwendungszweck.html> dataset.
+After the industrial production is calculated, the basic chemicals are separated into ammonia, chlorine, methanol and HVC. The production of these chemicals is assumed to be proportional to the production of basic chemicals without ammonia.
+
+The following subcategories [kton/a] are considered:
+- Electric arc
+- Integrated steelworks
+- Other chemicals
+- Pharmaceutical products etc.
+- Cement
+- Ceramics & other NMM
+- Glass production
+- Pulp production
+- Paper production
+- Printing and media reproduction
+- Food, beverages and tobacco
+- Alumina production
+- Aluminium - primary production
+- Aluminium - secondary production
+- Other non-ferrous metals
+- Transport Equipment
+- Machinery Equipment
+- Textiles and leather
+- Wood and wood products
+- Other Industrial Sectors
+- Ammonia
+- HVC
+- Chlorine
+- Methanol
+
 """
 
 import logging

scripts/build_industrial_production_per_country_tomorrow.py

@@ -4,6 +4,59 @@
 # SPDX-License-Identifier: MIT
 """
 Build future industrial production per country.
+
+Relevant Settings
+-----------------
+
+.. code:: yaml
+
+    industry:
+        St_primary_fraction:
+        DRI_fraction:
+        Al_primary_fraction:
+        HVC_primary_fraction:
+        HVC_mechanical_recycling_fraction:
+        HVC_chemical_recycling_fraction:
+.. seealso::
+    Documentation of the configuration file ``config/config.yaml`` at
+    :ref:`industry`
+
+Inputs
+-------
+
+- ``resources/industrial_production_per_country.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_production_per_country_tomorrow_{planning_horizons}.csv``
+
+Description
+-------
+
+This rule uses the ``industrial_production_per_country.csv`` file and the expected recycling rates to calculate the future production of the industrial sectors.
+
+**St_primary_fraction**
+The fraction of steel that is coming from primary production. This is more energy intensive than recycling steel (secondary production).
+
+**DRI_fraction**
+The fraction of primary steel that is produced in DRI plants.
+
+**Al_primary_fraction**
+The fraction of aluminium that is coming from primary production. This is more energy intensive than recycling aluminium (secondary production).
+
+**HVC_primary_fraction**
+The fraction of high value chemicals that are coming from primary production (crude oil or Fischer Tropsch).
+
+**HVC_mechanical_recycling_fraction**
+The fraction of high value chemicals that are coming from mechanical recycling.
+
+**HVC_chemical_recycling_fraction**
+The fraction of high value chemicals that are coming from chemical recycling.
+
+If not already present, the information is added as new column in the output file.
+
+The unit of the production is kt/a.
 """
 
 import pandas as pd

scripts/build_industrial_production_per_node.py

@@ -4,6 +4,26 @@
 # SPDX-License-Identifier: MIT
 """
 Build industrial production per model region.
+
+Inputs
+-------
+
+- ``resources/industrial_distribution_key_elec_s{simpl}_{clusters}.csv``
+- ``resources/industrial_production_per_country_tomorrow_{planning_horizons}.csv``
+
+Outputs
+-------
+
+- ``resources/industrial_production_per_node_elec_s{simpl}_{clusters}_{planning_horizons}.csv``
+
+Description
+-------
+
+This rule maps the industrial production per country from a certain time horizon to each bus region.
+The mapping file provides a value between 0 and 1 for each bus and industry subcategory, indicating the share of the country's production of that sector in that bus.
+The industrial production per country is multiplied by the mapping value to get the industrial production per bus.
+The unit of the production is kt/a.
+
 """
 
 from itertools import product

scripts/build_industry_sector_ratios.py

@@ -3,7 +3,49 @@
 #
 # SPDX-License-Identifier: MIT
 """
-Build specific energy consumption by carrier and industries.
+Build best case specific energy consumption by carrier and category.
+
+Relevant Settings
+-----------------
+
+.. code:: yaml
+
+    industry:
+        ammonia:
+..
+
+Inputs
+-------
+- ``resources/ammonia_production.csv``
+- ``data/bundle-sector/jrc-idees-2015``
+
+Outputs
+-------
+
+- ``resources/industry_sector_ratios.csv``
+
+Description
+-------
+
+This script uses the `JRC-IDEES <https://joint-research-centre.ec.europa.eu/potencia-policy-oriented-tool-energy-and-climate-change-impact-assessment/jrc-idees_en>` data to calculate an EU28 average specific energy consumption by carrier and industries.
+The industries are according to the rule `industrial_production_per_country <https://pypsa-eur.readthedocs.io/en/latest/sector.html#module-build_industrial_production_per_country>`.
+
+The following carriers are considered:
+- elec
+- coal
+- coke
+- biomass
+- methane
+- hydrogen
+- heat
+- naphtha
+- process emission
+- process emission from feedstock
+- (ammonia)
+
+If the `config["industry"]["ammonia"] <https://pypsa-eur.readthedocs.io/en/latest/configuration.html#industry>` is set to true the ammonia demand is not converted to hydrogen and electricity but is considered as a separate carrier.
+
+The unit of the specific energy consumption is MWh/t material and tCO2/t material for process emissions.
 """
 
 import pandas as pd