MApper

MApper is a desktop application that integrates Life Cycle Assessment (LCA), Dynamic Stock Modelling / Material Flow Analysis (DSM/MFA), prospective LCA (pLCA), and Absolute Environmental Sustainability Assessment (AESA) in one workflow. It is built for researchers who need to evaluate the environmental impact of evolving material systems over time and against planetary boundaries.

Website: mapper.leonardoferhati.com

---

Why MApper

These four methods are usually run in separate tools, by hand, with brittle data hand-offs between them. The integration is where the scientific value sits — and where the work disappears today.

• LCA tells you the impact of a product.
• DSM/MFA tells you how a stock of products and its material flows evolve over time.
• pLCA tells you how background impacts shift under future energy scenarios.
• AESA tells you whether the resulting impact is absolutely sustainable — i.e. within a fair share of planetary boundaries.

MApper couples all four in one cohort-preserving pipeline: a time-resolved material flow feeds time-matched prospective inventories, which produce year-by-year impacts, which are assessed against an assigned fair share of the planetary boundaries (Sustainability Ratios). One model, one data path, no manual stitching — every product cohort keeps its identity (fuel type, size, birth year) from LCA → pLCA → DSM/MFA → AESA. That four-method integration is MApper's reason to exist.

Reference study: the Danish passenger-car fleet, 2025–2050 — a full LCA → prospective-LCA → DSM/MFA → AESA run on an evolving vehicle stock under SSP scenarios. MApper is general-purpose, though: the same pipeline applies to wind turbines, buildings, electronics, food systems, or any other evolving product system.

Features

• LCA Engine — Brightway2 integration with ecoinvent 3.10. Multi-method LCIA with contribution analysis, treemaps, and Sankey diagrams; multi-archetype comparison with per-stage breakdown. Results are addressed by the full method tuple, so indicators sharing a display name stay distinct everywhere — EF v3.1 has four indicators called "global warming potential (GWP100)".

• Uncertainty — Monte Carlo propagation — Over the background (technosphere, biosphere and characterisation factors, resampled by bw2calc each iteration), the foreground (BOM quantities and parameter expressions, resampled per iteration — parameters are drawn once and expressions re-resolved against the draw, so a shared driver stays correlated instead of averaging away), and per-row uncertainty scored with the pedigree matrix, with a reusable material pedigree library.

  Comparisons use paired sampling, and only paired sampling: one sampled world per iteration, every compared system solved against it, so a driver two systems share cancels in their difference instead of inflating it. Sampling the systems independently can report "not distinguishable" where the paired run finds a consistent difference.

• Authored databases (new in 0.3.1) — Create your own Brightway database inside MApper and author activities in it from biosphere flows: a process whose impact is its direct emissions, or a supplier's cradle-to-gate figure entered as one characterised value. Authored activities link into a Bill of Materials like any ecoinvent activity. Supporting this:

  • a compartment picker that groups biosphere flows by substance and shows, per compartment, what each method's characterisation factor actually is — choosing NOx to urban air versus high stacks is a decision, not a guess;
  • uncertainty discipline — every exchange is lognormal with all five pedigree scores required, its basic variance defaults to ecoinvent's median for that flow, and a GSD² below ecoinvent's median for the same flow must carry a written reason. You cannot silently claim your data is tighter than ecoinvent's;
  • an uncertainty basis per exchange, for the case where the amount is not an emission but someone else's characterised result. It asks for more than the default — a variance and its source — and the basis follows the number into every result and workbook, so a reader comparing two GSD² values is told when they describe different quantities.

• Dynamic Stock Modelling — Cohort-based stock dynamics with Weibull survival and system-level projections. Material flow quantification grouped by material, component, stage, or archetype. Named DSM scenarios, scaling rules and survival configurations; with dependency rules, so one stock can drive another (vehicles driving chargers).

What MApper does not claim

Two constraints are design decisions, and the software states them rather than papering over them.

Authored activities are biosphere-only in v1. You can specify elementary flows; you cannot give an authored activity a technosphere input. That is deliberate: a technosphere link would not be translated into a prospective background, so an authored activity would silently keep base-year electricity in every future year of a prospective run. An authored activity therefore reports the emissions you entered, and nothing about its supply chain.

A partial inventory's uncovered indicators are marked "not specified", never reported as zero. When you declare an authored activity partial, you also declare which indicators it is complete for. Every result and every workbook that used it marks the rest as unknown rather than reporting a number that would read as "no impact" — because a flow you did not enter is not a flow that does not exist. An AESA axis fed by such a result is hatched and its Sustainability Ratio is reported as a lower bound.

Architecture

• Frontend: React + Vite + TypeScript + Tailwind CSS
• Backend: FastAPI + Python 3.11
• LCA engine: Brightway2 + bw2calc with UMFPACK factorisation reuse — each premise db is factorised once and back-substituted for every subsequent solve. UMFPACK is bundled in the desktop build via mapper-desktop.spec, so the shipped app always gets this path: the Danish fleet case (3 LCI scenarios × 26 years × 25 indicators) completes in under a minute, down from ≈ 54 minutes. See DESKTOP.md → "UMFPACK in the frozen build"
• DSM engine: Cohort-based dynamic stock model with Weibull survival
• Prospective: premise 2.1.3
• Desktop packaging: Tauri v2

Download and install

The desktop installers are attached to each GitHub release. Download them from the latest release. They are not code-signed, which is why each platform has a one-time step below.

macOS (Apple silicon only)

1. Download MApper_<version>_aarch64.dmg from the latest release.

2. Open it and drag MApper to Applications.

3. Run this once in Terminal, so macOS lets the unsigned app open:

   xattr -dr com.apple.quarantine /Applications/MApper.app
   

Windows

1. Download MApper_<version>_x64-setup.exe from the latest release and run it.
2. If Windows SmartScreen shows a warning, click More info, then Run anyway.

Data you supply. The ecoinvent database and the IAM scenario data that premise uses for prospective databases are separately licensed and are not included. Import ecoinvent from inside the app (Database Explorer → Import); to try MApper without it, see Try it without ecoinvent.

The sparse solver differs by platform. The macOS build links UMFPACK through scikit-umfpack, so each prospective database is factorised once and reused for every later solve. The Windows build falls back to SciPy's SuperLU (conda-forge publishes no Windows build of scikit-umfpack). The results are the same to solver tolerance, but large sparse solves, such as prospective runs over many years, are slower on Windows.

To run MApper from source instead, see the Quickstart below.

Quickstart

Prerequisites

• Miniconda or Anaconda
• Node.js 18+
• An ecoinvent licence and the EcoSpold2 release of the version and system model you want (unzipped) — see Example: first analysis

Install & run

git clone https://github.com/leofrht-jpg/MApper-Software.git
cd MApper-Software

conda env create -f environment.yml   # pinned environment; the one CI uses
conda activate map

# macOS/Linux only — the sparse solver that makes prospective LCA fast.
# Not in environment.yml because conda-forge has no Windows build.
conda install -c conda-forge scikit-umfpack=0.3.3 suitesparse

( cd mapper-frontend && npm ci )

./start.sh        # starts backend (FastAPI) + frontend (Vite)

./setup.sh (or setup.bat on Windows) runs exactly these steps if you prefer one command. It will not modify an existing map environment — use ./setup.sh --force to recreate one.

Open http://localhost:5173.

Try it without ecoinvent

MApper works out of the box with no licence. ecoinvent is separately licensed and is never bundled, so a fresh install has no life-cycle inventory data. Rather than leave you with nothing to run, MApper ships a demo project built from synthetic data:

cd mapper-backend
python scripts/load_demo_project.py --verify

or, in the app, open Database Explorer and click "Load demo project (no licence needed)".

The first run takes about 10 seconds and needs ~150 MB of disk: it installs biosphere3 and 762 LCIA methods, which ship inside bw2io and carry no licence restriction. Re-running is a no-op (~2 s).

What the demo gives you — a 31-year (2020–2050) passenger-vehicle fleet with battery-electric and combustion cohorts, and everything downstream of it:

Step	What you can verify
DSM Modeller	Cohort-tracked stock, inflows and outflows over 31 years, Weibull survival
LCA Architect	Two bills of materials linked to the synthetic database
Impact Assessment	A real bw2calc solve — real elementary flows, real IPCC characterisation factors
AESA	Impact results downscaled against planetary boundaries

That covers the DSM → material flows → LCA → AESA integration, which is the part of MApper the paper argues is novel.

[!WARNING] Every number in the demo is fictional. The inventory is invented — chosen so charts have sensible proportions, and wrong. The LCA arithmetic is real; the data it consumes is not. A red banner stays on screen for as long as the demo project is active. Do not cite, publish or present any demo output as an environmental assessment.

The demo lives in its own Brightway2 project (MApper demo (synthetic data)) and touches nothing else. Delete that project to remove it.

What still needs a licence: a real assessment needs your own ecoinvent database, and prospective (premise) analysis needs both ecoinvent and a premise key. The demo covers neither — it demonstrates that the software works, not what any real system emits.

Example: first analysis

This is the workflow with a real ecoinvent licence. Without one, use Try it without ecoinvent above.

1. Import ecoinvent (~10 min). MApper reads an unzipped EcoSpold2 release from a folder; it cannot open a .7z or .zip file.

   • Download the EcoSpold2 release for the version and system model you want (for example 3.12 cut-off) from ecoinvent, and unzip or extract it first. The extracted folder must contain datasets/ and MasterData/.
   • Database Explorer → Import → Import from local files. Paste the full path to the datasets folder (the folder with the .spold files directly inside it), click Verify, keep or edit the proposed database name, and click Import.
   • Alternative: Log in with ecoinvent account downloads a release directly. It needs your own ecoinvent licence.

   Known limitation. The import installs no LCIA methods. EF, ReCiPe and CML are not available in a freshly imported project (they are installed only for the demo project). The Methods Library offers IMPACT World+ (including an ecoinvent 3.12 variant), LC-Impact and an Excel upload. Importing ecoinvent 3.12 follows the same code path as the other versions but has no automated test yet.

2. (Optional) pLCA Developer → generate prospective databases (requires a premise key).

3. LCA Architect → import or create archetypes (Bills of Materials).

4. DSM Modeller → upload stock + inflows data.

5. Impact Assessment → set cohort mappings → calculate.

6. (Optional) AESA → compare impacts against planetary boundaries.

Prospective LCA requires a premise encryption key. Email [email protected] for a key, then mkdir -p ~/.premise && echo 'YOUR_KEY' > ~/.premise/premise_key.

Full instructions are in INSTALL.md.

System requirements

	Minimum	Recommended
RAM	8 GB	16 GB
Disk	5 GB	15 GB (with prospective DBs)
OS	macOS 13+, Windows 10+, Ubuntu 22.04+
Python	3.11	3.11
Node.js	18	20+

Commercial use

MApper is free for everyone, including for commercial use, under the Mozilla Public License 2.0. You can use it in companies, consulting work, and commercial research without a fee. The MPL applies file-level copyleft: if you modify MApper's own source files and distribute them, those modified files must remain under MPL 2.0 — but you may combine MApper with proprietary code in a larger work.

For general inquiries: [email protected].

Contributing

Contributions are welcome and are accepted under MPL 2.0 with DTU as the copyright holder. Please read CONTRIBUTING.md and our Code of Conduct before opening a pull request. Security issues: see SECURITY.md.

Citation

If you use MApper in your research, please cite it. The DOI below is the Zenodo concept DOI: it always resolves to the latest archived release, so a citation using it stays valid as MApper is updated. A JOSS (Journal of Open Source Software) paper is in preparation.

@software{ferhati_mapper_2026,
  author    = {Ferhati, Leonardo},
  title     = {MApper: A unified platform for Life Cycle Assessment,
               Dynamic Stock Modelling, prospective LCA, and Absolute
               Environmental Sustainability Assessment},
  year       = {2026},
  publisher  = {Technical University of Denmark},
  url        = {https://mapper.leonardoferhati.com},
  doi        = {10.5281/zenodo.22246255},
  note       = {Archived on Zenodo; this DOI resolves to the latest release. JOSS paper in preparation}
}

The DOI is the concept DOI and needs no updating between releases. Add the JOSS citation alongside it once the paper is published.

Copyright and license

© Copyright 2026 Technical University of Denmark

• Copyright holder: Technical University of Denmark (DTU).
• Lead developer: Leonardo Ferhati.
• License: Mozilla Public License 2.0 (MPL-2.0). Full text in LICENSE.

MApper depends on third-party open-source software, each under its own license — see NOTICE and THIRD_PARTY_LICENSES.md. The ecoinvent database and IAM scenario data are separately licensed and are not distributed with MApper; users must supply their own licensed data.

Contact

• Project & commercial inquiries: [email protected]
• Website: mapper.leonardoferhati.com
• Developer: leonardoferhati.com