Skip to content
VoLCA Docs

Core concepts

VoLCA is one LCA engine with several ways to use it: browser UI, desktop app, HTTP API, Python client, CLI, REPL, and MCP. The same concepts appear through each entry point, so it helps to learn the model once before choosing a tool.

This page gives the high-level map. When you need to build a decomposition, contribution, inventory, or substitution workflow, continue with Supply chain and inventory concepts.

The basic objects

Section titled “The basic objects”

Database

Section titled “Database”

A database is a loaded LCA dataset such as Agribalyse, ecoinvent, or a custom import. Most queries happen inside one selected database.

Typical operations:

  • list loaded databases;
  • load or unload a database;
  • search activities and flows inside a database;
  • compute inventories or impacts for one activity.

Activity

Section titled “Activity”

An activity is the process record you usually start from: for example a crop production, transformation process, transport step, electricity mix, or waste treatment activity.

An activity has:

  • a name;
  • a location;
  • one or more product outputs;
  • direct exchanges;
  • classifications, when available from the source database.

Product and process_id

Section titled “Product and process_id”

In VoLCA, the identifier you pass around is usually a process_id in this form:

activityUUID_productUUID

This matters because one activity can have several products or co-products. The process_id identifies not only the activity record, but also the reference product context you want to study.

Flow

Section titled “Flow”

A flow is something exchanged by an activity.

There are two broad families:

  • Technosphere flows: products or services exchanged between activities, such as wheat, electricity, transport, heat, packaging, or waste treatment.
  • Biosphere flows: elementary flows exchanged with the environment, such as CO₂ emissions, methane, water withdrawal, land occupation, or mineral resource extraction.

Technosphere graph

Section titled “Technosphere graph”

Technosphere exchanges form a graph:

root activity R (consumer)
        ▲
        │ edge: A supplies R
activity A (supplier of R, consumer of B)
        ▲
        │ edge: B supplies A
activity B (supplier of A)

In that graph:

  • an activity is a node;
  • an edge is a direct supplier → consumer relationship, so the arrow points upward from supplier to consumer in this diagram;
  • a path is a route through several connected edges, for example B → A → R in supplier-to-consumer direction, or R ← A ← B when tracing upstream from the root.

Edges and paths help explain the structure of the technosphere. They are different from inventory rows, which are cumulative biosphere flows after the system has been solved.

Direct data versus calculated results

Section titled “Direct data versus calculated results”

A common source of confusion is mixing what is directly stored on one activity with what is calculated after solving the supply chain.

Direct activity detail

Section titled “Direct activity detail”

Activity detail answers:

What does this activity record directly contain?

It includes the activity’s direct inputs, outputs, co-products, and direct biosphere exchanges. This is the right level when you want to inspect how a dataset author modelled one process.

Supply chain

Section titled “Supply chain”

Supply-chain results answer:

Which upstream activities are needed for the selected functional unit, and in what quantities?

This is calculated by solving the technosphere system. It is not just a tree expansion of direct inputs: loops, shared suppliers, and database modelling choices are handled by the engine.

Inventory

Section titled “Inventory”

Inventory answers:

What are the cumulative elementary flows for the selected functional unit?

It is where cumulative emissions and resource uses appear.

Impacts

Section titled “Impacts”

Impact assessment answers:

What is the characterized result for an LCIA method or method collection?

Impacts are calculated by applying characterization factors to the inventory.

Which concept should I use?

Section titled “Which concept should I use?”
  • To find the right process: search activities.
  • To inspect the foreground model: use activity detail.
  • To understand upstream activities: use supply chain.
  • To explain how one upstream activity is reached: use paths.
  • To get cumulative emissions/resources: use inventory.
  • To get characterized scores: use impacts.
  • To replace one supplier with another: use substitutions.
  • To compare or summarize groups: use aggregation.

Same concepts, different entry points

Section titled “Same concepts, different entry points”

The entry points differ in ergonomics, not in meaning.

  • UI / Desktop: best for visual inspection and exploratory understanding.
  • HTTP API: best for applications, services, dashboards, and reproducible integrations.
  • Python client (pyvolca): best for notebooks, data analysis, pandas workflows, and Python automation. It is a client for the HTTP API.
  • CLI / REPL: best for terminal exploration, batch jobs, and scripts.
  • MCP: best when an AI assistant should query VoLCA through controlled tools.

Once you understand the concepts, you can move between entry points without changing the underlying interpretation.

Going deeper

Section titled “Going deeper”

For ordinary use, this page may be enough. For expert workflows — for example decomposing Agribalyse transformation processes, extracting parameters, tracing suppliers, or preparing counterfactual substitutions — read the next guide:

Supply chain and inventory concepts →