User Guide

Overview

Pathways consumes a datapackage with:

• Scenario data: model, scenario, year, region, variables, values

• Mappings: links from scenario variables → LCA activities (and optional subshares)

• Matrices: prebuilt technosphere/biosphere/characterization elements

The main workflow is driven by pathways.Pathways.

Pathways workflow

1. Initialize

   from pathways import Pathways
   pw = Pathways("remind-SSP2-NPi.zip", ecoinvent_version="3.12")
   

   The initializer parses the datapackage, builds internal indices, loads classification info and LCIA method names, and prepares the scenario catalog:

   • pw.scenarios: available models, scenarios, regions, years

   • pw.lcia_methods: available impact categories (method names)

   • pw.units: unit conversion helpers

   Example

   print("LCIA methods:", pw.lcia_methods)
   # e.g. ["AWARE", "IPCC 2021 climate change GWP 100a", ...]
   

2. Calculate

   pw.calculate(
       methods=["AWARE"], models=["REMIND"], scenarios=["SSP2-NPi"],
       regions=["World"], years=[2020, 2050],
       demand_cutoff=1e-3, use_distributions=0
   )
   

   methods must be chosen from the list returned by pw.lcia_methods.

   Output shape

   pw.lca_results is an xarray DataArray with dimensions:

   (act_category, variable, year, region, location, model, scenario, impact_category)

   When aggregate_by is used during Monte Carlo runs, the dimensions stay in the output, but the collapsed coordinates become "aggregated".

   Advanced Monte Carlo options

   pw.calculate(
       methods=["AWARE"],
       models=["REMIND"],
       scenarios=["SSP2-NPi"],
       regions=["World"],
       years=[2050],
       variables=["Electricity|Generation"],
       use_distributions=300,
       solver="jacobi-gmres",
       iterative_rtol=1e-8,
       aggregate_by=["act_category", "location"],
       multiprocessing=True,
       postprocess_multiprocessing=True,
   )
   

   • solver="direct" is the default and uses bw2calc.MultiLCA.

   • solver="jacobi-gmres" uses an experimental iterative backend. It reuses prior supply arrays as warm starts when possible and falls back to the direct solve if GMRES does not converge.

   • The iterative backend exposes iterative_rtol, iterative_atol, iterative_restart, iterative_maxiter, and iterative_use_guess on pathways.Pathways.calculate().

   • aggregate_by currently supports "act_category" and "location". It collapses those dimensions before Monte Carlo iteration arrays are cached, which reduces cache size and shortens post-processing.

   • postprocess_multiprocessing=True parallelizes final cached-result assembly after the solver stage. Pathways also logs yearly assembly progress during this step.

3. Aggregate for display

   pw.aggregate_results(cutoff=0.01, interpolate=False)
   

   Aggregates contributions below the cutoff into an "other" category.

4. Export to Parquet

   path = pw.export_results("my_results")  # → my_results.gzip
   

Notes

• Supported ecoinvent_version values are "3.10", "3.11", and "3.12".

• Matrix files A_matrix.csv and B_matrix.csv are semicolon-delimited and may include a header row.

• Index files A_matrix_index.csv and B_matrix_index.csv may include a header row.

• If you loosen iterative_rtol for speed, compare the result against a direct-solver run before using it for production Monte Carlo analysis.