shrecc 0.1.0.dev3__tar.gz → 0.1.2.dev1__tar.gz

{shrecc-0.1.0.dev3/shrecc.egg-info → shrecc-0.1.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shrecc
-Version: 0.1.0.dev3
+Version: 0.1.2.dev1
 Summary: SHRECC: Smooth Hourly Resolution Electricity Consumption Calculation
 Author-email: Sabina Bednářová <sabina.bednarova@list.lu>
 Maintainer-email: Sabina Bednářová <sabina.bednarova@list.lu>
@@ -55,13 +55,11 @@ Requires-Dist: jupyterlab; extra == "notebooks"
 Requires-Dist: jupyter-black>=0.4.0; extra == "notebooks"
 Requires-Dist: matplotlib>=3.10.9; extra == "notebooks"
 Provides-Extra: docs
-Requires-Dist: furo==2024.1.29; extra == "docs"
 Requires-Dist: myst_parser==2.0.0; extra == "docs"
 Requires-Dist: sphinx==7.2.6; extra == "docs"
 Requires-Dist: sphinx-autobuild>=2024.10.3; extra == "docs"
 Requires-Dist: ipython>=8.37.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == "docs"
-Requires-Dist: myst-parser>=2.0.0; extra == "docs"
 Requires-Dist: sphinx-design>=0.6.1; extra == "docs"
 Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
 Requires-Dist: sphinx-autoapi>=3.5.0; extra == "docs"
@@ -85,7 +83,8 @@ scenario data for prospective years, while exposing the same workflow for both.
 - Hourly production, trade, consumption-volume, and consumption-mix results.
 - One reduced country-network solver shared by Energy Charts and TYNDP data.
 - Historical ecoinvent allocation and prospective premise/IAM mapping.
-- Hourly, daily, weekly, monthly, and explicit timestamp selections.
+- Annual or monthly Brightway inventories from range-based or explicit
+  timestamp selections, plus hourly LCIA without hourly foreground activities.
 - Inspectable intermediate results before any Brightway database is changed.
 - Resumable source acquisition and compressed, time-chunked result caches.
 - Brightway 2 and 2.5 database writing through `NewDatabase`.
@@ -153,6 +152,7 @@ electricity = NewDatabase(
     hour_range=[10, 14],
     project_name="SHRECCei311",
     source="auto",
+    inventory_resolution="annual",
 )
 
 electricity.create()
@@ -162,10 +162,30 @@ electricity.write()
 For a multi-year run, the month/day/time selection is reused for each year and
 `write()` creates one foreground database per year. A year suffix is added to
 `my_db_name` automatically unless explicit year-specific names are supplied.
-Foreground activity names and metadata also record their model year.
+Foreground activity names and metadata also record their modeled period.
 
-Intermediate canonical results and mapped tables remain available on the class
-instance through `results(year)` and `table(year)`. Use
+`inventory_resolution` controls how many foreground activities are written:
+`"annual"` creates one activity per country and year, `"monthly"` creates one
+per country and selected calendar month. Both resolutions apply
+`consumption_profile` within each period. Hourly inventories are not written
+as Brightway activities.
+
+Hourly LCIA is calculated directly from the retained hourly mixes. By default,
+SHRECC selects every installed EF v3.1 impact category, scores each unique
+background input once, and combines those scores with the hourly coefficients:
+
+```python
+lcia_results = electricity.lcia()
+hourly_intensity = lcia_results.hourly(2040)["intensity"]
+annual_intensity = lcia_results.annual()
+```
+
+Use `electricity.lcia(methods=..., engine="multilca")` to validate the
+optimized calculation with composite Brightway MultiLCA functional units.
+Neither engine writes hourly foreground activities.
+
+Intermediate canonical results and annual/monthly mapped tables remain
+available on the class instance through `results(year)` and `table(year)`. Use
 `mapping_report(year)` to inspect any historical technologies assigned to a
 country-specific high-voltage fallback activity.
 
@@ -173,6 +193,7 @@ country-specific high-voltage fallback activity.
 ## Contributing
 
 Please take a look at the [DEVELOPPING.md](https://git.list.lu/shrecc_project/shrecc/-/blob/main/DEVELOPPING.md) file for details on how to contribute code to the repository.
+Notably for the versioning.
 
 ## License
 

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/README.md

@@ -13,7 +13,8 @@ scenario data for prospective years, while exposing the same workflow for both.
 - Hourly production, trade, consumption-volume, and consumption-mix results.
 - One reduced country-network solver shared by Energy Charts and TYNDP data.
 - Historical ecoinvent allocation and prospective premise/IAM mapping.
-- Hourly, daily, weekly, monthly, and explicit timestamp selections.
+- Annual or monthly Brightway inventories from range-based or explicit
+  timestamp selections, plus hourly LCIA without hourly foreground activities.
 - Inspectable intermediate results before any Brightway database is changed.
 - Resumable source acquisition and compressed, time-chunked result caches.
 - Brightway 2 and 2.5 database writing through `NewDatabase`.
@@ -81,6 +82,7 @@ electricity = NewDatabase(
     hour_range=[10, 14],
     project_name="SHRECCei311",
     source="auto",
+    inventory_resolution="annual",
 )
 
 electricity.create()
@@ -90,10 +92,30 @@ electricity.write()
 For a multi-year run, the month/day/time selection is reused for each year and
 `write()` creates one foreground database per year. A year suffix is added to
 `my_db_name` automatically unless explicit year-specific names are supplied.
-Foreground activity names and metadata also record their model year.
+Foreground activity names and metadata also record their modeled period.
 
-Intermediate canonical results and mapped tables remain available on the class
-instance through `results(year)` and `table(year)`. Use
+`inventory_resolution` controls how many foreground activities are written:
+`"annual"` creates one activity per country and year, `"monthly"` creates one
+per country and selected calendar month. Both resolutions apply
+`consumption_profile` within each period. Hourly inventories are not written
+as Brightway activities.
+
+Hourly LCIA is calculated directly from the retained hourly mixes. By default,
+SHRECC selects every installed EF v3.1 impact category, scores each unique
+background input once, and combines those scores with the hourly coefficients:
+
+```python
+lcia_results = electricity.lcia()
+hourly_intensity = lcia_results.hourly(2040)["intensity"]
+annual_intensity = lcia_results.annual()
+```
+
+Use `electricity.lcia(methods=..., engine="multilca")` to validate the
+optimized calculation with composite Brightway MultiLCA functional units.
+Neither engine writes hourly foreground activities.
+
+Intermediate canonical results and annual/monthly mapped tables remain
+available on the class instance through `results(year)` and `table(year)`. Use
 `mapping_report(year)` to inspect any historical technologies assigned to a
 country-specific high-voltage fallback activity.
 
@@ -101,6 +123,7 @@ country-specific high-voltage fallback activity.
 ## Contributing
 
 Please take a look at the [DEVELOPPING.md](https://git.list.lu/shrecc_project/shrecc/-/blob/main/DEVELOPPING.md) file for details on how to contribute code to the repository.
+Notably for the versioning.
 
 ## License
 

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/pyproject.toml

@@ -79,20 +79,18 @@ notebooks = [
     "matplotlib>=3.10.9",
 ]
 docs = [
-    "furo==2024.1.29",
     "myst_parser==2.0.0",
     "sphinx==7.2.6",
     "sphinx-autobuild>=2024.10.3",
     "ipython>=8.37.0",
     "sphinx-rtd-theme>=3.0.2",
-    "myst-parser>=2.0.0",
     "sphinx-design>=0.6.1",
     "sphinx-copybutton>=0.5.2",
     "sphinx-autoapi>=3.5.0",
     "astroid<4",
     "sphinx-notfound-page>=1.1.0",
     "myst-nb>=1.2.0",
- ]
+]
 
 [tool.setuptools]
 include-package-data = true

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/shrecc/__init__.py

@@ -8,6 +8,7 @@
 __all__ = (
     "__version__",
     "NewDatabase",
+    "LCIAResults",
     "create_database",
     "filt_cutoff",
     "get_data",
@@ -15,6 +16,7 @@ __all__ = (
 )
 from .database import create_database, filt_cutoff
 from .energy_charts import data_processing, get_data
+from .lcia import LCIAResults
 from .pipeline import NewDatabase
 
-__version__ = "0.1.0.dev3"
+__version__ = "0.1.2.dev1"

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/shrecc/activity_mapping.py

@@ -13,6 +13,7 @@ from shrecc.mapping import (
     map_consumption_mix_to_ecoinvent_activities,
     mapping_gap_to_report,
     validate_consumption_profile,
+    validate_inventory_resolution,
 )
 
 __all__ = (
@@ -25,4 +26,5 @@ __all__ = (
     "map_consumption_mix_to_ecoinvent_activities",
     "mapping_gap_to_report",
     "validate_consumption_profile",
+    "validate_inventory_resolution",
 )

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/shrecc/analysis.py

@@ -176,7 +176,8 @@ def compare_electricity_generation_mixes(
     Args:
         foreground_databases: Mapping from display label to ``{year:
             database_name}`` mappings. Foreground databases are expected to
-            contain activities named ``"Electricity mix in {country}, {year}"``.
+            contain activities named
+            ``"electricity, consumption mix, {year}"``.
         background_databases: Mapping from year to ecoinvent or premise
             background database name.
         countries: Consumer-country codes to compare.
@@ -396,7 +397,7 @@ def _comparison_roots(
     roots = {
         label: resolver.find_unique(
             databases[year],
-            f"Electricity mix in {country}, {year}",
+            f"electricity, consumption mix, {year}",
             country,
         )
         for label, databases in foreground_databases.items()

{shrecc-0.1.0.dev3 → shrecc-0.1.2.dev1}/shrecc/database.py

@@ -2,6 +2,8 @@
 # Licensed under the MIT License (see LICENSE file for details).
 # Authors: [Sabina Bednářová, Thomas Gibon]
 
+from collections import defaultdict
+from dataclasses import dataclass
 from datetime import datetime
 from importlib.resources import files
 from packaging.version import parse as vparse
@@ -10,7 +12,6 @@ import re
 
 import bw2data as bd
 import pandas as pd
-from bw2data.query import Filter, Query
 
 from shrecc._legacy_database import (
     apply_mapping,
@@ -25,6 +26,7 @@ from shrecc.mapping import (
     activity_mix_to_database_table,
     load_ecoinvent_mapping as load_mapping_data,
     map_consumption_mix_to_ecoinvent_activities,
+    validate_inventory_resolution,
 )
 from shrecc.result_store import (
     MANIFEST_FILENAME,
@@ -34,6 +36,65 @@ from shrecc.result_store import (
 
 UNUSED_SOURCE = "Import balance (physical)"
 DEFAULT_ACTIVITY_FALLBACK_LOCATIONS = ("RER", "RoW", "GLO")
+FOREGROUND_ACTIVITY_NAME = "electricity, consumption mix"
+FOREGROUND_REFERENCE_PRODUCT = "electricity"
+FOREGROUND_UNIT = "kilowatt hour"
+
+
+@dataclass(frozen=True)
+class BackgroundActivityIndex:
+    """Indexed Brightway activity keys for one background database."""
+
+    database_name: str
+    by_name_location_unit: dict
+    by_name_location: dict
+
+
+def build_background_activity_index(eidb_name):
+    """Load and index one Brightway background database for fast matching."""
+    database = bd.Database(eidb_name)
+    by_name_location_unit = defaultdict(list)
+    by_name_location = defaultdict(list)
+    if hasattr(database, "nodes_to_dataframe"):
+        nodes = database.nodes_to_dataframe(
+            columns=["database", "code", "name", "location", "unit"],
+            return_sorted=False,
+        )
+        records = (
+            (
+                (row.database, row.code),
+                row.name,
+                row.location,
+                row.unit,
+            )
+            for row in nodes.itertuples(index=False)
+        )
+    else:
+        records = (
+            (
+                key,
+                activity.get("name"),
+                activity.get("location"),
+                activity.get("unit"),
+            )
+            for key, activity in database.load().items()
+        )
+
+    for key, name, location, unit in records:
+        if name is None or location is None:
+            continue
+        by_name_location[(name, location)].append(key)
+        if unit is not None:
+            by_name_location_unit[(name, location, unit)].append(key)
+    return BackgroundActivityIndex(
+        database_name=eidb_name,
+        by_name_location_unit={
+            key: tuple(values) for key, values in by_name_location_unit.items()
+        },
+        by_name_location={
+            key: tuple(values) for key, values in by_name_location.items()
+        },
+    )
 
 
 def filt_cutoff(
@@ -199,6 +260,7 @@ def map_known_inputs(
     strict=False,
     include_network=True,
     fallback_locations=DEFAULT_ACTIVITY_FALLBACK_LOCATIONS,
+    background_index=None,
 ):
     """
     Maps known inputs from the ecoinvent database to the filtered dataframe.
@@ -210,12 +272,19 @@ def map_known_inputs(
         include_network (bool): Also resolve the fixed electricity-network inputs.
         fallback_locations: Ordered fallback geographies tried when the requested
             activity name and unit do not exist at the requested geography.
+        background_index: Optional prebuilt index for ``eidb_name``. Reuse this
+            when resolving several tables against the same background database.
 
     Returns:
         dict: A dictionary mapping known inputs to their corresponding entries in the ecoinvent database.
     """
-    ei_db = bd.Database(eidb_name)
-    ei_db_data = ei_db.load()
+    if background_index is None:
+        background_index = build_background_activity_index(eidb_name)
+    if background_index.database_name != eidb_name:
+        raise ValueError(
+            "Background activity index belongs to "
+            f"{background_index.database_name!r}, not {eidb_name!r}"
+        )
     known_inputs = {}
     missing_inputs = []
     country_to_code = {
@@ -247,20 +316,19 @@ def map_known_inputs(
             for fallback_loc in fallback_locations or ()
             if fallback_loc != loc
         )
-        results = []
+        results = ()
         resolved_loc = loc
         for candidate_loc in candidate_locations:
-            q = Query()
-            q.add(Filter("name", "is", name))
-            q.add(Filter("location", "is", candidate_loc))
-            q.add(Filter("unit", "is", "kilowatt hour"))
-            results = q(ei_db_data)
+            results = background_index.by_name_location_unit.get(
+                (name, candidate_loc, "kilowatt hour"),
+                (),
+            )
             resolved_loc = candidate_loc
             if results:
                 break
 
         if len(results) == 1:
-            exchange = list(results).pop()
+            exchange = results[0]
             known_inputs[(original_loc, original_name, unit)] = exchange
             known_inputs[(loc, name, unit)] = exchange
             known_inputs[(resolved_loc, name, unit)] = exchange
@@ -278,14 +346,9 @@ def map_known_inputs(
     for act in network:
         loc = act["loc"]
         name = act["name"]
-        q = Query()
-        filter_name = Filter("name", "is", name)
-        filter_loc = Filter("location", "is", loc)
-        q.add(filter_name)
-        q.add(filter_loc)
-        results = q(ei_db_data)
+        results = background_index.by_name_location.get((name, loc), ())
         if len(results) == 1:
-            known_inputs_network[(loc, name)] = list(results).pop()
+            known_inputs_network[(loc, name)] = results[0]
         else:
             print("Couldnt find activity:" + name)
             missing_inputs.append((loc, name, len(results)))
@@ -359,6 +422,71 @@ def get_network_activities(eidb_name):
     return network_act
 
 
+def get_country_network_activities(eidb_name, country):
+    """Return the fixed network exchanges included for one consumer country."""
+    specific_network = {
+        "land": (
+            "market for transmission network, electricity, high voltage "
+            "direct current land cable"
+        ),
+        "subsea": (
+            "market for transmission network, electricity, high voltage "
+            "direct current subsea cable"
+        ),
+        "construction": (
+            "transmission network construction, electricity, high voltage"
+        ),
+    }
+    land_cable_countries = {
+        "AT",
+        "BE",
+        "DK",
+        "EE",
+        "ES",
+        "FI",
+        "FR",
+        "GR",
+        "HR",
+        "IT",
+        "LT",
+        "LV",
+        "ME",
+        "MT",
+        "NO",
+        "SE",
+        "TR",
+        "UK",
+    }
+    subsea_cable_countries = {
+        "DK",
+        "EE",
+        "ES",
+        "FI",
+        "FR",
+        "GR",
+        "HR",
+        "IT",
+        "LT",
+        "ME",
+        "MT",
+        "NO",
+        "PL",
+        "UK",
+    }
+    selected = []
+    for exchange in get_network_activities(eidb_name):
+        name = exchange["name"]
+        if name not in specific_network.values():
+            selected.append(exchange)
+        elif name == specific_network["land"] and country in land_cable_countries:
+            selected.append(exchange)
+        elif name == specific_network["subsea"] and country in subsea_cable_countries:
+            selected.append(exchange)
+        elif name == specific_network["construction"] and country == "CH":
+            selected.append(exchange)
+    return selected
+
+
 def create_activity_dict(
     dataframe_filt,
     known_inputs,
@@ -367,6 +495,7 @@ def create_activity_dict(
     eidb_name=None,
     year=None,
     consumption_profile=None,
+    inventory_resolution=None,
 ):
     """
     Creates a dictionary of activities for the BW database based on the filtered dataframe and known inputs.
@@ -383,24 +512,30 @@ def create_activity_dict(
             name is left unchanged to avoid repeating it.
         consumption_profile (str, optional): Temporal weighting represented by
             the foreground inventory, stored as activity metadata.
+        inventory_resolution (str, optional): ``"annual"`` or ``"monthly"``.
+            When omitted, time-indexed columns are treated as monthly and
+            country-only columns as annual for compatibility.
 
     Returns:
         dict: A dictionary containing activities to be written to the BW2 database.
     """
     activities = {}
     activity_year = int(year) if year is not None else None
+    resolution = (
+        validate_inventory_resolution(inventory_resolution)
+        if inventory_resolution is not None
+        else ("monthly" if dataframe_filt.columns.nlevels > 1 else "annual")
+    )
     for i, col in enumerate(dataframe_filt.columns):
         if dataframe_filt.columns.nlevels > 1:
             time, country = col
-            activity = f"{time} Electricity mix"
-            name = f"{activity} in {country}"
-            name_contains_year = str(activity_year) in str(time)
+            period = _format_inventory_period(time, resolution)
         else:
             country = col
-            name = f"Electricity mix in {country}"
-            name_contains_year = False
-        if activity_year is not None and not name_contains_year:
-            name = f"{name}, {activity_year}"
+            period = str(activity_year) if activity_year is not None else None
+        name = FOREGROUND_ACTIVITY_NAME
+        if period is not None:
+            name = f"{name}, {period}"
         code = f"electricity {i}"
         bd_version = bd.__version__
         if not isinstance(bd_version, str):
@@ -414,11 +549,17 @@ def create_activity_dict(
             prod_exchange_type = bd.labels.production_edge_default
         act = {
             "name": name,
-            "unit": "kWh",
+            "unit": FOREGROUND_UNIT,
             "code": code,
             "location": str(country),
-            "reference product": "Electricity mix",
+            "reference product": FOREGROUND_REFERENCE_PRODUCT,
             "type": act_type,
+            "inventory_resolution": resolution,
+            "comment": _inventory_comment(
+                resolution,
+                period,
+                consumption_profile,
+            ),
             "exchanges": [],
         }
         if activity_year is not None:
@@ -431,7 +572,7 @@ def create_activity_dict(
                 "input": (db_name, code),
                 "name": name,
                 "location": str(country),
-                "unit": "kWh",
+                "unit": FOREGROUND_UNIT,
                 "amount": 1,
                 "type": prod_exchange_type,
             }
@@ -447,91 +588,16 @@ def create_activity_dict(
                         "type": "technosphere",
                     }
                     act["exchanges"].append(new_exchange)
-        network = get_network_activities(eidb_name or db_name)
-        specific_network = [
-            "market for transmission network, electricity, high voltage direct current land cable",
-            "market for transmission network, electricity, high voltage direct current subsea cable",
-            "transmission network construction, electricity, high voltage",
-        ]
-        land_cable = [
-            "FR",
-            "IT",
-            "GR",
-            "DK",
-            "AT",
-            "BE",
-            "EE",
-            "ES",
-            "FI",
-            "HR",
-            "IT",
-            "LT",
-            "LV",
-            "ME",
-            "MT",
-            "NO",
-            "SE",
-            "TR",
-            "UK",
-        ]
-        subsea_cable = [
-            "FR",
-            "IT",
-            "GR",
-            "DK",
-            "EE",
-            "ES",
-            "FI",
-            "HR",
-            "IT",
-            "LT",
-            "ME",
-            "MT",
-            "NO",
-            "PL",
-            "UK",
-        ]
-        for exch_net in network:
-            if exch_net["name"] not in specific_network:
-                exchange = known_inputs_network.get((exch_net["loc"], exch_net["name"]))
-                if exchange:
-                    new_exchange = {
+        for exch_net in get_country_network_activities(eidb_name or db_name, country):
+            exchange = known_inputs_network.get((exch_net["loc"], exch_net["name"]))
+            if exchange:
+                act["exchanges"].append(
+                    {
                         "input": exchange,
                         "amount": float(exch_net["val"]),
                         "type": "technosphere",
                     }
-                    act["exchanges"].append(new_exchange)
-            if (
-                country in land_cable and exch_net["name"] == specific_network[0]
-            ):  # writing the land cable
-                exchange = known_inputs_network.get((exch_net["loc"], exch_net["name"]))
-                if exchange:
-                    new_exchange = {
-                        "input": exchange,
-                        "amount": float(exch_net["val"]),
-                        "type": "technosphere",
-                    }
-                    act["exchanges"].append(new_exchange)
-            if (
-                country in subsea_cable and exch_net["name"] == specific_network[1]
-            ):  # writing the subsea cable
-                exchange = known_inputs_network.get((exch_net["loc"], exch_net["name"]))
-                if exchange:
-                    new_exchange = {
-                        "input": exchange,
-                        "amount": float(exch_net["val"]),
-                        "type": "technosphere",
-                    }
-                    act["exchanges"].append(new_exchange)
-            if country == "CH" and exch_net["name"] == specific_network[2]:
-                exchange = known_inputs_network.get((exch_net["loc"], exch_net["name"]))
-                if exchange:
-                    new_exchange = {
-                        "input": exchange,
-                        "amount": float(exch_net["val"]),
-                        "type": "technosphere",
-                    }
-                    act["exchanges"].append(new_exchange)
+                )
         activities[(db_name, code)] = act
     return activities
 
@@ -545,6 +611,7 @@ def create_database(
     strict=False,
     year=None,
     consumption_profile=None,
+    inventory_resolution=None,
 ):
     """
     Creates an "ecoinvent-like" BW database based on a previously filtered dataframe.
@@ -563,6 +630,8 @@ def create_database(
             and stored as activity metadata.
         consumption_profile (str, optional): Temporal weighting stored as
             foreground activity metadata.
+        inventory_resolution (str, optional): Temporal resolution stored in
+            activity names, metadata, and comments.
 
     Returns:
         None
@@ -585,6 +654,32 @@ def create_database(
         eidb_name=eidb_name,
         year=year,
         consumption_profile=consumption_profile,
+        inventory_resolution=inventory_resolution,
     )
     elec_db = setup_database(project_name, db_name)
     elec_db.write(activities)
+
+
+def _format_inventory_period(time, inventory_resolution):
+    """Format a table-column timestamp for an activity name."""
+    timestamp = pd.Timestamp(time)
+    if inventory_resolution == "monthly":
+        return timestamp.strftime("%Y-%m")
+    return str(timestamp.year)
+
+
+def _inventory_comment(
+    inventory_resolution,
+    period,
+    consumption_profile,
+):
+    """Build ActivityBrowser documentation for a foreground inventory."""
+    parts = [
+        "SHRECC electricity consumption mix.",
+        f"Inventory resolution: {inventory_resolution}.",
+    ]
+    if period is not None:
+        parts.append(f"Inventory period: {period}.")
+    if consumption_profile is not None:
+        parts.append(f"Consumption profile: {consumption_profile}.")
+    return " ".join(parts)