# Setup

This guide walks you through setting up your Brightway project using Activity Browser, preparing it for use with _mescal_. We provide Jupyter notebooks for each step, available on the [_mescal_ GitHub repository](https://github.com/matthieu-str/mescal/tree/master/dev).

> **Questions or issues?** Please file an [issue](https://github.com/matthieu-str/mescal/issues) along with a detailed description or contact the _mescal_ maintainers (for example, at matthieu.souttre@polymtl.ca)

---

![flowchart of the setup steps](../pics/setup.png "setup")


## Step 1: Install Activity Browser

Activity Browser is a graphical user interface for Brightway that makes project management much easier.

**Installation via conda:**
```bash
conda create -n ab -c conda-forge activity-browser
conda activate ab
activity-browser
```

📖 [Activity Browser Documentation](https://github.com/LCA-ActivityBrowser/activity-browser#installation)

---

## Step 2: Create Your Project

1. Open Activity Browser
2. Go to **Project → New project**
3. Give your project a meaningful name (typically, you should have one project per ecoinvent version, e.g., `ecoinvent3.10.1`)

Your project will store all databases, LCIA methods, and calculation setups in an isolated environment (i.e., there can be no exchanges among different projects).

---

## Step 3: Import Ecoinvent Database

This is the foundation for all LCA calculations in _mescal_. However, note that _mescal_ would also work with any other background database (if any) in your Brightway project.

**In Activity Browser:**
1. Navigate to **Database → Import database**
2. Select **ecoinvent** as the source
3. Choose your ecoinvent version (**3.9.1** or **3.10.1** recommended for Regioinvent compatibility)
4. Select a system model:
   - **Cutoff** — required for Regioinvent/Regiopremise
   - **Consequential** — for consequential LCA studies (not compatible with Regioinvent)
   - **APOS** — allocation at point of substitution
5. Enter your ecoinvent credentials when prompted

> ⚠ You should only have one ecoinvent database per project. If you need to work with multiple versions, create separate projects for each.

📖 [Brightway ecoinvent import guide](https://docs.brightway.dev/en/latest/content/examples/brightway-examples/import_data/import_ecoinvent/import_ecoinvent.html)

---

## Step 4: Regionalize Ecoinvent with Regioinvent (Optional)

[Regioinvent](https://github.com/CIRAIG/Regioinvent) is a tool to regionalize your ecoinvent database. Regioinvent has two main steps:
1. Elementary flows spatialization: it assigns geographic locations to elementary flows, thus enabling the use of regionalized LCIA methods that require spatialized flows (e.g., IMPACT World+ v2.1, EF 3.1, ReCiPe 2016).
2. Trade regionalization: it connects ecoinvent to BACI trade data, enabling more realistic supply chain modeling through national production processes and consumption markets.

### Why use Regioinvent?

- **Realistic supply chains**: Replaces generic RER, RoW, GLO processes with country-specific versions
- **Spatialized elementary flows**: Connects to regionalized LCIA methods (IMPACT World+ v2.1, EF 3.1, ReCiPe 2016)
- **Trade-based markets**: Uses UN COMTRADE/BACI data for realistic import mixes

### Installation
```bash
pip install regioinvent
```

### Required data

Download the pre-extracted trade data from [Zenodo](https://doi.org/10.5281/zenodo.11583814) (use the latest version).

**📓 Notebook:** [demo.ipynb](https://github.com/CIRAIG/Regioinvent/blob/master/doc/demo.ipynb)

---

## Step 5: Create Prospective Databases with Premise (Optional)

[Premise](https://premise.readthedocs.io/en/latest/) allows you to create prospective LCA databases by projecting ecoinvent into future scenarios generated by Integrated Assessment Models (IAMs).

**When to use Premise?**
- Model future energy transitions scenarios from IAMs
- Include emerging technologies
- Align inventories with climate scenarios (e.g., SSP, RCP pathways)

**📓 Notebook:** [import_premise_db.ipynb](https://github.com/matthieu-str/mescal/blob/master/dev/import_premise_db.ipynb)

> ⚠️ **Note:** You may need an encryption key from the Premise developers to access standard IAM scenarios. Contact romain.sacchi@psi.ch

---

## Step 6: Regionalize Premise with Regiopremise (Optional)

[Regiopremise](https://github.com/matthieu-str/Regiopremise) adapts Regioinvent to work with Premise databases. This allows you to combine prospective scenarios with regionalized supply chains.

### What's different from Regioinvent?

Regiopremise handles additional datasets introduced by Premise, for instance, the ones corresponding to Integrated Assessment Model (IAM) regions.

> ⚠️ **Note:** Regiopremise is also based on BACI trade data, which is not projected into the future. Therefore, the trade regionalization will be the same as in Regioinvent, even for Premise databases.

### Installation

Clone or download the repository:
```bash
git clone https://github.com/matthieu-str/Regiopremise.git
```

### Prerequisites

- A Brightway2 project with a **Premise-generated** ecoinvent database
- Trade data from [Zenodo](https://doi.org/10.5281/zenodo.11583814)

**📓 Notebook:** [demo.ipynb](https://github.com/matthieu-str/Regiopremise/blob/master/doc/demo.ipynb)

---

## Step 7: Install IMPACT World+ LCIA Method (Optional)

[IMPACT World+](http://www.impactworldplus.org/) is a globally regionalized life-cycle impact assessment method developed by [CIRAIG](https://ciraig.org/), providing both midpoint and endpoint indicators.

**📓 Notebook:** [download_impact_world_plus.ipynb](https://github.com/matthieu-str/mescal/blob/master/dev/download_impact_world_plus.ipynb)

---