Update docs on batteries.

conda/meta.yaml

@@ -24,7 +24,7 @@ requirements:
     - constructive_geometries>=0.9.5
     - cryptography
     - datapackage
-    - numpy
+    - numpy <2.0.0
     - pandas
     - platformdirs
     - prettytable

docs/extract.rst

@@ -893,29 +893,31 @@ Li-ion batteries
 ----------------
 
 When using ecoinvent 3.8 as a database, *premise* imports new inventories for lithium-ion batteries.
-NMC-111, NMC-6222 NMC-811 and NCA Lithium-ion battery inventories are originally
+NMC-111, NMC-622 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:
 
- ========================================================== =========== ======================================
-  Battery components                                         location    source
- ========================================================== =========== ======================================
-  battery management system production, for Li-ion battery     GLO         Schmidt et al. 2019
-  battery cell production, Li-ion, NMC111                      GLO         Dai et al. 2019, Crenna et al. 2021
-  battery cell production, Li-ion, NMC622                      GLO         Dai et al. 2019, Crenna et al. 2021
-  battery cell production, Li-ion, NMC811                      GLO         Dai et al. 2019, Crenna et al. 2021
-  battery cell production, Li-ion, NCA                         GLO         Dai et al. 2019, Crenna et al. 2021
-  battery cell production, Li-ion, LFP                         GLO         Schmidt et al. 2019
-  battery cell production, Li-ion, LTO                         GLO         Schmidt et al. 2019
-  battery cell production, Li-S                                GLO         Wickerts et al. (2023)
-  battery cell production, Li-O2                               GLO         Wang et al. (2020)
-  battery cell production, SIB                                 GLO         Zhang et al. (2024)
- ========================================================== =========== ======================================
+ ============================================================= =========== ======================================
+  Battery components                                            location    source
+ ============================================================= =========== ======================================
+  battery management system production, for Li-ion battery        GLO         Schmidt et al. 2019
+  bmarket for battery, Li-ion, NMC111, rechargeable, prismatic    GLO         Dai et al. 2019, Crenna et al. 2021
+  market for battery, Li-ion, NMC622, rechargeable, prismatic     GLO         Dai et al. 2019, Crenna et al. 2021
+  market for battery, Li-ion, NMC811, rechargeable, prismatic     GLO         Dai et al. 2019, Crenna et al. 2021
+  market for battery, Li-ion, NCA, rechargeable, prismatic        GLO         Dai et al. 2019, Crenna et al. 2021
+  market for battery, Li-ion, LFP, rechargeable, prismatic        GLO         Schmidt et al. 2019
+  market for battery cell, Li-ion, LTO                            GLO         Schmidt et al. 2019
+  market for battery, Li-sulfur, Li-S                             GLO         Wickerts et al. (2023)
+  market for battery, Li-oxygen, Li-O2                            GLO         Wang et al. (2020)
+  market for battery, Sodium-ion, SiB                             GLO         Zhang et al. (2024)
+  market for battery, NaCl, rechargeable, prismatic               GLO         Galloway & Dustmann (2003)
+ ============================================================= =========== ======================================
 
 These battery inventories are mostly used by battery electric vehicles,
 stationary energy storage systems, etc. (also imported by *premise*).
@@ -926,8 +928,8 @@ Li-S inventories can be found here: LCI_batteries3_.
 Li-O2 inventories can be found here: LCI_batteries4_.
 And SIB inventories can be found here: LCI_batteries5_.
 
-When using ecoinvent 3.9 and above, the NMC-111, NMC-811, LFP and NCA battery inventories are not imported
-(as are already present the ecoinvent database).
+When using ecoinvent 3.9 and above, the NMC-111, NMC-811, LFP and NCA battery inventories
+are not imported (as are already present the ecoinvent database).
 
 Graphite
 --------

docs/transform.rst

@@ -4,6 +4,83 @@ 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*.
+See EXTRACT/Import of additional inventories/Li-ion batteries for additional information.
+
+*premise* adjusts the mass of battery packs throughout the database
+to reflect progress in specific energy density (kWh/kg cell).
+
+
+Run
+
+.. code-block:: python
+
+    from premise import *
+    import brightway2 as bw
+
+    bw.projects.set_current("my_project)
+
+    ndb = NewDatabase(
+        scenarios=[
+                {"model":"remind", "pathway":"SSP2-Base", "year":2028}
+            ],
+        source_db="ecoinvent 3.7 cutoff",
+        source_version="3.7.1",
+        key='xxxxxxxxxxxxxxxxxxxxxxxxx'
+    )
+    ndb.update("battery")
+
+
+The table below shows the **current** specific energy density of
+different battery technologies.
+
+====================== ==================================== ==================== ================== ================= ===================
+Type                   Specific energy density (current)    BoP mass share [%]   Battery energy     kg battery/kWh      kg CO2-eq./kWh
+                       [kWh/kg cell]                                             density [kWh/kg
+                                                                                 battery]
+====================== ==================================== ==================== ================== ================= ===================
+Li-ion, NMC111         0.15                                 73%                  0.11               7.0               177
+Li-ion, NMC622         0.20                                 73%                  0.15               6.9               108
+Li-ion, NMC811         0.22                                 71%                  0.16               6.7               108
+Li-ion, NCA            0.23                                 71%                  0.16               6.3               100
+Li-ion, LFP            0.14                                 73%                  0.10               9.8               118
+Li-ion, LiMn2O4        0.13                                 80%                  0.10               9.6               92
+Li-ion, LTO            0.09                                 64%                  0.05               18.4              450
+Li-sulfur, Li-S        0.15                                 75%                  0.11               8.9               352
+Li-oxygen, Li-O2       0.36                                 55%                  0.20               5.1               125
+Sodium-ion, SiB        0.16                                 75%                  0.12               8.5               72
+====================== ==================================== ==================== ================== ================= ===================
+
+And the table below shows the **projected** (2050) specific energy density
+of different battery technologies.
+
+====================== ==================================== ==================== ================== ================
+Type                   Specific energy density (2050)       BoP mass share [%]   Battery energy     kg battery/kWh
+                       [kWh/kg cell]                                             density [kWh/kg
+                                                                                 battery]
+====================== ==================================== ==================== ================== ================
+Li-ion, NMC111         0.2                                  73%                  0.15               6.9
+Li-ion, NMC811         0.5                                  71%                  0.36               2.8
+Li-ion, NCA            0.35                                 71%                  0.25               4.0
+Li-ion, LFP            0.25                                 73%                  0.18               5.5
+Li-ion, LiMn2O4        0.2                                  80%                  0.16               6.3
+Li-ion, LTO            0.15                                 75%                  0.11               8.9
+Li-sulfur, Li-S        0.5                                  75%                  0.38               2.7
+Li-oxygen, Li-O2       0.50                                 64%                  0.20               5.1
+Sodium-ion, SiB        0.22                                 75%                  0.17               6.1
+====================== ==================================== ==================== ================== ================
+
+
+For example, in 2050, the mass of NMC811 batteries (cells and Balance of Plant) is expected to
+be 0.5/0.22 = 2.3 times lower for a same energy capacity. The report of changes
+shows the new mass of battery packs for each activity using them.
+
+The target values used for scaling can be modified by the user.
+The YAML file is located under premise/data/battery/energy_density.yaml.
+
 Biomass
 """""""
 

premise/__init__.py

@@ -5,7 +5,7 @@
     "clear_inventory_cache",
     "get_regions_definition",
 )
-__version__ = (2, 1, 1, "dev2")
+__version__ = (2, 1, 1, "dev4")
 
 
 from premise.new_database import NewDatabase

premise/battery.py

@@ -0,0 +1,181 @@
+"""
+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")
+
+        for ds in ws.get_many(
+            self.database,
+            ws.contains("name", "market for battery capacity"),
+        ):
+
+            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', '')}"
+        )