fmLCA

Create and simulate dynamic Life Cycle Assessment (LCA) models with the Functional Mockup Interface (FMI). The fmLCA project supports CLI and Python API workflows for inventory conversion, LCA runs, FMU generation, and sequential co-simulation.

Contributors

Kathryn Hinkelman, Fitzwilliam Keenan-Koch, and Anastasija Mensikova - SEE Lab, University of Vermont

Features

• Dynamic energy propagation through LCA calculations
• Parameterized subsystem composition from CSV inventories
• Single-input single-output LCA FMUs translating power to single score impacts overtime
• FMU generation for FMI-compatible co-simulation with optional black-box protection
• Brightway + ecoinvent based impact assessment workflows

Installation

Install From PyPI (API)

pip install fmlca

PyPI package: https://pypi.org/project/fmlca/

Use this option when you want to call fmLCA from Python code.

Install From Source (CLI And Development)

git clone https://github.com/see-lab/fmLCA.git
cd fmLCA
python -m venv venv
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Requirements:

• Python 3.9-3.13
• ecoinvent 3.8+ database

Brightway And Ecoinvent Setup

# Check status
python scripts/setup_brightway.py --name fmlca --ecoinvent 3.12 --check

# Import ecoinvent (LCI + LCIA)
python scripts/setup_brightway.py --name fmlca --ecoinvent 3.12 --system-model cutoff

For complete setup options, run:

python scripts/setup_brightway.py -h

Safe Project Selection

Set the target Brightway project explicitly in multi-project environments:

$env:FMLCA_BW_PROJECT = "fmlca"

Optional non-interactive project switching:

$env:FMLCA_AUTO_CONFIRM_PROJECT_SWITCH = "true"

CLI Workflow (Source Checkout)

The CLI examples below use scripts in this repository (for example, scripts/...) and are intended for source checkouts.

Get full options for each command with -h.

1) Convert CSV To Inventory JSON

python scripts/csv_to_json_translator.py example.csv
python scripts/csv_to_json_translator.py example1 example2 --output combined_system.json
python scripts/csv_to_json_translator.py -h

2) Run LCA

python src/lca_engine.py example --methods ipcc
python src/lca_engine.py -h

3) Build FMU

python scripts/create_fmu.py example --method ipcc
python scripts/create_fmu.py example --method ipcc --bw-project fmlca
python scripts/create_fmu.py -h

4) Run FMU / Sequential Co-simulation

python scripts/run_fmu.py --mode single --fmu fmu/Example_Ipcc_v1.0.0.fmu --u0 100 --step-size 60
python scripts/run_fmu.py --mode cosim --system-fmu fmu/PV_System_WECC.fmu --lca-fmu fmu/PvWecc_Ipcc_v1.0.0.fmu --system-output gri.P.real --lca-input u --lca-output y --parameter-name n_pv --parameter-value 2.0 --output-interval 3600 --solver CVode --save-plot results/cosim.png
python scripts/run_fmu.py -h

Python API Workflow

This is the recommended path when installed from PyPI (pip install fmlca).

Use lowercase package import:

from fmlca import csv_to_json_translator, create_fmu, lca_engine, run_fmu
csv_to_json_translator("data/inventory/example.csv", "data/inventory/example.json")
fmu_path = create_fmu("data/inventory/example.json", "fmu", method="ipcc", version="1.0.0")
results = lca_engine("data/inventory/example.json", ["IPCC 2021 climate change total excl biogenic GWP100"])
sim = run_fmu(fmu_path, stop_time=3600.0, input_u=100.0)

Two-FMU co-simulation API:

from pathlib import Path
from fmlca.run_fmu import sequential_cosim
system_result, lca_result = sequential_cosim(system_fmu=Path("fmu/PV_System_WECC.fmu"), lca_fmu=Path("fmu/PvWecc_Ipcc_v1.0.0.fmu"), start_s=0.0, stop_s=3600.0, system_output="gri.P.real", lca_input="u", lca_output="y")

Advanced Options

• Dymola preset: python scripts/create_fmu.py grid --method ipcc --target-tool dymola.
• Strict distribution mode: python scripts/create_fmu.py grid --method ipcc --target-tool dymola --export-mode bytecode --blackbox-policy enforce.
• Default safety posture: bytecode export + black-box enforce; run python scripts/create_fmu.py -h for all policy/export options.

Project Structure

├── src/                    # Core library modules
├── scripts/                # CLI tools
├── data/                   # Inventories and LCIA methods
│   ├── inventory/
│   └── methods/
├── config/                 # Configuration files
├── fmu/                    # Generated FMUs
├── results/                # Analysis outputs
└── tests/                  # Test suite

Testing

python tests/test_cumulative_fmu.py
python -m pytest tests/

Documentation

• Release Tracking

Contributing

Contributions are welcome. See CONTRIBUTING.md.

License

BSD 3-Clause License. See LICENSE.

AI Statement

Generative Artificial Intelligence tools (GitHub Copilot GPT-5.3-Codex, Claude Opus 4.8) were utilized in the drafting, optimization, and refactoring of portions of this codebase. All AI-assisted code has been rigorously audited, verified through unit testing, and peer-reviewed by human researchers, who maintain full accountability for the scientific validity and security of the software.

Citation

Citation details will be added here when available.

Links

• GitHub Repository
• SEE Lab
• Brightway Documentation

Maintained by the SEE Lab at University of Vermont