pathways is a Python package that characterizes the environmental impacts of products, sectors or transition scenarios over time using Life Cycle Assessment (LCA). Compared to traditional scenario results from energy models, pathways provides a more detailed and transparent view of the environmental impacts of a scenario by resolving supply chains between producers and consumers (as an LCA does). Hence, direct and indirect emissions are accounted for, and double-counting issues are partially resolved.

pathways is initially designed to work with data packages produced by premise, but can be used with any IAM scenarios and LCA databases.

pathways reads a scenario and a corresponding set of scenario-based LCA matrices and calculates the environmental impacts of the scenario (or a subset of it) over time.

If you use pathways in a scientific publication, we would appreciate citations to the following paper:

Sacchi et al., (2024). pathways: life cycle assessment of energy transition scenarios. Journal of Open Source Software, 9(103), 7309, https://doi.org/10.21105/joss.07309

pathways requires Python 3.10, 3.11, or 3.12 (>=3.10, <3.13). Dependencies are defined in pyproject.toml.

pathways is in an early development stage, and can be installed from the Github repo with pip:

  pip install git+https://github.com/polca/pathways.git

or alternatively, you can clone the repository and install it from the source:

    git clone https://github.com/polca/pathways.git
    cd pathways
    pip install .
    

pathways is also available via anaconda:

    conda install -c conda-forge -c romainsacchi pathways

.. note:: If you use an ARM architecture, you may want to also install the scikit-umfpack package from the conda-forge channel for faster calculation. However, you need to make sure that numpy<=1.24.4 is installed, as bw2io is not compatible with the latest version of numpy:

    conda install -c conda-forge scikit-umfpack

The documentation for pathways can be found at https://pathways.readthedocs.io/en/latest.

pathways is a Python package, and can be used in Python scripts or in a Python interpreter. See the example notebook.

To use the Pathways class, you need to provide it with a datapackage that contains your scenario data, mapping information, and LCA matrices. The datapackage should be a zip file that contains the following files:

• datapackage.json: a JSON file that describes the contents of the datapackage
• a mapping folder containing a mapping.yaml file that describes the mapping between the IAM scenario and the LCA databases
• a inventories folder containing the LCA matrices as CSV files
• a scenario_data folder containing the IAM scenario data as CSV file

from pathways import Pathways
datapackage_path = "path/to/your/datapackage.zip"
p = Pathways(
    datapackage=datapackage_path,
    ecoinvent_version="3.12",  # optional, supported: "3.10", "3.11", "3.12"
    debug=True # optional, if you want to see the logs
)

# Define your parameters (leave any as None to use all available values)
methods = ["IPCC 2021", "ReCiPe 2016"]
models = ["ModelA", "ModelB"]
scenarios = ["Baseline", "Intervention"]
regions = ["Region1", "Region2"]
years = [2020, 2025]
variables = ["Electricity", "Transport"]

# Run the calculation
p.calculate(
    methods=methods,
    models=models,
    scenarios=scenarios,
    regions=regions,
    years=years,
    variables=variables,
    use_distributions=0 # optional, if > 0: number of iterations for Monte Carlo analysis
)

The list of available LCIA methods can be obtained like so:

    print(p.lcia_methods)

The argument datapackage is the path to the datapackage.zip file that describes the scenario and the LCA databases -- see dev/sample. The argument methods is a list of methods to be used for the LCA calculations. The argument years is a list of years for which the LCA calculations are performed. The argument regions is a list of regions for which the LCA calculations are performed. The argument scenarios is a list of scenarios for which the LCA calculations are performed.

If not specified, all the methods, years, regions and scenarios defined in the datapackage.json file are used, which can be very time-consuming.

For larger Monte Carlo studies, Pathways.calculate(...) also supports an experimental iterative solver and cache-shaping options:

p.calculate(
    methods=methods,
    models=models,
    scenarios=scenarios,
    regions=regions,
    years=years,
    variables=variables,
    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 MultiLCA backend. It can reuse previous supply arrays as warm starts and falls back to the direct solve if GMRES does not converge.
• aggregate_by currently supports act_category and location. These dimensions are collapsed to a single "aggregated" label before Monte Carlo iteration arrays are cached, which reduces cache size and shortens post-processing.
• postprocess_multiprocessing=True parallelizes final cached-result assembly. During this phase, Pathways logs per-year assembly progress so long runs do not appear stalled.

Use aggregate_by only when you do not need detailed attribution along those dimensions in the final results. If you relax iterative_rtol for speed, check the result against a direct-solver reference first.

Once calculated, the results of the LCA calculations are stored in the .lcia_results attribute of the Pathways object as an xarray.DataArray.

You can display the LCA results with an optional cutoff parameter to filter insignificant data:

results = p.aggregate_results(cutoff=0.001)
print(results)

It can be further formatted to a pandas' DataFrame or exported to a CSV/Excel file using the built-in methods of xarray.

    df = results.to_dataframe()
    df.to_csv("results.csv")

Or the result can be exported as a gzip-compressed Parquet file for further use in pandas or dask:

    p.export_results(filename="results")

Results can be visualized using your favorite plotting library.

Finally, when running a Monte Carlo analysis (i.e., when use_distributions is greater than 0), parameters of the Monte Carlo analysis (coordinates of uncertain exchanges, values for each iteration, etc.) are stored in Excel files. It is possible to run Global Sensitivity Analysis (GSA) on the results of the Monte Carlo analysis, like so:

    from pathways import run_gsa
    run_gsa(method="delta")

The method argument can only be "delta" for now. It will run a Delta Moment-Independent Measure (DMIM) sensitivity analysis on the results of the Monte Carlo analysis, to rank the influence of each uncertain exchange on the results' distribution.

• Matrix files A_matrix.csv and B_matrix.csv are expected to be semicolon-delimited and can include a header row.
• Index files (A_matrix_index.csv, B_matrix_index.csv) can include a header row as well.
• By default, cache cleanup is restricted to the default Pathways cache directory (<user_data_dir>/cache).
  • To override this behavior intentionally, set PATHWAYS_ALLOW_UNSAFE_CACHE_DELETE=1.
• Legacy pickle cache files are blocked by default for safety.
  • To temporarily allow loading old pickle cache artifacts, set PATHWAYS_ALLOW_UNSAFE_PICKLE=1.
  • Regenerating cache files is recommended.

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Report bugs by filing issues on GitHub.

If you are reporting a bug, please include:

• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.
• For visual bugs, a screenshot or animated GIF of the bug in action.

Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.

Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.

pathways could always use more documentation, whether as part of the official pathways docs, in docstrings, or even on the web in blog posts, articles, and such.

The best way to send feedback is to file an issue on the GitHub repository.

• Romain Sacchi
• Alvaro Hahn Menacho

• PRISMA project

pathways is licensed under the terms of the BSD 3-Clause License.