mobev 0.1.0__tar.gz

mobev-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+- Copyright © `2026` `Yoann CHICHE`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

mobev-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mobev
+Version: 0.1.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
+
+[![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 directory containing:
+
+```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 using a modified version of the EQASIM tool : <https://github.com/RatonMagique/eqasim-france/tree/feat/iris-commune-weekday-pipeline-improvments> . See
+[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 an 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 complete pipeline
+
+The main entry point is `SimulationPipeline`. It loads the configuration and
+runs all three stages in order: trip preparation, charging resolution, and
+load-profile simulation.
+
+From Python:
+
+```python
+from mobev.core.pipeline import SimulationPipeline
+
+pipeline = SimulationPipeline.from_yaml("config/config.yaml")
+result = pipeline.run("data/input/trips/YOUR_FEEDER")
+
+print(result.load_timeseries_df)
+print(result.tariff_curve_df)  # empty when tariffs are disabled
+```
+
+The checked-in runner can also be used after updating `config_file` and
+`trip_folder` in [scripts/run_pipeline.py](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/blob/main/scripts/run_pipeline.py):
+
+```bash
+python scripts/run_pipeline.py
+```
+
+`EVSimulationResult` exposes all intermediate and final tables, including
+trips, locations, vehicles, parking events, charging stations, charging
+opportunities, SOC traces, charging sessions, load timeseries, and the tariff
+curve.
+
+## Run a decomposed pipeline
+
+Run the stages separately when you need to inspect or persist intermediate
+results, customize a stage, or integrate MobEV into a larger workflow:
+
+```python
+from mobev.core.charging_resolver import ChargingResolver
+from mobev.core.config import Config
+from mobev.core.profile_simulator import ProfileSimulator
+from mobev.core.trip_preparer import TripPreparer
+
+config = Config.from_yaml("config/config.yaml")
+trip_results = TripPreparer(config).run("data/input/trips/YOUR_FEEDER")
+charging_results = ChargingResolver(config).run(trip_results)
+profile_results = ProfileSimulator(config).run(trip_results, charging_results)
+
+print(profile_results.load_timeseries_df)
+```
+
+The stage contracts are:
+
+```text
+TripPreparer       -> TripResults
+ChargingResolver   -> ChargingResults
+ProfileSimulator   -> ProfileResults
+```
+
+## Testing
+
+Run the test suite with:
+
+```bash
+.venv/bin/pytest -q
+```
+
+
+## Further documentation
+
+The [Sphinx documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/) covers inputs,
+configuration, workflow, tariffs, results, visualization, and the public API.

mobev-0.1.0/README.md

@@ -0,0 +1,172 @@
+# MobEV
+
+[![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 directory containing:
+
+```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 using a modified version of the EQASIM tool : <https://github.com/RatonMagique/eqasim-france/tree/feat/iris-commune-weekday-pipeline-improvments> . See
+[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 an 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 complete pipeline
+
+The main entry point is `SimulationPipeline`. It loads the configuration and
+runs all three stages in order: trip preparation, charging resolution, and
+load-profile simulation.
+
+From Python:
+
+```python
+from mobev.core.pipeline import SimulationPipeline
+
+pipeline = SimulationPipeline.from_yaml("config/config.yaml")
+result = pipeline.run("data/input/trips/YOUR_FEEDER")
+
+print(result.load_timeseries_df)
+print(result.tariff_curve_df)  # empty when tariffs are disabled
+```
+
+The checked-in runner can also be used after updating `config_file` and
+`trip_folder` in [scripts/run_pipeline.py](https://git.persee.minesparis.psl.eu/planeterr/mobev/-/blob/main/scripts/run_pipeline.py):
+
+```bash
+python scripts/run_pipeline.py
+```
+
+`EVSimulationResult` exposes all intermediate and final tables, including
+trips, locations, vehicles, parking events, charging stations, charging
+opportunities, SOC traces, charging sessions, load timeseries, and the tariff
+curve.
+
+## Run a decomposed pipeline
+
+Run the stages separately when you need to inspect or persist intermediate
+results, customize a stage, or integrate MobEV into a larger workflow:
+
+```python
+from mobev.core.charging_resolver import ChargingResolver
+from mobev.core.config import Config
+from mobev.core.profile_simulator import ProfileSimulator
+from mobev.core.trip_preparer import TripPreparer
+
+config = Config.from_yaml("config/config.yaml")
+trip_results = TripPreparer(config).run("data/input/trips/YOUR_FEEDER")
+charging_results = ChargingResolver(config).run(trip_results)
+profile_results = ProfileSimulator(config).run(trip_results, charging_results)
+
+print(profile_results.load_timeseries_df)
+```
+
+The stage contracts are:
+
+```text
+TripPreparer       -> TripResults
+ChargingResolver   -> ChargingResults
+ProfileSimulator   -> ProfileResults
+```
+
+## Testing
+
+Run the test suite with:
+
+```bash
+.venv/bin/pytest -q
+```
+
+
+## Further documentation
+
+The [Sphinx documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/) covers inputs,
+configuration, workflow, tariffs, results, visualization, and the public API.

mobev-0.1.0/mobev/charging/__init__.py

@@ -0,0 +1 @@
+"""Provide support code for the MobEV pipeline."""

mobev-0.1.0/mobev/charging/charging_availability_assigner.py

@@ -0,0 +1,187 @@
+"""Assign persistent charging stations and enrich parking opportunities."""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import polars as pl
+
+from mobev.core.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class ChargingAvailabilityAssigner:
+    """Assign persistent chargers to location and location-type pairs.
+
+    Inputs: the global configuration, deduplicated location-type pairs,
+    normalized parking events, and a random number generator.
+
+    Process: samples one charger assignment for every ``(location_id,
+    location_type)`` pair, then joins that persistent assignment to each
+    matching parking event and applies the minimum parking-duration rule.
+
+    Outputs: a charging-station table and a parking-event table enriched with
+    charger availability, chargeability flags, and charging power.
+    """
+
+    def __init__(self, config: Config):
+        """Store the simulation configuration."""
+        self.config = config
+
+    def assign(
+        self,
+        location_types_df: pl.DataFrame,
+        parking_df: pl.DataFrame,
+        rng: np.random.Generator,
+    ) -> tuple[pl.DataFrame, pl.DataFrame]:
+        """Return persistent station assignments and enriched parking events.
+
+        RNG contract: availability is drawn once for every sorted unique
+        ``(location_id, location_type)`` pair. Power is then drawn by sorted
+        location type for available stations only. A fixed seed and identical
+        location-type inventory therefore produce identical assignments.
+        """
+        charging_station_df = self._sample_stations(location_types_df, rng)
+        minimum_parking_s = self.config.minimum_parking_time_minutes * 60.0
+
+        if parking_df.is_empty():
+            logger.debug(
+                "Assigned %s charging stations. No parking events.",
+                charging_station_df.height,
+            )
+            return charging_station_df, parking_df.with_columns(
+                [
+                    pl.lit(None, dtype=pl.Boolean).alias("charger_available"),
+                    pl.lit(None, dtype=pl.Float64).alias("charging_power_kw"),
+                    pl.lit(None, dtype=pl.Boolean).alias("is_chargeable"),
+                ]
+            )
+
+        opportunities_df = parking_df.join(
+            charging_station_df,
+            on=["location_id", "location_type"],
+            how="left",
+        ).with_columns(
+            (
+                (pl.col("parking_duration_s") >= minimum_parking_s)
+                & pl.col("charger_available")
+            ).alias("is_chargeable")
+        )
+
+        logger.debug(
+            "Assigned %s charging stations to %s unique locations. Charging power distribution: %s.",
+            int(charging_station_df.get_column("charger_available").sum() or 0),
+            charging_station_df.height,
+            charging_station_df.group_by("charging_power_kw")
+            .len()
+            .rename({"len": "count"})
+            .sort("charging_power_kw"),
+        )
+        logger.debug(
+            "Across %s parking event(s), %s are chargeable.",
+            opportunities_df.height,
+            int(opportunities_df.get_column("is_chargeable").sum() or 0),
+        )
+        return charging_station_df, opportunities_df
+
+    def _sample_stations(
+        self,
+        location_types_df: pl.DataFrame,
+        rng: np.random.Generator,
+    ) -> pl.DataFrame:
+        """Sample one persistent charger for every location and type pair."""
+        required_columns = {"location_id", "location_type"}
+        missing_columns = required_columns.difference(location_types_df.columns)
+        if missing_columns:
+            raise ValueError(
+                f"Location-type inventory is missing columns: {sorted(missing_columns)}"
+            )
+
+        stations_df = (
+            location_types_df.select(["location_id", "location_type"])
+            .with_columns(
+                [
+                    pl.col("location_id").cast(pl.String),
+                    pl.col("location_type").cast(pl.String),
+                ]
+            )
+            .unique()
+            .sort(["location_id", "location_type"])
+        )
+        if stations_df.is_empty():
+            return pl.DataFrame(
+                schema={
+                    "location_id": pl.String,
+                    "location_type": pl.String,
+                    "charger_available": pl.Boolean,
+                    "charging_power_kw": pl.Float64,
+                }
+            )
+
+        station_rows = stations_df.to_dicts()
+        availability_draws = rng.random(len(station_rows))
+        charger_available = np.zeros(len(station_rows), dtype=bool)
+        charging_power_kw = np.zeros(len(station_rows), dtype=float)
+        location_types = sorted({str(row["location_type"]) for row in station_rows})
+
+        for index, station in enumerate(station_rows):
+            probability = self.config.get_location_config(
+                str(station["location_type"])
+            )["charger_availability_probability"]
+            charger_available[index] = availability_draws[index] <= probability
+
+        for location_type in location_types:
+            available_indices = np.array(
+                [
+                    index
+                    for index, station in enumerate(station_rows)
+                    if station["location_type"] == location_type
+                    and charger_available[index]
+                ],
+                dtype=int,
+            )
+            if available_indices.size == 0:
+                continue
+            distribution = self.config.get_location_config(location_type)[
+                "charging_power_distribution"
+            ]
+            charging_power_kw[available_indices] = self._sample_power_distribution(
+                distribution,
+                available_indices.size,
+                rng,
+            )
+
+        return stations_df.with_columns(
+            [
+                pl.Series("charger_available", charger_available),
+                pl.Series("charging_power_kw", charging_power_kw),
+            ]
+        )
+
+    @staticmethod
+    def _sample_power_distribution(
+        distribution: dict[str, object],
+        size: int,
+        rng: np.random.Generator,
+    ) -> np.ndarray:
+        """Draw ``size`` charging powers for one configured location type."""
+        distribution_type = distribution["type"]
+
+        if distribution_type == "fixed":
+            return np.full(size, float(distribution["value"]), dtype=float)
+
+        if distribution_type == "categorical":
+            values = np.asarray(distribution["values"], dtype=float)
+            weights = np.asarray(distribution["weights"], dtype=float)
+            return rng.choice(values, size=size, p=weights / weights.sum())
+
+        if distribution_type == "uniform":
+            return rng.uniform(
+                float(distribution["low"]),
+                float(distribution["high"]),
+                size=size,
+            )
+
+        raise ValueError(f"Unsupported distribution type: {distribution_type!r}")