# Package Overview

**Beta status:** <span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span> 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

<span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span> 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.

![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

<span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span> 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).

## Community

### Contributing to <span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span>

<span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span> 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
<span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span>
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

<span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span> 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 <span style="color:#366e9c"><strong>py</strong></span><span style="color:#c83737"><strong>aesa</strong></span>.