mobev 0.2.0__tar.gz → 0.3.0__tar.gz

mobev-0.3.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: mobev
+Version: 0.3.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: 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)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/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.
+It requires Python 3.13 or newer. Install with `python -m pip install mobev` or
+`uv add mobev`; contributors can run `uv sync` from a checkout.
+
+[Full documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/)
+
+## Inputs and configuration
+
+Pass a directory containing `weekday_trips.gpkg` and `weekend_trips.gpkg`.
+Both need person/activity fields, car mode, seconds-since-midnight departure
+and arrival times, line geometry, and a CRS. See the [trip input schema](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#trip-inputs).
+Optional tariff CSVs need a zero-based contiguous integer positional index and
+exactly one numeric `price` or `price_eur_kwh` column in EUR/kWh; source
+timestamps are rejected. See [tariff inputs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#tariff-inputs).
+
+Use the complete [YAML template](config/config.yaml) and
+[parameter reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html).
+Relative tariff paths resolve from the YAML file. The main sections are
+`simulation`, `fleet`, `battery`, `charging`, `flexibility`, `tariff`, and
+`locations`. The YAML must include the simulation section and required charging fields;
+horizon dates default to 2024-01-01 through 2024-01-07. The template is ready to copy and edit. A minimal flat-tariff YAML is:
+
+```yaml
+simulation:
+  start_date: 2024-01-01
+  end_date: 2024-01-07
+charging:
+  target_soc: 0.9
+  minimum_parking_time_minutes: 15
+  charging_setup_duration_minutes: 0
+  range_anxiety:
+    type: normal
+    mean: 0.5
+    std: 0.15
+    min: 0.1
+    max: 0.9
+tariff:
+  unit: EUR/kWh
+  flat_tariff: 0.30
+```
+
+## Run from Python
+
+```python
+from mobev import SimulationPipeline
+
+pipeline = SimulationPipeline.from_yaml(
+    "config/config.yaml", "data/input/trips/YOUR_FEEDER"
+)
+result = pipeline.run()
+print(result.charging_simulation.charging_profiles_df.head())
+aggregate = pipeline.aggregate(by="total")
+print(aggregate.aggregated_profiles_df.head())
+```
+
+`TripPreparer`, `ScenarioBuilder`, and `ChargingSimulator` are the mandatory
+stages. They produce `PreparedTrips`, `ScenarioInputs`, and
+`ChargingSimulation`; `run()` returns `SimulationResults` containing all three.
+`ProfileAggregator` is an optional separate analysis stage producing
+`AggregatedProfiles`. Construct a pipeline with `SimulationPipeline.from_yaml`
+or `SimulationPipeline.from_config`, or call its individual stage methods.
+See the [workflow](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
+and [result attributes](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html).
+
+## Run from the command line
+
+```bash
+mobev --input-dir data/input/trips/YOUR_FEEDER --output-dir output --config config/config.yaml
+```
+
+The installed `mobev` command writes stage table Parquet files, indicator
+CSVs, `log_file.log`, and, by default, `metadata.json` and analysis PNGs.
+See [CLI options](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html#command-line-runner).
+
+## Charging decisions
+
+At each parking opportunity, the simulator checks whether projected next-trip
+SOC reaches the minimum reserve. Reserve charging starts immediately toward
+trip demand plus reserve; normal charging uses the configured target SOC and
+range-anxiety gate. A feasible normal charging window is chosen by mean tariff
+price and compared with the curve reference. Session cost uses delivered grid
+energy at each tariff slot. Trips that cannot meet demand above minimum SOC
+appear in `charging_simulation.infeasible_trips_df`. See the
+[charging decision algorithm](https://pages.persee.minesparis.psl.eu/planeterr/mobev/charging-algorithm.html).
+
+## Project links
+
+[Changelog](CHANGELOG.md) ·
+[Contribute](https://pages.persee.minesparis.psl.eu/planeterr/mobev/contribute.html) ·
+[API reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/)
+
+Build the docs from a checkout with `uv sync --group docs` and
+`make -C docs html`. Open `docs/build/html/index.html`; Sphinx warnings fail
+the build.

mobev-0.3.0/README.md

@@ -0,0 +1,109 @@
+# 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)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/mobev)](https://pypi.org/project/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.
+It requires Python 3.13 or newer. Install with `python -m pip install mobev` or
+`uv add mobev`; contributors can run `uv sync` from a checkout.
+
+[Full documentation](https://pages.persee.minesparis.psl.eu/planeterr/mobev/)
+
+## Inputs and configuration
+
+Pass a directory containing `weekday_trips.gpkg` and `weekend_trips.gpkg`.
+Both need person/activity fields, car mode, seconds-since-midnight departure
+and arrival times, line geometry, and a CRS. See the [trip input schema](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#trip-inputs).
+Optional tariff CSVs need a zero-based contiguous integer positional index and
+exactly one numeric `price` or `price_eur_kwh` column in EUR/kWh; source
+timestamps are rejected. See [tariff inputs](https://pages.persee.minesparis.psl.eu/planeterr/mobev/inputs.html#tariff-inputs).
+
+Use the complete [YAML template](config/config.yaml) and
+[parameter reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/configuration.html).
+Relative tariff paths resolve from the YAML file. The main sections are
+`simulation`, `fleet`, `battery`, `charging`, `flexibility`, `tariff`, and
+`locations`. The YAML must include the simulation section and required charging fields;
+horizon dates default to 2024-01-01 through 2024-01-07. The template is ready to copy and edit. A minimal flat-tariff YAML is:
+
+```yaml
+simulation:
+  start_date: 2024-01-01
+  end_date: 2024-01-07
+charging:
+  target_soc: 0.9
+  minimum_parking_time_minutes: 15
+  charging_setup_duration_minutes: 0
+  range_anxiety:
+    type: normal
+    mean: 0.5
+    std: 0.15
+    min: 0.1
+    max: 0.9
+tariff:
+  unit: EUR/kWh
+  flat_tariff: 0.30
+```
+
+## Run from Python
+
+```python
+from mobev import SimulationPipeline
+
+pipeline = SimulationPipeline.from_yaml(
+    "config/config.yaml", "data/input/trips/YOUR_FEEDER"
+)
+result = pipeline.run()
+print(result.charging_simulation.charging_profiles_df.head())
+aggregate = pipeline.aggregate(by="total")
+print(aggregate.aggregated_profiles_df.head())
+```
+
+`TripPreparer`, `ScenarioBuilder`, and `ChargingSimulator` are the mandatory
+stages. They produce `PreparedTrips`, `ScenarioInputs`, and
+`ChargingSimulation`; `run()` returns `SimulationResults` containing all three.
+`ProfileAggregator` is an optional separate analysis stage producing
+`AggregatedProfiles`. Construct a pipeline with `SimulationPipeline.from_yaml`
+or `SimulationPipeline.from_config`, or call its individual stage methods.
+See the [workflow](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html)
+and [result attributes](https://pages.persee.minesparis.psl.eu/planeterr/mobev/results.html).
+
+## Run from the command line
+
+```bash
+mobev --input-dir data/input/trips/YOUR_FEEDER --output-dir output --config config/config.yaml
+```
+
+The installed `mobev` command writes stage table Parquet files, indicator
+CSVs, `log_file.log`, and, by default, `metadata.json` and analysis PNGs.
+See [CLI options](https://pages.persee.minesparis.psl.eu/planeterr/mobev/workflow.html#command-line-runner).
+
+## Charging decisions
+
+At each parking opportunity, the simulator checks whether projected next-trip
+SOC reaches the minimum reserve. Reserve charging starts immediately toward
+trip demand plus reserve; normal charging uses the configured target SOC and
+range-anxiety gate. A feasible normal charging window is chosen by mean tariff
+price and compared with the curve reference. Session cost uses delivered grid
+energy at each tariff slot. Trips that cannot meet demand above minimum SOC
+appear in `charging_simulation.infeasible_trips_df`. See the
+[charging decision algorithm](https://pages.persee.minesparis.psl.eu/planeterr/mobev/charging-algorithm.html).
+
+## Project links
+
+[Changelog](CHANGELOG.md) ·
+[Contribute](https://pages.persee.minesparis.psl.eu/planeterr/mobev/contribute.html) ·
+[API reference](https://pages.persee.minesparis.psl.eu/planeterr/mobev/api/)
+
+Build the docs from a checkout with `uv sync --group docs` and
+`make -C docs html`. Open `docs/build/html/index.html`; Sphinx warnings fail
+the build.

{mobev-0.2.0 → mobev-0.3.0}/mobev/__init__.py

@@ -1,19 +1,23 @@
-"""MobEV public API."""
-
 from mobev._version import __version__
-from mobev.charging import ChargingSimulator
-from mobev.core.config import (
+from mobev.charging import ChargingDecisionEngine, ChargingSimulator
+from mobev.config import (
     BatteryConfig,
     ChargingConfig,
     Config,
+    EVSegmentConfig,
     FixedVehicleConfig,
     FleetConfig,
+    FlexibilityConfig,
     InitialSocConfig,
+    LocationChargingConfig,
+    PowerDistributionConfig,
+    RangeAnxietyConfig,
     SimulationConfig,
-    SocLimitsConfig,
+    SocDistributionConfig,
     TariffConfig,
+    TariffFileConfig,
 )
-from mobev.core.pipeline import SimulationPipeline
+from mobev.pipeline import SimulationPipeline
 from mobev.profiles import ProfileAggregator
 from mobev.results import (
     AggregatedProfiles,
@@ -23,29 +27,37 @@ from mobev.results import (
     ScenarioInputs,
     SimulationResults,
 )
-from mobev.scenario import ScenarioBuilder
+from mobev.scenario import ScenarioBuilder, TariffBuilder
 from mobev.trips import TripPreparer
 
 __all__ = [
     "AggregatedProfiles",
     "BatteryConfig",
     "ChargingConfig",
+    "ChargingDecisionEngine",
     "ChargingSimulation",
     "ChargingSimulator",
     "Config",
+    "EVSegmentConfig",
     "FixedVehicleConfig",
     "FleetConfig",
+    "FlexibilityConfig",
     "InitialSocConfig",
+    "LocationChargingConfig",
     "Metadata",
+    "PowerDistributionConfig",
     "PreparedTrips",
     "ProfileAggregator",
+    "RangeAnxietyConfig",
     "ScenarioBuilder",
     "ScenarioInputs",
     "SimulationConfig",
     "SimulationPipeline",
     "SimulationResults",
-    "SocLimitsConfig",
+    "SocDistributionConfig",
+    "TariffBuilder",
     "TariffConfig",
+    "TariffFileConfig",
     "TripPreparer",
     "__version__",
 ]

{mobev-0.2.0 → mobev-0.3.0}/mobev/_version.py

@@ -1,3 +1,3 @@
 """The single source of truth for the MobEV package version."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

mobev-0.3.0/mobev/charging/__init__.py

@@ -0,0 +1,6 @@
+"""Simulate charging from scenario-input artifacts."""
+
+from mobev.charging.charging_simulator import ChargingSimulator
+from mobev.charging.decision_engine import ChargingDecisionEngine
+
+__all__ = ["ChargingDecisionEngine", "ChargingSimulator"]