Metadata-Version: 2.4
Name: mobev
Version: 0.5.1
Summary: MobEV: mobility-based, geolocalized EV charging-demand model.
Author-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>
License: MIT
Project-URL: Repository, https://git.persee.minesparis.psl.eu/planeterr/mobev
Project-URL: Documentation, https://pages.persee.minesparis.psl.eu/planeterr/mobev/
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: geopandas
Requires-Dist: pyproj
Requires-Dist: shapely>=2
Requires-Dist: polars
Requires-Dist: PyYAML
Requires-Dist: matplotlib
Requires-Dist: pyarrow
Requires-Dist: colorlog
Requires-Dist: tqdm
Dynamic: license-file

# MobEV

<p align="left">
  <a href="https://pages.persee.minesparis.psl.eu/planeterr/mobev/">
    <img src="https://pages.persee.minesparis.psl.eu/planeterr/mobev/_static/logo.png" alt="MobEV logo" width="220">
  </a>
</p>

[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/mobev/)
[![uv](https://img.shields.io/badge/uv-managed-blue)](https://docs.astral.sh/uv/)

MobEV is a mobility-based, geolocalized electric-vehicle (EV) charging-demand
model for distribution-network studies. It turns weekly car-trip templates
into charging sessions, battery state-of-charge traces, and demand profiles
at a configured timestep.

MobEV requires Python 3.13 or newer:

```bash
python -m pip install mobev
# or, in a uv project
uv add mobev
```

## How it works

1. **Prepare trips:** validate and expand weekday and weekend GeoPackages
   across the simulation dates.
2. **Build the scenario:** sample EV ownership and vehicle attributes, assign
   parking and chargers, and prepare tariffs and optional weather.
3. **Simulate charging:** process trips and parking chronologically to produce
   battery states, charging decisions, sessions, and active-slot power profiles.

Aggregation is a separate analysis step. Use it to sum charging power for the
whole population or selected vehicles and locations, then plot or export it.

## First run

Follow [Getting started](https://pages.persee.minesparis.psl.eu/planeterr/mobev/getting-started.html)
to create a minimal YAML configuration and two small synthetic trip GeoPackages.
After creating those inputs, run:

```python
from mobev import SimulationPipeline

pipeline = SimulationPipeline.from_yaml(
    config_path="example/config.yaml",
    trip_source_dir="example/trips",
)
result = pipeline.run()
print(result.charging_simulation.charging_sessions_df.head())

total = pipeline.aggregate(by="total")
print(total.aggregated_profiles_df.head())
total.plot(save_path="example/total.png")
```

The tutorial uses baseline consumption and a flat tariff. Temperature-based
consumption requires enabling `battery.consumption_mode: temperature` and
passing a separate hourly weather file. The repository's `config/config.yaml`
is a study configuration that requires weather and tariff files.

## Documentation

- [Input formats](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html)
- [Configuration reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html)
- [Workflow, CLI, and scenario comparison](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
- [Charging decision algorithm](https://pages.persee.minesparis.psl.eu/planeterr/mobev/charging-algorithm.html)
- [Result tables](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html)
- [Aggregation and visualization](https://pages.persee.minesparis.psl.eu/planeterr/mobev/visualization.html)
- [API reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/)
- [Changelog](https://pages.persee.minesparis.psl.eu/planeterr/mobev/changelog.html)
- [Contributing and building the docs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/contribute.html)
