buildingdata 0.3.0__tar.gz → 0.5.0__tar.gz

{buildingdata-0.3.0 → buildingdata-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.3.0
+Version: 0.5.0
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -76,18 +76,25 @@ buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
 
 ## What it provides
 
-| Function | Source | Returns |
-| --- | --- | --- |
-| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
-| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
-| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
-| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
-| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
-| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |
+| Function | Source | Returns | Consumed by |
+| --- | --- | --- | --- |
+| `get_census()` | INSEE census (GCS) | polars `DataFrame` | buildingmodel — dwelling inference |
+| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` | buildingmodel — geocoding; building_eload — district lookup |
+| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` | buildingmodel — envelope & system inference |
+| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` | buildingmodel — gas-connection inference |
+| `get_ore()` | Agence ORE annual consumption per IRIS (GCS) | polars `DataFrame` | building_eload — calibration target |
+| `get_enedis_national()` / `get_enedis_regional()` | Enedis conso-inf36 measured consumption (GCS) | polars `DataFrame` | building_eload — validation reference |
+| `get_elmas(table)` | ELMAS non-residential load curves (GCS) | polars `DataFrame` | building_eload — non-residential model |
+| `get_occupant_diaries()` | synthetic occupant activity calendar (GCS) | polars `DataFrame` | building_eload — occupancy models |
+| `get_elecdom()` | Enedis panel Elecdom end-use load curves (GCS) | polars `DataFrame` | provenance only — source of building_eload constants |
+| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) or bulk cache | geopandas `GeoDataFrame` | building_eload → buildingmodel — input geometry |
+| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) or bulk cache | path to EPW file | buildingmodel — weather boundary condition |
 
 Reference datasets are pulled from a public Google Cloud Storage bucket and
 cached locally with generation-based freshness checks. French geospatial data
-uses CRS **EPSG:2154 (Lambert-93)**.
+uses CRS **EPSG:2154 (Lambert-93)**. The documentation page *Datasets*
+describes each dataset in detail — provenance, schema, units — and how
+`buildingmodel` / `building_eload` consume it.
 
 ## Bulk prefetch for large-scale simulations
 

{buildingdata-0.3.0 → buildingdata-0.5.0}/README.md

@@ -40,18 +40,25 @@ buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
 
 ## What it provides
 
-| Function | Source | Returns |
-| --- | --- | --- |
-| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
-| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
-| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
-| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
-| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
-| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |
+| Function | Source | Returns | Consumed by |
+| --- | --- | --- | --- |
+| `get_census()` | INSEE census (GCS) | polars `DataFrame` | buildingmodel — dwelling inference |
+| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` | buildingmodel — geocoding; building_eload — district lookup |
+| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` | buildingmodel — envelope & system inference |
+| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` | buildingmodel — gas-connection inference |
+| `get_ore()` | Agence ORE annual consumption per IRIS (GCS) | polars `DataFrame` | building_eload — calibration target |
+| `get_enedis_national()` / `get_enedis_regional()` | Enedis conso-inf36 measured consumption (GCS) | polars `DataFrame` | building_eload — validation reference |
+| `get_elmas(table)` | ELMAS non-residential load curves (GCS) | polars `DataFrame` | building_eload — non-residential model |
+| `get_occupant_diaries()` | synthetic occupant activity calendar (GCS) | polars `DataFrame` | building_eload — occupancy models |
+| `get_elecdom()` | Enedis panel Elecdom end-use load curves (GCS) | polars `DataFrame` | provenance only — source of building_eload constants |
+| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) or bulk cache | geopandas `GeoDataFrame` | building_eload → buildingmodel — input geometry |
+| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) or bulk cache | path to EPW file | buildingmodel — weather boundary condition |
 
 Reference datasets are pulled from a public Google Cloud Storage bucket and
 cached locally with generation-based freshness checks. French geospatial data
-uses CRS **EPSG:2154 (Lambert-93)**.
+uses CRS **EPSG:2154 (Lambert-93)**. The documentation page *Datasets*
+describes each dataset in detail — provenance, schema, units — and how
+`buildingmodel` / `building_eload` consume it.
 
 ## Bulk prefetch for large-scale simulations
 

{buildingdata-0.3.0 → buildingdata-0.5.0}/buildingdata/__init__.py

@@ -4,6 +4,7 @@ from .reference import (
     get_census,
     get_diagnosis,
     get_districts,
+    get_elecdom,
     get_elmas,
     get_enedis_national,
     get_enedis_regional,

{buildingdata-0.3.0 → buildingdata-0.5.0}/buildingdata/gcs.py

@@ -27,16 +27,31 @@ def get_client():
 def get_blob(name):
     """Return the Blob object for a given name, or None if not found.
 
+    Returning None on a missing blob is the contract ``ensure_blob_cached``
+    relies on to raise a named
+    :class:`~buildingdata.exceptions.RemoteNotAvailableError` -- which is in
+    turn what every ``get_X`` accessor documents under ``Raises``. ``reload()``
+    is what populates the blob's metadata (``generation``, size) used by the
+    cache freshness check, but it raises ``NotFound`` on a missing object
+    *before* ``exists()`` is ever reached, so it is caught here. Without this,
+    an accessor whose blob has not been staged yet surfaced an opaque
+    ``google.api_core.exceptions.NotFound`` instead of the documented error.
+
     Args:
         name (str): blob name inside the configured bucket.
 
     Returns:
         google.cloud.storage.Blob or None.
     """
+    from google.api_core.exceptions import NotFound
+
     client = get_client()
     bucket = client.bucket(get_bucket())
     blob = bucket.blob(name)
-    blob.reload()
+    try:
+        blob.reload()
+    except NotFound:
+        return None
     return blob if blob.exists() else None
 
 

{buildingdata-0.3.0 → buildingdata-0.5.0}/buildingdata/reference/__init__.py

@@ -2,6 +2,7 @@
 from .census import get_census
 from .diagnosis import get_diagnosis
 from .districts import get_districts
+from .elecdom import get_elecdom
 from .elmas import get_elmas
 from .enedis import get_enedis_national, get_enedis_regional
 from .gas_network import get_gas_network

buildingdata-0.5.0/buildingdata/reference/diagnosis.py

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_columns
+
+
+_BLOB_NAME = "energy_performance_diagnosis_latest.parquet"
+
+
+# Heating/DHW energies excluded from inference (no meaningful DPE data for coal)
+_EXCLUDED_ENERGIES = ["Charbon"]
+
+# Columns this accessor operates on directly (coal filter + dtype casts). If any
+# is absent the raw polars error is opaque; validating up front names the DPE
+# schema drift explicitly. ``heating_system`` + ``region`` are the join keys
+# ``buildingmodel``'s energy-system inference keys on; ``backup_heating_energy``
+# / ``dhw_energy`` carry the fuel labels the coal filter reads.
+_REQUIRED_COLUMNS = (
+    "heating_system",
+    "region",
+    "backup_heating_energy",
+    "dhw_energy",
+)
+
+
+def get_diagnosis(refresh=False):
+    """Return the cleaned DPE energy performance diagnosis DataFrame.
+
+    Downloads energy_performance_diagnosis_latest.parquet from GCS on first
+    call. Applies the filtering and type casts that previously lived in
+    buildingmodel/io/diagnosis.py so that buildingmodel receives a clean frame.
+
+    One row is one post-reform DPE record (issued on or after 1 July 2022), not
+    one dwelling of the stock: records are matched to buildings by
+    ``buildingmodel``, so every column is intensive — a ratio, a U-value, a rate
+    or a per-m² quantity — and carries over regardless of the building's size.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: DPE records. Beyond the matching keys
+            (``construction_year_class``, ``residential_type``,
+            ``heating_system``, and the ``district``/``city``/``city_group``/
+            ``department``/``region`` geography) the columns group as:
+
+            * envelope — ``wall_u_value``, ``roof_u_value``, ``floor_u_value``,
+              ``wall_window_u_value``, ``wall_window_share``,
+              ``envelope_u_value`` (whole-envelope Ubat),
+              ``thermal_bridge_linear_loss``, ``thermal_bridge_loss_share``,
+              ``air_change_rate``, ``air_permeability``, ``storey_height``,
+              ``inertia_class``, ``{wall,roof,floor}_insulation_type``;
+            * systems — ``main_heating_energy``, ``backup_heating_energy``,
+              ``dhw_energy``, ``heating_mode``/``dhw_mode`` (individual /
+              collective / mixed), the ``*_efficiency`` and ``*_scop`` pairs,
+              ``intermittency_factor``, ``backup_heating_share``,
+              ``dhw_storage_volume``;
+            * observed performance — ``energy_class``, ``ghg_class`` and the
+              ``annual_*_per_area`` intensities, for calibrating simulated
+              output against the diagnosis itself.
+
+            ``main_heating_system_efficiency`` is a combustion efficiency (≤ 1)
+            and is **null for heat pumps**, which have no such value; their
+            seasonal performance is in ``main_heating_system_scop`` instead
+            (null for every other generator). The same split applies to the
+            ``backup_heating_*`` pair. Treating a SCOP as an efficiency
+            understates heat-pump performance roughly threefold, hence the two
+            columns.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+        SchemaValidationError: if the fetched frame is missing one of the
+            columns this accessor operates on (see ``_REQUIRED_COLUMNS``).
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+
+
+    df = pl.read_parquet(dest)
+
+
+    require_columns(df, _REQUIRED_COLUMNS, "DPE/EPC diagnosis")
+
+    # Remove records with coal heating/DHW — no useful inference data.
+    # ``fill_null(False)`` is load-bearing: ``backup_heating_energy`` is null for
+    # the ~76% of records with no secondary generator, ``is_in`` returns null for
+    # those, and ``filter`` drops null rows. Without it this filter keeps only
+    # dwellings that happen to own a backup system — a heavily biased subsample —
+    # instead of dropping the few hundred coal records it is meant to remove.
+    df = df.filter(
+        ~pl.col("backup_heating_energy").is_in(_EXCLUDED_ENERGIES).fill_null(False)
+        & ~pl.col("dhw_energy").is_in(_EXCLUDED_ENERGIES).fill_null(False)
+    )
+
+    df = df.with_columns([
+        pl.col("heating_system").cast(pl.Categorical),
+        pl.col("region").cast(pl.Int64),
+    ])
+
+    if "living_area" in df.columns:
+        df = df.drop(["living_area"])
+    if "living_area_class" in df.columns:
+        df = df.drop(["living_area_class"])
+
+    return df

buildingdata-0.5.0/buildingdata/reference/elecdom.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..exceptions import SchemaValidationError
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_columns, require_dtype, require_value_range
+
+_BLOB_NAME = "elecdom_daily_load_curves_latest.parquet"
+
+_DATASET = "Enedis panel Elecdom daily load curves"
+
+# The tidy (long) shape the staged blob must have: one row per
+# (period, end use, hour-of-day). See ``doc/pending_uploads.md`` section 5 for
+# the exact transformation from the source CSV.
+_REQUIRED_COLUMNS = (
+    "period_label",
+    "season",
+    "day_type",
+    "end_use",
+    "is_specific_electricity",
+    "hour",
+    "mean_power_w",
+)
+
+_STRING_COLUMNS = ("period_label", "season", "day_type", "end_use")
+
+# 5 season blocks x 3 day types x 10 end uses x 24 hours.
+_EXPECTED_ROWS = 5 * 3 * 10 * 24
+
+_SEASONS = ("december_february", "march_may", "june_august", "september_november", "all_seasons")
+_DAY_TYPES = ("weekday", "weekend", "all_days")
+
+# Plausible band for an hourly panel-mean per-dwelling end-use load, in watts.
+# The published curves peak around 410 W; 20 kW leaves ample headroom while
+# still catching a W <-> kWh/Wh-per-day style rescale.
+_MAX_PLAUSIBLE_W = 20_000.0
+# A W -> kW rescale would leave every value below 1 W and would *not* trip the
+# upper bound, so the lower end of the scale is asserted separately.
+_MIN_PLAUSIBLE_PEAK_W = 1.0
+
+
+def _validate(df):
+    """Assert the Elecdom load-curve blob matches its documented contract."""
+    require_columns(df, _REQUIRED_COLUMNS, _DATASET)
+    require_dtype(df, _STRING_COLUMNS, pl.String, _DATASET)
+    require_dtype(df, ("is_specific_electricity",), pl.Boolean, _DATASET)
+    require_dtype(df, ("hour",), pl.Int64, _DATASET)
+    require_dtype(df, ("mean_power_w",), pl.Float64, _DATASET)
+
+    if df.height != _EXPECTED_ROWS:
+        raise SchemaValidationError(
+            f"{_DATASET}: got {df.height} rows, expected exactly {_EXPECTED_ROWS} "
+            f"({len(_SEASONS)} season blocks x {len(_DAY_TYPES)} day types x 10 end "
+            f"uses x 24 hours). A short frame means the source CSV was partially "
+            f"read or a period/end-use block was dropped during staging."
+        )
+
+    hours = sorted(df["hour"].unique().to_list())
+    if hours != list(range(24)):
+        raise SchemaValidationError(
+            f"{_DATASET}: 'hour' must cover 0..23 exactly, got {hours}. The source "
+            f"publishes 24 left-closed hourly bins '[h,h+1['."
+        )
+    for column, expected in (("season", _SEASONS), ("day_type", _DAY_TYPES)):
+        observed = sorted(df[column].unique().to_list())
+        if observed != sorted(expected):
+            raise SchemaValidationError(
+                f"{_DATASET}: {column!r} must be exactly {sorted(expected)}, got "
+                f"{observed}. The 'Période' parsing at staging time drifted."
+            )
+
+    require_value_range(df, "mean_power_w", 0.0, _MAX_PLAUSIBLE_W, _DATASET)
+    peak = df["mean_power_w"].max()
+    if peak is None or peak < _MIN_PLAUSIBLE_PEAK_W:
+        raise SchemaValidationError(
+            f"{_DATASET}: 'mean_power_w' peaks at {peak}, below "
+            f"{_MIN_PLAUSIBLE_PEAK_W} W. The published curves peak in the hundreds "
+            f"of watts; this looks like a watt-to-kilowatt rescale, which the upper "
+            f"bound cannot catch."
+        )
+    return df
+
+
+def get_elecdom(refresh=False):
+    """Return the Enedis "panel Elecdom" daily end-use load curves (polars).
+
+    **Provenance-only accessor.** Nothing in ``building_eload`` calls this at
+    runtime. The Elecdom study is the published source behind two hand-derived
+    literal constant sets in ``building_eload``
+    (``models/specific.py::ACTIVITY_ELECTRICITY_WEIGHT_TABLE`` and
+    ``models/cooking.py::COOKING_CONFIG``, paper Tab. 1 ref. [37]); those stay
+    the runtime source of truth. This accessor exists so the raw table those
+    constants were transcribed from is versioned, fetchable and schema-checked,
+    making an offline re-derivation reproducible. Its only intended consumer is
+    such a re-derivation script.
+
+    Provenance: Enedis "panel Elecdom" appliance / end-use load study, open
+    dataset *"Courbes de charge journalières horaires par usage"*
+    (`elecdom-courbes-de-charge-journalieres-horaires`), cited as paper Tab. 1
+    ref. [37]. The published table is a panel-mean per-dwelling daily load
+    curve, broken down by season block, day type and end use.
+
+    Shape: tidy/long, one row per (period, end use, hour) -- 5 season blocks
+    x 3 day types x 10 end uses x 24 hours = 3600 rows.
+
+    Columns:
+
+    * ``period_label`` (``str``) -- the verbatim source ``Période`` label, e.g.
+      ``"Mois de Décembre - Février (Jours ouvrées)"``. Kept so a row can be
+      traced back to the raw CSV without reversing the parsing.
+    * ``season`` (``str``) -- one of ``"december_february"``, ``"march_may"``,
+      ``"june_august"``, ``"september_november"``, ``"all_seasons"``.
+    * ``day_type`` (``str``) -- ``"weekday"`` (source *Jours ouvrées*),
+      ``"weekend"`` (*Week-end*), ``"all_days"`` (source's empty parentheses).
+    * ``end_use`` (``str``) -- the verbatim French ``Poste`` label, one of
+      ``Chauffage direct`` (direct electric heating), ``Chauffe eau`` (DHW),
+      ``Cuisson`` (cooking), ``Ventilation``, ``Froid`` (refrigeration),
+      ``Audiovisuel``, ``Informatique/Bureautique``, ``Lavage séchage``
+      (washing/drying), ``Eclairage`` (lighting), ``Autres``. Left untranslated
+      on purpose: this is a provenance artifact, and any English mapping would
+      be an editorial choice the re-derivation script should own.
+    * ``is_specific_electricity`` (``bool``) -- True for the seven end uses the
+      source also republishes under its ``"Electricité spécifique - "`` period
+      prefix (everything except direct heating, DHW and cooking). The prefixed
+      block is a byte-identical duplicate of the base rows, so it is collapsed
+      into this flag rather than duplicated (verified at staging; see
+      ``doc/pending_uploads.md``).
+    * ``hour`` (``Int64``) -- 0..23, the left edge of the source's left-closed
+      hourly bin ``[h, h+1[``.
+    * ``mean_power_w`` (``Float64``) -- **watts**: the panel-mean load over that
+      hour bin, equivalently Wh consumed during the hour. Published values run
+      from a few W to ~410 W.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: the 3600-row tidy Elecdom load-curve table.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+            The blob is **not staged yet** -- see ``doc/pending_uploads.md``
+            section 5 for the maintainer handoff -- so this is the expected
+            outcome until it is uploaded.
+        SchemaValidationError: if the fetched frame is missing a column, carries
+            a wrong dtype, is not the full 3600-row grid, has an unexpected
+            season/day-type/hour vocabulary, or has implausible watt values.
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return _validate(pl.read_parquet(dest))

buildingdata-0.5.0/buildingdata/reference/occupant_diaries.py

@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+import re
+
+import polars as pl
+
+from ..exceptions import SchemaValidationError
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_dtype
+
+_BLOB_NAME = "occupant_diaries_latest.parquet"
+
+_DATASET = "occupant activity diaries"
+
+# The timeline column. The staged blob was written from pandas, which round-trips
+# an unnamed index through parquet as ``__index_level_0__``; that is the name the
+# blob in the bucket actually carries today, and ``building_eload``'s
+# ``load_activity_diaries`` renames it to ``datetime`` on read. Accept either, so
+# a future re-staging that names the index properly keeps validating, but reject
+# anything else -- that rename is load-bearing for the consumer.
+_INDEX_COLUMN_NAMES = ("datetime", "__index_level_0__")
+
+# Every non-timeline column must be an occupant column. ``DwellingProcessor``
+# builds its occupant pool as ``[c for c in columns if c != "datetime"]``, so a
+# stray extra column (a leftover id, a weekday flag) would silently be drawn as
+# if it were an occupant's diary. Pinning the name shape makes that fail loud.
+_OCCUPANT_COLUMN_RE = re.compile(r"^occupant_\d+$")
+
+# The activity-code vocabulary. This mirrors ``building_eload``'s
+# ``models/occupancy.py::DEFAULT_OCCUPANCY_PER_ACTIVITY`` (flattened) -- the only
+# place the vocabulary is enumerated. It is transcribed rather than imported
+# because the dependency runs the other way (``building_eload`` depends on
+# ``buildingdata``), so keep the two in sync when the taxonomy changes.
+#
+# Validating it matters because both consumers of an unknown code fail
+# *silently*: ``set_occupancy_labels`` maps anything unrecognised to
+# ``"is_absent"`` (the occupant vanishes from the load), and ``specific.py``'s
+# left join against ``ACTIVITY_ELECTRICITY_WEIGHT_TABLE`` yields a null weight.
+# The check is a subset test, not equality: a smaller diary book that happens
+# not to use every code is legitimate.
+_ACTIVITY_CODES = frozenset(
+    {
+        # at home
+        "Hygiene",
+        "Other_at_home",
+        "Meal_at_home",
+        "Home_working",
+        "Cooking",
+        "Dish_washing",
+        "Housework",
+        "Clothes_washing",
+        "Ironing",
+        "Home_DIY",
+        "Gardening",
+        "Television",
+        "HiFi",
+        "Video_game",
+        "Computer",
+        "Electronic_Device",
+        # asleep
+        "Sleep",
+        # away
+        "Other_outside",
+        "Meal_outside",
+        "At_work",
+        "At_school",
+        "Shopping",
+        "Work_journey",
+        "Other_journey",
+    }
+)
+
+_SECONDS_PER_DAY = 24 * 60 * 60
+_FULL_YEAR_DAYS = (365, 366)
+
+
+def _index_column(df):
+    """Return the name of the diary's single Datetime timeline column."""
+    datetime_cols = [name for name, dtype in df.schema.items() if dtype == pl.Datetime]
+    if not datetime_cols:
+        raise SchemaValidationError(
+            f"{_DATASET}: no Datetime column found; expected exactly one timeline "
+            f"column named one of {list(_INDEX_COLUMN_NAMES)}. Got dtypes "
+            f"{ {name: str(t) for name, t in list(df.schema.items())[:5]} } (first 5 "
+            f"of {df.width}). Without a timeline the diaries cannot be aligned "
+            f"onto a simulation year."
+        )
+    if len(datetime_cols) > 1:
+        raise SchemaValidationError(
+            f"{_DATASET}: expected exactly one Datetime timeline column, found "
+            f"{datetime_cols}. Consumers treat every non-timeline column as an "
+            f"occupant diary, so a second temporal column would be drawn as one."
+        )
+    name = datetime_cols[0]
+    if name not in _INDEX_COLUMN_NAMES:
+        raise SchemaValidationError(
+            f"{_DATASET}: the timeline column is named {name!r}, expected one of "
+            f"{list(_INDEX_COLUMN_NAMES)}. ``building_eload`` renames "
+            f"``__index_level_0__`` to ``datetime`` on read and would raise on "
+            f"any other name."
+        )
+    return name
+
+
+def _require_complete_timeline(df, index_col):
+    """Assert the timeline is a gap-free regular grid covering a whole year.
+
+    The ELMAS lesson applies here too: a diary book that is one step short, has
+    a duplicated timestamp, or covers ten months instead of twelve does not
+    raise anywhere downstream -- ``align_activity_diaries`` rolls and slices it
+    happily and produces a quietly wrong calendar.
+    """
+    series = df[index_col]
+    if series.null_count():
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline has "
+            f"{series.null_count()} null timestamp(s)."
+        )
+    if not series.is_sorted():
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline is not sorted ascending; "
+            f"consumers roll the frame positionally and assume calendar order."
+        )
+
+    steps = series.diff().drop_nulls().unique().to_list()
+    if len(steps) != 1:
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline is not a regular grid; found "
+            f"{len(steps)} distinct steps {sorted(steps)[:5]} over {df.height} rows. "
+            f"A gap or a duplicated timestamp silently misaligns the calendar roll."
+        )
+    step = steps[0]
+    step_seconds = step.total_seconds()
+    if step_seconds <= 0 or _SECONDS_PER_DAY % step_seconds:
+        raise SchemaValidationError(
+            f"{_DATASET}: timeline step {step} does not divide a calendar day "
+            f"evenly; the diaries cannot be indexed by day-of-week."
+        )
+
+    steps_per_day = int(_SECONDS_PER_DAY // step_seconds)
+    days, remainder = divmod(df.height, steps_per_day)
+    if remainder or days not in _FULL_YEAR_DAYS:
+        raise SchemaValidationError(
+            f"{_DATASET}: {df.height} rows at a {step} step is {df.height / steps_per_day:.4f} "
+            f"days, not a whole year ({' or '.join(str(d) for d in _FULL_YEAR_DAYS)} days, "
+            f"i.e. {' or '.join(str(d * steps_per_day) for d in _FULL_YEAR_DAYS)} rows). "
+            f"A truncated diary book is the exact failure mode this check exists for: "
+            f"it raises nothing downstream, it just yields a wrong year."
+        )
+
+
+def _require_known_activity_codes(df, occupant_cols):
+    """Assert every observed activity code is in the documented vocabulary."""
+    observed = set()
+    for column in occupant_cols:
+        observed.update(df[column].unique().drop_nulls().to_list())
+    unknown = sorted(observed - _ACTIVITY_CODES)
+    if unknown:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(unknown)} unknown activity code(s) {unknown[:10]}"
+            f"{'...' if len(unknown) > 10 else ''}. The documented vocabulary is "
+            f"{sorted(_ACTIVITY_CODES)}. Unknown codes do not raise downstream -- "
+            f"``set_occupancy_labels`` maps them to 'is_absent' and the specific-"
+            f"electricity weight join yields null -- so they are rejected here. If "
+            f"the taxonomy genuinely grew, extend both ``_ACTIVITY_CODES`` here and "
+            f"``building_eload``'s DEFAULT_OCCUPANCY_PER_ACTIVITY / "
+            f"ACTIVITY_ELECTRICITY_WEIGHT_TABLE."
+        )
+
+
+def _validate(df):
+    """Run the full occupant-diary contract check on a loaded frame."""
+    index_col = _index_column(df)
+
+    occupant_cols = [c for c in df.columns if c != index_col]
+    if not occupant_cols:
+        raise SchemaValidationError(
+            f"{_DATASET}: no occupant column found next to the {index_col!r} "
+            f"timeline; the diary book is empty."
+        )
+    malformed = [c for c in occupant_cols if not _OCCUPANT_COLUMN_RE.match(c)]
+    if malformed:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(malformed)} non-timeline column(s) do not match "
+            f"'occupant_<n>': {malformed[:10]}{'...' if len(malformed) > 10 else ''}. "
+            f"``DwellingProcessor`` draws every non-timeline column as an occupant "
+            f"profile, so a stray column would be simulated as a person."
+        )
+
+    require_dtype(df, occupant_cols, pl.String, _DATASET)
+
+    null_counts = df.select(pl.col(occupant_cols).null_count()).row(0)
+    nulls = [c for c, n in zip(occupant_cols, null_counts) if n]
+    if nulls:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(nulls)} occupant column(s) contain null activity "
+            f"codes: {nulls[:10]}{'...' if len(nulls) > 10 else ''}. A null code is "
+            f"treated as 'is_absent' downstream without warning."
+        )
+
+    _require_complete_timeline(df, index_col)
+    _require_known_activity_codes(df, occupant_cols)
+    return df
+
+
+def get_occupant_diaries(refresh=False):
+    """Return the occupant activity-diary calendar DataFrame (polars).
+
+    The occupant-diary "book" is a synthetic, time-indexed activity calendar:
+    one column per simulated occupant holding an activity-code string per
+    timestep, consumed by ``building_eload``'s ``DynamicSimulation`` as the base
+    pool of activity profiles that dwellings draw from. Downloaded from
+    ``occupant_diaries_latest.parquet`` on GCS on first call.
+
+    The canonical blob is the 1000-occupant book that ``DynamicParameters``
+    uses by default (``occupant_book_1000_pers_*.parquet``). Larger books
+    (10k/100k occupants) are separate artifacts staged by the maintainer and
+    passed explicitly via ``DynamicParameters.activity_file``; they are not
+    served here.
+
+    Contract enforced on every call (see ``Raises``):
+
+    * exactly one naive ``Datetime`` timeline column, named ``datetime`` or
+      ``__index_level_0__`` (the pandas-written index name the staged blob
+      currently carries; ``building_eload`` renames it to ``datetime``);
+    * at least one occupant column, and *every* non-timeline column named
+      ``occupant_<n>`` -- consumers draw all of them as occupant profiles;
+    * every occupant column ``String``-typed and null-free;
+    * the timeline a gap-free, ascending, regular grid whose step divides a
+      day, spanning exactly one whole calendar year (365 or 366 days);
+    * every observed activity code in the documented vocabulary (the flattened
+      ``building_eload`` ``DEFAULT_OCCUPANCY_PER_ACTIVITY`` taxonomy, 24 codes).
+      The check is a subset test -- a book that does not use every code passes.
+
+    Vintage note: the blob staged today is a **10-minute** book over leap year
+    2024 (52 704 rows x 1000 occupants). The step is validated generically
+    rather than pinned to 10 minutes, but note that ``building_eload``'s
+    ``align_activity_diaries`` hardcodes ``intervals_per_day = 144``: restaging
+    at another resolution requires a matching change there.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: one ``occupant_<i>`` column per occupant (``str``
+            activity codes) plus a naive ``Datetime`` timeline column, over one
+            full representative calendar year.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+        SchemaValidationError: if the fetched frame violates any clause of the
+            contract above, naming the offending column(s) or code(s).
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return _validate(pl.read_parquet(dest))