3. Workflow Guide

This section describes the end-to-end workflow and provides runnable commands you can adapt.

Quick Start

Adjust paths, states, and design variants as needed. Example commands assume your repo layout matches the folders below.

3.1 Repository Layout

dss_xlrm/
├── 0_code_xlrm/           # Experimental design generation
├── 1b_smartds_eulp_match/ # Circuit-building matching
├── 1c_eulp_downloads/     # EULP data acquisition
├── 2_profiles_heat_pumps/ # Profile generation (baseline)
├── 3_kvar_kw_prep/        # Reactive power ratios
├── 4_profiles_heat_pumps_dm/  # Demand management profiles
├── 5_profiles_heat_pumps_un/  # Uncontrolled profiles
├── 6_instantiate_circuits_*/  # Instantiation & simulation
└── 7_results_analysis/    # Aggregation & analysis

3.2 Phase-by-Phase

Phase 1 — Experimental Design (0_code_xlrm)

  • Generate scenario dictionaries using DOE (LHS/Sobol). N_CASES controls scenario count.

  • Key script: run_mix_generator.py

  • Outputs: mixes_lhs.json, mixes_sobol.json

cd 0_code_xlrm
python run_mix_generator.py

Phase 2 — Circuit ↔ Building Matching (1b_smartds_eulp_match)

Sequential scripts:

  1. copy_circuits.py — Copy Smart-DS circuits to working dir

  2. circuit_make_daily_list_sets.py — Extract daily load patterns

  3. review_parquet_matches.py — Review available parquet files

  4. match_smartds_parquets_NC.py — Match circuits to EULP profiles

  5. clean_up_bldgs_NC.py — Filter/organize building data

  6. select_rep_family_NC.py — Select representative buildings

cd ../1b_smartds_eulp_match
python copy_circuits.py
python circuit_make_daily_list_sets.py
python review_parquet_matches.py
python match_smartds_parquets_NC.py
python clean_up_bldgs_NC.py
python select_rep_family_NC.py

Phase 3 — Data Acquisition (1c_eulp_downloads)

Download EULP parquet files from OEDI (open access).

cd ../1c_eulp_downloads
python download_parquets_homes_NC.py
python download_parquets_commercial_NC.py

Phase 4 — Profile Generation (2/4/5 profiles)

Variants: baseline (2_profiles_heat_pumps), demand management (4_profiles_heat_pumps_dm), uncontrolled (5_profiles_heat_pumps_un).

Typical workflow:

cd ../2_profiles_heat_pumps
python scale_feeder_curves_NC.py
python find_max_day_curve_NC.py
python plot_parquet_differences.py
python get_scenario_csv_controls.py

Phase 5 — Reactive Power Preparation (3_kvar_kw_prep)

Run the longer job to build reactive power ratios (kVAr/kW).

cd ../3_kvar_kw_prep
python rev_spec_kvar_kw_ratio.py   # ~579 minutes for full dataset

Phase 6 — Circuit Instantiation & Simulation (6_instantiate_circuits_*)

Create circuit instances, assign DERs, and run power flow simulations.

  • Main script: instantiate_circuits_and_runs_APPLYFILTER.py

  • Runner: power_flow_sim_daily_EV_STO_DG_deploy.py

  • Features: EV assignments (controlled/uncontrolled), PV/storage placement, heat pump profiles (baseline/DM/uncontrolled)

cd ../6_instantiate_circuits_summer_lhs   # example path; adjust for season/design
python instantiate_circuits_and_runs_APPLYFILTER.py
python power_flow_sim_daily_EV_STO_DG_deploy.py

Phase 7 — Results Analysis (7_results_analysis)

Aggregate across scenarios, seasons, and DOE designs.

cd ../7_results_analysis
python append_experiment_results.py

3.3 Configuration Highlights

  • States: NC, TX, CA (with circuit filtering for connection issues)

  • Seasons: Summer, Winter

  • Scenario parameters: EV 5–80%, storage 0–20%, PV 0–20%, heat pump shares (baseline/DM/uncontrolled)

  • Storage control: Peak shaving algorithm customizable (see get_scenario_csv_controls.py and instantiation scripts)

Tip — Storage Controller Defaults (example)

  • Sizing vs. peak: 0.75×

  • Duration: 4 h

  • Peak target factor: 0.8

  • Reserve: 20%