Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
raphaeljolivet committed Apr 18, 2024
1 parent d53e1fc commit d149c81
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 58 deletions.
15 changes: 3 additions & 12 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,15 @@ doc:
clean:
rm -r dist

package-pip:
package:
python setup.py sdist bdist_wheel --universal

package-conda :
conda build --py 3.9 conda-recipe

package : package-pip package-conda

tst-upload-pip:
tst-upload:
twine upload --repository-url https://test.pypi.org/legacy/ dist/lca_algebraic*

upload-pip:
upload:
twine upload dist/lca_algebraic*

upload-conda:
anaconda upload --force ~/mambaforge/conda-bld/noarch/lca_algebraic-$(VERSION)-py_0.tar.bz2

upload : upload-pip upload-conda

pytest:
pytest test
Expand Down
58 changes: 12 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@

# Introduction

This library is a layer above [**brightway2**](https://brightway.dev/) designed for the definition of **parametric inventories**
with fast computation of LCA impacts, suitable for **monte-carlo** analyis.
with fast computation of LCA impacts, suitable for **monte-carlo** / global sensitivity analysis

It integrates the magic of [Sympy](https://www.sympy.org/en/index.html) in order
to write parametric formulas as regular Python expressions.
It integrates the magic of [Sympy](https://www.sympy.org/en/index.html) in order to write parametric formulas as regular Python expressions.

**lca-algebraic** provides a set of **helper functions** for :
* **compact** & **human readable** definition of activites :
**lca-algebraic** provides a set of **helper functions** for :
* **compact** & **human readable** definition of activities :
* search background (tech and biosphere) activities
* create new foreground activites with parametrized amounts
* create new foreground activities with parametrized amounts
* parametrize / update existing background activities (extending the class **Activity**)
* Definition of parameters
* Fast computation of LCAs
Expand All @@ -19,13 +17,14 @@ to write parametric formulas as regular Python expressions.
# Installation

We don't provide conda package anymore.
Please use pip for installation

This packages is available via [pip /pypi](https://pypi.org/project/lca-algebraic/)

## 1) Setup separate environement

First create a python environment, with **Python** [>=3.9] :

**With Conda or mamba**
**With Conda (or [mamba](https://mamba.readthedocs.io/en/latest/index.html))**

```bash
conda env create -n lca python==3.10
Expand All @@ -39,51 +38,18 @@ python3.10 -m venv .venv
source .venv/bin/activate
```


## 2) Install lca_algebraic

> pip install lca_algebraic

# Usage & documentation

Please refer to the [online documentation](https://lca_algebraic.readthedocs.org/)

# Licence & Copyright

This library has been developed by [OIE - MinesParistech](http://www.oie.mines-paristech.fr), for the project *INCER-ACV*,
This library has been developed by [OIE - MinesParistech](http://www.oie.mines-paristech.fr), for the project [*INCER-ACV*](https://librairie.ademe.fr/energies-renouvelables-reseaux-et-stockage/4448-incer-acv.html),
lead by [ADEME](https://www.ademe.fr/).

It is distributed under the **[BSD licence](/LICENSE)**.


# Principles

The main idea of this libray is to move from **procedural definition** of models (slow and prone to errors) to a **declarative / purely functionnal** definition of parametric models (models as **pure functions**).

This enables **fast computation of LCA impacts**.
We leverage the **power of symbolic calculus** provided by the great libary [SymPy](https://www.sympy.org/en/index.html).

We define our model in a **separate DB**, as a nested combination of :
* other foreground activities
* background activities :
* Technical, refering **ecoinvent DB**
* Biopshere, refering **brightway2** biosphere activities

The **amounts** in exchanges are expressed either as **static amounts**, or **symbolic expressions** of pre-defined **parameters**.

Each activity of our **root model** is defined as a **parametrized combination** of the **foreground activities**, which can themselves be expressed by the **background activities**.

When computing LCA for foreground models, the library develops the model as a combination of **only background activities**. It computes **once for all** the impact of **background activities** and compiles a **fast numpy** (vectorial) function for each impact, replacing each background activity by the **static value of the corresponding impact**.

By providing **large vectors** of **parameter values** to those numpy functions, we can compute LCA for **thousands of values** at a time.


# Compatibility with brightway2

Under the hood, the activities we define with **lca-algebraic** are standard **brightway2** activities.
The amounts of exchanges are stored as **float values** or **serialized as string** in the property **formula**.
It is distributed under the [BSD License](./LICENSE)

Parameters are also stored in the **brightay2** projets, making it fully compatible with **brightway**.
# Documentation

Thus, a model defined with **lca-algebraic** is stored as a regular **bw2** projet. We can use **bw2** native support for [parametrized dataset](https://2.docs.brightway.dev/intro.html#parameterized-datasets) for computing LCAs, even if much more slower than the method explain here.
Full documentation and example notebooks are [hosted on **readthedocs**](https://lca-algebraic.readthedocs.io/)

0 comments on commit d149c81

Please sign in to comment.