ev-flow 3.0.0__py3-none-any.whl

ev_flow-3.0.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: ev-flow
+Version: 3.0.0
+Summary: Synthetic plug-in electric vehicle charging dataset pipeline and library API.
+Project-URL: Homepage, https://github.com/bertravacca/ev-flow
+Project-URL: Repository, https://github.com/bertravacca/ev-flow
+Project-URL: Issues, https://github.com/bertravacca/ev-flow/issues
+Author-email: Bertrand Travacca <bertrand.travacca@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Bertrand Travacca
+        
+        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.
+License-File: LICENSE
+Keywords: charging,electric-vehicles,energy,ev,grid,nhts,synthetic-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=16
+Requires-Dist: pytz>=2024.1
+Requires-Dist: requests>=2.32
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ev-flow
+
+Synthetic plug-in electric vehicle (PEV) charging dataset pipeline and library API.
+
+`ev-flow` generates realistic, fleet-scale charging behavior for residential and workplace EVs, grounded in the National Household Travel Survey (NHTS) and a regional sales-mix model. It exposes both a low-level pipeline (NHTS loading, donor matching, travel-week building, plug-in modeling, state-of-charge trajectory, hourly rasterisation) and a clean `Fleet` / `Profile` library API for downstream studies.
+
+## Install
+
+```bash
+pip install ev-flow
+```
+
+Then set `PEV_SYNTH_DATA_ROOT` to point at your data tree — see the next section. Without that step, `generate_profiles(...)` will raise `FileNotFoundError` because the wheel does not bundle the cached fleet bundles.
+
+## Data directory
+
+`ev-flow` ships only the Python package; the cached fleet bundles (NHTS-derived parquets etc.) are not bundled in the wheel. Point the package at your local data directory via the `PEV_SYNTH_DATA_ROOT` environment variable:
+
+```bash
+export PEV_SYNTH_DATA_ROOT=/path/to/your/ev-flow-data
+```
+
+The directory should contain the `pev/processed/<region>/<profile_type>_ev_synth/` layout that `python -m pev_synth.cache_regen one ...` writes. If `PEV_SYNTH_DATA_ROOT` is unset, the package falls back to `<repo_root>/data/` — only useful in a `pip install -e .` dev checkout where the `data/` tree sits next to `src/`.
+
+### First run / bootstrap (dev checkout)
+
+The cached fleet bundles are **not** in the repo and **not** in the wheel — you build them from NHTS 2017 microdata, which is also not bundled. For a fresh `pip install -e .` dev checkout the one-time sequence is:
+
+```bash
+# (a) one-time: download (~84 MB ORNL zip) + process NHTS 2017.
+#     Writes the California parquets and the national hhpub.csv/vehpub.csv
+#     to data/pev/raw/nhts2017/.
+python -m pev_synth.nhts_loader
+
+# (b) build a cache for the (region, profile_type) you want.
+#     Subcommands are `one`, `batch`, `audit`.
+python -m pev_synth.cache_regen one --region bay_area --profile-type residential
+
+# (c) now the library API works:
+python -c "import pev_synth as ps; print(ps.generate_profiles('residential', n=10, region='bay_area'))"
+```
+
+Step (a) runs once: the loader persists the national `hhpub.csv` / `vehpub.csv`, so non-CA regions (`boston`, `chicago`, `dallas_fort_worth`, `new_york_metro`, `seattle`) are then handled automatically by `cache_regen one` without re-downloading.
+
+Pip-installed (non-dev) users do not run the bootstrap — instead point `PEV_SYNTH_DATA_ROOT` at a prebuilt data tree as described above.
+
+## Quick start
+
+```python
+import pev_synth as ps
+
+ps.list_regions()
+# ['bay_area', 'boston', 'chicago', 'dallas_fort_worth',
+#  'la_basin', 'new_york_metro', 'seattle', 'us_national']
+
+ps.list_profile_types()
+# ['residential', 'workplace']
+
+fleet = ps.generate_profiles('residential', n=1000, region='bay_area', seed=42)
+prof  = fleet[0]
+
+pa   = prof.generate_presence_absence('2001-01-01', '2001-01-08', freq='15min')
+sess = prof.charging_sessions('2001-06-01', '2001-06-08')
+soc  = prof.soc_trajectory('2001-06-01', '2001-06-08', freq='15min')
+```
+
+The PyPI distribution name is **`ev-flow`** but the Python import name is **`pev_synth`** (this mirrors the `scikit-learn` / `sklearn` convention).
+
+## Workplace caveat
+
+In v2.0 the `workplace` cluster centres are fit from the 105-vehicle public EVWatts cohort, whose plug-in median is ~12:00 LT — approximately 3 hours later than the literature-canonical workplace median of ~09:00 LT. The W1-W4 validator checks flag this divergence as `EXPLAINED_FAIL` rather than as a bug. `pev_synth` surfaces this caveat as a `RuntimeWarning` at `Fleet.__init__` whenever `profile_type == 'workplace'`. See `src/pev_synth/plug_in_model.py:42-48` for the full discussion.
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `nhts_loader` | National Household Travel Survey 2017 public-use file loader |
+| `vehicle_archetypes` | N-EV archetype sampler |
+| `donor_matcher` | NHTS donor-vehicle matcher |
+| `travel_week_builder` | One-year travel sequence builder |
+| `plug_in_model` | Session plug-in / dwell sampler |
+| `soc_trajectory` | Continuous-time state-of-charge ledger + session extraction |
+| `hourly_resampler` | 15-minute and hourly plug-status rasteriser |
+| `validation_bounds_curator` | Bound curation |
+| `validator` | Validation runner + report writer (11 §10 + 3 integration + 1 DST + 1 winter + 10 workplace + 1 workplace-optim checks) |
+| `regions` | 8-region registry |
+
+Full library API reference and methodology rationale live in the [`documentation/`](documentation/) folder (expanding ahead of the docs-site launch).
+
+## Development
+
+```bash
+git clone https://github.com/bertravacca/ev-flow
+cd ev-flow
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. See `LICENSE`.

ev_flow-3.0.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+pev_synth/__init__.py,sha256=LB02h9rXB6TFOTjkf2kBu0NNkUumusR6YKeC6plGUnQ,2553
+pev_synth/_meta.py,sha256=iBifIm6zHE358-UyHqAvrtgDUS9b4Fxl3DvfTukrARA,9800
+pev_synth/_paths.py,sha256=GCO3D1Oad4q8HIHOJMdNU8Qqulh6sygKIFxxyn4qjvE,3559
+pev_synth/_phev_fuel_economy.py,sha256=v5_Os1m1o_ZEHJQZwD_loYdBEKJCkwuv7qQvWTp1nlg,13979
+pev_synth/_seeds.py,sha256=MpkitrzELerWoCGfOmcS3Eg8FiACmuM4HJouJIj94IY,7734
+pev_synth/_utc_migration.py,sha256=UtLQ1Sk0QVv8I1rYy4WCDxZ4IeueTJ6hcY84yQSlYaA,17572
+pev_synth/acs_loader.py,sha256=ffAJR-IF9GBwNxD8M7ab4RqXI5DcZSj_bfYg1aUFKIc,27780
+pev_synth/api.py,sha256=52g4aAGICfDAJarRHSiRHuZFB4NXGfVIDA05ngJ4ceQ,64268
+pev_synth/cache_regen.py,sha256=4fIoGWCZCkTyL1Msypmy3wG-Qcbj9_S_fh67RlWjXrI,44338
+pev_synth/donor_matcher.py,sha256=GRpqTLop43TArxekcZOIRTrqv6k0iPzjAOrH3hqLP7M,58078
+pev_synth/hourly_resampler.py,sha256=cDk2BRIWuLJQEykCno_kO4yQOhj6wQtz338ee6mjz-g,37191
+pev_synth/nhts_loader.py,sha256=chMYuXVU4vsWMM9m_Eua0pf7Husrt2dlLx4rpuatAUw,27877
+pev_synth/nhts_nextgen_loader.py,sha256=7Jn3rnZgBqG4KHuOPwscvYlzXmNtmnnOZf1wZdsAntg,27538
+pev_synth/plug_in_model.py,sha256=NklOJ9djfca33mYBfUgdWKeqyXA2hfnPA95rtS4PYo0,88662
+pev_synth/regions.py,sha256=dQ73M6dC3hd_usQSSZ1vosvdh0AapxLn7OqKSUft1Tk,16911
+pev_synth/sales_mix_data.py,sha256=Jh5kU6OL2WcIqVuKMU0YQ10iz7IAoOB_QsmFUrAtvOA,46701
+pev_synth/soc_trajectory.py,sha256=PRmrp9XES7VaCTs5768SRh4O6i8QyBKZWHi-hbseO3s,66279
+pev_synth/travel_week_builder.py,sha256=0HKTbVXCT3kfp4cCvi6qMpx4G8Zl-5QnKLSnSLKnQ0o,78934
+pev_synth/validation_bounds_curator.py,sha256=FmcEt-eCZ5AMQvcw96FarCtUACvM96BTIwi7Ij_4NBo,112621
+pev_synth/validator.py,sha256=SqtucMG197ZeDK_u9lDPI5DfcYYB9r5W2bJxgVYDw54,121344
+pev_synth/vehicle_archetypes.py,sha256=Ifd_Mfw76eC2nSpMow573GqophDt9WWygZeY-e6W9zo,81972
+ev_flow-3.0.0.dist-info/METADATA,sha256=5t06x945my1ZBjdFk4GObnZExt2xfJosgLpV8XBbsAg,7589
+ev_flow-3.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ev_flow-3.0.0.dist-info/licenses/LICENSE,sha256=Sz1QYg2p2ekJRUWeWOBUpj7pZm2nPe5jjZQon5vHUXU,1074
+ev_flow-3.0.0.dist-info/RECORD,,

ev_flow-3.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ev_flow-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bertrand Travacca
+
+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.

pev_synth/__init__.py

@@ -0,0 +1,68 @@
+"""pev_synth — Synthetic EV charging dataset pipeline + library API.
+
+Library API (v2.0)
+------------------
+The public surface for downstream code is:
+
+    >>> import pev_synth as ps
+    >>> ps.list_regions()
+    ['bay_area', 'boston', 'chicago', 'dallas_fort_worth', 'la_basin',
+     'new_york_metro', 'seattle', 'us_national']
+    >>> ps.list_profile_types()
+    ['residential', 'workplace']
+    >>> fleet = ps.generate_profiles('residential', n=1000,
+    ...                              region='bay_area')
+    >>> prof = fleet[0]
+    >>> pa = prof.generate_presence_absence('2001-01-01', '2001-01-08')
+
+See ``src/pev_synth/api.py`` and ``docs/pev_synth_api.md`` for details.
+
+Pipeline modules (M1..M9, methodology v2.0.0, master seed 20260520)
+-------------------------------------------------------------------
+* ``nhts_loader``               — NHTS 2017 public-use file loader.
+* ``vehicle_archetypes``        — N-EV archetype sampler (M2).
+* ``donor_matcher``             — NHTS donor-vehicle matcher (M3).
+* ``travel_week_builder``       — one-year travel sequence builder (M4).
+* ``plug_in_model``             — session plug-in / dwell sampler (M5).
+* ``soc_trajectory``            — continuous-time SoC ledger + sessions (M6).
+* ``hourly_resampler``          — 15-min + hourly plug-status rasteriser (M7).
+* ``validation_bounds_curator`` — bound curation (M8).
+* ``validator``                 — §10 validation runner + report writer (M9).
+* ``regions``                   — 8-region registry (Region dataclass).
+* ``_utc_migration``            — package-internal v1.1 → v2.0 UTC cache
+                                  migrator (leading underscore = not part of
+                                  the public API; used only by in-house
+                                  callers with a v1.1 cache to upgrade).
+
+The library API wraps the artifacts these modules produce.
+"""
+
+from __future__ import annotations
+
+from .api import (
+    Fleet,
+    Profile,
+    ProfileType,
+    generate_profiles,
+    regenerate_fleet,
+)
+
+# v2.0: ``list_profile_types`` and the Region registry come from
+# ``pev_synth.regions`` so the public listing returns ``["residential",
+# "workplace"]`` (``fleet_depot`` was de-scoped — plan §2.6).
+from .regions import REGIONS, Region, list_profile_types, list_regions
+
+__version__ = "3.0.0"
+
+__all__ = [
+    "Fleet",
+    "Profile",
+    "ProfileType",
+    "REGIONS",
+    "Region",
+    "generate_profiles",
+    "list_profile_types",
+    "list_regions",
+    "regenerate_fleet",
+    "__version__",
+]

pev_synth/_meta.py

@@ -0,0 +1,266 @@
+"""Single typed writer for the per-cache ``meta.json`` artifact.
+
+RFC-021: seven independent modules (M2 – M7 + cache_regen.finalise +
+validator) currently read-modify-write ``meta.json`` with ad-hoc keys.
+Symptoms include the known ``donor_borrow_rate`` nesting bug and lots of
+silently-overlapping top-level keys.
+
+This module:
+
+* documents the canonical sub-namespaces (one per producer) in
+  :class:`MetaSchema`,
+* exposes :class:`MetaWriter` with ``setdefault``-semantics so the
+  multi-producer pattern stays append-only.
+
+Existing per-module helpers (``update_meta_with_m5``,
+``update_meta_with_m7``, …) continue to work in v2.0-rev — they just
+hand off the atomic write to :func:`MetaWriter.write`. The CLI surface
+is untouched.
+
+Math notation: ASCII.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "MetaSchema",
+    "MetaWriter",
+    "load_meta",
+    "write_meta_atomic",
+]
+
+
+#: Canonical RMW (read-modify-write) stage keys for ``MetaWriter.update``.
+#: Each maps a stage label to (sub_namespace_key, module_provenance_key).
+RMW_STAGES: dict[str, tuple[str, str]] = {
+    "donor_matcher": ("donor_matcher", "m3_donor_matcher"),
+    "soc_trajectory": ("soc_trajectory", "m6_soc_trajectory"),
+    "hourly_resampler": ("hourly_resampler", "m7_hourly_resampler"),
+}
+
+
+@dataclass
+class MetaSchema:
+    """Documented canonical schema for ``meta.json``.
+
+    Each top-level key is owned by one producer; secondary writers MUST
+    use ``setdefault`` semantics to avoid clobbering. This dataclass is
+    informational — it does not enforce key presence at runtime (yet);
+    runtime validation lives in :func:`pev_synth.validator.run`.
+    """
+
+    #: Set by M2 / cache_regen at bootstrap.
+    methodology_version: str = ""
+    master_seed: int = 0
+    region: dict[str, Any] = field(default_factory=dict)
+    profile_type: str = ""
+    cache_provenance: str = ""
+    storage_timezone: str = ""
+    run_timestamp_utc: str = ""
+    git_commit: str = ""
+    #: One sub-namespace per producer module.
+    module_provenance: dict[str, str] = field(default_factory=dict)
+    vehicle_archetypes: dict[str, Any] = field(default_factory=dict)
+    donor_matcher: dict[str, Any] = field(default_factory=dict)
+    travel_week_builder: dict[str, Any] = field(default_factory=dict)
+    plug_in_model: dict[str, Any] = field(default_factory=dict)
+    soc_trajectory: dict[str, Any] = field(default_factory=dict)
+    hourly_resampler: dict[str, Any] = field(default_factory=dict)
+    validator: dict[str, Any] = field(default_factory=dict)
+    #: Aggregate metrics derived from sub-namespaces.
+    donor_borrow_rate: float = 0.0
+    consumption_model: dict[str, Any] = field(default_factory=dict)
+
+    # ---- v3.0 OPTIONAL provenance extensions ---------------------------
+    # All default to ``None`` (or absent on disk via setdefault) so v2.1
+    # meta.json files still validate against this schema unchanged.
+
+    #: Realized NHTS vintage mix actually drawn for this cache (e.g.
+    #: ``{"2017": 1.0}`` for v2.1-style default, or ``{"2017": 0.8,
+    #: "2022_nextgen": 0.2}`` when NextGen enrichment is opted in).
+    nhts_vintage_mix: dict[str, float] | None = None
+
+    #: HOUSEID stitching mode used by M4 — ``"v2_per_travday"`` (legacy
+    #: per-TRAVDAY donor-day reuse) or ``"v3_within_hh"`` (intra-HOUSEID
+    #: person-day reuse with weekday/weekend partition; v3.0 default).
+    houseid_stitch_mode: str | None = None
+
+    #: True when the v3 PHEV gasoline extension (gas_kwh_equivalent
+    #: ledger) is active for this cache; False/None for BEV-only or
+    #: legacy v2.1 runs.
+    phev_modeled: bool | None = None
+
+    #: True when ACS PUMS raking was applied to the household-mix
+    #: expected PMF for this region/profile combination.
+    acs_calibration_applied: bool | None = None
+
+    #: Free-form descriptor of the SPEECh K=16 axis projection in use
+    #: (e.g. ``"start_time_marginal_with_P(G)_prior"``). ``None`` when
+    #: the K=16 SPEECh path is not active (legacy K=6 fit).
+    speech_k16_axis_projection: str | None = None
+
+
+def load_meta(meta_path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Idempotent loader — returns ``{}`` if the file is absent."""
+    p = Path(meta_path)
+    if not p.is_file():
+        return {}
+    with p.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def write_meta_atomic(
+    meta_path: str | os.PathLike[str],
+    meta: dict[str, Any],
+    *,
+    default: Any = None,
+) -> Path:
+    """Atomic JSON write (tmp + os.replace) with sorted keys + indent=2.
+
+    ``default`` is forwarded to :func:`json.dump` to coerce non-trivial
+    payloads (numpy scalars, ``Path``); ``None`` is the standard JSON
+    behaviour.
+    """
+    p = Path(meta_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(p.suffix + ".tmp")
+    with tmp.open("w", encoding="utf-8") as fh:
+        json.dump(meta, fh, indent=2, sort_keys=True, default=default)
+    os.replace(tmp, p)
+    return p
+
+
+class MetaWriter:
+    """Append-only ``meta.json`` writer with ``setdefault`` semantics.
+
+    Usage:
+
+        with MetaWriter(meta_path) as m:
+            m.set_default("methodology_version", "v3.0")
+            m.merge("plug_in_model", {"K_chosen_by_BIC": 4, ...})
+
+    The writer reloads the file on enter and persists atomically on
+    exit. Concurrent writers on the same cache are NOT serialised — the
+    contract is per-stage, sequential.
+    """
+
+    def __init__(self, meta_path: str | os.PathLike[str]) -> None:
+        self.meta_path = Path(meta_path)
+        self.meta: dict[str, Any] = {}
+
+    def __enter__(self) -> MetaWriter:
+        self.meta = load_meta(self.meta_path)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
+        if exc_type is None:
+            write_meta_atomic(self.meta_path, self.meta)
+
+    # ---- ergonomic helpers -------------------------------------------
+
+    def set_default(self, key: str, value: Any) -> None:
+        """``setdefault`` semantics — never overwrite an existing key."""
+        self.meta.setdefault(key, value)
+
+    def set(self, key: str, value: Any) -> None:
+        """Force-set; use only when the producer is the sole owner."""
+        self.meta[key] = value
+
+    def merge(self, key: str, payload: dict[str, Any]) -> None:
+        """Update sub-namespace ``key`` with ``payload`` (shallow merge)."""
+        block = self.meta.setdefault(key, {})
+        if isinstance(block, dict):
+            block.update(payload)
+        else:
+            self.meta[key] = payload
+
+    def record_module(self, module_name: str, methodology_version: str) -> None:
+        """Stamp ``module_provenance[module] = methodology_version``."""
+        prov = self.meta.setdefault("module_provenance", {})
+        if isinstance(prov, dict):
+            prov[module_name] = methodology_version
+
+    # ---- RFC-021.r unified update entry point ------------------------
+
+    @classmethod
+    def update(
+        cls,
+        meta_path: str | os.PathLike[str],
+        *,
+        stage: str,
+        payload: dict[str, Any],
+        methodology_version: str | None = None,
+        top_level: dict[str, Any] | None = None,
+        json_default: Any = None,
+    ) -> Path:
+        """Single-call read-modify-write for one RMW stage.
+
+        Parameters
+        ----------
+        meta_path:
+            Path to the cache's ``meta.json``.
+        stage:
+            One of the keys in :data:`RMW_STAGES` (``donor_matcher``,
+            ``soc_trajectory``, ``hourly_resampler``). Determines which
+            sub-namespace block and which ``module_provenance`` key the
+            payload writes through.
+        payload:
+            Block-level dict appended under ``meta[<sub_namespace>]``.
+        methodology_version:
+            If given, also stamped into
+            ``meta.module_provenance[<prov_key>]``. When omitted, the
+            value is read from ``payload['methodology_version']`` if
+            present.
+        top_level:
+            Optional sibling keys to merge at the root of ``meta`` (e.g.
+            ``{"donor_borrow_rate": 0.07, "package_versions": {...}}``).
+            Uses shallow ``dict.update`` for nested dict values.
+        json_default:
+            Forwarded to :func:`json.dump` (e.g. a numpy coercer).
+
+        Returns
+        -------
+        Path
+            The path the meta was written to (same as ``meta_path``).
+        """
+        if stage not in RMW_STAGES:
+            raise KeyError(
+                f"unknown RMW stage {stage!r}; "
+                f"valid keys: {sorted(RMW_STAGES)}"
+            )
+        sub_key, prov_key = RMW_STAGES[stage]
+
+        p = Path(meta_path)
+        meta = load_meta(p)
+
+        # Sub-namespace block: force-set (single owner per RMW stage).
+        meta[sub_key] = dict(payload)
+
+        # Module provenance stamp.
+        version = methodology_version
+        if version is None:
+            version = payload.get("methodology_version")
+        if version is not None:
+            prov = meta.setdefault("module_provenance", {})
+            if isinstance(prov, dict):
+                prov[prov_key] = version
+
+        # Top-level sibling merges (e.g. donor_borrow_rate, run_timestamp_utc,
+        # package_versions). Nested dicts are shallow-merged; scalars overwrite.
+        if top_level:
+            for k, v in top_level.items():
+                if (
+                    isinstance(v, dict)
+                    and isinstance(meta.get(k), dict)
+                ):
+                    meta[k].update(v)
+                else:
+                    meta[k] = v
+
+        return write_meta_atomic(p, meta, default=json_default)

pev_synth/_paths.py

@@ -0,0 +1,116 @@
+"""Central path registry for ``pev_synth``.
+
+This module is the **single source of truth** for the repo-root path and
+every ``data/pev/...`` subtree the package reads or writes. Replaces six
+repeated ``Path(__file__).resolve().parents[2]`` computations across
+modules (Arch:A2-1, Dev:P2).
+
+All helpers return absolute :class:`pathlib.Path` instances.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+__all__ = [
+    "repo_root",
+    "data_root",
+    "raw_root",
+    "processed_root",
+    "intermediate_root",
+    "nhts_intermediate_root",
+    "validation_bounds_root",
+    "cache_dir",
+    "replicate_dir",
+]
+
+
+def repo_root() -> Path:
+    """Return the absolute path to the repository root.
+
+    Anchored on this file's location: ``src/pev_synth/_paths.py`` is two
+    levels deep under the repo root.
+    """
+    return Path(__file__).resolve().parents[2]
+
+
+def data_root() -> Path:
+    """Return the package data root.
+
+    Resolution order:
+      1. If env var ``PEV_SYNTH_DATA_ROOT`` is set, use that (resolved to
+         an absolute path). This is the supported override for users who
+         pip-installed ``ev-flow`` and keep their data elsewhere on disk.
+      2. Otherwise fall back to ``<repo_root>/data`` — the dev layout
+         where ``data/`` sits next to ``src/``.
+
+    All downstream helpers (``raw_root``, ``processed_root``,
+    ``intermediate_root``, ``validation_bounds_root``, ``cache_dir``,
+    ``replicate_dir``) chain through this function, so the override
+    propagates everywhere.
+    """
+    env = os.environ.get("PEV_SYNTH_DATA_ROOT")
+    if env:
+        return Path(env).expanduser().resolve()
+    return repo_root() / "data"
+
+
+def raw_root() -> Path:
+    """``<repo_root>/data/pev/raw`` — raw inputs (CSVs, NHTS, …)."""
+    return data_root() / "pev" / "raw"
+
+
+def processed_root() -> Path:
+    """``<repo_root>/data/pev/processed`` — per-region cached outputs."""
+    return data_root() / "pev" / "processed"
+
+
+def intermediate_root() -> Path:
+    """``<repo_root>/data/pev/intermediate``."""
+    return data_root() / "pev" / "intermediate"
+
+
+def nhts_intermediate_root(region: str | None = None) -> Path:
+    """Return ``data/pev/intermediate/nhts`` or, optionally, a region subdir.
+
+    The per-region NHTS parquets (``hhpub.parquet`` etc.) live under
+    ``intermediate/nhts/<region.name>/`` per the brief (line 103) and
+    RFC-014 / RFC-017.
+    """
+    base = intermediate_root() / "nhts"
+    if region is None:
+        return base
+    return base / region
+
+
+def validation_bounds_root() -> Path:
+    """``<repo_root>/data/pev/validation_bounds``.
+
+    Per RFC-009 the brief layout is per-region:
+    ``<root>/<region>/<profile_type>/<check_id>.parquet``.
+    """
+    return data_root() / "pev" / "validation_bounds"
+
+
+def cache_dir(region: str, profile_type: str) -> Path:
+    """Return the v2.0-native cache root for one ``(region, profile_type)``.
+
+    ``<processed_root>/<region>/<profile_type>_ev_synth``. Matches the brief
+    line 11 layout.
+    """
+    return processed_root() / region / f"{profile_type}_ev_synth"
+
+
+def replicate_dir(region: str, profile_type: str, r: int, R: int = 1) -> Path:
+    """Return the replicate directory for ``(region, profile_type, r)``.
+
+    Per brief line 11 / RFC-022:
+
+    * R == 1: flat layout — returns the cache_dir itself (r=0 alias).
+    * R > 1: nested layout — ``<cache_dir>/replicates/r{r}/``.
+    """
+    base = cache_dir(region, profile_type)
+    if R <= 1:
+        return base
+    return base / "replicates" / f"r{int(r)}"