ev-flow: A Reproducible, NHTS-Grounded Generator of Synthetic Plug-in Electric Vehicle Charging Behavior for Eight U.S. Regions

Abstract

Electric-vehicle grid-integration studies need large, behaviorally realistic populations of individual charging profiles, but real charging telemetry is scarce and privacy-restricted, and the existing open generators are calibrated to non-U.S. mobility surveys or flatten the regional, seasonal, and equipment heterogeneity that drives aggregate demand. We present \texttt{ev-flow} (import name \texttt{pev\_synth}), an open-source, MIT-licensed Python package that generates synthetic plug-in electric vehicle charging behavior for eight U.S. regions, grounded in 2017 National Household Travel Survey (NHTS) microdata and regional sales-mix models. A deterministic nine-stage pipeline (M1--M9) carries each vehicle from survey records to a time-stamped charging profile: it stitches survey person-days into donor-matched 365-day travel calendars with a temperature-dependent winter energy uplift, samples behavioral plug-in start times from the published SPEECh K=16 Gaussian-mixture parameterization, evaluates a three-layer Bernoulli plug-in model, propagates a continuous-time state-of-charge ledger with an explicit PHEV gasoline range-extension term, and rasterizes plug status to 15-minute and hourly grids. The package generates residential and workplace profile types with descriptive EVSE brand and connector enrichment; every output is UTC-stored, timezone-aware, and bit-reproducible from a single master seed. A validation runner compares the generated distributions against published bounds and classifies every divergence with literature provenance: the reference \texttt{bay\_area} residential profile rolls up to 11 PASS, 0 unexplained FAIL, 6 explained failures, and 4 explained skips across 21 applicable checks. \texttt{ev-flow} fills a U.S.-focused, NHTS-grounded niche complementary to European generators such as emobpy and VencoPy and to charging simulators such as datafev and ACN-Sim.