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

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

Use the complete YAML template and parameter reference. 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:

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

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 and result attributes.

Run from the command line

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.

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.

Project links

Changelog · Contribute · API reference

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.