carculator_utils

Shared physics, parameter handling, background systems, inventories and export machinery for the carculator vehicle models.

Developed at the Paul Scherrer Institute. This checkout prepares the unpublished release 1.3.7; see CHANGELOG.md for release status and changes.

Installation

Use Python 3.12 (>=3.12,<3.13) and a fresh environment. The shared runtime requires NumPy >=1.26.4,<2.

python3.12 -m venv .venv
source .venv/bin/activate

On Windows, activate with .venv\Scripts\activate. After publication, install this release from PyPI:

python -m pip install "carculator_utils==1.3.7"

Before publication, use the matching source checkouts as described under development. Core calculations use bundled resources and need no Brightway project, ecoinvent installation or network access. Brightpath supplies Brightway Excel, SimaPro CSV and openLCA JSON-LD export as a runtime dependency. To select the tested legacy Brightway stack:

python -m pip install "carculator_utils[excel,brightway]==1.3.7"

The Brightway extra supports the legacy stack (bw2io<0.9, bw2data<4, bw2calc<2). Exports default to ecoinvent 3.12 cutoff; importing them requires that background database in the destination tool. Legacy 3.9/3.10 targets reject newly introduced suppliers without a reviewed backward mapping. openLCA export currently supplies foreground processes and requires manual background/elementary-flow linking before calculation. See the export guide for examples and compatibility details.

Vehicle packages

Quick start

from carculator_utils.background_systems import BackgroundSystemModel

background = BackgroundSystemModel()
print(sorted(background.fuel_specs))

This shared package has no standalone default vehicle. Choose a vehicle package from the family table below for complete model/LCIA runs.

Modelling and validation

For a guided explanation of the inputs, units and assumptions, read Understanding inputs and results. The validation examples include bar charts, source records and the limits of each comparison. Measured energy comparisons are separate from the model-to-model comparison of the background database update.

The bundled A matrix and all 57 B matrices were rebuilt with premise 2.5.4 and ecoinvent 3.12 cutoff. B contains precomputed LCIA coefficients. See the rebuild and validation guide for scenarios, reproducible scripts and source hashes. The former NMC-523 option is now NMC-532, using the actual 5:3:2 chemistry; update custom chemistry selections.

Explicit battery unit prices now survive chemistry selection and cost adjustment. Use battery_costs for scoped prices, including zero or values equal to packaged defaults; see battery-cost inputs and precedence.

The vehicle models include tabulated 2025 parameters and documented temporal extensions. These combine engineering assumptions and selected calibration evidence; they are not independent measurements for every vehicle configuration.

TtW energy is in kJ/km. For BEVs it is net stored-energy depletion; model.battery_terminal_energy reports terminal DC separately, while electricity consumption is grid electricity in kWh/km. Identify the measurement boundary before comparing energy outputs. Availability-masked zeroes do not represent physically zero consumption.

Supported background scenarios are SSP2-NPi, SSP2-PkBudg1000, SSP2-PkBudg650, and static. ReCiPe supports midpoint/endpoint and EF midpoint. Use fresh model instances for independent cases. inputs.stochastic(n, seed=...) seeds parameter draws and the projected-cost factors used by the current array builder. Keep its auxiliary sample coordinates; older hand-built arrays do not recover that seed automatically.

See validation and limitations, migration notes and the documentation.

Development and release

Use matching sibling checkouts, especially carculator_utils 1.3.7 or newer:

python -m pip install -e ".[test,docs,excel,brightway]"
python -m pip check
python -m pytest
python -m sphinx -b html docs docs/_build/html

The docs extra includes the extensions used by this repository. See RELEASING.md for artifact verification, release order and publication.

Support and license

Contact carculator@psi.ch or open an issue. Maintained by Romain Sacchi, with contributions from the carculator development team. See contributing. Licensed under BSD-3-Clause.