Metadata-Version: 2.4
Name: mobev
Version: 0.1.0
Summary: MobEV: mobility-based, geolocalized EV charging-demand model.
Author-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>
License-Expression: 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

[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![PyPI version](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/mobev/)
[![Package manager](https://img.shields.io/badge/package%20manager-uv-6E56CF?logo=uv&logoColor=white)](https://docs.astral.sh/uv/)
[![Tests](https://img.shields.io/badge/tests-pytest-0A9EDC?logo=pytest&logoColor=white)](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/tree/main/tests)
[![Documentation](https://img.shields.io/badge/docs-Sphinx-4B8BBE?logo=readthedocs&logoColor=white)](https://pages.persee.minesparis.psl.eu/planeterr/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.

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

## Requirements and installation

MobEV requires Python 3.13 or newer.

Install the published package with pip:

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

Or add it to an existing uv-managed project:

```bash
uv add mobev
```

For development from a repository checkout, use the included lock file:

```bash
uv sync
```

To build the documentation locally:

```bash
uv sync --group docs
make -C docs html
```

## Inputs

Each simulation needs a trip directory containing:

```text
weekday_trips.gpkg
weekend_trips.gpkg
```

The source data must provide person and activity identifiers, departure and
arrival times, activity purposes, car mode, and trip geometries. They are generated using a modified version of the EQASIM tool : <https://github.com/RatonMagique/eqasim-france/tree/feat/iris-commune-weekday-pipeline-improvments> . See
[input documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html) for the complete input
schema.

When tariff-aware charging is enabled, the tariff CSV must contain a
contiguous integer index and one numeric `price` or `price_eur_kwh` column.

## Configuration

The authoritative configuration template is available in the
[configuration documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html).
Repository users can copy [config/config.yaml](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/blob/main/config/config.yaml)
when maintaining separate experiments, then pass the copy to the pipeline.
The repository template uses project-relative data paths. When using the
installed package, provide an absolute path for `tariff.file` (or disable the
tariff) and pass the trip-directory path explicitly.

The main sections are:

- `simulation`: timestep, start datetime, random seed, distance factor, CRS,
  and seasonal consumption.
- `fleet`: EV penetration and fixed or segmented vehicle attributes.
- `battery`: usable SOC limits, charging efficiency, and initial SOC.
- `charging`: minimum parking duration and SOC thresholds.
- `tariff`: optional time-of-use charging and tariff CSV settings.
- `locations`: charger availability and charger-power distributions by
  location type.

Edit the YAML values directly, for example:

```yaml
simulation:
  timestep_minutes: 15
  random_seed: 42

fleet:
  ev_penetration: 0.10

tariff:
  enabled: false
  file: path/to/tariff.csv
```

Set `tariff.enabled` to `true` only when `tariff.file` points to a valid CSV.
The random seed makes fleet sampling, charger assignment, and initial SOC
reproducible for the same inputs and dependency versions.

## Run the complete pipeline

The main entry point is `SimulationPipeline`. It loads the configuration and
runs all three stages in order: trip preparation, charging resolution, and
load-profile simulation.

From Python:

```python
from mobev.core.pipeline import SimulationPipeline

pipeline = SimulationPipeline.from_yaml("config/config.yaml")
result = pipeline.run("data/input/trips/YOUR_FEEDER")

print(result.load_timeseries_df)
print(result.tariff_curve_df)  # empty when tariffs are disabled
```

The checked-in runner can also be used after updating `config_file` and
`trip_folder` in [scripts/run_pipeline.py](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/blob/main/scripts/run_pipeline.py):

```bash
python scripts/run_pipeline.py
```

`EVSimulationResult` exposes all intermediate and final tables, including
trips, locations, vehicles, parking events, charging stations, charging
opportunities, SOC traces, charging sessions, load timeseries, and the tariff
curve.

## Run a decomposed pipeline

Run the stages separately when you need to inspect or persist intermediate
results, customize a stage, or integrate MobEV into a larger workflow:

```python
from mobev.core.charging_resolver import ChargingResolver
from mobev.core.config import Config
from mobev.core.profile_simulator import ProfileSimulator
from mobev.core.trip_preparer import TripPreparer

config = Config.from_yaml("config/config.yaml")
trip_results = TripPreparer(config).run("data/input/trips/YOUR_FEEDER")
charging_results = ChargingResolver(config).run(trip_results)
profile_results = ProfileSimulator(config).run(trip_results, charging_results)

print(profile_results.load_timeseries_df)
```

The stage contracts are:

```text
TripPreparer       -> TripResults
ChargingResolver   -> ChargingResults
ProfileSimulator   -> ProfileResults
```

## Testing

Run the test suite with:

```bash
.venv/bin/pytest -q
```


## Further documentation

The [Sphinx documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/) covers inputs,
configuration, workflow, tariffs, results, visualization, and the public API.
