Metadata-Version: 2.4
Name: mobev
Version: 0.3.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: shapely>=2
Requires-Dist: polars
Requires-Dist: PyYAML
Requires-Dist: matplotlib
Requires-Dist: pyarrow
Requires-Dist: colorlog
Dynamic: license-file

# MobEV

<p align="left">
  <a href="https://pages.persee.minesparis.psl.eu/planeterr/mobev/">
    <img src="docs/source/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/)

MobEV is a mobility-based, geolocalized EV charging-demand model. It
generates EV charging-demand profiles for distribution-network studies from
weekly car-trip data. The model samples an EV fleet and charging access,
simulates battery state of charge and charging sessions, and aggregates the
resulting demand at the configured timestep.
It requires Python 3.13 or newer. Install with `python -m pip install mobev` or
`uv add mobev`; contributors can run `uv sync` from a checkout.

[Full documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/)

## Inputs and configuration

Pass a directory containing `weekday_trips.gpkg` and `weekend_trips.gpkg`.
Both need person/activity fields, car mode, seconds-since-midnight departure
and arrival times, line geometry, and a CRS. See the [trip input schema](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#trip-inputs).
Optional tariff CSVs need a zero-based contiguous integer positional index and
exactly one numeric `price` or `price_eur_kwh` column in EUR/kWh; source
timestamps are rejected. See [tariff inputs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#tariff-inputs).

Use the complete [YAML template](config/config.yaml) and
[parameter reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html).
Relative tariff paths resolve from the YAML file. The main sections are
`simulation`, `fleet`, `battery`, `charging`, `flexibility`, `tariff`, and
`locations`. The YAML must include the simulation section and required charging fields;
horizon dates default to 2024-01-01 through 2024-01-07. The template is ready to copy and edit. A minimal flat-tariff YAML is:

```yaml
simulation:
  start_date: 2024-01-01
  end_date: 2024-01-07
charging:
  target_soc: 0.9
  minimum_parking_time_minutes: 15
  charging_setup_duration_minutes: 0
  range_anxiety:
    type: normal
    mean: 0.5
    std: 0.15
    min: 0.1
    max: 0.9
tariff:
  unit: EUR/kWh
  flat_tariff: 0.30
```

## Run from Python

```python
from mobev import SimulationPipeline

pipeline = SimulationPipeline.from_yaml(
    "config/config.yaml", "data/input/trips/YOUR_FEEDER"
)
result = pipeline.run()
print(result.charging_simulation.charging_profiles_df.head())
aggregate = pipeline.aggregate(by="total")
print(aggregate.aggregated_profiles_df.head())
```

`TripPreparer`, `ScenarioBuilder`, and `ChargingSimulator` are the mandatory
stages. They produce `PreparedTrips`, `ScenarioInputs`, and
`ChargingSimulation`; `run()` returns `SimulationResults` containing all three.
`ProfileAggregator` is an optional separate analysis stage producing
`AggregatedProfiles`. Construct a pipeline with `SimulationPipeline.from_yaml`
or `SimulationPipeline.from_config`, or call its individual stage methods.
See the [workflow](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
and [result attributes](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html).

## Run from the command line

```bash
mobev --input-dir data/input/trips/YOUR_FEEDER --output-dir output --config config/config.yaml
```

The installed `mobev` command writes stage table Parquet files, indicator
CSVs, `log_file.log`, and, by default, `metadata.json` and analysis PNGs.
See [CLI options](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html#command-line-runner).

## Charging decisions

At each parking opportunity, the simulator checks whether projected next-trip
SOC reaches the minimum reserve. Reserve charging starts immediately toward
trip demand plus reserve; normal charging uses the configured target SOC and
range-anxiety gate. A feasible normal charging window is chosen by mean tariff
price and compared with the curve reference. Session cost uses delivered grid
energy at each tariff slot. Trips that cannot meet demand above minimum SOC
appear in `charging_simulation.infeasible_trips_df`. See the
[charging decision algorithm](https://pages.persee.minesparis.psl.eu/planeterr/mobev/charging-algorithm.html).

## Project links

[Changelog](CHANGELOG.md) ·
[Contribute](https://pages.persee.minesparis.psl.eu/planeterr/mobev/contribute.html) ·
[API reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/)

Build the docs from a checkout with `uv sync --group docs` and
`make -C docs html`. Open `docs/build/html/index.html`; Sphinx warnings fail
the build.
