Add battery transformation + documentation

docs/extract.rst

@@ -896,9 +896,10 @@ When using ecoinvent 3.8 as a database, *premise* imports new inventories for li
 NMC-111, NMC-6222 NMC-811 and NCA Lithium-ion battery inventories are originally
 from Dai_ et al. 2019. They have been adapted to ecoinvent by Crenna_ et al, 2021.
 LFP and LTO Lithium-ion battery inventories are from  Schmidt_ et al. 2019.
-Li-S battery inventories are from Wickerts_ et al. 2023.
-Li-O2 battery inventories are from Wang_ et al. 2020.
-Finally, SIB battery inventories are from Zhang22_ et al. 2024.
+Li-S (Lithium-sulfur) battery inventories are from Wickerts_ et al. 2023.
+Li-O2 (Lithium-air) battery inventories are from Wang_ et al. 2020.
+Finally, SIB (Sodium-ion) battery inventories are from Zhang22_ et al. 2024.
+Ecoinvent provides also inventories for LMO (Lithium Maganese Oxide) batteries.
 
 They introduce the following datasets:
 

docs/transform.rst

@@ -4,6 +4,33 @@ TRANSFORM
 A series of transformations are applied to the Life Cycle Inventory (LCI) database to align process performance
 and technology market shares with the outputs from the Integrated Assessment Model (IAM) scenario.
 
+Battery
+"""""""
+
+Inventories for several battery technologies are provided in *premise*.
+
+*premise* adjusts the mass of battery packs throughout the database
+to reflect progress in cell energy density.
+
+| Battery Type | 2020 (kWh/kg)        | 2050 Target (kWh/kg) |
+|--------------|----------------------|----------------------|
+| NMC111       | 0.150                | 0.200                |
+| NMC622       | 0.200                | 0.350                |
+| NMC811       | 0.220                | 0.500                |
+| NCA          | 0.280                | 0.350                |
+| LFP          | 0.140                | 0.250                |
+| LTO          | 0.080                | 0.150                |
+| LMO          | 0.130                | 0.200                |
+| Li-O2        | 0.240                | 0.500                |
+| BoP          | 0.2                  | 0.5                  |
+
+For example, in 2050, the mass of NMC811 batteries (cells and Balance of Plant) is expected to
+be 2.3 times lower.
+The report of changes will show the new mass of battery packs in the database.
+
+The target values used for scaling can be modified by the user.
+The YAML file is located in the premise/data/battery/energy_density.yaml.
+
 Biomass
 """""""
 

premise/battery.py

@@ -0,0 +1,153 @@
+"""
+module to adjust the battery inputs to reflect progress in
+terms of cell energy density.
+
+"""
+
+import yaml
+
+from .filesystem_constants import DATA_DIR
+from .logger import create_logger
+from .transformation import BaseTransformation, IAMDataCollection, List, np, ws
+
+logger = create_logger("battery")
+
+
+def load_cell_energy_density():
+    """
+    Load cell energy density data.
+    """
+    with open(DATA_DIR / "battery/energy_density.yaml", "r") as file:
+        data = yaml.load(file, Loader=yaml.FullLoader)
+
+    result = {}
+    for key, value in data.items():
+        names = value['ecoinvent_aliases']['name']
+        if isinstance(names, list):
+            for name in names:
+                result[name] = value['target']
+        else:
+            result[names] = value['target']
+
+    return result
+
+
+def _update_battery(scenario, version, system_model):
+    battery = Battery(
+        database=scenario["database"],
+        iam_data=scenario["iam data"],
+        model=scenario["model"],
+        pathway=scenario["pathway"],
+        year=scenario["year"],
+        version=version,
+        system_model=system_model,
+        cache=scenario.get("cache"),
+        index=scenario.get("index"),
+    )
+
+    battery.adjust_battery_mass()
+
+    scenario["database"] = battery.database
+    scenario["index"] = battery.index
+    scenario["cache"] = battery.cache
+
+    return scenario
+
+
+class Battery(BaseTransformation):
+    """
+    Class that modifies the battery market to reflect progress
+    in terms of cell energy density.
+
+    """
+
+    def __init__(
+        self,
+        database: List[dict],
+        iam_data: IAMDataCollection,
+        model: str,
+        pathway: str,
+        year: int,
+        version: str,
+        system_model: str,
+        cache: dict = None,
+        index: dict = None,
+    ) -> None:
+        super().__init__(
+            database,
+            iam_data,
+            model,
+            pathway,
+            year,
+            version,
+            system_model,
+            cache,
+            index,
+        )
+        self.system_model = system_model
+
+    def adjust_battery_mass(self) -> None:
+        """
+        Adjust vehicle components (e.g., battery).
+        Adjust the battery mass to reflect progress in battery technology.
+        Specifically, we adjust the battery mass to reflect progress in
+        terms of cell energy density.
+        We leave the density unchanged after 2050.
+        """
+
+        energy_density = load_cell_energy_density()
+
+        filters = [ws.contains("name", x) for x in energy_density]
+
+        for ds in ws.get_many(
+            self.database,
+            ws.exclude(
+                ws.either(
+                    *[
+                        ws.contains("name", x)
+                        for x in [
+                            "market for battery",
+                            "battery production",
+                            "battery cell production",
+                            "cell module production",
+                        ]
+                    ]
+                )
+            ),
+        ):
+
+            for exc in ws.technosphere(ds, ws.either(*filters)):
+                name = [x for x in energy_density if x in exc["name"]][0]
+
+                scaling_factor = energy_density[name][2020] / np.clip(
+                    np.interp(
+                        self.year,
+                        list(energy_density[name].keys()),
+                        list(energy_density[name].values()),
+                    ),
+                    0.1,
+                    0.5,
+                )
+
+                if "log parameters" not in ds:
+                    ds["log parameters"] = {}
+
+                ds["log parameters"]["battery input"] = exc["name"]
+                ds["log parameters"]["old battery mass"] = exc["amount"]
+                exc["amount"] *= scaling_factor
+                ds["log parameters"]["new battery mass"] = exc["amount"]
+
+                self.write_log(ds, status="modified")
+
+    def write_log(self, dataset, status="created"):
+        """
+        Write log file.
+        """
+
+        logger.info(
+            f"{status}|{self.model}|{self.scenario}|{self.year}|"
+            f"{dataset['name']}|{dataset['location']}|"
+            f"{dataset.get('log parameters', {}).get('battery input', '')}|"
+            f"{dataset.get('log parameters', {}).get('old battery mass', '')}|"
+            f"{dataset.get('log parameters', {}).get('new battery mass', '')}"
+        )

premise/data/battery/energy_density.yaml

@@ -0,0 +1,78 @@
+# Battery cell energy densities, in kWh/kg cell
+---
+
+NMC111:
+  ecoinvent_aliases:
+    name:
+     - market for battery cell, Li-ion, NMC111
+     - market for battery, Li-ion, NMC111, rechargeable, prismatic
+  target:
+    2020: 0.150
+    2050: 0.200
+
+NMC622:
+  ecoinvent_aliases:
+    name:
+     - market for battery cell, Li-ion, NMC622
+     - market for battery, Li-ion, NMC622, rechargeable, prismatic
+  target:
+    2020: 0.200
+    2050: 0.350
+
+NMC811:
+  ecoinvent_aliases:
+    name:
+    - market for battery cell, Li-ion, NMC811
+    - market for battery, Li-ion, NMC811, rechargeable, prismatic
+  target:
+    2020: 0.220
+    2050: 0.500
+
+NCA:
+  ecoinvent_aliases:
+    name:
+     - market for battery cell, Li-ion, NCA
+     - market for battery, Li-ion, NCA, rechargeable, prismatic
+  target:
+      2020: 0.280
+      2050: 0.350
+
+LFP:
+  ecoinvent_aliases:
+    name:
+      - market for battery cell, Li-ion, LFP
+      - market for battery, Li-ion, LFP, rechargeable, prismatic
+  target:
+      2020: 0.140
+      2050: 0.250
+
+LTO:
+  ecoinvent_aliases:
+    name: market for battery cell, Li-ion, LTO
+  target:
+      2020: 0.080
+      2050: 0.150
+
+LMO:
+  ecoinvent_aliases:
+    name:
+      - market for battery cell, Li-ion, LiMn2O4
+      - market for battery, Li-ion, LiMn2O4, rechargeable, prismatic
+
+  target:
+      2020: 0.130
+      2050: 0.200
+
+Li-O2:
+  ecoinvent_aliases:
+    name: market for battery, Li-oxygen, Li-O2
+  target:
+      2020: 0.24
+      2050: 0.50
+
+BoP:
+  ecoinvent_aliases:
+    name: market for battery management system
+  target:
+      2020: 0.2
+      2050: 0.5

premise/data/utils/logging/logconfig.yaml

@@ -72,6 +72,14 @@ handlers:
     formatter: simple
     mode: a
 
+  file_battery:
+    class: logging.FileHandler
+    level: INFO
+    filename: "export/logs/premise_battery.log"
+    encoding: utf8
+    formatter: simple
+    mode: a
+
   file_emissions:
     class: logging.FileHandler
     level: INFO
@@ -132,6 +140,11 @@ loggers:
     handlers: [ file_fuel ]
     propagate: False
 
+  battery:
+    level: INFO
+    handlers: [ file_battery ]
+    propagate: False
+
   heat:
     level: INFO
     handlers: [ file_heat ]

premise/data/utils/logging/reporting.yaml

@@ -462,6 +462,49 @@ premise_heat:
         unit: kg CO2/reference flow
     tab: Heat
 
+premise_battery:
+    columns:
+      timestamp:
+        name: timestamp
+        description: Timestamp of the log entry
+      module:
+        name: module
+        description: Module name
+      level:
+        name: level
+        description: Log level
+      status:
+        name: status
+        description: Status of the dataset
+      model:
+        name: model
+        description: IAM model name
+      pathway:
+        name: pathway
+        description: Pathway name
+      year:
+        name: year
+        description: Year
+      dataset:
+        name: dataset
+        description: Dataset name
+      region:
+        name: region
+        description: Region name
+      battery input:
+        name: Battery provider
+        description: Name of the battery provider
+        unit: unitless
+      old battery mass:
+        name: Old battery mass
+        description: Mass of the battery before adjustment
+        unit: kg
+      new battery mass:
+        name: New battery mass
+        description: Mass of the battery after adjustment
+        unit: kg
+    tab: Battery
+
 premise_emissions:
     columns:
       timestamp: