# Package Overview

**Beta status:** `pyaesa` is currently in beta testing. Please report bugs,
unexpected behavior, documentation gaps, and installation or workflow issues on
the [GitHub Issues page](https://github.com/AESAtoolkit/pyaesa/issues).

## Package Scope

`pyaesa` supports AESA workflows from data preparation to deterministic and
uncertainty results. The package follows three calculation phases:

1. Phase A computes life-cycle assessment results, including IO-LCA from
   processed MRIO data.
2. Phase B computes allocated carrying capacities, with
   `aCC = aSoCC * CC`.
3. Phase C computes absolute sustainability ratios, with `ASR = LCA / aCC`.

## Workflow Map

The figure below summarizes the main package data sources, public workflow
functions, study objectives, and output families.

**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 below. Consequently, *the user must focus solely on the desired study objective*, and run the *single* relevant function.

![High level pyaesa package map](https://raw.githubusercontent.com/AESAtoolkit/pyaesa/main/images/fig-pyaesa-high-level.svg)

## Example Output 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.

![Example outputs generated by the package](../images/example_output_figures.svg)

## 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 [Workflow Reference](workflow_reference.md).

## Copyright

    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.

    Copyright (C) 2026,
    Université Paris-Saclay, Université catholique de Louvain,
    Luxembourg Institute of Science and Technology, RWTH Aachen University.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.

## Community

### Contributing to `pyaesa`

`pyaesa` uses the GitHub Discussions [Ideas](https://github.com/AESAtoolkit/pyaesa/discussions/categories/ideas) category to collect feature ideas and development priorities from users.

Use [Ideas](https://github.com/AESAtoolkit/pyaesa/discussions/categories/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](https://github.com/AESAtoolkit/pyaesa/blob/main/CONTRIBUTING.md).

### Sharing Reproducible Case Studies

Users are encouraged to share AESA case studies developed with
`pyaesa`
in the [AESA_case_studies](https://github.com/AESAtoolkit/AESA_case_studies)
repository. This supports the AESA community by making case studies easier to
understand, inspect, reproduce, compare, and extend.

## Installation

`pyaesa` requires Python 3.11 to 3.14 and at least 4 GB of available RAM.

```bash
python -m pip install pyaesa
```

The [Workflow Reference](workflow_reference.md) provides the main data sources,
workflow functions, and study objectives supported by `pyaesa`.