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 source directory containing two files:

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 with a modified version of EQASIM. See the 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 a relative or 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 simulation pipeline

The public API has three mandatory simulation stages. run() executes them and returns the main SimulationResults object. It contains the three mandatory-stage result objects. Profile aggregation is optional and is intended for data analysis and visualisation; it returns a separate AggregatedProfiles object.

from mobev import SimulationPipeline

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

assert result.charging_simulation.charging_profiles_df is not None

Run individual stages when you need to inspect or reuse their result objects:

prepared = pipeline.prepare_trips()
scenario = pipeline.build_scenario(prepared)
simulation = pipeline.simulate(scenario)
aggregated = pipeline.aggregate(by="total")

The mandatory stage contracts are:

TripPreparer -> PreparedTrips
ScenarioBuilder -> ScenarioInputs
ChargingSimulator -> ChargingSimulation
ProfileAggregator (optional) -> AggregatedProfiles

The stage internals and table schemas are documented in the workflow, results, and API reference pages.

Testing

Run the test suite with:

.venv/bin/pytest -q

Further documentation

The Sphinx documentation is the authoritative project documentation. It covers inputs, configuration, the three mandatory pipeline stages, optional aggregation for analysis and visualisation, tariff behavior, result objects, visualization, logging, and the public API. PRICE_PLAN.md, PRICE_RESPONSE.md, and ev_price_response_modelling_approaches.md are design/research notes rather than supported runtime documentation.