HESTIA Engine Models

HESTIA's set of models for running calculations or retrieving data using external datasets and internal lookups.

Documentation

Documentation for every model can be found in the HESTIA Guide.

Install

1. Install python 3.12 minimum
2. Install the module:

pip install hestia_earth.models

Usage

from hestia_earth.models.pooreNemecek2018 import run

cycle_data = {"@type": "Cycle", ...}
# cycle is a JSONLD node Cycle
result = run('no3ToGroundwaterSoilFlux', cycle_data)
print(result)

This will display only the result of the no3ToGroundwaterSoilFlux model (Emission).

Additionally, to reduce the number of queries to the HESTIA API and run the models faster, prefetching can be enabled:

from hestia_earth.models.preload_requests import enable_preload

enable_preload()

Using the orchestrator

The models come with an "orchestrator", which allows you to run a pre-configured set of models instead of a single one.

The configuration for each Node (Cycle, Site or ImpactAssessment) can be found in the config folder.

Usage:

from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config

cycle = {"@type": "Cycle", ...}
result = run(cycle, load_config(cycle))
print(result)

This will display the Cycle recalculated with all HESTIA default models running.

Using Spatial Models

We have models that can gap-fill geographical information on a Site. If you want to use these models:

1. Install the library: pip install hestia-earth-earth-engine
2. Follow the Getting Started instructions.

Disabling the standardised drought indices

The SPEI and SPI models run by default. Set the env variable ENABLE_DROUGHT_INDEX to false to turn them off.

They are fitted over a fixed climate reference period (1979-2020), so they also fetch precipitationMonthly and potentialEvapotranspirationMonthly over that period rather than over the Site's own years only - four decades of monthly values per Site. Turning them off restores the narrower window, which is the reason to do it on a self-hosted run.

Leaving spatial models out of the cache

The Site pre-check and cache_sites fetch the values of every geospatialDatabase model in one query, whether or not the model is in your config. Set the env variable GEOSPATIAL_EXCLUDED_MODELS to a comma-separated list of model keys (e.g. region) to leave those models out of the query, so a run without GADM does not query gadm36_1 for a model it does not run.

Collecting logs in JSON format

:info: This is an experimental feature and is not yet integrated in all the HESTIA tools.

To collect logs in JSON format:

1. Set the env variable LOG_JSON_ENABLED to true
2. Use the following code to collect contribution logs:

from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config
from hestia_earth.models.jlog import reset_collected_logs, get_collected_logs

# make sure the logs are reset before each run
reset_collected_logs()

# run the models as usual
impact = {"@type": "ImpactAssessment", ...}
result = run(impact, load_config(impact))
print(result)

# write the logs to a JSON file
logs = get_collected_logs()
with open("logs.json", "w") as f:
    f.write(to_string(logs, indent=2))

When a node is recalculated in separate passes (e.g. stage 1 then stage 2 in different processes), seed the later pass with the earlier one's logs so stage-1-only placements are not lost:

from hestia_earth.models.jlog import load_collected_logs, get_collected_logs

# stage 2: load the logs collected during stage 1, then run stage 2 as usual
load_collected_logs(stage1_logs)
result = run(impact, load_config(impact), stage=2)
logs = get_collected_logs()  # contains both stage 1 and stage 2

Collecting contribution data

:info: This is an experimental feature and is not yet integrated in all the HESTIA tools.

To collect contribution data of impacts/endpoints on ImpactAssessment:

1. Set the env variable LOG_CONTRIBUTION_ENABLED to true
2. Use the following code to collect contribution logs:

from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config
from hestia_earth.models.log_contribution import reset_contributions, get_contributions

# make sure the contributions are reset before each run
reset_contributions()

# run the models as usual
impact = {"@type": "ImpactAssessment", ...}
result = run(impact, load_config(impact))
print(result)

# write the contributions to a JSON file
contributions = get_contributions()
with open("contributions.json", "w") as f:
    f.write(to_string(contributions, indent=2))

The contribution data will store the factors used for each emissionsResourceUse that contributes to specific impacts, and likewise impacts that contribute to endpoints. The index in the data represents the index of the blank node in the list of contributing blank nodes.

Using the ecoinventV3 model

⚠️ This model has been deprecated and no further support will be provided.

ecoinvent is a consistent, transparent, and well validated life cycle inventory database. We use ecoinvent data to ascertain the environmental impacts of activities that occur outside of our system boundary, for example data on the environmental impacts of extracting oil and producing diesel, or the impacts of manufacturing plastics.

The ecoinventV3 model requires a valid license to run. We are currently working on a way to enable users of this code with a valid ecoinvent licence to run these models themselves, but for now, these models are only available on the public platform.

Amortising Land Use Change Emissions Using Linear Discounting

In compliance with Land Sector and Removals Standard & Guidance set by the Greenhouse Gas Protocol (2026), HESTIA amortises LUC emissions using linear discounting by default.

On the main HESTIA platform, we have chosen to amortise emissions using linear discounting, and this cannot be changed. The amortisation method can only be changed on the Community Edition.

For more information, see our guide page on linear discounting.

To opt-out of linear discounting on the Community Edition, and revert to amortising emissions using equal apportioning:

1. Set the env variable USE_LINEAR_DISCOUNTING to false

TypeScript / JavaScript package

The model metadata is also published to npm as @hestia-earth/engine-models:

npm install @hestia-earth/engine-models

It exposes the links between models, terms and their documentation (model-links.json), and the KaTeX formulas extracted from each model, with bindings that map every symbol to a value logged at runtime (the "jlog"):

import { getFormulas } from '@hestia-earth/engine-models';

getFormulas({ model: 'ipcc2019', term: 'ch4ToAirEntericFermentation' });
// => [ { formula: 'E_{CH4} = (GE \\times Y_m) / 55.65', bindings: [...] } ]

See formulas/README.md for the full guide on getting a model's formulas, rendering them with KaTeX, and substituting the symbols with the values from a given execution.