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

Requirements and installation

MobEV requires Python 3.13 or newer.

Install the published package with pip:

python -m pip install mobev

Or add it to an existing uv-managed project:

uv add mobev

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

uv sync

To build the documentation locally:

uv sync --group docs
make -C docs html

Inputs

Each simulation needs a trip directory containing:

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 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. Repository users can copy 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:

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:

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:

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:

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:

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

Testing

Run the test suite with:

.venv/bin/pytest -q

Further documentation

The Sphinx documentation covers inputs, configuration, workflow, tariffs, results, visualization, and the public API.