Metadata-Version: 2.4
Name: mobev
Version: 0.6.0
Summary: MobEV: mobility-based, geolocalized EV charging-demand model.
Author-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>
License: 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: pyproj
Requires-Dist: shapely>=2
Requires-Dist: polars
Requires-Dist: PyYAML
Requires-Dist: matplotlib
Requires-Dist: pyarrow
Requires-Dist: colorlog
Requires-Dist: tqdm
Dynamic: license-file

# MobEV

<p align="left">
  <a href="https://pages.persee.minesparis.psl.eu/planeterr/mobev/">
    <img src="https://pages.persee.minesparis.psl.eu/planeterr/mobev/_static/logo.png" alt="MobEV logo" width="220">
  </a>
</p>

[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/mobev/)
[![uv](https://img.shields.io/badge/uv-managed-blue)](https://docs.astral.sh/uv/)

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:

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

## Simulation workflow

### 1. Prepare trip inputs

Provide a directory containing two geolocated trip templates:

```text
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](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html)
and the [Getting Started example](https://pages.persee.minesparis.psl.eu/planeterr/mobev/getting-started.html)
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](docs/source/examples/config.yaml), saved as
`example/config.yaml`, and use the
[configuration reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html)
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](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#weather-inputs).

### 4. Run the pipeline

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

```python
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](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html).

### 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:

```python
total = pipeline.aggregate(by="total")
print(total.aggregated_profiles_df.head())
print(total.build_indicators("indicators"))
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. Saved aggregate plots include an aggregation ID in
their filenames.

![Weekly charging demand split by nominal charger capacity](docs/source/_static/test21_charging_power_category.png)

For an external-grid study, optionally connect station results to nearby buses
through `pipeline.connect_to_grid()`. See the
[grid connection guide](https://pages.persee.minesparis.psl.eu/planeterr/mobev/grid-connections.html)
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](https://pages.persee.minesparis.psl.eu/planeterr/mobev/stages.html) · [Workflow and CLI](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
- [Inputs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html) · [Configuration](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html)
- [Results](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html) · [Aggregation and visualization](https://pages.persee.minesparis.psl.eu/planeterr/mobev/visualization.html)
- [External-grid connection](https://pages.persee.minesparis.psl.eu/planeterr/mobev/grid-connections.html)
- [API](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/index.html) · [Contributing](https://pages.persee.minesparis.psl.eu/planeterr/mobev/contribute.html) · [Changelog](https://pages.persee.minesparis.psl.eu/planeterr/mobev/changelog.html)
