bw-superstructure 1.0.2
allows prospective LCA calculations for scenarios using the superstructure and scenario-difference-file approach of the activity-browser and brightway2
Requires Python: >=3.7

# bw_superstructure

[![PyPI - Version](https://img.shields.io/pypi/v/bw-superstructure.svg)](https://pypi.org/project/bw-superstructure)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bw-superstructure.svg)](https://pypi.org/project/bw-superstructure)

-----

**Contents**

- [bw\_superstructure](#bw_superstructure)
  - [Introduction](#introduction)
  - [Installation](#installation)
  - [Features](#features)
  - [Requirements](#requirements)
  - [Features missing so far](#features-missing-so-far)
  - [Relation to the activity-browser (AB)](#relation-to-the-activity-browser-ab)
  - [License](#license)
  - [Contribution](#contribution)
  - [Contact](#contact)


## Introduction

The brightway-superstructure library allows to conduct scenario LCA calculations using the approach of the [superstructure](https://link.springer.com/article/10.1007/s11367-021-01974-2), as it has been developed for the [activity-browser](https://github.com/LCA-ActivityBrowser/activity-browser) (AB). 

## Installation

First install python 3.10 and pip. 
If you use conda-forge, please add the channels `bsteubing` and `cmutel` for the brightway dependencies.

For installation via pip use:
```console
pip install bw-superstructure
```

To install from git source use hatch:  
```console
pip install hatch
hatch build
pip install -I .\dist\bw_superstructure-1.0.1-py3-none-any.whl
```

If you would like to have another version, replace `1.0.1` with the desired version number.

## Features

- relinking a database (DB) from one to another (background-) DB
- creating a user-defined calculation set-up for several functional units and impact categories 
- calculating scenario LCA scores with a superstructure and a scenario-difference-file
- exporting the LCA scores for the scenarios for each functional unit to an excel workbook

These features are illustrated in an [example](https://github.com/CHarpprecht/bw_superstructure/blob/main/example/example.py). 

## Requirements

- a working [brightway2](https://docs.brightway.dev/en/legacy/index.html)-project with databases
- functional units specified in an excel file (see inputs in [example-folder](https://github.com/CHarpprecht/bw_superstructure/tree/main/example/inputs)) or in a list
- impact categories specified in a yaml file (see inputs in [example-folder](https://github.com/CHarpprecht/bw_superstructure/tree/main/example/inputs))

Required for scenario calculations:
- a superstructure database (e.g. generated by [premise](https://github.com/polca/premise))
- a scenario difference file (SDF) (excel file, same format as for the AB, see provided [template](https://github.com/CHarpprecht/bw_superstructure/blob/main/example/inputs/template_scenario_difference_file.xlsx))


## Features missing so far

- specifying a value for the functional units (so far, the amount is set to 1 by default for each functional unit)
- contribution analyses
- monte carlo analysis
- using several scenario difference files for the LCA calculation

## Relation to the activity-browser (AB)

The code in this repository is mainly extracted from the [activity-browser](https://github.com/LCA-ActivityBrowser/activity-browser). The following AB version was used:

- version: 2022.11.16
- branch: activity-browser-dev

The extraction of code was conducted as follows:
- original objects and functions from the AB are in the sub-modules [bwutils](https://github.com/CHarpprecht/bw_superstructure/tree/main/bw_superstructure/bwutils) and [superstructure](https://github.com/CHarpprecht/bw_superstructure/tree/main/bw_superstructure/superstructure)
- each file has the original filename as in the AB
- in the header of the file, the relative path for that file within the AB is given
- each function or objects states the source of the AB and whether it has been adapted or not
- all of the objects are original, unless otherwise stated, apart from the functions in the superstructure.manager, which defines functions which originally where methods of the class SuperstructureManager of the ab
- search for "Note: source" to see all objects from the activity-browser
- search for "adaptations:" to see the adaptations. no adaptations are mentioned, no adaptations were done

## License

`bw-superstructure` is distributed under the terms of the [LGPL-3.0](https://spdx.org/licenses/LGPL-3.0) license.

The license for the data in the [example](https://github.com/CHarpprecht/bw_superstructure/blob/main/example/example.py) is [CC-BY-4.0](https://spdx.org/licenses/CC-BY-4.0.html).

## Contribution

If you would like to contribute to `bw-superstructure`, please read, sign and send the [Contributors License Agreement (CLA)](https://github.com/CHarpprecht/bw_superstructure/blob/main/bw_superstructure_Individual%20Contributor%20License%20Agreement.docx) to [Carina Harpprecht](carina.harpprecht@dlr.de).

When contributing to this repository, please discuss the changes you would like to make via issue, email, or any other method with the owners of this repository before making a change. 

The library of `bw-superstructure` will be provided as-is in its current release version. 
Minor bugs will be fixed in the future, but currently, no major support can be offered to the software. 
However, feel free to get in touch in case you have any questions or would like to contribute.


## Contact

- Carina Harpprecht: carina.harpprecht@dlr.de