Flow Mapping

Flow mapping is the process of linking elementary flows in your LCA databases to characterization factors in your LCIA methods. Good mapping coverage is essential for accurate LCIA results.

Why mapping matters

Different databases and methods use different names for the same substance. For example, “Carbon dioxide, fossil” in EcoSpold 2 might be “CO2 (fossil)” in an ILCD method. VoLCA resolves these differences automatically through a matching cascade.

The matching cascade

For each characterization factor in a method, VoLCA tries to match it to a database flow in this order; the first hit wins, and the strategy that matched is recorded:

Step	Strategy	Description
1	UUID	exact elementary-flow UUID match
2	CAS	CAS-number match (compartment-aware)
3	Name	normalized-name match (compartment-aware)
4	Synonym	matched via a loaded synonym group (e.g. `"CO2"` ↔ `"Carbon dioxide, fossil"`)
—	Unmatched	none of the above hit — the flow stays uncharacterized and contributes nothing to the score

Checking coverage

# Summary: matched/unmatched counts and rates
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID>

# Detailed: which CFs matched and by what strategy
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID> --matched

# Gaps: CFs with no database match
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID> --unmatched

# Gaps: database flows with no characterization
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID> --uncharacterized

Improving coverage with flow synonyms

Flow synonym sets teach VoLCA how to translate flow names between systems. You can:

Use a pre-built synonym set (shipped with VoLCA for common database/method combinations)
Add a custom CSV synonym set

[[flow-synonyms]]
name = "my-synonyms"
path = "/data/my-synonyms.csv"
active = true

The CSV has a name1,name2 header — one synonym pair per row. A running server can also accept one at runtime through the web UI or POST /api/v1/flow-synonyms/upload.

Cross-database flow linking

When you have multiple databases loaded (e.g. ecoinvent + agribalyse), VoLCA can link flows between them using depends in the config:

[[databases]]
name = "agribalyse"
path = "/data/agribalyse4.csv"
load = true
depends = ["ecoinvent"]    # background flows resolved in ecoinvent

After loading, finalize the cross-database links:

# Via API
POST /api/v1/db/agribalyse/finalize

This resolves agribalyse’s background activities against ecoinvent, enabling full inventory computation across databases.

API endpoints

GET /api/v1/db/{db}/method/{methodId}/mapping          — coverage stats
GET /api/v1/db/{db}/method/{methodId}/flow-mapping     — per-flow mapping detail

MCP tools

{ "name": "get_flow_mapping", "arguments": { "database": "ecoinvent", "method_id": "..." } }