Metadata-Version: 2.4
Name: aiphoria
Version: 0.9.4
Summary: Dynamic MFA tool
Author-email: Janne Järvikylä <janne.jarvikyla@efi.int>
Maintainer-email: Janne Järvikylä <janne.jarvikyla@efi.int>
License-Expression: MIT
Project-URL: Homepage, https://github.com/EuropeanForestInstitute/aiphoria
Project-URL: Issues, https://github.com/EuropeanForestInstitute/aiphoria/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas==2.2.2
Requires-Dist: Pillow>=12.1.1
Requires-Dist: plotly==6.0.0
Requires-Dist: openpyxl==3.1.3
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: xlrd
Requires-Dist: xlwt
Requires-Dist: tqdm
Requires-Dist: IPython
Requires-Dist: xlsxwriter
Dynamic: license-file

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/aiphoria-logo.png" height="50">
    <img alt="aiphoria logo" src="https://raw.githubusercontent.com/EuropeanForestInstitute/aiphoria/main/assets/aiphoria-logo.png" height="160">
  </picture>
</h1>

![GitHub Release](https://img.shields.io/github/v/release/EuropeanForestInstitute/aiphoria)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/EuropeanForestInstitute/aiphoria/publish-pypi.yaml)
![Tests](https://img.shields.io/github/actions/workflow/status/EuropeanForestInstitute/aiphoria/run-tests.yaml?label=tests)
![Coverage](assets/coverage.svg)
![GitHub License](https://img.shields.io/github/license/EuropeanForestInstitute/aiphoria)
<br>


## Python package for assessing and visualizing dynamic wood material flows
aiphoria is Python package that facilitates the assessment of wood materials flows, associated carbon stocks, and stock changes, as well as and their visualization over time.
**aiphoria** builds on top of [ODYM - Open Dynamic Material Systems Model](https://github.com/IndEcol/ODYM).

## Features:
**aiphoria** allows you to:
- **Solve flows** provided both in absolute and relative (%) values, for example semi-finished wood product statistics (absolute values) to end-uses (relative values)
- **Conduct dynamic MFA as well as temporary carbon storage assessment**
- **Visualize material flows** through a Sankey diagram and provided timestep.

## Use cases:
**aiphoria** is ideal for:
- **Any temporal and spatial situation where material systems want to be assessed**
- **Product sink/stock effects**


# Installation

**aiphoria** is available at Python Package Index (PyPi) and as source distribution in [Github](https://github.com/EuropeanForestInstitute/aiphoria/wiki)<br>

## Install from PyPi
```
pip install aiphoria
```

## Install from GitHub
```
pip install git+https://github.com/EuropeanForestInstitute/aiphoria.git
```

# How to use

## Showcase
**aiphoria** includes helper function to showcase example scenario with visualizations.<br>
Showcase / example scenario can be run by the following code:

```python
from aiphoria.example import run_example

run_example(remove_existing_output_dir=True)
```

Network and Sankey visualizations are opened automatically in browser and output is generated<br>
inside user home directory to directory called "aiphoria_example_scenario".<br>

## Advanced usage
For the users who are already familiar using **aiphoria** the package exposes function for running
scenarios by using the one-liner:

```python
from aiphoria.runner import run_scenarios

run_scenarios(path_to_settings_file="path/to/scenario/file.xlsx",
              path_to_output_dir="~/scenario_result",
              remove_existing_output_dir=False)
```

Using parameter **path_to_output_dir** overrides the output path defined in scenario file.<br>
This makes easier to change target from Python script itself or when running multiple scenarios in batch.<br>
Parameters:
- path_to_settings_file (string): Path to scenario settings file
- path_to_output_dir (string): Path to directory where results are saved
- remove_existing_output_dir: If True then existing output directory is deleted (defaults to False). If directory already exists then error is raised and execution is stopped

## Documentation

Online documentation can be found in [GitHub wiki](https://github.com/EuropeanForestInstitute/aiphoria/wiki).

## Support:

If you have any questions or need help, do not hesitate to contact us:
- Cleo Orfanidou [cleo.orfanidou@efi.int](mailto:cleo.orfanidou@efi.int)
- Janne Järvikylä [janne.jarvikyla@efi.int](mailto:janne.jarvikyla@efi.int)

## Special thanks
A huge thank you to the following people who made aiphoria better:
- Gustavo Ezequiel Martinez (virtual flows, system testing)
  - GitHub: [GustavoEzMartinez](https://github.com/GustavoEzMartinez)
  - Email: [gustavoezequiel.martinez@vito.be](mailto:gustavoezequiel.martinez@vito.be)

- Arthur Jakobs (packaging, CI/CD)
  - GitHub: [jakobsarthur](https://github.com/jakobsarthur)
  - Email: [artos.jakobs@psi.ch](mailto:artos.jakobs@psi.ch)

## Funding:
aiphoria developers / European Forest Institute receive funding from the European Union’s Horizon Europe Research and Innovation Programme [`ForestPaths (ID No 101056755)`](https://forestpaths.eu/), [`Monifun (ID No 101134991)`](https://www.monifun.eu/) and [`eco2adapt (ID No 101059498)`](https://www.eco2adapt.eu/).
