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

# MobEV

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

[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![PyPI version](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/mobev/)
[![Package manager](https://img.shields.io/badge/package%20manager-uv-6E56CF?logo=uv&logoColor=white)](https://docs.astral.sh/uv/)
[![Tests](https://img.shields.io/badge/tests-pytest-0A9EDC?logo=pytest&logoColor=white)](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/tree/main/tests)
[![Documentation](https://img.shields.io/badge/docs-Sphinx-4B8BBE?logo=readthedocs&logoColor=white)](https://pages.persee.minesparis.psl.eu/planeterr/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/](https://pages.persee.minesparis.psl.eu/planeterr/mobev/)**.

## Requirements and installation

MobEV requires Python 3.13 or newer.

Install the published package with pip:

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

Or add it to an existing uv-managed project:

```bash
uv add mobev
```

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

```bash
uv sync
```

To build the documentation locally:

```bash
uv sync --group docs
make -C docs html
```

## Inputs

Each simulation needs a trip source directory containing two files:

```text
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](https://github.com/RatonMagique/eqasim-france/tree/feat/iris-commune-weekday-pipeline-improvments).
See the [input documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html)
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](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html).
Repository users can copy [config/config.yaml](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/blob/main/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:

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

```python
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:

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

The mandatory stage contracts are:

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

The stage internals and table schemas are documented in the
[workflow](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html),
[results](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html),
and API reference pages.

## Testing

Run the test suite with:

```bash
.venv/bin/pytest -q
```


## Further documentation

The [Sphinx documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/) 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.
