ev-flow 3.0.0__tar.gz

ev_flow-3.0.0/.gitignore

@@ -0,0 +1,54 @@
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Notebooks
+*.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*~
+
+# Secrets / local config
+.env
+.env.*
+!.env.example
+
+# Local data caches (if any are dropped here during development)
+data/
+results/
+
+# In-progress scientific-publication work — separate effort with its own
+# tooling/repo; not part of the ev-flow package.
+docs/Scientific publication/
+
+# Private / internal: AI-assistant instructions and internal working docs.
+# These stay on the local dev machine and are deliberately NOT published to
+# the public GitHub repo. Public-facing docs live in documentation/ instead.
+CLAUDE.md
+AGENTS.md
+.cursorrules
+.github/copilot-instructions.md
+docs/

ev_flow-3.0.0/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.

ev_flow-3.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ev-flow"
+version = "3.0.0"
+description = "Synthetic plug-in electric vehicle charging dataset pipeline and library API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Bertrand Travacca", email = "bertrand.travacca@gmail.com" },
+]
+keywords = [
+    "electric-vehicles",
+    "ev",
+    "charging",
+    "synthetic-data",
+    "energy",
+    "grid",
+    "nhts",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.26",
+    "pandas>=2.2",
+    "pyarrow>=16",
+    "requests>=2.32",
+    "scikit-learn>=1.4",
+    "scipy>=1.12",
+    "pytz>=2024.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.5",
+    "build>=1.2",
+    "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/bertravacca/ev-flow"
+Repository = "https://github.com/bertravacca/ev-flow"
+Issues = "https://github.com/bertravacca/ev-flow/issues"
+
+# --- Hatch build configuration ---------------------------------------------
+# Only the src/pev_synth/ tree is packaged. Everything else at the repo root
+# (README, LICENSE, tests/, CI config, etc.) lives in the repo but is
+# excluded from the published wheel/sdist by packaging only src/pev_synth.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pev_synth"]
+
+# ``only-include`` is an allowlist: the sdist ships exactly these paths (plus
+# the auto-generated PKG-INFO). ``include`` alone is not exclusive under
+# hatchling and was leaking docs/ and .gitignore into the sdist.
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/pev_synth",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+# --- Tooling ---------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

ev_flow-3.0.0/src/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__",
+]