Documentation: pyaesa.readthedocs.io reproduces the documentation of this GitHub repository.

Issues and feedback: Please report bugs, unexpected behavior, documentation gaps, and installation or workflow issues on the GitHub Issues page.

pyaesa is a Python package for absolute environmental sustainability assessment (AESA) workflows. It supports data download, data processing, deterministic calculations, figure rendering, Monte Carlo uncertainty and Sobol variance.

The package follows the three AESA phases described in the JRC guidance. The calculation chain is:

1. Phase A builds life cycle assessment (LCA) results.
2. Phase B builds allocated carrying capacity (aCC) results: aCC = aSoCC * CC.
3. Phase C builds absolute sustainability ratio (ASR) results: ASR = LCA / aCC.

aSoCC means allocated share of carrying capacity. CC means carrying capacity. CC can be static, for example with LCIA methods PB-LCIA or EF3.1, or dynamic through AR6 climate change pathways.

License

pyaesa source code is distributed under the GPL 3.0 license. Downloaded datasets remain governed by their original providers' terms and conditions documented in the Data Source Licenses And Terms section.

Community

Contributing to pyaesa

pyaesa uses the GitHub Discussions Ideas category to collect feature ideas and development priorities from users.

Use Ideas to propose new features, request additional allocation methods, upvote existing proposals, and comment with your use case, data source, expected workflow, or implementation constraints.

To propose direct code modifications, for example implementing new allocation methods or other features, see CONTRIBUTING.md.

Sharing Reproducible Case Studies

Users are encouraged to share AESA case studies developed with pyaesa in the AESA_case_studies repository. This supports the AESA community by making case studies easier to understand, inspect, reproduce, compare, and extend.

Installation

Install the package from PyPI:

python -m pip install pyaesa

For local development from a repository clone, install in editable mode:

python -m pip install -e .

pyaesa requires at least 4 GB of available RAM to run.

High-level overview of the package

The figure below provides a high-level overview of the package, including main data sources, high-level public functions and study objectives supported by the package. More details are provided in the next sections.

Example Output Figures

pyaesa produces result tables and figures. The example below illustrates some of the 83 figure families available with pyaesa. For steady-state carrying capacities, it shows allocated carrying capacity (aCC) trajectories and a single-year ASR polar figure. For dynamic climate change carrying capacities based on AR6 pathways, it shows global carrying capacity (CC) and allocated carrying capacity (aCC) trajectories and cumulative budgets.

Data Sources By AESA Phase

EXIOBASE is supported for ixi and pxp source variants. The examples use EXIOBASE 3.10.2 but EXIOBASE 3.9.6 is also supported.

Current EXIOBASE LCIA coverage is gwp100_lcia and pb_lcia. Therefore in pyaesa EF3.1 is available for non-LCIA based allocation routes, but it is not currently available for pyaesa owned IO-LCA or LCIA based allocation methods. tutorials/core_prerequisites/2_process_data.ipynb explains the detailed process for adding LCIA methods with EXIOBASE characterization matrices and matching carrying capacity thresholds, either for private project use or for public package submission.

Data Source Licenses And Terms

The GPL 3.0 license applies to pyaesa source code only. Downloaded datasets remain governed by their original providers' terms and conditions. For all data sources, cite the original provider following the recommended citation guide.

Public Workflow Function Map

Core Prerequisites To Run Once

Run set_workspace(...) once at the beginning of each Python session.

Run the download and processing functions needed before the selected study endpoint: MRIO processing for aSoCC and pyaesa owned IO-LCA, and population/GDP processing for allocation methods that use those inputs (once run they are kept on disk and can be reused across studies). For dynamic AR6 CC and downstream routes that use it, download AR6 raw inputs; the matching processed AR6 scope can be created by the downstream dynamic route when it is missing so it does not need to be run separately.

MRIO Storage And Runtime

MRIO raw download storage and runtime by source:

MRIO processed output storage and runtime by source:

The measurements were taken on Windows 11 with Python 3.14, an 11th Gen Intel Core i7 1165G7 CPU, 32 GB RAM.

AESA Functions

Support Functions

Study objectives and recommended routes

1. Run set_workspace(...) once for the workspace.

2. Download the raw data families needed by the study endpoint.

3. Run process_mrio(...) and process_pop_gdp(...) when the endpoint needs processed MRIO or population/GDP assets. Direct process_ar6(...) runs are optional for dynamic AR6 CC, aCC, and ASR endpoints because those routes can provision the matching processed AR6 scope when it is missing.

4. Choose a study objective that fit your application. Study objectives are study endpoints from the user perspective. A study objective corresponds to an expected output for the user. In pyaesa, five study objectives are currently available:

5. Once your have chosen the study objective (i.e., the endpoint), call the corresponding deterministic or uncertainty function directly. It is very important for the user to understand that to reach a desired study objective, pyaesa automatically runs upstream computations needed to produce the desired endpoint, i.e., to ensure that all previous outputs are available before running the downstream function providing the endpoint. This is illustrated via the green arrows (automatic nesting) in the figure above. Consequently, the user must focus solely on the desired study objective, and run the single relevant function.

Check out tutorials/study_objectives/0_study_objectives.md to understand how to select and reach study objectives in pyaesa.

Set of tutorials

The README is the tutorial navigator. The tutorial notebooks are split into reusable prerequisite data preparation notebooks, study endpoint notebooks, and optional workflow notebooks.

Core prerequisites tutorials:

Study objectives tutorials:

Optional tutorials:

Methodological notes:

The UNCASExt article provides the methodological basis for pyaesa. Two methodological appendices supporting the package implementation are distributed with pyaesa:

set_workspace(...) copies the appendix PDF files and LaTeX source archives into the active workspace under data_raw/methodological_notes/.

Use the API reference in docs/api.rst for exact signatures and parameter contracts. Use docs/tutorial.rst for the notebook index.

Citation

Please cite these references when using pyaesa, as they constitute the methodological basis for pyaesa, including the allocation methods included in the package.

de Bantel, E. I., Pirson, T., Puig-Samper, G., Hartmann, J. M., Bol, D., Bouillass, G., Yannou, B., Jankovic, M., & Hauschild, M. Z. (2026). UNCASExt – A systematic computational framework for uncertainty propagation and scope consistency in absolute environmental sustainability assessments (AESA). Sustainable Production and Consumption, 69, 394–415. https://doi.org/10.1016/j.spc.2026.09.018

Pirson, T., de Bantel, E. I., Puig-Samper, G., Hartmann, J. M., von der Assen, N., Owsianiak, M., Clavreul, J., Bouillass, G., Yannou, B., Jankovic, M., & Bol, D. (2026, May 17-21). pyaesa - Toward A Python Package for Systematically Allocating Carrying Capacities Under Uncertainty in AESA [Poster spotlight presentation, 5.07.P-Th207]. SETAC Europe 36th Annual Meeting, Maastricht, Netherlands. https://doi.org/10.13140/RG.2.2.32727.43684

For data source citations, see methodological_notes/recommended_citations.txt.

Use of generative AI

Generative AI tools were used during the development of pyaesa. As the development of the package took several months from the initial ideation to the first release, several tools were used including OpenAI Codex models 5.3 to 5.5, Codex Spark 5.3, Anthropic Claude Opus 4.6 and Sonnet 4.6, and GitHub Copilot.

These tools were used to support implementation tasks, including code generation, refactoring, debugging, test design, documentation drafting, code review, computing time optimization, memory use reduction, and figure rendering workflows.

The development of AESA methodology and workflow, mathematical expressions, software architecture and the figures conception were defined by the authors. Generative AI outputs were used as implementation drafts, checked and modified where needed, and retained only after review and testing by human intelligence.

Funding information

This work was made possible thanks to the support and fundings from several sources:

• The work of Erwan Ike de Bantel received organizational support of the CircularIT Alliance project. Erwan Ike de Bantel is affiliated to Université Paris-Saclay, CentraleSupélec, Laboratoire Genie Industriel, 91190 Gif-sur-Yvette, France.

• The work of Thibault Pirson is part of the SOIL project, which received funding from the European Union’s Horizon Europe research and innovation program under the HORIZON-KDTJU-2023-1-IA grant agreement N°101139785. Views and opinions expressed are however those of the authors only and do not necessarily reflect those of the European Union or CHIPS. Neither the European Union nor the granting authority can be held responsible for them. Thibault Pirson is affiliated to Université catholique de Louvain, Institute of Information and Communication Technologies, Electronics, and Applied Mathematics (ICTEAM), 1348 Louvain-la-Neuve, Belgium.

• Gonzalo Puig-Samper is affiliated to Luxembourg Institute of Science and Technology, 5 Avenue des Hauts-Fourneaux, Esch-sur-Alzette, L-4362, Luxembourg.

• Jan Marcus Hartmann is affiliated to Institute of Technical Thermodynamics, RWTH Aachen University, Schinkelstraße 8, 52062 Aachen, Germany.

Acknowledgments

The authors would like to thank Anders Bjørn, Michaël Lejeune, Romain Sacchi, Joanna Schlesinger-Martinat, Niklas von der Assen, Mikolaj Owsianiak, Natacha Gondran, Timo Diepers, Sankalp Shrivastava, Andrea Paulillo, and Julie Clavreul for the valuable discussions and interactions during the realization of this work.