LiAISON is a Python framework for performing automated, scalable life cycle assessment (LCA) with support for prospective analysis using integrated assessment model (IAM) scenarios.

To inquire about using LiAISON in your research, please contact Patrick Lamers at patrick.lamers@nlr.gov.

• Automated LCA Calculations: Automatically link foreground inventory processes to background ecoinvent database
• Prospective LCA: Integrate future scenarios from IAM models (IMAGE, GCAM) via premise
• Regional Analysis: Perform location-specific LCA calculations with automatic fallback to alternative geographies
• Monte Carlo Analysis: Uncertainty quantification for foreground inventory
• Batch Processing: Execute multiple LCA scenarios programmatically for optimization and systems modeling
• Flexible Configuration: YAML-based configuration for easy scenario management

The LiAISON framework consists of three modular components:

1. Life Cycle Inventory Reader: Imports and stores the base ecoinvent database in Brightway2
2. Prospective LCA Updater: Modifies the base database with future scenarios from IAM models using premise
3. Automated LCA Calculator: Links user-defined foreground processes to background inventory and performs LCIA

This modular design enables:

• One-time database import with reusable projects
• Separation of database updates from LCA calculations
• Integration with systems models and optimization frameworks

Prospective LCA updates the background database with future projections of:

• Electricity generation mixes
• Transportation technologies
• Industrial processes
• Material production

Multiple IAM models and Shared Socioeconomic Pathways (SSPs) are supported through premise.

• Operating System: Linux, macOS, or Windows with Anaconda
• Python: 3.10 or 3.11
• RAM: Minimum 8 GB (16 GB recommended for large analyses)

• ecoinvent license: ecoinvent 3.8 database (cutoff allocation)
• IAM Access Key (for prospective LCA): Contact developers for premise decryption key

The environment includes:

• brightway2==2.4.7 - LCA calculation engine
• bw2data==3.6.6 - Brightway2 data management
• bw2calc==1.8.2 - Brightway2 calculation module
• bw2io==0.8.7 - Brightway2 input/output (required for ecoinvent 3.8)
• premise==2.3.0.dev1 - Prospective database scenarios
• premise-gwp==0.9.7 - GWP methods for premise

Download and install Anaconda or Miniconda for your operating system.

git clone https://github.com/NREL/LiAISON.git
cd LiAISON

# Create environment from file
conda env create -f environment.yml -n liaison

# Activate the environment
conda activate liaison

# Check brightway2 installation
python -c "import brightway2 as bw; print(f'Brightway2 version: {bw.__version__}')"

# Check premise installation
python -c "import premise; print(f'Premise installed successfully')"

Ecoinvent 3.8 Compatibility: The environment includes bw2data==3.6.6, bw2calc==1.8.2, and bw2io==0.8.7 which are specifically required for ecoinvent 3.8. These versions are automatically installed via the environment file.

For Other ecoinvent Versions: If you plan to use ecoinvent versions newer than 3.8, you will need:

pip install --upgrade bw2io  # Install latest version (>0.8.8)

1. Download ecoinvent 3.8 cutoff allocation, ecoSpold02 from the ecoinvent website

   • File: ecoinvent 3.8_cutoff_ecoSpold02.7z (~61 MB)

2. Extract the database:

   # Extract to the data/inputs/ecoinvent directory
   7z x "ecoinvent 3.8_cutoff_ecoSpold02.7z" -o"data/inputs/ecoinvent/"

3. Rename the extracted folder:

   # Ensure underscore between 'ecoinvent' and '3.8'
   mv "data/inputs/ecoinvent/ecoinvent 3.8_cutoff_ecoSpold02" \
      "data/inputs/ecoinvent/ecoinvent_3.8_cutoff_ecoSpold02"

Directory Structure:

LiAISON/
├── data/
│   ├── inputs/
│   │   ├── ecoinvent/
│   │   │   └── ecoinvent_3.8_cutoff_ecoSpold02/
│   │   │       └── datasets/
│   │   ├── example1.csv
│   │   ├── example2.csv
│   │   ├── emission_name_bridge.csv
│   │   ├── process_name_bridge.csv
│   │   └── location_bridge.csv
│   └── output/
├── environment.yml
├── run.sh
└── __main__.py

Execute a complete test run to verify installation:

# Make the script executable
chmod +x run.sh

# Run with test configuration
./run.sh

This will:

1. Read the ecoinvent 3.8 database (first time only, ~10-15 minutes)
2. Create a simple foreground inventory
3. Perform LCA with TRACI and ReCiPe methods
4. Generate results in data/output/

Edit the run.sh script to specify your configuration file:

#!/usr/bin/env bash
PATH_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
DATADIR=$PATH_DIR"/data"
yaml="example1"  # Change to your YAML file name (without .yaml extension)

python __main__.py --datapath=$DATADIR --lca_config_file=$DATADIR/$yaml.yaml

Then execute:

./run.sh

LiAISON uses YAML files for configuration. Three example configurations are provided:

Performs LCA on an existing ecoinvent process (US electricity grid).

Key Settings:

• read_base_lci_database: true (first run only)
• update_base_database_with_future_information: false
• use_base_database_for_lca: true
• No foreground inventory creation

Creates a complex foreground system for hydrogen production via polymer electrolyte water electrolysis (PEWE).

Key Settings:

• Creates 3 linked activities (stack → plant → operation)
• foreground_inventory: example2.csv
• Links to ecoinvent background processes

Performs future-oriented LCA for hydrogen production in 2040 under SSP2-RCP26 scenario.

Key Settings:

• update_base_database_with_future_information: true
• updated_database: ecoinvent_2040_SSP2-RCP26
• model: image (or gcam)
• Requires model_key for premise access

data_directories:
  ecoinvent_data: ecoinvent/ecoinvent_3.8_cutoff_ecoSpold02/datasets/
  liaisondata: inputs/
  output: output/

flags:
  correct_uncertainty: false          # Apply uncertainty corrections
  mc_foreground: false                # Monte Carlo on foreground
  lca: true                           # Perform LCA calculation
  lca_activity_modification: false   # Edit ecoinvent activities
  update_base_database_with_future_information: false  # Run prospective updater
  read_base_lci_database: true       # Import ecoinvent (first time only)
  use_base_database_for_lca: true    # Use base ecoinvent (vs updated)
  regional_sensitivity: false         # Regional analysis

input_filenames:
  emission_bridge: emission_name_bridge.csv
  creation_inventory: N/A
  foreground_inventory: example1.csv
  modification_inventory: N/A
  location_bridge: location_bridge.csv
  process_bridge: process_name_bridge.csv

output_filenames:
  results_filename: lcia_results

scenario_parameters:
  base_database: ecoinvent3.8
  base_project: base_project_ecoinvent38
  functional_unit: 1
  initial_year: 2020
  lca_project_name: lca_project_ecoinvent
  location: US
  unit: kilowatt hour
  mc_runs: 1
  model: image                       # IAM model: 'image' or 'gcam'
  model_key: your_key_here          # Request from developers
  primary_process_to_study: example  # Main process for LCA
  process: example                   # Process name for results
  updated_database: ecoinvent3.8
  updated_project_name: ecoinvent_3.8

Important: For prospective LCA, the naming convention is critical:

• updated_database: ecoinvent_[YEAR]_[SCENARIO]
• updated_project_name: ecoinvent_[YEAR]_[SCENARIO]_[model]

Example:

updated_database: ecoinvent_2040_SSP2-RCP26
updated_project_name: ecoinvent_2040_SSP2-RCP26_image

Create a CSV file with the following columns:

process,flow,value,unit,input,year,comments,type,process_location,supplying_location
my_process,my_product,1,kilogram,FALSE,2020,none,production,US,US
my_process,electricity,50,kilowatt hour,TRUE,2020,none,technosphere,US,US

For complex systems with multiple linked activities (see example2.csv):

1. Define all production flows (one per activity)
2. Link activities by using production flows as technosphere inputs
3. Specify location for each process and input source
4. Include biosphere flows (emissions) as needed

Example structure:

# Activity 1: Component Production
component_production,component,1,unit,FALSE,2020,none,production,US,US
component_production,steel,10,kilogram,TRUE,2020,none,technosphere,US,US

# Activity 2: Plant Construction (uses component)
plant_construction,plant,1,unit,FALSE,2020,none,production,US,US
plant_construction,component,0.5,unit,TRUE,2020,none,technosphere,US,US

# Activity 3: Operation (uses plant)
operation,hydrogen,1,kilogram,FALSE,2020,none,production,US,US
operation,plant,3.18E-07,unit,TRUE,2020,none,technosphere,US,US
operation,electricity,55,kilowatt hour,TRUE,2020,none,technosphere,US,US

Bridge files map your custom names to ecoinvent nomenclature.

Maps foreground technosphere flows to ecoinvent activities:

Common_name,Ecoinvent_name,Ecoinvent_code
electricity,market group for electricity, high voltage,abc123...
steel,market for steel, low-alloyed,def456...

Best Practice: Always include the Ecoinvent_code (activity UUID) to ensure exact matches. Find codes using:

• Activity Browser
• ecoQuery
• Brightway2: activity['code']

Maps biosphere flows to ecoinvent elementary flows:

Common_name,Ecoinvent_name,Ecoinvent_code
CO2,Carbon dioxide, fossil,ghi789...
NOx,Nitrogen oxides,jkl012...

Maps location names (typically not needed if using standard ISO codes):

location_common,location_ecoinvent
United States,US
California,US-WECC

python __main__.py \
  --datapath=/path/to/data \
  --envpath=/path/to/brightway_env \
  --lca_config_file=/path/to/data/config.yaml

Parameters:

• --datapath: Directory containing input/output folders
• --envpath: (Optional) Custom Brightway2 data directory
• --lca_config_file: Path to YAML configuration file

The provided script simplifies execution:

#!/usr/bin/env bash
PATH_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
DATADIR=$PATH_DIR"/data"
yaml="your_config"  # Without .yaml extension

python __main__.py --datapath=$DATADIR --lca_config_file=$DATADIR/$yaml.yaml

1. First Time Setup (~10-15 minutes):

   • Set read_base_lci_database: true
   • Imports ecoinvent 3.8 into Brightway2
   • Creates base project

2. Subsequent Runs (seconds to minutes):

   • Set read_base_lci_database: false
   • Uses stored base project
   • Performs LCA calculations

3. Prospective LCA (15-45 minutes per scenario):

   • Set update_base_database_with_future_information: true
   • Downloads IAM data via premise
   • Updates database for future year/scenario
   • Stores updated project for reuse

LiAISON provides informative console messages during execution:

Complete Success

Complete Success - Provided location US for market group for electricity, low voltage was found.
Chosen location was US. Chosen process was market group for electricity, low voltage

→ Exact match found at requested location

Minor Success

Minor Success - Provided location US for low alloyed steel was not found.
Shifting to market for steel, low-alloyed GLO

→ Process found at alternative location (RoW, GLO, RER, etc.)

Activity Not Found

Failed - Not found nitrogen, from air separation US b55af830...

→ Activity doesn't exist in ecoinvent; check spelling or add to bridge file

Multiple Activities

INFO: Process dictionary length when [process]@[location]@[unit] is chosen is 3
INFO Multiple activities found ---- [activity1] [code1]
INFO Multiple activities found ---- [activity2] [code2]

→ Multiple matches; first is chosen by default. Specify Ecoinvent_code in bridge file to select exact match.

Unit Mismatch

Warning --- UNIT ERROR US for market group for electricity
Warning --- Correct unit should be kilowatt hour

→ Your unit doesn't match ecoinvent. Update foreground inventory.

When an activity isn't found at the specified location, LiAISON searches in order:

1. Requested location (e.g., US)
2. North America (USA, RNA)
3. Rest of World (RoW)
4. Global (GLO)
5. Europe (RER)

Results are saved in data/output/:

LCIA Results (lcia_results_[database]_[process].csv):

lcia,value,unit,year,method
Global Warming,100.5,kg CO2 eq,ecoinvent_2020_SSP2-Base,TRACI2.1
Acidification,0.25,kg SO2 eq,ecoinvent_2020_SSP2-Base,TRACI2.1
...

Electricity Mix ([database]_electricity_mix.csv):

• Breakdown of electricity generation sources
• Useful for understanding background electricity impacts

LiAISON calculates impacts using multiple methods:

TRACI 2.1 (9 categories):

• Global warming
• Acidification
• Eutrophication
• Ecotoxicity
• Human health - Carcinogenic
• Human health - Non-carcinogenic
• Ozone depletion
• Photochemical oxidation
• Respiratory effects

ReCiPe Midpoint (H) (18 categories):

• Climate change
• Ozone depletion
• Human toxicity
• Particulate matter formation
• Ionising radiation
• Photochemical oxidant formation
• Terrestrial acidification
• Freshwater eutrophication
• Marine eutrophication
• Terrestrial ecotoxicity
• Freshwater ecotoxicity
• Marine ecotoxicity
• Agricultural land occupation
• Urban land occupation
• Natural land transformation
• Water depletion
• Mineral resource depletion
• Fossil resource depletion

IPCC 2013 (via premise, for prospective LCA):

• GWP 100a (various accounting methods)

Enable uncertainty propagation on foreground inventory:

flags:
  mc_foreground: true
  
scenario_parameters:
  mc_runs: 1000  # Number of Monte Carlo iterations

Note: This applies uncertainty only to foreground processes. Background ecoinvent uncertainties are always included in stochastic calculations.

Test how location affects results without modifying CSV:

flags:
  regional_sensitivity: true
  
scenario_parameters:
  location: CA  # Override all locations to California

Edit existing ecoinvent activities directly (advanced):

flags:
  lca_activity_modification: true

This extracts an ecoinvent activity, allows modification, and uses the modified version for LCA.

For prospective LCA, follow the naming convention:

SSP Scenarios:

# Format: ecoinvent_[YEAR]_[SSP]-[RCP]
updated_database: ecoinvent_2030_SSP2-Base
updated_database: ecoinvent_2050_SSP1-RCP19
updated_database: ecoinvent_2040_SSP2-RCP26

Available Scenarios (depends on IAM model):

• SSP1-RCP19 (Sustainability, 1.5°C pathway)
• SSP2-Base (Middle of the road, baseline)
• SSP2-RCP26 (Middle of the road, 2°C pathway)
• SSP2-RCP45 (Middle of the road, moderate mitigation)
• SSP5-Base (Fossil-fueled development, baseline)

Issue: Could not open [config.yaml] for configuration

• Solution: Check that YAML file exists and path is correct in run.sh

Issue: No module named 'brightway2'

• Solution: Activate the conda environment: conda activate liaison

Issue: KeyError: 'ecoinvent3.8'

• Solution: Run with read_base_lci_database: true to import ecoinvent first

Issue: Process not found in ecoinvent

• Solution:
  1. Check spelling in bridge files
  2. Verify process exists in ecoinvent 3.8
  3. Try providing Ecoinvent_code in bridge file
  4. Check alternative locations (GLO, RoW)

Issue: Premise fails with authentication error

• Solution: Request valid model_key from developers (email address below)

Issue: Unit mismatch errors

• Solution: Check ecoinvent documentation for correct units. Common mismatches:
  • kWh vs kilowatt hour
  • kg vs kilogram
  • m3 vs cubic meter

Speed up repeated runs:

1. Import ecoinvent once (read_base_lci_database: true), then set to false
2. For prospective LCA, create updated databases once, then reuse
3. Use use_base_database_for_lca: true when prospective update not needed

Reduce memory usage:

• Process results in batches if running many scenarios
• Clear output directory between large runs
• Close other applications during premise updates

Check LiAISON messages: The console output provides detailed information about:

• Which activities were found/not found
• Location substitutions made
• Unit mismatches
• Database search progress

Enable detailed logging:

import logging
logging.basicConfig(level=logging.DEBUG)

LiAISON/
├── __main__.py                    # Main entry point
├── liaison_model.py               # LCA workflow orchestration
├── lci_calculator.py              # LCI calculations and LCIA methods
├── search_activity_ecoinvent.py   # Activity search functions
├── edit_activity_ecoinvent.py     # Activity editing functions
├── ecoinvent_explorer.py          # Database exploration utilities
├── main_database_reader.py        # Ecoinvent import
├── main_database_editor.py        # Premise integration
├── environment.yml                # Conda environment specification
├── run.sh                         # Execution script
├── data/
│   ├── inputs/
│   │   ├── ecoinvent/             # Ecoinvent database (user-provided)
│   │   ├── example1.csv           # Simple foreground inventory
│   │   ├── example2.csv           # Complex foreground inventory (PEWE)
│   │   ├── example1.yaml          # Basic LCA configuration
│   │   ├── example2.yaml          # Foreground creation configuration
│   │   ├── example3.yaml          # Prospective LCA configuration
│   │   ├── process_name_bridge.csv
│   │   ├── emission_name_bridge.csv
│   │   └── location_bridge.csv
│   └── output/                    # Results directory
└── README.md

LiAISON is designed to integrate with:

• Systems models: ReEDS, GCAM, etc.
• Optimization frameworks: Pyomo, CPLEX, etc.
• Decision support tools: Multi-criteria analysis, techno-economic assessment

import yaml
import subprocess

# Run LCA for optimization iteration
def run_lca_iteration(technology_mix, output_dir):
    # Update foreground inventory with optimization results
    create_inventory_csv(technology_mix, "temp_inventory.csv")
    
    # Update YAML configuration
    config = load_config("base_config.yaml")
    config['input_filenames']['foreground_inventory'] = "temp_inventory.csv"
    config['data_directories']['output'] = output_dir
    
    with open("temp_config.yaml", "w") as f:
        yaml.dump(config, f)
    
    # Execute LiAISON
    subprocess.run(["python", "__main__.py", 
                   "--datapath=data",
                   "--lca_config_file=temp_config.yaml"])
    
    # Parse results
    return parse_lcia_results(output_dir)

If you use LiAISON in your research, please cite:

@article{liaison2023,
  title={LiAISON: Life Cycle Analysis Integration into Scalable Open-source Numerical Models},
  author={Ghosh, Tapajyoti and Lamers, Patrick and Chun, Soomin and others},
  journal={Environmental Science & Technology},
  year={2023},
  doi={10.1021/acs.est.2c04246}
}

• Tapajyoti Ghosh - Lead Developer (tghosh@nrel.gov)
• Patrick Lamers - Principal Investigator (plamers@nrel.gov)
• Soomin Chun - Contributor (schun@nrel.gov)
• Shubhankar Upasani - Contributor
• Alberta Carpenter - Contributor
• Romain Sacchi - Premise Integration (romain.sacchi@psi.ch)

• Email: tghosh@nrel.gov
• Issues: GitHub Issues
• Discussions: GitHub Discussions

For premise-related questions or to request a model encryption key, contact the developers via email.

[Include license information]

This work was supported by the U.S. Department of Energy's Office of Energy Efficiency and Renewable Energy (EERE).

Note: This is research software under active development. While we strive for accuracy and reliability, please validate results for your specific use case and report any issues on GitHub.