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.
Supported method formats
Section titled “Supported method formats”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
.csvfile, the{methods}export SimaPro itself reads - Columnar method CSV – a single
.csvfile, one column per impact category - openLCA JSON-LD – an
ImpactCategory.jsondocument
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
Loading a method
Section titled “Loading a method”Via config file (recommended for production)
Section titled “Via config file (recommended for production)”[[methods]]name = "EF3.1"path = "/data/EF3.1" # directory or .zip of ILCD method XML filesactive = true # default true; set false to keep it unloadedVia CLI upload
Section titled “Via CLI upload”Upload a ZIP or directory once, then it persists across restarts:
volca --config volca.toml method upload /data/EF3.1.zip --name "EF3.1"Via the API
Section titled “Via the API”# List loaded methodscurl http://localhost:8080/api/v1/methods
# List method collectionscurl http://localhost:8080/api/v1/method-collectionsExporting a method collection
Section titled “Exporting a method collection”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.
| Format | Keyword | File |
|---|---|---|
| SimaPro method CSV | simapro | one .csv |
| Columnar CSV | csv | one .csv, one column per impact category |
| openLCA JSON-LD | openlca | a .zip, one ImpactCategory per method |
| ILCD package | ilcd | a .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}/exportwith 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).
What a collection holds
Section titled “What a collection holds”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
Comparing two method collections
Section titled “Comparing two method collections”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, withpairs=base=otheronce per pair you choose, an optionallimiton each list of factors, andcategory=NAMEto compare only the pair starting from that base category, much faster than comparing them all. - Python and assistants:
compare_method_collections.
Changing a method collection
Section titled “Changing a method collection”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}, thenPOST /api/v1/method-collections/{name}/factorswithopset toset,removeoraddfor one factor,scaleorset-allfor every factor a selector reaches,POST /api/v1/method-collections/{name}/categorieswithopset toadd,rename,set-unitorremove,GETandPOST /api/v1/method-collections/{name}/scoring-sets(opset tocreate,rename,set-unit,remove,add-row,change-row,remove-row, among others),POST /api/v1/method-collections/{name}/undo(withline=Nto undo a given line, and undoing an undo line redoes its change) andGET /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_rowand 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.
Listing available methods
Section titled “Listing available methods”# Flat list of all characterization methodsvolca --config volca.toml methods
# Or via CLIvolca --config volca.toml --format table methodsEach method has a UUID that you pass to impacts and flow-mapping commands.
Computing LCIA scores
Section titled “Computing LCIA scores”# Single methodvolca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID>
# Export to CSVvolca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID> --csv scores.csvComparing the impacts of a few processes
Section titled “Comparing the impacts of a few processes”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.
Checking flow mapping coverage
Section titled “Checking flow mapping coverage”Before running LCIA, verify how well the method maps to your database flows:
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
# See which database flows each CF reaches, and howvolca --config volca.toml --db ecoinvent flow-mapping <METHOD_UUID> --matchedThe matching cascade
Section titled “The matching cascade”When VoLCA matches a characterization factor to a database flow, it tries in order; the first hit wins:
- UUID – exact elementary-flow UUID match
- CAS – CAS-number match (compartment-aware)
- Name – normalized-name match (compartment-aware)
- Synonym – name matched via loaded flow synonym sets
- 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.
Flow hotspot analysis
Section titled “Flow hotspot analysis”Find which flows drive an impact the most:
volca --config volca.toml --db ecoinvent impacts <PROCESS_ID> --method <METHOD_UUID># Result includes top contributing flows per categoryVia API:
GET /api/v1/db/{db}/activity/{id}/contributing-flows/{collection}/{methodId}?limit=10GET /api/v1/db/{db}/activity/{id}/contributing-activities/{collection}/{methodId}?limit=10A 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.