Compile an OpenDSS model from a .dss file on disk and run power flow.

Loads the circuit, solves it in snapshot mode, and returns a summary with convergence status, bus/line/load counts, and total losses.

Args: params: CompileFileInput with dss_path and optional buscoords_path.

Returns: Circuit summary with convergence, counts, and losses.

Compile an OpenDSS circuit from inline DSS commands and run power flow.

Pass the complete DSS script as a multi-line string. The server writes it to a temporary file, compiles it, and solves in snapshot mode.

Args: params: CompileScriptInput with the DSS script text.

Returns: Circuit summary with convergence, counts, and losses.

Execute a single OpenDSS text command on the currently loaded circuit.

Useful for modifying the circuit after compilation (adding elements, changing parameters, setting modes, etc.).

Args: params: RunCommandInput with the DSS command string.

Returns: The DSS result string, or confirmation of execution.

Get voltage magnitude (pu) for all buses in the compiled circuit.

Returns per-bus voltage data including average, min, max pu values, kV base, number of phases, distance from source, and coordinates. Filter by kv_base range to focus on MV or LV buses.

Args: params: VoltageInput with kv_min/kv_max filters.

Returns: Table of bus voltages sorted by voltage (ascending).

Get voltage statistics: min, max, mean, std, violation counts.

Provides a quick overview of the voltage regulation status including the number of buses below 0.95 pu and above 1.05 pu.

Args: params: VoltageInput with kv_min/kv_max filters.

Returns: Voltage statistics summary.

Get active and reactive power for every load in the circuit.

Returns nominal and actual (solved) kW/kvar for each load element.

Args: params: VoltageInput (only response_format is used).

Returns: Table of load powers.

Get power flow (P, Q) and max current for every line.

Useful for identifying overloaded lines and understanding power distribution across the network.

Args: params: VoltageInput (only response_format is used).

Returns: Table of line flows sorted by current (descending).

Get thermal loading (% of NormAmps) for every line and transformer.

Max phase current at terminal 1 against NormAmps and EmergAmps of the element. Shunt elements (capacitors) are skipped. Sorted by loading descending, so overloaded elements come first.

For transformers loading_pct is NOT the nameplate loading: NormAmps comes from normhkva, which defaults to 1.1 x kVA. Transformers also carry kva_nominal, i_nominal_a (winding 1) and loading_nominal_pct, the loading against nameplate kVA; report that one as "% of rated capacity".

Args: params: VoltageInput (only response_format is used).

Returns: Table with element, buses, i_max_a, norm_amps, emerg_amps, loading_pct (and, for transformers, kva_nominal, i_nominal_a, loading_nominal_pct).

Report buses outside [v_min, v_max] pu and elements above loading_max %.

Voltage limits apply per phase (bus v_min_pu / v_max_pu). Defaults are 0.95 / 1.05 pu and 100 % of NormAmps; pass the limits of the applicable standard (e.g. NTC 1340 / CREG) explicitly when they differ. Use it after every solve to verify the case before reporting results.

Args: params: ViolationsInput with limits and optional kV base filter.

Returns: Counts plus the lists of voltage and thermal violations.

Edit properties of an existing element and re-solve.

Typed alternative to opendss_run_command("Edit ..."): checks that the element exists, builds the Edit command from the properties dict, reads the values back from OpenDSS and reports convergence. Fails on unknown properties instead of silently ignoring them.

Args: params: EditElementInput with element (Class.Name), properties, solve.

Returns: Command executed, values read back and solve status.

Create a new element (PVSystem, Storage, Load, Line, Capacitor, RegControl, InvControl, LoadShape...) from a properties dict and re-solve.

Typed alternative to opendss_run_command("New ..."): refuses to overwrite an existing element, verifies that OpenDSS created it and reads the properties back. Use element_class + name, not 'Class.Name' in name.

Args: params: AddElementInput with element_class, name, properties, solve.

Returns: Command executed, values read back and solve status.

Enable or disable all elements of a class, or only the named ones, and re-solve.

Typical use: disable every PVSystem to get the base case, or disable a Capacitor / RegControl to test its effect. Without names it runs BatchEdit Class..* enabled=yes|no.

Args: params: EnableElementsInput with element_class, enabled, names, solve.

Returns: Elements affected and solve status.

Run a three-phase fault at a specific bus.

Applies a 3-phase fault with specified resistance and returns fault currents (per phase), short-circuit power (Scc), and voltage sag impact (number of buses below 0.80 and 0.50 pu during the fault).

The circuit must be compiled first with opendss_compile_file or _script.

Args: params: FaultInput with bus name and fault resistance.

Returns: Fault currents, Scc, and voltage impact summary.

Run a single-phase-to-ground (1F-G) fault at a specific bus.

Applies a 1-phase fault on the specified phase with given resistance and returns fault current magnitude, 3I0, per-phase voltages (pre/post), short-circuit power, and voltage sag impact.

Use two calls with different r_fault values (e.g., 0.01 and 1.0) to extract zero-sequence Thévenin impedance Z0_th via dual-fault method.

The circuit must be compiled first with opendss_compile_file or _script.

Args: params: Fault1PhInput with bus name, phase, and fault resistance.

Returns: Fault current, 3I0, Scc_1ph, and voltage impact summary.

Extract positive-sequence Thévenin impedance (Z1) at a bus.

Uses the dual-fault method: two 3-phase faults with different R_fault values to algebraically solve for R1_th and X1_th.

The circuit must be compiled first.

Args: params: TheveninZ1Input with bus name and two fault resistances.

Returns: R1_th, X1_th, Z1_th, X/R ratio, and supporting data.

Extract zero-sequence Thévenin impedance (Z0) at a bus.

Uses the dual-fault method with 1F-G faults: two single-phase faults with different R_fault, combined with Z1 extraction, to solve for R0_th and X0_th.

Returns both Z0 and Z1 (needed for the calculation). The circuit must be compiled first.

Args: params: TheveninZ0Input with bus name, phase, and two fault resistances.

Returns: R0_th, X0_th, Z0_th, plus Z1 data and supporting information.

Run three-phase faults at multiple buses to build a fault current curve.

Re-compiles the circuit for each bus to get clean, independent results. Useful for plotting Icc vs distance or sizing protection equipment.

Args: params: FaultSweepInput with list of buses.

Returns: Table of fault currents and Scc per bus.

Run a quasi-static time series (QSTS) simulation.

Requires LoadShapes to be defined in the circuit model. Supports daily (24h), yearly (8760h), and dutycycle modes.

The circuit must be compiled first. LoadShapes must already be defined in the DSS model for time-varying behavior.

Args: params: QSTSInput with mode, stepsize, number of steps.

Returns: Convergence status and final-state voltage summary.

Run a hosting capacity study by incrementally adding PV generation.

Tests multiple PV levels at the given load multiplier and reports, per level: Vmin/Vmax, voltage and thermal violation counts, worst loaded element, head flow (negative = reverse flow into the substation) and the binding constraint (voltage, thermal, convergence or none). Supports uniform distribution (equal PV per bus) and worst-case (all PV at the first bus given). Run it at minimum load (load_mult ~0.3): DER limits do not show at peak. The circuit is recompiled clean afterwards, so edits made with run_command/edit_element before the study are lost.

The circuit must be compiled from a file first (not from script).

Args: params: HostingCapacityInput with bus list, PV steps, transformer kVA, load_mult and limits.

Returns: Table per PV level plus hosting_capacity_kw (last level without violations) and the first binding constraint.

Generate a voltage visualization plot and save it as PNG.

Supported plot types:

• voltage_profile: Scatter plot of voltage vs distance from substation.

• topology: Georeferenced network map colored by voltage level.

The circuit must be compiled and solved first.

Args: params: PlotInput with plot_type and kv_base filters.

Returns: Path to the generated PNG image file.