Skip to content

LCIA Methods

VoLCA computes environmental impacts by applying characterization factors from LCIA methods to inventory flows. Methods are loaded separately from databases, so you can mix and match.

VoLCA reads four method formats, the same four it exports:

  • ILCD method package – a ZIP archive or a directory of XML files structured per the ILCD data format spec (used by GreenDelta’s openLCA and SimaPro)
  • SimaPro method CSV – a single .csv file, the {methods} export SimaPro itself reads
  • Columnar method CSV – a single .csv file, one column per impact category
  • openLCA JSON-LD – an ImpactCategory .json document

Common method packages:

  • EF 3.1 / EF 3.0 – European Commission PEF methods (available from European Commission)
  • ReCiPe 2016 – Midpoint and endpoint methods
  • CML 2002 – Classic midpoint method
  • IPCC 2021 – Climate change characterization
Section titled “Via config file (recommended for production)”
[[methods]]
name = "EF3.1"
path = "/data/EF3.1" # directory or .zip of ILCD method XML files
active = true # default true; set false to keep it unloaded

Upload a ZIP or directory once, then it persists across restarts:

Terminal window
volca --config volca.toml method upload /data/EF3.1.zip --name "EF3.1"
Terminal window
# List loaded methods
curl http://localhost:8080/api/v1/methods
# List method collections
curl http://localhost:8080/api/v1/method-collections

Any loaded collection can be exported to any of four formats, whatever format it was imported from. A method loaded from an ILCD package (for example the Environmental Footprint 3.1 reference package) can be handed to a SimaPro user as one .csv file carrying its impact categories, and its single scores as damage categories and normalization-weighting sets wherever the format can hold them. A single score SimaPro cannot express is left out, and the export says which one and why.

FormatKeywordFile
SimaPro method CSVsimaproone .csv
Columnar CSVcsvone .csv, one column per impact category
openLCA JSON-LDopenlcaa .zip, one ImpactCategory per method
ILCD packageilcda .zip, lciamethods/ plus the flows/ it needs
  • Web UI: the Export button on the collection’s card in the Methods page opens a menu of the four.
  • CLI: volca method export NAME --format simapro --out method.csv
  • API: POST /api/v1/method-collections/{name}/export with body {"format": "simapro"} – the response body is the file itself.

How much survives depends on the format. openLCA and ILCD carry UUIDs, direction and location natively, so a collection round-trips through them unchanged. The two CSV formats have no place for a region, so a regionalized factor is written the way SimaPro method files write it (a name-suffixed substance per region, like Water, FR), and land occupation/transformation factors are filed under the Raw compartment.

Anything the chosen format cannot carry is reported in export warnings (shown in the UI and CLI, and sent in the X-Volca-Export-Warnings response header), never dropped silently: a factor without a compartment, per-factor units in ILCD, a scoring set in any format but SimaPro, and in SimaPro a set it cannot hold (a display multiplier, a damage that is not a sum of categories times coefficients, a weight on a category a damage groups, a score other than the sum of the weighted damages).

A collection’s page lists its impact categories, and for each says what it holds without listing its factors: how many factors each medium holds, how many are written for a location and for how many locations (and how many carry the location at the end of their name, as a SimaPro file writes Ammonia, FR), how many are zero, how many are pattern or exclusion rows, which select flows rather than name one, and how many are duplicates, factors one key answers to at one place, listed below the table. Places are read the way the comparison below reads them.

A category’s factor list filters on the same reading: pick a medium or a location and the list keeps the factors the profile counted there, a location read at the end of a name included.

  • API: GET /api/v1/method-collections/{name}/profile
  • Python and assistants: profile_method_collection

Two loaded collections can be compared factor by factor, for example two releases of one method, or one method as two tools publish it. Nothing is scored: the comparison reads the factors themselves.

The engine pairs the impact categories first, by name, then by impact category. Inside each pair it pairs the factors at the same direction, compartment and location: by flow identifier, then by name, then by synonym, then by CAS number, then by pattern. A factor that states no location but ends its name with a code of the geographies table is read at that location, so Ammonia, FR in a SimaPro file meets ammonia at FR in an ILCD package; a name ending in anything else, like Methane, fossil, is kept whole. A factor whose name starts with Occupation, or Transformation, and that is filed under the whole natural resource medium (Raw in a SimaPro file) is read in its land subcompartment, and every land factor as taken from nature, whether its file writes it as an input or an output. Two places that an if_absent row of the compartment table links are read as one when each collection writes one of them and never the other: an ILCD package files the long-term emissions to air at unspecified (long-term) and a SimaPro file at low. pop., long-term, so their factors pair, each shown at its compartment as written. A collection that writes both places keeps them apart. Each pair says which of the five ways above paired it, and each changed factor gives both values and their ratio once both are read per one unit. A factor that went from zero to a value has no ratio and says so. A key that names several factors on one side pairs none of them: they are listed as ambiguous, never guessed. So is a name whose two factors carry different CAS numbers when either number names another factor: a file that writes paraquat dichloride under the name paraquat, and the paraquat ion under its chemical name, is listed as one group of four with the Paraquat and the Paraquat dichloride of the other side, each with its value.

Categories whose names differ between the two collections stay unpaired until you pair them yourself, which is common between two formats.

  • Web UI: on a collection’s page, “Compare with another collection”. Pick the other collection; an unpaired category offers the categories it can be paired with, and choosing one compares again. Click a category to see its factors: filter them by kind of change, search them by substance, and show them 500 at a time. Download every factor as a CSV.
  • API: GET /api/v1/method-collections/{name}/compare?other_collection=OTHER, with pairs=base=other once per pair you choose, an optional limit on each list of factors, and category=NAME to compare only the pair starting from that base category, much faster than comparing them all.
  • Python and assistants: compare_method_collections.

A published method is never changed in place: copy it, change the copy, and compare the copy with the original to see exactly what moved. The copy is loaded at once and scores as its source did.

A collection the configuration declares, or one built into the engine, is copied with what the configuration added to its files (patches, global-methods, scoring), so the copy holds what the collection held. A copy of an uploaded collection, or of another copy, takes its source’s changes along and can undo them like its own.

Each change is one line appended to a journal (journal.jsonl) beside the copy’s files, which are never rewritten: loading the copy reads the files again and replays the journal over them. A line records the value it replaced, so a source file that no longer holds what a line changed stops the load, naming the line, rather than replaying it over something else.

A copy’s categories change the same way. A new category starts with no factor, its impact category being its name unless another is given. A rename carries along the scoring sets and the unregionalized categories that named the category, in the same line, so they keep scoring it. A removal records the category whole, factors included, so its undo puts it back where it was.

A copy’s scoring sets change too, read as the rows of a guided grouping: a row adds up categories, each times a coefficient, under a label, divided by a normalization and times a weight. A row with a weight joins the score that adds up the rows (the Single score a new set starts with); a score written another way is left as it is. A row a SimaPro file divides by 0 is counted as zero, and reads so. A set made, renamed or given another unit, and a row added, changed or removed, are each one line, undone at once, so a set a SimaPro file translates comes back exactly as it was read. A row that computes something, and a score, can also be given a formula of their own, which reads the set’s names (a category, or another row); a formula naming nothing the set holds, or reading itself through another row, is refused.

Undoing a change writes its inverse as a new line rather than erasing one, so the history keeps every step. Some changes are refused, each with a sentence saying why:

  • two factors written identically at one place cannot be changed one at a time, only together through a selector, and a value that would make a factor identical to another is refused before it is written;

  • a category name already in use is refused, and so is removing a category a scoring set weighs, naming the set;

  • a normalization of zero, a row labelled like another one in its set, and a row removed while a score reads it other than as the sum of the rows are refused;

  • an undo is refused when a later line changed the same factor or category since, naming that line so it can be undone first;

  • a copy reads its source’s files where they lie, so the collection holding them cannot be deleted while a copy exists. A copy of a copy reads the first source’s files, so the copy in between can be deleted;

  • a read-only engine changes nothing.

  • Web UI: a collection from the configuration says “Copy to edit” on a category’s factor list, and its card in the Methods page has a Copy button. On a copy, each factor has Edit and Remove, and “Add a factor” searches the flows the collection characterizes, or those of a loaded database. A factor can also be changed from a comparison, in the list of a compared category. The collection’s Overview has “Add a category” under its categories, and a Remove on each, which asks to confirm; a category’s factor list has Rename and Change unit beside its count. The Scoring tab shows each scoring set’s rows, with Rename, Change unit and Remove on the set, Edit and Remove on each row, and “Add a row”, which picks categories by their names. Formula, on a row and on a score, writes a formula and offers the names that match the word being typed. Each row and score shows its value on the activity last opened. The collection’s History tab lists the changes in sentences, an undone one struck through, with “Undo last change”.

  • API: POST /api/v1/method-collections/{name}/copy/{newName}, then POST /api/v1/method-collections/{name}/factors with op set to set, remove or add for one factor, scale or set-all for every factor a selector reaches, POST /api/v1/method-collections/{name}/categories with op set to add, rename, set-unit or remove, GET and POST /api/v1/method-collections/{name}/scoring-sets (op set to create, rename, set-unit, remove, add-row, change-row, remove-row, among others), POST /api/v1/method-collections/{name}/undo (with line=N to undo a given line, and undoing an undo line redoes its change) and GET /api/v1/method-collections/{name}/history.

  • Python: copy_method_collection, set_method_factor, remove_method_factor, add_method_factor, scale_method_factors, set_method_factors, add_method_category, rename_method_category, set_method_category_unit, remove_method_category, scoring_sets, create_scoring_set, add_scoring_row, change_scoring_row, remove_scoring_row and the other scoring set methods, undo_method_edit, method_history.

  • Assistants: copy_method_collection, edit_method_factors, edit_method_categories, list_scoring_sets, edit_scoring_sets, undo_method_edit, get_method_history.

Terminal window
# Flat list of all characterization methods
volca --config volca.toml methods
# Or via CLI
volca --config volca.toml --format table methods

Each method has a UUID that you pass to impacts and flow-mapping commands.

Terminal window
# Single method
volca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID>
# Export to CSV
volca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID> --csv scores.csv

The web interface sets a few processes side by side, one small chart per impact category and one bar per process, each process in a colour of its own: there are as many places as colours, and a full comparison says so. The processes can come from different loaded databases: each is scored with the same method collection, at its database’s default parameter values.

On a process’s page, Compare, under the other analyses, opens the comparison with that process; Add a process then picks the others. Hosted, the Equivalents analysis also lets you tick candidates and compare them with the process you started from.

The scores are shown per one unit you choose, 1 kg for instance. A process whose product is counted in tonnes is converted, and its line says “counted in t, shown per kg”. A process counted in litres measures something else: it is set apart with that reason and draws no bar, and its unit stays offered, so choosing it compares the processes counted in volume instead.

The comparison lives in its address, so it can be bookmarked or shared: /compare-impacts?process=<database>/<process>&process=<database>/<process>&collection=<collection>&unit=kg. On the shared engine, comparing needs a free account.

Before running LCIA, verify how well the method maps to your database flows:

Terminal window
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID>

This shows:

  • Total characterization factors
  • How many are matched (and by what strategy: UUID, CAS, name, or synonym)
  • How many are unmatched
  • How many database flows are uncharacterized
Terminal window
# See which database flows each CF reaches, and how
volca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID> --matched

When VoLCA matches a characterization factor to a database flow, it tries in order; the first hit wins:

  1. UUID – exact elementary-flow UUID match
  2. CAS – CAS-number match (compartment-aware)
  3. Name – normalized-name match (compartment-aware)
  4. Synonym – name matched via loaded flow synonym sets
  5. Unmatched – no match found; the flow stays uncharacterized and won’t contribute to the score

Low matching rates are normal for some method/database combinations. The summary flow-mapping prints lists exactly which characterization factors found no flow. See Flow Mapping for the full cascade and Flow Mapping Audit for closing gaps.

Find which flows drive an impact the most:

Terminal window
volca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID>
# Result includes top contributing flows per category

Via API:

GET /api/v1/db/{db}/activity/{id}/contributing-flows/{collection}/{methodId}?limit=10
GET /api/v1/db/{db}/activity/{id}/contributing-activities/{collection}/{methodId}?limit=10

A single score of a scoring set breaks down the same way, under score/{set}/{score} in place of {methodId}. Every activity’s parts add up to the score. A score whose formula is not a weighted sum of its indicators has no such parts and is refused. An assistant asks the same through the MCP tools get_score_contributing_flows and get_score_contributing_activities.

Every contributing flow of an indicator carries matchKind, a short name for how the engine found its factor. A single score weighs several factors into one, so its flows carry none, and their factor is what one unit of the flow adds to the score. When that is not enough, ask for the whole story on one flow:

GET /api/v1/db/{db}/method/{methodId}/explain-cf/{flowId}

It answers in sentences the engine writes itself, names the line of the method that supplied the factor, and lists the steps it walked before that one. See Flow mapping for what each step means.