mobev 0.1.0__py3-none-any.whl

mobev/charging/__init__.py

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

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}")

mobev/charging/ev_fleet_sampler.py

@@ -0,0 +1,140 @@
+"""Select EV-owning people and sample their vehicle and tariff attributes."""
+
+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 EVFleetSampler:
+    """Inputs: the global configuration, a prepared trip table, and a random
+    number generator.
+
+    Process: samples which people own EVs, then assigns EV attributes using
+    either fixed values or configured fleet segments, and filters the
+    trip table to the sampled EV population.
+
+    Outputs: a vehicle table describing the sampled EV fleet and the subset of
+    trip rows belonging to those EVs.
+    """
+
+    def __init__(self, config: Config):
+        """Implement the internal  init   operation."""
+        self.config = config
+
+    @staticmethod
+    def _sample_initial_soc(
+        method: str,
+        fixed_soc: float,
+        distribution: dict[str, float],
+        count: int,
+        rng: np.random.Generator,
+    ) -> np.ndarray:
+        """Draw fixed or bounded normal initial SOC values."""
+        if method == "fixed":
+            values = np.full(count, fixed_soc, dtype=float)
+        elif method == "distribution":
+            values = rng.normal(distribution["mean"], distribution["std"], size=count)
+            values = np.clip(values, distribution["min"], distribution["max"])
+        else:
+            raise ValueError(f"Unsupported initial SOC method: {method!r}")
+        return np.clip(values, 0.0, 1.0)
+
+    def sample(
+        self,
+        trips_df: pl.DataFrame,
+        rng: np.random.Generator,
+    ) -> tuple[pl.DataFrame, pl.DataFrame]:
+        """Return sampled EV vehicles and the subset of trips belonging to them."""
+        person_count = (
+            trips_df["person_id"].n_unique() if not trips_df.is_empty() else 0
+        )
+        logger.debug("Sampling EV ownership for %s unique people.", person_count)
+        person_ids = (
+            trips_df.select("person_id")
+            .unique()
+            .sort("person_id")
+            .to_series()
+            .to_numpy()
+        )
+        ev_person_ids = person_ids[
+            rng.random(person_ids.size) <= self.config.ev_penetration
+        ]
+        ev_count = ev_person_ids.size
+
+        if self.config.attribute_mode == "segment":
+            if self.config.fleet_segments is None:
+                raise ValueError("Segment sampling requires config.fleet_segments.")
+            segments = self.config.fleet_segments
+            shares = np.asarray([segment["share"] for segment in segments], dtype=float)
+            segment_indices = rng.choice(
+                len(segments), size=ev_count, p=shares / shares.sum()
+            )
+            segment_names = np.asarray(
+                [segment["name"] for segment in segments], dtype=str
+            )[segment_indices]
+            capacities_kwh = np.asarray(
+                [segment["battery_capacity_kwh"] for segment in segments], dtype=float
+            )[segment_indices]
+            consumptions_kwh_per_km = np.asarray(
+                [segment["consumption_kwh_per_km"] for segment in segments], dtype=float
+            )[segment_indices]
+        else:
+            segment_names = np.full(ev_count, "fixed")
+            capacities_kwh = np.full(
+                ev_count, self.config.fixed_vehicle_battery_capacity_kwh, dtype=float
+            )
+            consumptions_kwh_per_km = np.full(
+                ev_count, self.config.fixed_vehicle_consumption_kwh_per_km, dtype=float
+            )
+
+        initial_soc_fractions = self._sample_initial_soc(
+            self.config.initial_soc_mode,
+            self.config.fixed_initial_soc_fraction,
+            self.config.initial_soc_distribution,
+            ev_count,
+            rng,
+        )
+        follows_tariff = (
+            rng.random(ev_count) <= self.config.tariff_following_probability
+            if self.config.tariff_enabled
+            else np.zeros(ev_count, dtype=bool)
+        )
+        vehicles_df = pl.DataFrame(
+            {
+                "vehicle_id": np.asarray(
+                    [f"ev-{person_id}" for person_id in ev_person_ids]
+                ),
+                "person_id": ev_person_ids,
+                "vehicle_segment": segment_names,
+                "battery_capacity_kwh": capacities_kwh,
+                "consumption_kwh_per_km": consumptions_kwh_per_km,
+                "initial_soc_fraction": initial_soc_fractions,
+                "min_soc_fraction": np.full(ev_count, self.config.minimum_soc_fraction),
+                "max_soc_fraction": np.full(ev_count, self.config.maximum_soc_fraction),
+                "min_energy_kwh": capacities_kwh * self.config.minimum_soc_fraction,
+                "max_energy_kwh": capacities_kwh * self.config.maximum_soc_fraction,
+                "follows_tariff": follows_tariff,
+            }
+        )
+        if vehicles_df.is_empty():
+            logger.warning("No EVs were sampled from the provided trips.")
+            return vehicles_df, trips_df.head(0)
+
+        filtered_trips = trips_df.join(
+            vehicles_df.select(["person_id", "vehicle_id"]),
+            on="person_id",
+            how="inner",
+        )
+        logger.debug(
+            "Sampled %s EVs and retained %s EV trip rows.",
+            vehicles_df.height,
+            filtered_trips.height,
+        )
+        return vehicles_df, filtered_trips

mobev/charging/parking_interval_builder.py

@@ -0,0 +1,207 @@
+"""Construct parking intervals between chronological vehicle trips."""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+
+import polars as pl
+
+from mobev.core.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class ParkingIntervalBuilder:
+    """Build parking intervals from chronologically ordered EV trips."""
+
+    def __init__(self, config: Config):
+        """Implement the internal  init   operation."""
+        self.config = config
+        self.simulation_end_datetime = config.start_datetime + timedelta(days=7)
+
+    def build(self, trips_df: pl.DataFrame) -> pl.DataFrame:
+        """Return parking intervals derived from the validated trip schedule."""
+        if trips_df.is_empty():
+            logger.warning(
+                "Received empty trips dataframe when building parking intervals."
+            )
+            return self._empty_parking_events()
+
+        logger.debug("Building parking intervals from %s trip rows.", trips_df.height)
+        parking_df = self._build_lazy_intervals(trips_df).collect(engine="streaming")
+        logger.debug("Built %s parking intervals.", parking_df.height)
+        return parking_df
+
+    def _build_lazy_intervals(self, trips_df: pl.DataFrame) -> pl.LazyFrame:
+        """Build initial, intermediate, and final parking events column-wise."""
+        sort_columns = ["person_id", "departure_datetime"]
+        if "trip_index" in trips_df.columns:
+            sort_columns.append("trip_index")
+
+        simulation_start = pl.lit(self.config.start_datetime, dtype=pl.Datetime)
+        simulation_end = pl.lit(self.simulation_end_datetime, dtype=pl.Datetime)
+        ordered_trips = (
+            trips_df.lazy()
+            .sort(sort_columns)
+            .with_columns(
+                [
+                    pl.col("trip_id")
+                    .cum_count()
+                    .over("person_id")
+                    .alias("trip_position"),
+                    pl.col("trip_id").shift(-1).over("person_id").alias("next_trip_id"),
+                    pl.col("departure_datetime")
+                    .shift(-1)
+                    .over("person_id")
+                    .alias("next_departure_datetime"),
+                    pl.col("preceding_purpose")
+                    .shift(-1)
+                    .over("person_id")
+                    .alias("next_preceding_purpose"),
+                ]
+            )
+        )
+
+        overlap_count = (
+            ordered_trips.filter(
+                pl.col("next_departure_datetime").is_not_null()
+                & (pl.col("arrival_datetime") > pl.col("next_departure_datetime"))
+            )
+            .select(pl.len())
+            .collect()
+            .item()
+        )
+        if overlap_count:
+            logger.error("Detected %s negative parking intervals.", overlap_count)
+            raise ValueError("Parking event duration cannot be negative.")
+
+        initial_events = ordered_trips.filter(
+            (pl.col("trip_position") == 1)
+            & (pl.col("departure_datetime") > simulation_start)
+        ).select(
+            self._event_columns(
+                vehicle_id=pl.col("vehicle_id"),
+                person_id=pl.col("person_id"),
+                start_datetime=simulation_start,
+                end_datetime=pl.col("departure_datetime"),
+                location_id=pl.col("start_location_id"),
+                location_type=self._first_nonempty("preceding_purpose"),
+                preceding_trip_id=pl.lit(None, dtype=pl.Int64),
+                next_trip_id=pl.col("trip_id"),
+            )
+        )
+        intermediate_events = ordered_trips.filter(
+            pl.col("next_departure_datetime").is_not_null()
+        ).select(
+            self._event_columns(
+                vehicle_id=pl.col("vehicle_id"),
+                person_id=pl.col("person_id"),
+                start_datetime=pl.col("arrival_datetime"),
+                end_datetime=pl.col("next_departure_datetime"),
+                location_id=pl.col("end_location_id"),
+                location_type=self._first_nonempty(
+                    "following_purpose", "next_preceding_purpose"
+                ),
+                preceding_trip_id=pl.col("trip_id"),
+                next_trip_id=pl.col("next_trip_id"),
+            )
+        )
+        final_events = ordered_trips.filter(
+            pl.col("next_trip_id").is_null()
+            & (pl.col("arrival_datetime") < simulation_end)
+        ).select(
+            self._event_columns(
+                vehicle_id=pl.col("vehicle_id"),
+                person_id=pl.col("person_id"),
+                start_datetime=pl.col("arrival_datetime"),
+                end_datetime=simulation_end,
+                location_id=pl.col("end_location_id"),
+                location_type=self._first_nonempty("following_purpose"),
+                preceding_trip_id=pl.col("trip_id"),
+                next_trip_id=pl.lit(None, dtype=pl.Int64),
+            )
+        )
+
+        return (
+            pl.concat([initial_events, intermediate_events, final_events])
+            .sort(["vehicle_id", "start_datetime"])
+            .with_row_index("parking_event_id")
+            .with_columns(pl.col("parking_event_id").cast(pl.Int64))
+            .select(
+                [
+                    "parking_event_id",
+                    "vehicle_id",
+                    "person_id",
+                    "start_datetime",
+                    "end_datetime",
+                    "parking_duration_s",
+                    "location_id",
+                    "location_type",
+                    "preceding_trip_id",
+                    "next_trip_id",
+                ]
+            )
+        )
+
+    @staticmethod
+    def _first_nonempty(*column_names: str) -> pl.Expr:
+        """Return the first non-null, non-empty purpose or the ``other`` fallback."""
+        candidates = [
+            pl.when(
+                pl.col(column).is_not_null() & (pl.col(column).cast(pl.String) != "")
+            )
+            .then(pl.col(column).cast(pl.String))
+            .otherwise(None)
+            for column in column_names
+        ]
+        return pl.coalesce([*candidates, pl.lit("other")])
+
+    @staticmethod
+    def _event_columns(
+        *,
+        vehicle_id: pl.Expr,
+        person_id: pl.Expr,
+        start_datetime: pl.Expr,
+        end_datetime: pl.Expr,
+        location_id: pl.Expr,
+        location_type: pl.Expr,
+        preceding_trip_id: pl.Expr,
+        next_trip_id: pl.Expr,
+    ) -> list[pl.Expr]:
+        """Implement the internal event columns operation."""
+        duration_seconds = (
+            (end_datetime - start_datetime)
+            .dt.total_microseconds()
+            .truediv(1_000_000.0)
+            .alias("parking_duration_s")
+        )
+        return [
+            vehicle_id.cast(pl.String).alias("vehicle_id"),
+            person_id.cast(pl.Int64).alias("person_id"),
+            start_datetime.cast(pl.Datetime("us")).alias("start_datetime"),
+            end_datetime.cast(pl.Datetime("us")).alias("end_datetime"),
+            duration_seconds,
+            location_id.cast(pl.String).alias("location_id"),
+            location_type.cast(pl.String).alias("location_type"),
+            preceding_trip_id.cast(pl.Int64).alias("preceding_trip_id"),
+            next_trip_id.cast(pl.Int64).alias("next_trip_id"),
+        ]
+
+    @staticmethod
+    def _empty_parking_events() -> pl.DataFrame:
+        """Implement the internal empty parking events operation."""
+        return pl.DataFrame(
+            schema={
+                "parking_event_id": pl.Int64,
+                "vehicle_id": pl.String,
+                "person_id": pl.Int64,
+                "start_datetime": pl.Datetime,
+                "end_datetime": pl.Datetime,
+                "parking_duration_s": pl.Float64,
+                "location_id": pl.String,
+                "location_type": pl.String,
+                "preceding_trip_id": pl.Int64,
+                "next_trip_id": pl.Int64,
+            }
+        )

mobev/charging/parking_location_normalizer.py

@@ -0,0 +1,83 @@
+"""Normalize raw activity purposes to configured charging location types."""
+
+from __future__ import annotations
+
+import logging
+
+import polars as pl
+
+from mobev.core.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class ParkingLocationNormalizer:
+    """Inputs: the global configuration and a parking-event table with raw
+    location labels.
+
+    Process: normalizes location labels to canonical categories, falls back to
+    `other` for unknown labels, and joins configured charger-access metadata onto each parking event.
+
+    Outputs: a parking-event table enriched with normalized location types and
+    location-level charging metadata.
+    """
+
+    def __init__(self, config: Config):
+        """Implement the internal  init   operation."""
+        self.config = config
+        self._known_location_types = tuple(config.location_charging_configs)
+        self._location_metadata_df = pl.DataFrame(
+            {
+                "location_type": list(config.location_charging_configs),
+                "charger_availability_probability": [
+                    location["charger_availability_probability"]
+                    for location in config.location_charging_configs.values()
+                ],
+            }
+        )
+
+    def normalize(self, parking_df: pl.DataFrame) -> pl.DataFrame:
+        """Return parking events with canonical location types and metadata."""
+        if parking_df.is_empty():
+            logger.warning(
+                "Received empty parking dataframe when normalizing locations."
+            )
+            return parking_df
+
+        logger.debug(
+            "Normalizing location metadata for %s parking events.", parking_df.height
+        )
+        normalized_location_expr = (
+            pl.col("location_type")
+            .cast(pl.Utf8, strict=False)
+            .fill_null("other")
+            .str.strip_chars()
+            .str.to_lowercase()
+        )
+
+        normalized_locations = parking_df.select(
+            normalized_location_expr.alias("location_type")
+        ).unique()
+        unknown_locations = sorted(
+            normalized_locations.filter(
+                ~pl.col("location_type").is_in(self._known_location_types)
+            )
+            .get_column("location_type")
+            .to_list()
+        )
+        if unknown_locations:
+            logger.debug(
+                "Unknown location types %s; falling back to 'other'.",
+                unknown_locations,
+            )
+
+        resolved_df = parking_df.with_columns(
+            pl.when(normalized_location_expr.is_in(self._known_location_types))
+            .then(normalized_location_expr)
+            .otherwise(pl.lit("other"))
+            .alias("location_type")
+        ).join(self._location_metadata_df, on="location_type", how="left")
+        logger.debug(
+            "Normalized location metadata for %s parking events.", resolved_df.height
+        )
+        return resolved_df

mobev/charging/trip_schedule_validator.py

@@ -0,0 +1,53 @@
+"""Validate that each vehicle trip schedule is chronological and non-overlapping."""
+
+from __future__ import annotations
+
+import logging
+
+import polars as pl
+
+logger = logging.getLogger(__name__)
+
+
+class TripScheduleValidator:
+    """Inputs: a trip table for the sampled EV population.
+
+    Process: sorts trips by person and departure time, checks that successive
+    trips do not overlap, and raises an error when an invalid schedule is found.
+
+    Outputs: the validated and chronologically ordered trip table used to derive
+    parking intervals.
+    """
+
+    def validate(self, trips_df: pl.DataFrame) -> pl.DataFrame:
+        """Return the ordered trip schedule after overlap validation."""
+        if trips_df.is_empty():
+            logger.warning(
+                "Received empty trips dataframe when validating trip schedules."
+            )
+            return trips_df
+
+        logger.debug(
+            "Validating ordered trip schedules for %s trip rows.", trips_df.height
+        )
+        sorted_trips = trips_df.sort(["person_id", "departure_datetime", "trip_index"])
+        validation_df = sorted_trips.with_columns(
+            pl.col("departure_datetime")
+            .shift(-1)
+            .over("person_id")
+            .alias("next_departure_datetime")
+        )
+        overlap_count = validation_df.filter(
+            pl.col("next_departure_datetime").is_not_null()
+            & (pl.col("arrival_datetime") > pl.col("next_departure_datetime"))
+        ).height
+        if overlap_count:
+            logger.error(
+                "Detected %s overlapping trip rows while validating schedules.",
+                overlap_count,
+            )
+            raise ValueError(
+                "Trips overlap for at least one person; charging simulation requires ordered trip chains."
+            )
+        logger.debug("Validated %s trip schedule rows.", sorted_trips.height)
+        return sorted_trips