Metadata-Version: 2.4
Name: mobev
Version: 0.7.0
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 turns weekly geolocated car-trip templates into electric-vehicle charging
sessions, battery state-of-charge traces, and timestep demand profiles for
distribution-network studies. It helps users connect mobility assumptions to
where and when vehicles draw electricity.

- Prepare repeated weekday/weekend trip templates and sample an EV fleet.
- Simulate charging sessions, battery state, and timestep demand.
- Analyze selected vehicles or locations and export tables and plots.
- Optionally assign charging stations to distribution-grid buses.

Python 3.13 or newer is required. Install with:

```bash
python -m pip install mobev
```

## First run

Supply weekday/weekend geolocated trip GeoPackages and a YAML configuration.
The [runnable synthetic tutorial](https://pages.persee.minesparis.psl.eu/planeterr/mobev/getting-started.html)
creates both inputs and explains expected outputs. After preparing them:

```python
from mobev import SimulationPipeline

pipeline = SimulationPipeline.from_yaml("example/config.yaml", "example/trips")
result = pipeline.run()
total = pipeline.aggregate_total()
total.plot(save_path="example/total.png")
```

![Weekly charging demand by nominal charger capacity](docs/source/_static/test21_charging_power_category.png)

This figure illustrates a separate, larger study. Categories represent nominal
charger capacity; plotted power represents actual timestep demand.

## Study assumptions

Weekday/weekend templates repeat, and trip clocks and reporting use UTC.
Chargers are assigned per typed location. Station capacity is inferred from
concurrency; it does not impose a separate shared-station charging limit.
Infeasible trips are recorded while the itinerary continues with battery energy
floored at zero. Grid assignment does not establish electrical feasibility by
load flow. See [modeling assumptions](https://pages.persee.minesparis.psl.eu/planeterr/mobev/stages.html#modeling-assumptions).

## Documentation

- [First run](https://pages.persee.minesparis.psl.eu/planeterr/mobev/getting-started.html)
- [Your inputs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html) and [configuration](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html)
- [Python and CLI recipes](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
- [Analysis](https://pages.persee.minesparis.psl.eu/planeterr/mobev/visualization.html) and [result meanings](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html)
- [Grid studies](https://pages.persee.minesparis.psl.eu/planeterr/mobev/grid-connections.html)
- [Glossary](https://pages.persee.minesparis.psl.eu/planeterr/mobev/glossary.html), [API](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/index.html)
