Supply chain and inventory concepts

VoLCA has several entry points, but they expose the same calculation model. Whether you use the browser UI, HTTP API, pyvolca, CLI, or MCP, the important distinction is between direct activity data, the resolved technosphere, and the cumulative biosphere inventory.

This page is the deeper companion to Core concepts. It is for users building analysis, extraction, contribution, or substitution workflows across real LCA databases, where similar processes may be authored through different modelling patterns.

From activity data to results

At a high level, VoLCA does this:

activity direct exchanges
        ↓ build technosphere matrix A and biosphere matrix B
solve (I - A) x = demand
        ↓
scaling vector x for the supply chain
        ↓
B x = cumulative life-cycle inventory
        ↓
characterization factors × inventory = LCIA results

The same root process_id can therefore be inspected at different levels:

• Activity detail: direct exchanges as stored on the activity record.
• Supply-chain entries: activities required after solving the system, with their scaling factors.
• Technosphere graph relationships: supplier → consumer links inside the resolved subgraph.
• Paths: one route through that graph from the root to a target activity.
• Inventory: cumulative elementary flows per functional unit.
• Impacts: characterized inventory for a method or method collection.

Activity detail: direct exchanges

Use activity detail when you need to inspect what a process directly declares.

Typical questions:

• What are the direct technosphere inputs?
• Which output is the reference product?
• Are there co-products?
• Are emissions or resources declared directly on this activity?
• Does a technosphere input link to another activity?

Important: activity detail is not the full upstream LCI. It is the foreground record for the selected activity.

Access points:

• UI: activity detail / direct exchanges panel.
• HTTP API: GET /api/v1/db/{db}/activity/{process_id}.
• Python: Client.get_activity(process_id).
• CLI: volca --db <db> activity <process_id>.
• MCP: activity/detail tool, when exposed by the connected server.

Supply-chain entries: solved activity amounts

Supply-chain entries come from the solved scaling vector x. Each entry represents an activity that is needed to satisfy the root demand.

Key fields:

• process_id: the activity/reference-product identifier.
• name, location, product, unit: descriptive fields for interpretation.
• scalingFactor: raw value from the solved scaling vector.
• quantity: physical amount for the root functional unit; in VoLCA this is the scaling factor multiplied by the root reference amount where applicable.
• depth: shortest graph distance from the root, useful for navigation but not a robust semantic classifier.

Use entries when you need cumulative activity-level quantities, such as “how much of this upstream electricity activity is needed for 1 kg of the root product?”.

Access points:

• HTTP API: GET /api/v1/db/{db}/activity/{process_id}/supply-chain.
• Python: Client.get_supply_chain(process_id, ...).
• MCP: supply-chain tool, when exposed.

Graph relationships: edges and paths

The resolved supply chain can be viewed as a technosphere graph. Activities are nodes. Direct supplier → consumer relationships are edges. A path is one connected route through several edges.

root consumer R
        ▲
        │ edge: A supplies R
consumer A / supplier A
        ▲
        │ edge: B supplies A
supplier B

edge direction: supplier → consumer
upstream trace from root: R ← A ← B

In API payloads, an edge is usually represented with fields such as:

• edgeFrom: supplier process_id.
• edgeTo: consumer process_id.
• edgeAmount: direct technosphere coefficient.

edgeAmount is a local coefficient: the amount of the supplier product required per unit of the consumer activity/reference product. It describes the direct relation between two activities, not the solved amount of the supplier for the root functional unit.

To attribute an edge relation to the root functional unit, combine the local coefficient with the solved scale of the consumer:

edge contribution for root FU ≈ edgeAmount × consumer.scalingFactor × root reference amount

Equivalently, if consumer.quantity is already expressed for the root functional unit in the unit you need:

edge contribution for root FU ≈ edgeAmount × consumer.quantity

Choose the expression that matches the units you are reporting. The important point is that raw edge coefficients are local ratios; cumulative activity amounts live on supply-chain entries.

Use graph relationships when you need to:

• see which consumer directly uses a supplier;
• explain why an upstream activity appears in the solved supply chain;
• trace routes from a root activity to a target activity;
• build substitution triplets.

Access points:

• HTTP API: GET /api/v1/db/{db}/activity/{process_id}/supply-chain?include-edges=true.
• Python: Client.get_supply_chain(process_id, include_edges=True, ...).
• Consumers direction: GET /api/v1/db/{db}/activity/{supplier_process_id}/consumers?include-edges=true or Client.get_consumers(..., include_edges=True).

Paths: routes through the graph

A path query returns one root → target route through the technosphere graph. It is useful when you want to inspect a relationship before turning it into a general rule.

Typical questions:

• How does this root process reach a given electricity activity?
• Which intermediate activity connects the root to a transformation step?
• Is the target a direct input, or does it appear through a deeper modelling pattern?

Access points:

• HTTP API: GET /api/v1/db/{db}/activity/{process_id}/path-to?target=<text>.
• Python: Client.get_path_to(process_id, target="...").
• MCP: path/supply-chain exploration tool, when exposed.

The path response includes cumulative quantities and local step ratios along one root → target route.

Inventory: cumulative biosphere flows

Inventory is computed after the technosphere has been solved and the biosphere matrix has been applied.

Use inventory when you need:

• cumulative emissions;
• cumulative resource extractions;
• a raw LCI before characterization;
• a check that a decomposition or substitution changes the expected elementary flows.

Access points:

• HTTP API: GET /api/v1/db/{db}/activity/{process_id}/inventory.
• Python: Client.get_inventory(process_id, ...).
• CLI: volca --db <db> inventory <process_id>.
• MCP: inventory tool, when exposed.

For summarized inventory views, use aggregation instead of manually grouping raw inventory rows:

• HTTP API: GET /api/v1/db/{db}/activity/{process_id}/aggregate?scope=biosphere&group_by=name.
• Python: Client.aggregate(process_id, scope="biosphere", group_by="name", ...).

Substitutions: replace a supplier in a specific consumer

A substitution identifies the exact direct supplier → consumer relationship to replace:

from     = original supplier process_id
to       = replacement supplier process_id
consumer = activity that directly consumes the original supplier

The consumer matters because the same supplier may appear in multiple places in the graph, with different modelling meanings.

Access points:

• HTTP API: POST substitution body to compatible endpoints such as supply-chain, inventory, and impacts.
• Python: pass substitutions=[{"from": ..., "to": ..., "consumer": ...}] to compatible methods.

Use substitutions when the goal is a counterfactual LCI/LCIA result. You usually do not need to reconstruct the whole inventory yourself; let VoLCA recompute it after the substitution.

Building extraction workflows

For workflows such as extracting transformation parameters from Agribalyse processes, avoid relying only on a fixed depth. Depth is useful for navigation, but it is not the concept you want to extract.

A robust workflow is usually:

1. Find the target activity by name, product, geography, classification, or a configured preset.
2. Inspect direct exchanges to see whether the transformation inventory is on the activity itself.
3. Use supply-chain entries and paths to detect wrapper or layered authoring patterns.
4. Classify roles semantically: raw material, electricity, heat, added water, waste, co-product, allocation-relevant outputs, etc.
5. Use entries for cumulative activity quantities.
6. Use graph relationships to explain local supplier → consumer links or to prepare substitutions.
7. Use inventory or impacts for biosphere/LCIA verification.

For an expert LCA user, the key design choice is the classification logic: decide which LCA patterns matter for your dataset, then use VoLCA endpoints to expose the evidence for each pattern.

Common pitfalls

• Do not interpret raw edgeAmount values as cumulative activity quantities.
• Do not assume the right max-depth is known in advance for all processes.
• Do not use depth as a substitute for semantic role detection.
• Use inventory or biosphere aggregation for cumulative emissions and resources.
• Do not build substitutions without the consumer; the same supplier may appear in multiple places with different meanings.
• Do not assume all Agribalyse transformations use the same authoring pattern.