API Reference

solve_ots(opt_parameters::Dict)

Solve an Optimal Transmission Switching problem with wildfire risk considerations.

Required Parameters

• :network => String - Network name (e.g., "RTS", "CATS", "Texas7k", "Texas2k", "WECC240")
• :model => String - "DCOTS", "LACOTS", "DCOPF", or "LACOPF"
  • DCOTS/LACOTS: wildfire-aware optimal transmission switching
  • DCOPF/LACOPF: pure OPF (no wildfire risk, no line de-energization). Investment options (battery, solar, hardening) still apply. Allowed objectives: "loadshed" or "cost".
• :objective => String - "loadshed", "wildfire", "cost", or "tradeoff" (DCOPF/LACOPF: "loadshed" or "cost" only)
• :times => Array or String - Time specification:
  • Array of tuples: [(year, month, day), ...]
  • Year string: "2020"
  • Month string: "June 2021"

Optional Parameters

• :switching_method => String - Solution method: "optimal" (default) or "thresholded"
• :wildfire_data => Dict - Wildfire risk data (lineid => riskvalue). Auto-loaded from data/USGS_FPI if not provided
• :risk_metric => String - For CATS: risk metric to use ("maxwfpi", "meanwfpi", "cumwfpi", etc.) (default: "cumwfpi")
• :T => Int - Hours per day (default: 24)
• :tradeoff_weight => Float64 - For "tradeoff" objective, 0=loadshed, 1=wildfire (default: 0.5)
• :threshold => Float64 - Risk threshold (loadshed obj) or loadshed threshold (wildfire obj). Required for "thresholded" method.
• :threshold_pct => Float64 - Percentage threshold (0.8 = keep 80% of risk, remove 20%)
• :voll => Float64 - Value of Lost Load in USD/MWh for "cost" objective (default: 10000.0)
• :warm_start => Dict or String - For LACOTS: warm start values or "auto" to run DCOTS first
• :non_linear => Bool - For LACOTS: use non-linear apparent power constraints (default: false)
• :time_limit => Float64 - Solver time limit in seconds (default: 86400.0)
• :mip_gap => Float64 - MIP optimality gap (default: 0.01)
• :output_format => String - "dict", "jld2", or "txt" (default: "dict")
• :output_path => String - File path for output (required if format is "jld2" or "txt")
• :lp_str => String - If provided, save the optimization model to an LP file at this path (default: "")
• :log_str => String - If provided, save Gurobi solver log output to a file at this path (default: "")

Returns

Results dictionary or writes to file based on output_format

verify_ac(ac_parameters::Dict, planning_results::Union{Dict,Nothing}=nothing)

Run package-owned polar AC feasibility checks (mode = "ACPF") or redispatch with load shedding (mode = "ACOPF"). Planning results are replayed as fixed line statuses, fixed load allocations, and fixed resource capacities; no AC planning variables are created.

plot_results(results, features; format="pdf", output_dir=".", plot_dir="", day=nothing, infrastructure_off=false, ls_off=false, kwargs...)

Generate publication-quality plots from solve_ots() results.

Arguments

• results: Dict from solveots(), String path to .jld2 file, or Vector{Dict} for :tradeoffcurve
• features: Vector of Symbols — which plots to generate (see documentation for full list)
• format: Output format — "png", "pdf", "svg", "eps" (default: "pdf")
• output_dir: Directory to save output files (default: current directory)
• plot_dir: Alternative to output_dir — if non-empty, takes precedence (default: "")
• day: For geographic plots — nothing=aggregate view, Int=specific day (default: nothing)
• infrastructure_off: For :network_overview — hide infrastructure layer (batteries, solar, hardened lines) (default: false)
• ls_off: For :network_overview — hide load shed bubble layer (default: false)
• kwargs...: Passed through to underlying renderers (dpi, size, fontsize, etc.)

Feature Symbols

• :network_overview — All layers combined (branches, buses, infrastructure, load shed)
• :load_shed_timeseries — Hourly load shedding bar chart (T1)
• :battery_dispatch — SOC and charge/discharge profiles (T2)
• :solar_generation — Hourly solar generation (T3)
• :generation_dispatch — Total generation over time (T4)
• :tradeoff_curve — Risk vs. load shed Pareto curve (S1); requires Vector{Dict} input
• :cost_breakdown — Infrastructure cost bar chart (S2)

load_txt(filepath::String) -> Dict

Load results from a text file saved by save_txt. Returns a dictionary containing all variable data.

get_network_solar_data(network_name::String, date; api_key::String="", save_to_file::Bool=false, output_dir::String="")

Fetch solar generation profiles for all buses in a network.

Arguments

• network_name: Name of the network (e.g., "RTS", "Texas7k")
• date: Date input. Can be:
  • Date object
  • Tuple (year, month, day)
  • String "all" for the full year (8760 hours)
• api_key: NREL API key. If not provided, checks ENV["NRELAPIKEY"] or uses "DEMO_KEY"
• save_to_file: If true, saves data to CSV instead of returning it.
• output_dir: Optional override for output directory. If empty, defaults to "data/solarcurves/<networkmapped_name>"

Returns

• If save_to_file is false: Dict{Int, Dict{String, Vector{Float64}}}
• If save_to_file is true: Nothing

get_network_census(network_name; kwargs...) -> String

End-to-end entry point. Pulls tract demographics within radius_m of any bus in the network, runs the 3-pass assignment against load buses, aggregates to per-bus totals, and writes a single CSV to <data_dir>/census_data/<network_name>_census_<acs_year>.csv. Returns the output path.

Keyword arguments

• api_key::String="" — Census API key (or CENSUS_API_KEY env var; anonymous fallback ~500 req/day)
• acs_year::Int=2022
• radius_m::Float64=25_000.0 — per-bus tract-inclusion radius (meters)
• weighting::Symbol=:inverse — :inverse (default) or :proportional
• data_dir::String="data"
• output_path::String="" — override the default output location

load_census_data(network_name; acs_year=2022, data_dir="data", file_path="") -> DataFrame

Load the unified per-bus Census ACS demographics for a network.

Expects a CSV at <data_dir>/census_data/<network_name>_census_<acs_year>.csv produced by get_network_census. Returns an empty typed DataFrame (with @warn) if the file is missing — plotting and downstream use should degrade gracefully rather than crash.

Returns

DataFrame with columns: BusID, totalpop, numhouseholds, numwhite, numblack, numnative, numasian, numhispanic, numbelowpoverty, numabovepoverty, numlowincome, nummiddleincome, numhighincome, median_income.