VoLCA

VoLCA is a Life Cycle Assessment engine that turns LCA databases into inspectable, queryable answers — fast.

It loads EcoSpold2, EcoSpold1, SimaPro CSV, and ILCD process databases, builds supply chain dependency trees, computes life cycle inventories using sparse matrix algebra, and applies characterization methods for impact assessment. Everything runs in-memory against your own data.

What It Does

Browse activities and flows across multiple databases
Explore supply chain trees, force-directed dependency graphs, and supply chain composition by sector classification
Compute life cycle inventories (LCI) and impact scores (LCIA) — single method or batch across a full collection
Normalize and weight LCIA results with Raw / Normalized / Weighted view toggle; compute a single-score in Pt when normalization-weighting data is available
Map method characterization factors to database flows with a 4-step cascade (UUID → CAS → name → synonym) and coverage statistics
Link databases across nomenclatures (e.g., a sector database referencing Agribalyse)
Upload databases and method collections via the web UI, without touching config files

Key Features

Multiple database formats: EcoSpold2 (.spold), EcoSpold1 (.xml), SimaPro CSV, ILCD process datasets
Archive support: Load databases directly from .zip, .7z, .gz, or .xz archives — no manual extraction
Cross-database linking: Resolve supplier references across databases, with configurable dependencies and topological load ordering
LCIA method collections: Load ILCD method packages (ZIP or directory), SimaPro method CSV exports, or tabular CSV from config or UI
Normalization and weighting: Batch LCIA computes normalized and weighted scores per category and a single aggregated score (Pt) when NW data is present in the method collection
Flow mapping engine: 4-step matching cascade (UUID → CAS → name → synonym) with per-strategy coverage statistics and inspection UI
Activity classifications: ISIC, CPC, and category fields parsed from EcoSpold1/2 and ILCD, with a Composition page showing supply chain breakdown by classification
Auto-extracted synonyms: Synonym pairs extracted automatically from loaded databases and method packages, available for toggling and download
Reference data management: Flow synonyms, compartment mappings, and unit definitions can be configured in TOML, uploaded via UI, or toggled independently
Web interface: Multi-page Elm app with search, tree view, graph view, inventory, LCIA, method management, composition, and reference data pages
Desktop application: Native Windows/Linux app — no installation or configuration needed
Fast cache: Per-database cache with automatic schema-based invalidation; large databases load in ~45s cold, ~2-3s cached
Optional access control: Single-code login with cookie-based session

Getting Started

Desktop Application (Recommended)

Download and run the installer for Windows or Linux from the releases page. The desktop app bundles the complete engine and opens a browser-based UI automatically.

Web Server

# Build (requires PETSc — see Building section)
./build.sh

# Start the server
volca --config volca.toml server --port 8080
# Open http://localhost:8080

Command Line

The CLI is a lightweight HTTP client that connects to a running server (~0.2s per command). Start the server once, then query it freely:

# Start server (loads databases into memory once)
volca --config volca.toml server --port 8080

# In another terminal — all commands talk to the server via HTTP
volca --config volca.toml activities --name "electricity" --geo "FR"
volca --config volca.toml --db agribalyse tree "12345678-..." --depth 3
volca --config volca.toml --db agribalyse lcia "12345678-..." --method METHOD_UUID

Interactive REPL

# Launch REPL (auto-starts the server if not running)
volca --config volca.toml repl

# Inside the REPL:
# volca> activities --name "wheat"
# volca> use agribalyse
# volca[agribalyse]> inventory UUID
# volca[agribalyse]> :format table
# volca[agribalyse]> lcia UUID --method METHOD_UUID
# volca[agribalyse]> :help
# volca[agribalyse]> :quit

Configuration

A TOML config file enables multi-database setups, method collections, and reference data:

[server]
port = 8080
host = "127.0.0.1"
password = "mysecret"          # optional — omit to disable auth

[[databases]]
name = "agribalyse-3.2"
displayName = "Agribalyse 3.2"
path = "DBs/AGB32_final.CSV"
description = "SimaPro CSV"
load = true

[[databases]]
name = "my-sector-db"
displayName = "Sector DB"
path = "DBs/sector.CSV"
depends = ["agribalyse-3.2"]   # loads agribalyse first, then links
load = true

[[methods]]
name = "EF-3.1"
path = "DBs/EF-v3.1.zip"      # ILCD method package (ZIP or directory)

# SimaPro method CSV exports and tabular CSV are also accepted:
# path = "DBs/EF3.1_methods.csv"

[[flow-synonyms]]
name = "Default flow synonyms"
path = "data/flows.csv"        # CSV with two columns: name1,name2
active = true

[[compartment-mappings]]
name = "Default compartment mapping"
path = "data/compartments.csv"
active = true

[[units]]
name = "Default units"
path = "data/units.csv"
active = true

The depends field ensures dependency databases load first and their flows are available for cross-database linking. Setting load = true on a database transitively loads all its dependencies. Reference data sections (flow-synonyms, compartment-mappings, units) can also be uploaded and toggled at runtime via the web UI.

Web Interface

Page	What it shows
Activities	Searchable list with name, geography, and product filters
Tree	Hierarchical upstream dependency view
Graph	Force-directed network with configurable cutoff
Inventory	Environmental flows split into Emissions and Resources
LCIA	Impact scores per category with method picker; Raw / Normalized / Weighted toggle; single-score footer when NW data is available
Composition	Supply chain breakdown by activity classification (ISIC/CPC/category)
Methods	Load, unload, upload, and inspect ILCD and SimaPro method collections
Flow Mapping	Per-method CF coverage: matched by UUID/CAS/name/synonym, unmapped list
Databases	Load, unload, upload, and configure cross-database links
Database Setup	Data path picker, dependency editor, linking diagnostics
Flow Synonyms	Manage synonym sets; browse groups, download auto-extracted pairs
Compartment Mappings	Manage compartment name mappings
Units	Manage unit definitions for dimensional analysis

REST API

All per-database resources are scoped under /api/v1/db/{name}/:

GET    /api/v1/db/{name}/activity/{id}                  Activity details
GET    /api/v1/db/{name}/activity/{id}/tree             Supply chain tree
GET    /api/v1/db/{name}/activity/{id}/inventory        Life cycle inventory
GET    /api/v1/db/{name}/activity/{id}/graph?cutoff=    Supply chain graph
GET    /api/v1/db/{name}/activity/{id}/supply-chain     Supply chain composition
GET    /api/v1/db/{name}/activity/{id}/lcia/{methodId}  LCIA score (single method)
GET    /api/v1/db/{name}/activity/{id}/lcia-batch/{col} LCIA batch (all categories, with optional NW scores and single-score)
GET    /api/v1/db/{name}/activities?name=&geo=&product= Search activities
GET    /api/v1/db/{name}/flows?q=&lang=                 Search flows
GET    /api/v1/db/{name}/flow/{flowId}                  Flow details
GET    /api/v1/db/{name}/flow/{flowId}/activities       Activities using a flow
GET    /api/v1/db/{name}/method/{id}/mapping            Mapping coverage stats
GET    /api/v1/db/{name}/method/{id}/flow-mapping       Per-flow mapping detail
GET    /api/v1/db                                       List databases and status
POST   /api/v1/db/upload                                Upload a database archive
POST   /api/v1/db/{name}/load                           Load a configured database
POST   /api/v1/db/{name}/finalize                       Finalize cross-DB linking
DELETE /api/v1/db/{name}                                Delete a database
GET    /api/v1/methods                                        List individual methods
GET    /api/v1/method/{id}                                    Method details
GET    /api/v1/method/{id}/factors                            Characterization factors
GET    /api/v1/method-collections                             List method collections
POST   /api/v1/method-collections/{name}/load                 Load a method collection
POST   /api/v1/method-collections/{name}/unload               Unload a method collection
POST   /api/v1/method-collections/upload                      Upload a method package
DELETE /api/v1/method-collections/{name}                      Delete a method collection
GET    /api/v1/flow-synonyms                                  List synonym sets
POST   /api/v1/flow-synonyms/{name}/load                      Activate a synonym set
POST   /api/v1/flow-synonyms/{name}/unload                    Deactivate a synonym set
GET    /api/v1/flow-synonyms/{name}/groups                    Browse synonym groups
GET    /api/v1/flow-synonyms/{name}/download                  Download synonym CSV
GET    /api/v1/compartment-mappings                           List compartment mappings
GET    /api/v1/units                                          List unit definitions
POST   /api/v1/auth                                           Login (returns session cookie)

The lcia-batch response includes per-category normalizedScore and weightedScore fields (when normalization-weighting data is present in the method collection), plus a singleScore sum in Pt.

MCP Server

VoLCA exposes an MCP (Model Context Protocol) endpoint at POST /mcp, making LCA data queryable by AI assistants (Claude, Cursor, etc.) natively.

Configure it in your MCP client:

{
  "mcpServers": {
    "volca": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Available tools:

Tool	Description
`list_databases`	List loaded databases
`search_activities`	Search by name, geography, or product
`search_flows`	Search biosphere flows
`get_activity`	Activity details and exchanges
`get_tree`	Supply chain tree with loop detection
`get_supply_chain`	Flat upstream activity list with quantities
`get_inventory`	LCI biosphere flows (top N by quantity)
`compute_lcia`	LCIA score for an activity and method
`list_methods`	List loaded impact assessment methods
`get_flow_mapping`	CF-to-flow mapping coverage for a method

Authentication uses the same password as the REST API.

CLI Commands

Global Options

Option	Description
`--config FILE`	TOML config file for multi-database setup
`--url URL`	Server URL (default: from config; or set `VOLCA_URL`)
`--password PWD`	Server password (or set `VOLCA_PASSWORD`)
`--db NAME`	Database name to query
`--format FORMAT`	Output format: `pretty` (default), `json`, `table`, `csv`
`--jsonpath PATH`	Field to extract for CSV output (e.g., `srResults`)
`--tree-depth N`	Maximum tree depth (default: 2)
`--no-cache`	Disable caching (for development)

Modes of Operation

# Start server (loads databases — run once)
volca --config volca.toml server --port 8080

# Single HTTP command (connects to running server, ~0.2s)
volca --config volca.toml [--db NAME] COMMAND [OPTIONS]

# Interactive REPL (auto-starts server if not running)
volca --config volca.toml repl

Search

volca activities --name "electricity" --geo "DE" --limit 10
volca activities --product "steel" --limit 10 --offset 20
volca flows --query "carbon dioxide" --limit 5

Analysis

# Activity details
volca activity "12345678-..."

# Supply chain tree
volca tree "12345678-..." --tree-depth 3

# Life cycle inventory
volca inventory "12345678-..."

# Impact assessment (--method takes a method UUID, not a file path)
volca lcia "12345678-..." --method METHOD_UUID

# Matrix export (Ecoinvent universal format — runs locally, not via HTTP)
volca export-matrices ./output_dir

Flow Mapping Diagnostics

# Summary: how well does a method match a database?
volca --db agribalyse mapping METHOD_UUID

# See every mapped CF with its match strategy (uuid/cas/name/synonym)
volca --db agribalyse mapping METHOD_UUID --matched

# List CFs that found no DB flow
volca --db agribalyse mapping METHOD_UUID --unmatched

# List DB biosphere flows with no CF
volca --db agribalyse mapping METHOD_UUID --uncharacterized

# Machine-readable output
volca --db agribalyse mapping METHOD_UUID --matched --format json

Database and Method Management

# List, upload, delete databases
volca database                                  # list (default)
volca database upload mydb.7z --name "My DB"    # upload
volca database delete my-db                     # delete

# List, upload, delete method collections
volca method                                    # list (default)
volca method upload EF-3.1.zip --name "EF 3.1"  # upload
volca method delete ef-31                        # delete

API and CLI Feature Matrix

Feature	REST API	CLI
Search
Search activities	`GET /db/{db}/activities?name=&geo=&product=`	`activities --name --geo --product`
Search flows	`GET /db/{db}/flows?q=&lang=`	`flows --query --lang`
Analysis
Activity details	`GET /db/{db}/activity/{id}`	`activity ID`
Supply chain tree	`GET /db/{db}/activity/{id}/tree`	`tree ID --depth N`
Supply chain graph	`GET /db/{db}/activity/{id}/graph?cutoff=`	—
Life cycle inventory	`GET /db/{db}/activity/{id}/inventory`	`inventory ID`
LCIA (single method)	`GET /db/{db}/activity/{id}/lcia/{methodId}`	`lcia ID --method METHOD_UUID`
LCIA batch	`GET /db/{db}/activity/{id}/lcia-batch/{col}`	—
Flow details	`GET /db/{db}/flow/{flowId}`	`flow FLOW_ID`
Flow activities	`GET /db/{db}/flow/{flowId}/activities`	`flow FLOW_ID activities`
Flow Mapping
Mapping coverage	`GET /db/{db}/method/{id}/mapping`	`mapping METHOD_UUID`
Per-flow mapping	`GET /db/{db}/method/{id}/flow-mapping`	`mapping METHOD_UUID --matched`
Unmatched CFs	included in mapping response	`mapping METHOD_UUID --unmatched`
Uncharacterized flows	—	`mapping METHOD_UUID --uncharacterized`
Database Management
List databases	`GET /db`	`database`
Upload database	`POST /db/upload`	`database upload FILE --name NAME`
Load database	`POST /db/{name}/load`	— (use config `load = true`)
Delete database	`DELETE /db/{name}`	`database delete NAME`
Finalize linking	`POST /db/{name}/finalize`	—
Method Management
List methods	`GET /methods`	`methods`
Method details	`GET /method/{id}`	—
Method factors	`GET /method/{id}/factors`	—
List collections	`GET /method-collections`	`method`
Upload collection	`POST /method-collections/upload`	`method upload FILE --name NAME`
Delete collection	`DELETE /method-collections/{name}`	`method delete NAME`
Reference Data
Flow synonyms	`GET /flow-synonyms`	`synonyms`
Compartment mappings	`GET /compartment-mappings`	`compartment-mappings`
Units	`GET /units`	`units`
Matrix Export
Universal format	—	`export-matrices DIR` (local only)
Debug matrices	—	`debug-matrices ID --output FILE` (local only)
Auth
Login	`POST /auth`	—

All API routes are prefixed with /api/v1/. A dash (—) means the feature is only available in one interface.

Building

Linux / macOS

Install the MUMPS sparse solver and other dependencies, then build:

# Debian/Ubuntu
sudo apt install build-essential python3 curl zlib1g-dev libmumps-seq-dev nodejs npm

# macOS
brew install gcc python3 curl node mumps

# Fedora
sudo dnf install gcc gcc-c++ make python3 curl zlib-devel MUMPS-devel nodejs npm

# Arch Linux
sudo pacman -S base-devel python curl zlib mumps nodejs npm

Install the Haskell toolchain via GHCup, then:

./build.sh              # Build backend + frontend
./build.sh --test       # Build and run tests
./build.sh --desktop    # Build desktop application

Windows (MSYS2)

Install MSYS2 and open the "MSYS2 UCRT64" terminal

Install dependencies:

pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-mumps make python git

Install GHCup for the compiler toolchain

Run:

./build.sh            # Same script as Linux/macOS
./build.sh --desktop  # Builds Windows installer (.exe)

Docker

docker build -t volca .
docker run -p 8080:8080 -v /path/to/data:/data volca

Performance

Databases are loaded entirely into memory. A schema-aware cache (.bin.zst per database, stored in cache/) makes subsequent startups fast. Once the server is running, CLI commands complete in ~0.2s.

Database	Cold load	Cached load
Large database (25k activities)	~45s	~2-3s
Small sector database	~2s	<0.5s

Matrix solving uses MUMPS_SEQ sparse LU factorization. Inventory computation for a typical supply chain takes under 15 seconds on a large database.

Testing

./build.sh --test

# Or manually
cabal test --test-show-details=streaming

Tests cover matrix construction (sign convention), inventory calculation (golden values), parsers (EcoSpold1/2, ILCD, SimaPro, classification fields), and matrix export format compliance.

License

GNU Affero General Public License 3.0 or later — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 589 Commits
app		app
data		data
desktop		desktop
mumps-hs		mumps-hs
petsc-hs		petsc-hs
plugins/examples		plugins/examples
pyvolca		pyvolca
src		src
test-data		test-data
test		test
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bench.sh		bench.sh
build-mumps.sh		build-mumps.sh
build-petsc.sh		build-petsc.sh
build.sh		build.sh
cabal.project		cabal.project
cabal.project.local.example		cabal.project.local.example
docker-build.sh		docker-build.sh
docker-entrypoint.sh		docker-entrypoint.sh
expected_results.sh		expected_results.sh
gen-cabal-config.sh		gen-cabal-config.sh
gen-version.sh		gen-version.sh
hie.yaml		hie.yaml
lib.sh		lib.sh
petsc.env		petsc.env
release.sh		release.sh
rts-flags.sh		rts-flags.sh
versions.env		versions.env
volca.cabal		volca.cabal
volca.sh		volca.sh
volca.toml		volca.toml
worktree-build.sh		worktree-build.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

VoLCA

What It Does

Key Features

Getting Started

Desktop Application (Recommended)

Web Server

Command Line

Interactive REPL

Configuration

Web Interface

REST API

MCP Server

CLI Commands

Global Options

Modes of Operation

Search

Analysis

Flow Mapping Diagnostics

Database and Method Management

API and CLI Feature Matrix

Building

Linux / macOS

Windows (MSYS2)

Docker

Performance

Testing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

VoLCA

What It Does

Key Features

Getting Started

Desktop Application (Recommended)

Web Server

Command Line

Interactive REPL

Configuration

Web Interface

REST API

MCP Server

CLI Commands

Global Options

Modes of Operation

Search

Analysis

Flow Mapping Diagnostics

Database and Method Management

API and CLI Feature Matrix

Building

Linux / macOS

Windows (MSYS2)

Docker

Performance

Testing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages