Metadata-Version: 2.4
Name: carculator_bus
Version: 0.1.2
Summary: Prospective life cycle assessment of buses
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_bus
Project-URL: Documentation, https://carculator-bus.readthedocs.io/
Project-URL: Changelog, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_bus/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_bus/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: carculator_utils>=1.3.7
Requires-Dist: prettytable
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: sphinx-design; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Provides-Extra: excel
Requires-Dist: carculator_utils[excel]>=1.3.7; extra == "excel"
Provides-Extra: brightway
Requires-Dist: carculator_utils[brightway]>=1.3.7; extra == "brightway"
Dynamic: license-file

# carculator_bus

Prospective environmental and economic life cycle assessment of city buses and coaches, including depot, opportunity and in-motion charging.

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

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

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. The matching `carculator_utils` runtime installs
`brightpath>=1.0.0a6,<1.1` for Brightway Excel, SimaPro CSV and openLCA JSON-LD
exports. It uses Brightpath's v1 API, currently an alpha; model and LCIA
calculations do not import Brightpath or Brightway.

The `excel` extra remains a compatibility alias. To select the tested legacy
Brightway stack (`bw2io<0.9`, `bw2data<4`, `bw2calc<2`), use:

```bash
python -m pip install "carculator_bus[brightway]==0.1.2"
```

Brightpath also installs `bw2io` without that extra. Export targets ecoinvent
3.12 cut-off by default; legacy 3.9/3.10 targets reject suppliers without
verified older links. External suppliers must be matched to the corresponding
background in the destination tool. See [inventory export](docs/inventory_export.rst).

## Quick start

```python
from carculator_bus import (
    BusInputParameters,
    BusModel,
    InventoryBus,
    fill_xarray_from_input_parameters,
)

inputs = BusInputParameters()
inputs.static()
_, array = fill_xarray_from_input_parameters(
    inputs,
    scope={"size": ["13m-city"], "powertrain": ["ICEV-d", "BEV-depot"], "year": [2025]},
)
model = BusModel(array)
model.set_all()
print(model["TtW energy"])  # kJ per vehicle-kilometre

inventory = InventoryBus(model, functional_unit="pkm")
impacts = inventory.calculate_impacts()
print(impacts.sel(impact_category="climate change").sum("impact"))
```

Bus model cost outputs are already per passenger-kilometre; inventory normalization is a separate choice.

## Inventory export

With the completed `inventory` from the quick start:

```python
workbook = inventory.export_lci(software="brightway2", format="file", directory="exports")
simapro_csv = inventory.export_lci(software="simapro", format="file", directory="exports")
foreground_zip = inventory.export_lci(software="openlca", format="file", directory="exports")
```

Retain exactly one sample before constructing the model and inventory. Each year
gets its own export; multiple years return a list. Exports preserve the original
inventory and calculated impacts. The default `export_lci()` returns an unlinked
Brightway importer.

The openLCA ZIP contains foreground processes, without an ecoinvent background or
LCIA methods; map external providers and elementary flows before calculation.
SimaPro CSV uses Latin-1 and warns when omitting custom noise flows. See the
[export guide](docs/inventory_export.rst) for return types, sample selection and
format-specific limitations.

## 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.


Battery unit prices supplied by users now survive chemistry selection and cost
adjustment. Use `battery_costs` for explicit prices scoped by vehicle, year and
sample; see [battery-cost inputs](docs/usage.rst#battery-unit-costs).

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.

Charger-equipped buses deliberately include **at least one replacement battery**
over service life, even if cycling demand alone implies none. The initial pack
is additional. This is a fleet-life assumption, not a calibrated ageing model;
see [battery replacement accounting](docs/modeling.rst#current-battery-replacement-policy).

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_bus/blob/master/docs/validity.rst), [migration notes](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_bus/blob/master/docs/release.rst)
and the [documentation](https://carculator-bus.readthedocs.io/en/latest/).

## Development and release

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

```bash
python -m pip install -e "../carculator_utils[test,excel,brightway]" -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_bus/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_bus/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_bus/blob/master/CONTRIBUTING.md).
Licensed under [BSD-3-Clause](https://github.com/Laboratory-for-Energy-Systems-Analysis/carculator_bus/blob/master/LICENSE).

The shared LCA background now uses premise 2.5.4 and ecoinvent 3.12 cutoff.
The former `NMC-523` option is replaced by `NMC-532` (actual Ni:Mn:Co 5:3:2
inventory); update custom chemistry selections. See `docs/release.rst`.
