ev-flow 3.0.0__tar.gz → 3.0.2__tar.gz

{ev_flow-3.0.0 → ev_flow-3.0.2}/.gitignore

@@ -44,11 +44,5 @@ results/
 # 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
+# Internal working docs kept on the local dev machine, not published.
 docs/

ev_flow-3.0.2/ATTRIBUTION.md

@@ -0,0 +1,76 @@
+# Data sources, licensing & attribution
+
+`ev-flow` is MIT-licensed (see [LICENSE](LICENSE)). It is grounded in several
+upstream public data sources. This file discharges the attribution and notice
+obligations of those sources. Two notices below are **legally required** and
+are reproduced verbatim; the remainder are courtesy citations (the data is
+either U.S. Government public-domain or carries no binding attribution clause,
+but we credit it as a matter of scientific good practice).
+
+`ev-flow`'s code is built to consume the SPEECh Original Model — its loader,
+schema, and CC-BY citations live in `pev_synth.plug_in_model`. The SPEECh-derived
+JSON is built by the user from the upstream Mendeley source and is **not**
+redistributed in the wheel, but SPEECh is the load-bearing model dependency, so
+its CC-BY-4.0 notice is reproduced here (and in the source). This file is shipped
+in the sdist.
+
+---
+
+## Required notices
+
+### SPEECh Original Model — CC BY 4.0
+
+> Contains data from "SPEECh Original Model" by Siobhan Powell, Gustavo Vianna
+> Cezar, and Ram Rajagopal, Mendeley Data, V1 (2021),
+> <https://doi.org/10.17632/gvk34mybtb.1>, licensed under CC BY 4.0
+> (<https://creativecommons.org/licenses/by/4.0/>). **Modified:** a subset of
+> the home and work driver-group Gaussian-mixture components was converted from
+> pickle to JSON and reweighted.
+
+Associated publication: Powell, S.; Cezar, G. V.; Rajagopal, R. (2022).
+*Scalable probabilistic estimates of electric vehicle charging given observed
+driver behavior.* Applied Energy 309, 118382.
+<https://doi.org/10.1016/j.apenergy.2021.118382>
+
+### U.S. Census Bureau Data API — required disclaimer
+
+`pev_synth.acs_loader` accesses the Census Bureau Data API at runtime. Per the
+[Census Data API Terms of Service](https://www.census.gov/data/developers/about/terms-of-service.html),
+any product using the API must display the following notice:
+
+> This product uses the Census Bureau Data API but is not endorsed or certified
+> by the Census Bureau.
+
+(The underlying ACS PUMS statistics are public domain; this is an
+endorsement-disclaimer, not a copyright attribution. The Census terms also
+prohibit using the data to re-identify any individual, household, or entity.)
+
+---
+
+## Courtesy citations
+
+These sources impose no binding attribution requirement on `ev-flow`, but are
+credited here.
+
+| Source | Used for | License / status | Citation |
+|---|---|---|---|
+| **NHTS 2017** (& NextGen 2022) — USDOT/FHWA, hosted by ORNL | Travel micro-data backbone (`nhts_loader`, `nhts_nextgen_loader`) | U.S. Government work — public domain (17 U.S.C. §105); public-use confidentiality condition (no respondent re-identification) | U.S. Department of Transportation, Federal Highway Administration. 2017 National Household Travel Survey (and 2022 NextGen NHTS). <https://nhts.ornl.gov> |
+| **U.S. Census ACS 5-Year PUMS** | Household-mix raking/calibration (`acs_loader`) | U.S. Government work — public domain; API use governed by Census Data API ToS (see required notice above) | U.S. Census Bureau, ACS 5-Year PUMS, via the Census Data API. <https://api.census.gov/data> |
+| **EPA / DOE fueleconomy.gov** | PHEV combined fuel economy (`_phev_fuel_economy`) | U.S. Government data — public domain (17 U.S.C. §105); site administered by ORNL for DOE/EPA | U.S. EPA & U.S. DOE, fueleconomy.gov vehicle data. <https://www.fueleconomy.gov/ws/> |
+| **EV WATTS Public Database** — DOE/Energetics (INL, NREL, PNNL) | Workplace cohort calibration & validation bounds (`sales_mix_data`, `validation_bounds_curator`) | DOE-sponsored public dataset; attribution requested, not required | Pritchard, E. *EV Watts Public Database.* U.S. DOE, 2023. <https://doi.org/10.15483/1970735> |
+| **California CVRP rebate statistics** | CA regional BEV/PHEV sales-mix weights (`sales_mix_data`) | © Center for Sustainable Energy (for CARB); no open-data license; aggregate facts, partly re-derived | California Clean Vehicle Rebate Project (CVRP), Center for Sustainable Energy / CARB. <https://cleanvehiclerebate.org/en/rebate-statistics> |
+| **NYSERDA Drive Clean Rebate** | NY regional sales-mix weights (approximation) (`sales_mix_data`) | NY State Open Data (Open NY) Terms of Use — permissive, no attribution required | NYSERDA Electric Vehicle Drive Clean Rebate Data (Open NY). <https://data.ny.gov/Energy-Environment/NYSERDA-Electric-Vehicle-Drive-Clean-Rebate-Data-B/thd2-fu8y> |
+| **Argonne National Laboratory — EV-FACTS** | National BEV/PHEV sales-mix shape (`sales_mix_data`) | Published DOE/Argonne analysis (© UChicago Argonne, LLC); aggregate share data is non-copyrightable fact | Argonne National Laboratory, Light-Duty Electric Drive Vehicles Monthly Sales Updates / EV-FACTS. <https://www.anl.gov/ev-facts/model-sales> |
+| **NOAA NCEI** — Integrated Surface Database / U.S. Climate Normals 1991–2020 | Winter ambient-temperature uplift (`travel_week_builder`, `regions`) | U.S. Government work — public domain (NCEI applies CC0-1.0); attribution requested | NOAA National Centers for Environmental Information, Integrated Surface Database / U.S. Climate Normals 1991–2020. |
+| **NREL technical reports** (TP-5400-81065, TP-5400-69031, CP-5400-85902) & EVI-Pro Lite | Modeling priors & validation bounds (`vehicle_archetypes`, `validation_bounds_curator`) | U.S. Government-sponsored publications; scholarly citation | National Renewable Energy Laboratory, U.S. DOE. (Report numbers cited inline in source.) |
+
+**CAISO** market prices are *not* shipped with `ev-flow`. The optional
+`caiso_data` dependency (imported behind a guard in `validator`) is a separate
+package; if a downstream user supplies it, CAISO's own terms apply to that user.
+
+---
+
+*This audit was performed against each source's official terms. Where a source
+could not be verified to high confidence, it is credited conservatively. If you
+are a rights holder and believe attribution here is incorrect, please open an
+issue.*

ev_flow-3.0.2/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to **ev-flow** are documented here. This project follows
+[Semantic Versioning](https://semver.org).
+
+## [3.0.2] - 2026-06-09
+
+### Added
+- The PEP 561 `py.typed` marker now ships inside the `pev_synth` wheel, so
+  downstream type checkers (mypy, pyright) pick up ev-flow's inline type hints
+  when the package is installed from PyPI.
+- `ATTRIBUTION.md` is now included in the source distribution, documenting every
+  upstream data source's license and the required SPEECh (CC BY 4.0) and U.S.
+  Census Bureau Data API notices.
+
+### Fixed
+- Cross-platform correctness: all `meta.json`, `validation_report.json`, and
+  `validation_report.md` reads and writes in `api` and `validator` now pass an
+  explicit `encoding="utf-8"`, instead of relying on the platform default
+  encoding. This makes bundle metadata and validation reports round-trip
+  identically on Windows (where the default was previously `cp1252`).
+
+## [3.0.1] - 2026-06-02
+
+### Fixed
+- Pin `pandas>=2.2,<3`. pandas 3.0 changed the default datetime resolution
+  from nanoseconds to microseconds, which broke the 15-minute plug-status
+  rasteriser, the SoC-trajectory parquet schema, and UTC/DST timestamp
+  handling for users who resolved pandas 3.0 on Python 3.11+. The published
+  3.0.0 declared an uncapped `pandas>=2.2`; this release caps it.
+
+## [3.0.0] - 2026-06-01
+
+### Added
+- Initial public release. Synthetic plug-in electric vehicle charging dataset
+  pipeline and library API, grounded in NHTS 2017 micro-data and a regional
+  sales-mix model across 8 US regions.
+- PyPI distribution name `ev-flow`; Python import name `pev_synth`.
+
+[3.0.2]: https://github.com/bertravacca/ev-flow/releases/tag/v3.0.2
+[3.0.1]: https://github.com/bertravacca/ev-flow/releases/tag/v3.0.1
+[3.0.0]: https://github.com/bertravacca/ev-flow/releases/tag/v3.0.0

{ev_flow-3.0.0 → ev_flow-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ev-flow
-Version: 3.0.0
+Version: 3.0.2
 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
@@ -41,14 +41,16 @@ 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: pandas<3,>=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: bandit>=1.7; extra == 'dev'
 Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
@@ -57,6 +59,14 @@ Description-Content-Type: text/markdown
 
 # ev-flow
 
+[![CI](https://github.com/bertravacca/ev-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/bertravacca/ev-flow/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/bertravacca/ev-flow/branch/main/graph/badge.svg)](https://codecov.io/gh/bertravacca/ev-flow)
+[![security](https://github.com/bertravacca/ev-flow/actions/workflows/security.yml/badge.svg)](https://github.com/bertravacca/ev-flow/actions/workflows/security.yml)
+[![PyPI version](https://img.shields.io/pypi/v/ev-flow.svg)](https://pypi.org/project/ev-flow/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ev-flow.svg)](https://pypi.org/project/ev-flow/)
+[![DOI](https://zenodo.org/badge/1245084094.svg)](https://zenodo.org/badge/latestdoi/1245084094)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 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.
@@ -154,6 +164,29 @@ pip install -e ".[dev]"
 pytest
 ```
 
+## Versioning
+
+`ev-flow` follows [Semantic Versioning](https://semver.org). See
+[`documentation/versioning.md`](documentation/versioning.md) for what counts as
+a major/minor/patch change, the deprecation policy, and the distinction between
+the package version and a cache's `methodology_version`.
+
+## Data sources & attribution
+
+`ev-flow` is grounded in public data sources. Two upstream notices are required:
+
+- **SPEECh Original Model** (Powell, Cezar & Rajagopal, Mendeley Data, 2021) is
+  licensed **CC BY 4.0**. ev-flow consumes a modified (pickle→JSON, reweighted)
+  subset of its driver-group mixtures. <https://doi.org/10.17632/gvk34mybtb.1>
+- This product uses the **U.S. Census Bureau Data API** but is not endorsed or
+  certified by the Census Bureau.
+
+Full per-source licensing, citations, and the modification statement are in
+[`ATTRIBUTION.md`](ATTRIBUTION.md) (NHTS, Census ACS PUMS, EPA fueleconomy.gov,
+EV WATTS, CVRP, NYSERDA, Argonne EV-FACTS, NOAA, NREL).
+
 ## License
 
-MIT. See `LICENSE`.
+MIT. See `LICENSE`. Note that the MIT license covers the `ev-flow` *code*; the
+upstream data sources retain their own licenses — see
+[`ATTRIBUTION.md`](ATTRIBUTION.md).

{ev_flow-3.0.0 → ev_flow-3.0.2}/README.md

@@ -1,5 +1,13 @@
 # ev-flow
 
+[![CI](https://github.com/bertravacca/ev-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/bertravacca/ev-flow/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/bertravacca/ev-flow/branch/main/graph/badge.svg)](https://codecov.io/gh/bertravacca/ev-flow)
+[![security](https://github.com/bertravacca/ev-flow/actions/workflows/security.yml/badge.svg)](https://github.com/bertravacca/ev-flow/actions/workflows/security.yml)
+[![PyPI version](https://img.shields.io/pypi/v/ev-flow.svg)](https://pypi.org/project/ev-flow/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ev-flow.svg)](https://pypi.org/project/ev-flow/)
+[![DOI](https://zenodo.org/badge/1245084094.svg)](https://zenodo.org/badge/latestdoi/1245084094)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 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.
@@ -97,6 +105,29 @@ pip install -e ".[dev]"
 pytest
 ```
 
+## Versioning
+
+`ev-flow` follows [Semantic Versioning](https://semver.org). See
+[`documentation/versioning.md`](documentation/versioning.md) for what counts as
+a major/minor/patch change, the deprecation policy, and the distinction between
+the package version and a cache's `methodology_version`.
+
+## Data sources & attribution
+
+`ev-flow` is grounded in public data sources. Two upstream notices are required:
+
+- **SPEECh Original Model** (Powell, Cezar & Rajagopal, Mendeley Data, 2021) is
+  licensed **CC BY 4.0**. ev-flow consumes a modified (pickle→JSON, reweighted)
+  subset of its driver-group mixtures. <https://doi.org/10.17632/gvk34mybtb.1>
+- This product uses the **U.S. Census Bureau Data API** but is not endorsed or
+  certified by the Census Bureau.
+
+Full per-source licensing, citations, and the modification statement are in
+[`ATTRIBUTION.md`](ATTRIBUTION.md) (NHTS, Census ACS PUMS, EPA fueleconomy.gov,
+EV WATTS, CVRP, NYSERDA, Argonne EV-FACTS, NOAA, NREL).
+
 ## License
 
-MIT. See `LICENSE`.
+MIT. See `LICENSE`. Note that the MIT license covers the `ev-flow` *code*; the
+upstream data sources retain their own licenses — see
+[`ATTRIBUTION.md`](ATTRIBUTION.md).

{ev_flow-3.0.0 → ev_flow-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ev-flow"
-version = "3.0.0"
+version = "3.0.2"
 description = "Synthetic plug-in electric vehicle charging dataset pipeline and library API."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,7 +35,7 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=1.26",
-    "pandas>=2.2",
+    "pandas>=2.2,<3",
     "pyarrow>=16",
     "requests>=2.32",
     "scikit-learn>=1.4",
@@ -50,6 +50,8 @@ dev = [
     "ruff>=0.5",
     "build>=1.2",
     "twine>=5",
+    "bandit>=1.7",
+    "pip-audit>=2.7",
 ]
 
 [project.urls]
@@ -73,6 +75,8 @@ only-include = [
     "src/pev_synth",
     "README.md",
     "LICENSE",
+    "ATTRIBUTION.md",
+    "CHANGELOG.md",
     "pyproject.toml",
 ]
 

{ev_flow-3.0.0 → ev_flow-3.0.2}/src/pev_synth/__init__.py

@@ -52,7 +52,7 @@ from .api import (
 # "workplace"]`` (``fleet_depot`` was de-scoped — plan §2.6).
 from .regions import REGIONS, Region, list_profile_types, list_regions
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"
 
 __all__ = [
     "Fleet",

{ev_flow-3.0.0 → ev_flow-3.0.2}/src/pev_synth/api.py

@@ -1471,7 +1471,7 @@ class Fleet:
             "api_version": _api_version,
             "storage_timezone": _STORAGE_TZ,
         }
-        with (target / "meta.json").open("w") as f:
+        with (target / "meta.json").open("w", encoding="utf-8") as f:
             json.dump(meta_out, f, indent=2, default=str)
 
         return target
@@ -1498,7 +1498,7 @@ class Fleet:
                 f"meta.json is required to load a Fleet bundle; "
                 f"expected at {meta_file}"
             )
-        with meta_file.open() as f:
+        with meta_file.open(encoding="utf-8") as f:
             meta = json.load(f)
         profile_type = meta.get("profile_type")
         if not isinstance(profile_type, str) or not profile_type:
@@ -1700,7 +1700,7 @@ def generate_profiles(
     meta: dict[str, Any] = {}
     if meta_file.exists():
         try:
-            with meta_file.open() as f:
+            with meta_file.open(encoding="utf-8") as f:
                 meta = json.load(f)
         except json.JSONDecodeError:
             meta = {}

ev_flow-3.0.2/src/pev_synth/py.typed

@@ -0,0 +1 @@
+

{ev_flow-3.0.0 → ev_flow-3.0.2}/src/pev_synth/validator.py

@@ -2587,7 +2587,7 @@ def run(
     meta_for_checks: dict[str, Any] = {}
     meta_path = output_root / "meta.json"
     if meta_path.exists():
-        with meta_path.open() as f:
+        with meta_path.open(encoding="utf-8") as f:
             meta_for_checks = json.load(f)
 
     # RFC-008.r — the legacy ``energy_kwh`` alias is acceptable ONLY when
@@ -2862,10 +2862,10 @@ def run(
     # Write JSON + MD.
     json_path = output_root / "validation_report.json"
     md_path = output_root / "validation_report.md"
-    with json_path.open("w") as f:
+    with json_path.open("w", encoding="utf-8") as f:
         json.dump(report.to_dict(), f, indent=2, sort_keys=False, default=str)
         f.write("\n")
-    md_path.write_text(_emit_markdown(report) + "\n")
+    md_path.write_text(_emit_markdown(report) + "\n", encoding="utf-8")
 
     # Update meta.json with M9 provenance (idempotent — overwrites the
     # `validator` key only; keeps everything else byte-stable except for
@@ -2958,7 +2958,8 @@ def _run_with_replicates(
     # Re-emit the markdown with the aggregated (mean, std, n=R) columns.
     md_path = parent_root / "validation_report.md"
     md_path.write_text(
-        _emit_markdown(canonical, replicate_stats=replicate_stats, R=R) + "\n"
+        _emit_markdown(canonical, replicate_stats=replicate_stats, R=R) + "\n",
+        encoding="utf-8",
     )
     # Re-emit JSON with the replicate stats appended.
     aggregated = canonical.to_dict()
@@ -2968,7 +2969,7 @@ def _run_with_replicates(
     }
     aggregated["replicates"] = {"R": R, "n_dirs": len(replicate_dirs)}
     json_path = parent_root / "validation_report.json"
-    with json_path.open("w") as f:
+    with json_path.open("w", encoding="utf-8") as f:
         json.dump(aggregated, f, indent=2, sort_keys=False, default=str)
         f.write("\n")
 
@@ -2995,7 +2996,7 @@ def _update_meta_json(meta_path: Path, report: Report) -> None:
     :data:`MASTER_SEED`.
     """
     if meta_path.exists():
-        with meta_path.open() as f:
+        with meta_path.open(encoding="utf-8") as f:
             meta = json.load(f)
     else:
         meta = {}
@@ -3015,7 +3016,7 @@ def _update_meta_json(meta_path: Path, report: Report) -> None:
         "report_json": "validation_report.json",
         "report_md": "validation_report.md",
     }
-    with meta_path.open("w") as f:
+    with meta_path.open("w", encoding="utf-8") as f:
         json.dump(meta, f, indent=2, sort_keys=True)
         f.write("\n")