Skip to main content

edges: Edge-based life cycle impact assessment

PyPI version

edges is a library allowing flexible Life Cycle Impact Assessment (LCIA) for the brightway2/brightway25 LCA framework.

Unlike traditional LCIA methods that apply characterization factors (CFs) solely to nodes (e.g., elementary flows), edges applies CFs directly on the edges — the exchanges between suppliers and consumers — allowing for more precise and context-sensitive impact characterization.

This approach enables LCIA factors to reflect the specific context of each exchange, including parameters such as:

  • Geographic region of production and consumption
  • Magnitude of flows
  • Scenario-based parameters (e.g., changing atmospheric conditions)

The edges Python library offers a novel approach to applying characterization factors (CFs) during the impact assessment phase of Life Cycle Assessment (LCA). Unlike conventional methods that uniformly assign CFs to nodes (e.g., processes like Water, from well in the brightway2 ecosystem), edges shifts the focus to the edges—the exchanges or relationships between nodes. This allows CFs to be conditioned based on the specific context of each exchange. Essentially, edges introduces unique values in the characterization matrix tailored to the characteristics of each edge.

By focusing on edges, the library incorporates contextual information such as the attributes of both the supplier and the consumer (e.g., geographic location, ISIC classification, amount exchanged, etc.). This enables a more detailed and flexible impact characterization, accommodating parameters like the location of the consumer and the magnitude of the exchange.

When necessary, custom CF definitions can also match on unit to distinguish flows that would otherwise share the same name, location, categories, or reference product.

Furthermore, edges supports the calculation of weighted CFs for both static regions (e.g., RER) and dynamic regions (e.g., RoW), enhancing its ability to model complex and region-specific scenarios.

Paired methods can set "domestic_pairs": "zero" to assign zero to domestic technosphere exchanges whose consumer is a country and whose supplier lies entirely within it. Explicit CF rows with location criteria on both sides take precedence; rows with an omitted or __ANY__ location on either side yield to domestic zeroing. Cross-border and region-to-region exchanges retain their usual matching behavior.

Key Features

  • Edge-based CFs: Assign CFs specifically to individual exchanges between processes.
  • Geographic resolution: Supports 346 national and sub-national regions.
  • Scenario-based flexibility: Incorporate parameters (e.g., CO₂ atmospheric concentration) directly in CF calculations, enabling dynamic scenario analysis.
  • Efficient workflow: Clearly separates expensive exchange-mapping tasks (performed once) from inexpensive scenario-based numeric CF evaluations.
  • Transparent reporting: Can expand weighted fallback consumer regions into country-specific rows in the detailed CF table for deterministic runs.
  • Mixed supplier matrices: Supports method files that combine biosphere-technosphere and technosphere-technosphere CF rows in one JSON file.

Currently, the library provides regionalized CFs for:

  • AWARE 2.0 (water scarcity impacts)
  • ImpactWorld+ 2.1
  • GeoPolRisk 1.0
  • GLAM 1.0 (32 curated practitioner methods from V1.0.2024.10)
  • GLAM3 Land use impacts on biodiversity
  • IBIF v2 biodiversity intactness (CO2, NH3, NOx, land occupation, roads, and all pressures)
  • Swiss Ecological Scarcity 2021 (UBP total and all 20 categories, including Noise)

For UBP comparisons across software, see the SimaPro comparison evidence and modelling differences. Agreement with another implementation is a diagnostic check, not proof of correctness.

The 32 curated GLAM practitioner methods are bundled in edges/data/ and listed by get_available_methods(). For example, select ("GLAM 1.0", "Terrestrial acidification", "damage") as the method in the LCIA workflow below. Indicators, scenarios and assessment levels are separate alternatives with their own output units; do not add their scores together. The existing GLAM3 biodiversity collection remains separately available.

The methods contain 222,676 rules with exact elementary-flow names, category paths and input units from the ecoinvent 3.10--3.12 reference catalogs. Unsupported identities, compartments and unit conversions are excluded. Each JSON retains a one-sentence indicator description, full author/year/DOI citations and two-space indentation. Exchanges contain only supplier, consumer and value; detailed provenance stays in external audit files.

All 288 practitioner validation cases passed across electricity, wheat and copper inventories in ecoinvent cutoff 3.10, 3.11 and 3.12. Independent checks verified direct CF values and exact final exchange sets after geographic fallback, with no missing, extra or duplicate mapped edges. These checks ran sequentially with one numerical thread and a 2 GiB memory guard; moving the unchanged JSON files into the package preserves that evidence.

The GLAM build and coverage audit documents source conversions, approved mapping assumptions and nine climate substances without published CFs, whose flows remain uncharacterized. The 195 optional native research methods remain under dev/GLAM/methods_native/, outside the installed package, and can be loaded by filepath. Their full runtime validation is separate from the practitioner release checks.

Installation

You can install the library using pip:

pip install edges

Documentation

Getting Started

Check out the examples' notebook.

Check available methods from edges

    
from edges import get_available_methods

# Get the available methods
methods = get_available_methods()
print(methods)

Perform edge-based LCIA with edges

import bw2data
from edges import EdgeLCIA

# Select an activity from the LCA database
act = bw2data.Database("ecoinvent-3.10-cutoff").random()

# Define a method
method = ('AWARE 2.0', 'Country', 'unspecified', 'yearly')
# Prospective variant: ('AWARE 2.0 prospective', 'Country', 'all', 'yearly')
# Swiss Ecological Scarcity total: ('Ecological Scarcity 2021', 'total', 'UBP')
# GLAM practitioner: ('GLAM 1.0', 'Terrestrial acidification', 'damage')

# Initialize the LCA object
LCA = EdgeLCIA({act: 1}, method)
LCA.lci()

# Map CFs to exchanges: apply suggested strategies
LCA.apply_strategies()

# or apply these strategies manually
#LCA.map_exchanges()

# If needed, extend the mapping to aggregated and `dynamic` regions (e.g., RoW)
#LCA.map_aggregate_locations()
#LCA.map_dynamic_locations()
#LCA.map_contained_locations()

# add global CFs to exchanges missing a CF
#LCA.map_remaining_locations_to_global()

# Evaluate CFs
LCA.evaluate_cfs()

# Perform the LCIA calculation
LCA.lcia()
print(LCA.score)

# Optional but recommended: print a dataframe with the characterization factors used
# this allows you to check whether exchanges have been given the correct CFs
# include_unmatched=True allows you to see which exchanges were not matched (and if some should have been)
# split_aggregate_consumers=True expands weighted consumer fallback rows
# (e.g. RER, GLO, RoW, RoE) into country rows in deterministic runs
LCA.generate_cf_table(split_aggregate_consumers=True)

For deterministic regionalized runs, generate_cf_table(split_aggregate_consumers=True) replaces weighted fallback rows for aggregate or dynamic consumer regions with country-specific rows whose amount and impact sum back to the original row. The raw split used for each exchange is also available after evaluate_cfs() via lca.scenario_cfs[*]["reporting_split"].

When a method mixes biosphere- and technosphere-supplier CFs, the exported table includes supplier matrix and direction columns so you can tell which contributions came from biosphere-technosphere versus technosphere-technosphere matches.

Perform parameter-based LCIA

Consider the following LCIA data file (saved under gwp_example.json)`:

{
  "name": "Example LCIA Method",
    "version": "1.0",
    "description": "Example LCIA method for greenhouse gas emissions",
    "unit": "kg CO2e",
    "exchanges": [
      {
        "supplier": {
          "name": "Carbon dioxide",
          "operator": "startswith",
          "matrix": "biosphere"
        },
        "consumer": {
          "matrix": "technosphere",
          "type": "process"
        },
        "value": "1.0"
      },
      {
        "supplier": {
          "name": "Methane, fossil",
          "operator": "contains",
          "matrix": "biosphere"
        },
        "consumer": {
          "matrix": "technosphere",
          "type": "process"
        },
        "value": "28 * (1 + 0.001 * (co2ppm - 410))"
      },
      {
        "supplier": {
          "name": "Dinitrogen monoxide",
          "operator": "equals",
          "matrix": "biosphere"
        },
        "consumer": {
          "matrix": "technosphere",
          "type": "process"
        },
        "value": "265 * (1 + 0.0005 * (co2ppm - 410))"
      }
  ]
}

Symbolic CF expressions are intentionally narrow: arithmetic, parameter names, literal values, and bare allowlisted function calls. Arbitrary Python syntax such as attribute access, subscripting, comprehensions, imports, or method calls is rejected. Functions passed through allowed_functions remain trusted Python code.

We can perform a parameter-based LCIA calculation as follows:

import bw2data
from edges import EdgeLCIA

# Select an activity from the LCA database
bw2data.projects.set_current("ecoinvent-3.10.1-cutoff")
act = bw2data.Database("ecoinvent-3.10.1-cutoff").random()
print(act)

# Define scenario parameters (e.g., atmospheric CO₂ concentration and time horizon)
params = {
    "some scenario": {
         "co2ppm": {"2020": 410, "2050": 450, "2100": 500}, "h": {"2020": 100, "2050": 100, "2100": 100}
    }
}

# Define an LCIA method (symbolic CF expressions stored in JSON)
method = ('GWP', 'scenario-dependent', '100 years')

# Initialize LCIA
lcia = EdgeLCIA(
   demand={act: 1},
   filepath="lcia_example_3.json",
   parameters=params
)

# Perform inventory calculations (once)
lcia.lci()

# Map exchanges to CF entries (once)
lcia.map_exchanges()

# Optionally, resolve geographic overlaps and disaggregations (once)
lcia.map_aggregate_locations()
lcia.map_dynamic_locations()
lcia.map_remaining_locations_to_global()

# Run scenarios efficiently
results = []
for idx in {"2020", "2050", "2100"}:
    lcia.evaluate_cfs(idx)
    lcia.lcia()
    df = lcia.generate_cf_table(split_aggregate_consumers=True)

    scenario_result = {
        "scenario": idx,
        "co2ppm": params["some scenario"]["co2ppm"][idx],
        "score": lcia.score,
        "CF_table": df
    }
    results.append(scenario_result)

    print(f"Scenario (CO₂ {params['some scenario']['co2ppm'][idx]} ppm): Impact = {lcia.score}")

Scenario-dependent methods can store expressions directly in value, as older method files do, or keep a numeric baseline value and use value_expression for the dynamic scenario/year value. Regionalized methods can similarly pair numeric weight with weight_expression; aggregate fallback shares are recomputed from evaluated dynamic weights during evaluate_cfs(...). If the method declares an interpolation policy with method: "linear" and extrapolation: "nearest", missing numeric years are linearly interpolated and out-of-range years use the closest available endpoint. Methods without this metadata keep the legacy exact-or-last parameter fallback.

Data Sources

See Methods from Documentation.

Methodology

See Theory from Documentation.

Contributing

Contributions are welcome! Please follow these steps to contribute:

  1. Fork the repository.
  2. Create a new branch for your feature or fix.
  3. Commit your changes.
  4. Submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE.md file for more information.

Contact

For any questions or inquiries, please contact the project maintainer at romain.sacchi@psi.ch.

For questions or issues around the use of edges, you can also join the discussion group at https://premise.groups.io/g/edgese.

Contributors

Acknowledgments

The development of this library was supported by the French agency for Energy ADEME, via the financing of the HySPI project. The HySPI project aims to provide a methodological framework to analyze and quantify, in a systemic and prospective manner, the environmental impacts of the decarbonization strategy of hydrogen production used by the industry in France. We also acknowledge financial support from the Europe Horizon project RAWCLIC as well as the Europe Horizon project PRISMA.

Metadata

Release files for edges 1.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edges 1.5.2
File Size Uploaded Provenance Actions
edges-1.5.2.tar.gz 39.9 MB Without provenance Details for edges-1.5.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edges 1.5.2
File Interpreter ABI Platform Actions
edges-1.5.2-py3-none-any.whl Python 3 none any Details for edges-1.5.2-py3-none-any.whl

Total release size: 81.2 MB

Release files / edges-1.5.2.tar.gz

Download URL edges-1.5.2.tar.gz
Size 39.9 MB
Tags Source
SHA-256 checksum
How to use checksums
b5164ddbc4b92c64c6661aa413440a7cef893f61ed5c1b7132b86134217a1cc9
BLAKE2b-256 checksum
How to use checksums
a5221073f286392c072f91b87b6114b07994b06ed0d3f2b617369e591f85c69e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / edges-1.5.2-py3-none-any.whl

Download URL edges-1.5.2-py3-none-any.whl
Size 41.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
1193abdab9839d2ed2dad56acc9ff590cd49b85df92fc09d68514351fa6ad18a
BLAKE2b-256 checksum
How to use checksums
63812a3f7c3b24dd2a9c2d7f8b20298c881e2abbe4df38e450b0fb52e4ffb598
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for edges 1.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page