Metadata-Version: 2.4
Name: carculator_utils
Version: 1.3.7
Summary: Shared vehicle life cycle assessment calculations and inventories
Author-email: Romain Sacchi <romain.sacchi@psi.ch>
License: BSD 3-Clause License
        
        Copyright (c) 2020, Paul Scherrer Institut
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils
Project-URL: Documentation, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/tree/master/docs
Project-URL: Changelog, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: BSD License
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2,>=1.26.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: scipy>=1.11
Requires-Dist: xarray>=2024.1.0
Requires-Dist: numexpr
Requires-Dist: klausen
Requires-Dist: stats_arrays>=0.6
Requires-Dist: PyYAML
Requires-Dist: pyprind
Requires-Dist: pycountry
Requires-Dist: brightpath<1.1,>=1.0.0a6
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: hypothesis>=6; extra == "test"
Requires-Dist: openpyxl; extra == "test"
Requires-Dist: xlsxwriter; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-immaterial; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Provides-Extra: excel
Requires-Dist: xlsxwriter; extra == "excel"
Provides-Extra: brightway
Requires-Dist: bw2io<0.9,>=0.8.12; extra == "brightway"
Requires-Dist: bw2data<4,>=3.6; extra == "brightway"
Requires-Dist: bw2calc<2,>=1.8; extra == "brightway"
Dynamic: license-file

# carculator_utils

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

[![Installed artifacts](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/actions/workflows/main.yml)
[![PyPI](https://img.shields.io/pypi/v/carculator_utils)](https://pypi.org/project/carculator_utils/)

Developed at the [Paul Scherrer Institute](https://www.psi.ch/en).
This checkout prepares the unpublished release **1.3.7**; see [CHANGELOG.md](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/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`.

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

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

```bash
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:

```bash
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](docs/inventory_export.rst) for examples and compatibility details.

## Vehicle packages

| Package | Prepared version |
| --- | --- |
| `carculator_utils` | 1.3.7 |
| `carculator` | 1.9.7 |
| `carculator_truck` | 0.5.2 |
| `carculator_bus` | 0.1.2 |
| `carculator_two_wheeler` | 0.1.1 |

## Quick start

```python
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](docs/interpretation.rst). The
[validation examples](docs/validation_examples.rst) 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](docs/background_rebuild.rst) 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](docs/battery_costs.rst).

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](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/docs/validity.rst), [migration notes](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/docs/release.rst)
and the [documentation](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/tree/master/docs).

## Development and release

Use matching sibling checkouts, especially `carculator_utils` **1.3.7 or newer**:

```bash
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](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/RELEASING.md) for artifact verification, release order and publication.

## Support and license

Contact [carculator@psi.ch](mailto:carculator@psi.ch) or open an [issue](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/issues).
Maintained by [Romain Sacchi](https://github.com/romainsacchi), with contributions
from the carculator development team. See [contributing](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/CONTRIBUTING.md).
Licensed under [BSD-3-Clause](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_utils/blob/master/LICENSE).
