MobEV

MobEV turns weekly geolocated car-trip templates into electric-vehicle charging sessions, battery state-of-charge traces, and timestep demand profiles for distribution-network studies. It helps users connect mobility assumptions to where and when vehicles draw electricity.

The simulation follows three mandatory stages: prepare weekday/weekend trips → build a fleet and charging scenario → simulate battery use and charging decisions. Optional analysis aggregates and visualizes results for selected vehicles, locations, or the whole population. External-grid connection assigns stations to nearby eligible electricity buses using station capacity and voltage level. It limits combined LV station capacity per bus and permits restricted MV fallback, without load-flow analysis.

Python 3.13 or newer is required. Install with:

python -m pip install mobev

Simulation workflow

1. Prepare trip inputs

Provide a directory containing two geolocated trip templates:

example/trips/
├── weekday_trips.gpkg
└── weekend_trips.gpkg

Each GeoPackage describes car trips with departure and arrival times, activity locations and purposes, and a declared coordinate reference system. MobEV repeats weekday and weekend templates over the simulation dates. See the input schemas and the Getting Started example for a small runnable dataset.

2. Create the configuration file

Define simulation dates, fleet and battery assumptions, charger availability and capacity, charging behavior, and tariffs in a YAML file. Start with the minimal example configuration, saved as example/config.yaml, and use the configuration reference to adapt it to your study.

3. Add weather when needed

Weather is required only when battery.consumption_mode is temperature. Provide a separate CSV or Parquet file with datetime and air_temperature columns, covering every simulation hour. Temperatures are in degrees Celsius; timestamps use UTC or are converted to UTC. Pass its path as weather_file when creating the pipeline. Other consumption modes do not require weather. See the weather input example.

4. Run the pipeline

The pipeline prepares trips, builds the fleet and charging scenario, then simulates battery use and charging decisions:

from mobev import SimulationPipeline

pipeline = SimulationPipeline.from_yaml(
    config_path="example/config.yaml",
    trip_source_dir="example/trips",
    # weather_file="example/weather.csv",  # Required for temperature mode.
)
results = pipeline.run()

print(results.charging_simulation.charging_sessions_df.head())
print(results.charging_simulation.charging_stations_df.head())

Results contain prepared trips, scenario inputs, battery state-of-charge traces, charging decisions and sessions, timestep charging profiles, and station capacity summaries. The installed mobev command also runs the pipeline and saves tables and analysis outputs; see the workflow and CLI guide.

5. Analyze results

Aggregation is a separate step after run(). Sum charging demand across the population, inspect indicators, or select locations for a more focused analysis:

total = pipeline.aggregate(by="total")
print(total.aggregated_profiles_df.head())
print(total.build_indicators("indicators"))
total.save_csv("indicators", "example/indicators.csv")
total.save_parquet("aggregated_profiles_df", "example/total.parquet")
total.plot(category="charger_capacity_kw", save_path="example/charging_by_capacity.png")

homes = pipeline.aggregate(by="location_type", location_types=["home"])
print(homes.charging_stations_df.head())
homes.plot(save_path="example/home_charging.png")

Each call returns an independent aggregation. Charging profiles report actual power in kW; station capacity describes the assumed maximum power available. The plot below illustrates charging demand split by nominal charger capacity from a larger simulation. Save each aggregation frame by using the save apis, attribute name and output paths.

For an external-grid study, optionally connect station results to nearby buses through pipeline.connect_to_grid(). See the grid connection guide for required bus inputs, LV capacity allocation, and MV fallback.

Use the documentation links below for input schemas, configuration constraints, CLI options, result meanings, and API details.

• Pipeline · Workflow and CLI
• Inputs · Configuration
• Results · Aggregation and visualization
• External-grid connection
• API · Contributing · Changelog