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 4-step cascade.

The matching cascade

For each characterization factor in a method, VoLCA attempts to match it to database flows in this order:

Step	Strategy	Example
1	Exact name + exact compartment	`"Carbon dioxide, fossil"` + `"air/unspecified"`
2	Synonym match	`"CO2"` → `"Carbon dioxide, fossil"` via synonym set
3	Compartment fallback	Name matches, compartment generalized (e.g. `"air, high pop."` → `"air"`)
4	Unmatched	No match — factor contributes 0

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 (provided with VoLCA for common database/method combinations)
Upload a custom CSV synonym set

# Upload a custom synonym set
volca --config volca.toml method upload synonyms.csv --name "my-synonyms"

Format: a CSV with name_in_db,canonical_name columns.

Cross-database flow linking

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

[[databases]]
name = "agribalyse"
format = "simapro"
path = "/data/agribalyse4.csv"
load = true
depends_on = ["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": "..." } }