Time-series power flow

The time-series workflow applies ordered operating-point changes to one CompiledPowerFlowSystem. The same schedule and session support transmission-only, distribution-only, and mixed transmission-distribution systems.

The layer changes source operating points; it does not introduce another power flow formulation. Each step uses the normal system solve, control review, coupled certification, and result extraction operations.

Define an operating-point schedule

One schedule contains a strictly increasing time axis and zero or more device profiles. Each profile identifies a source device by region, class, and stable name. Active and reactive multipliers are absolute values relative to the base operating point. They are not incremental changes from the preceding step.

The following TOML schedule is validated by the documentation test suite:

schema = "gpf.time-series/1"
time = [0.0, 1.0, 2.0]

[[profiles]]
region = "feeder"
element_class = "load"
element = "customer"
active_multiplier = [1.0, 1.1, 0.9]
reactive_multiplier = [1.0, 1.1, 0.9]

A multiplier series must contain one value or one value for every time coordinate. A one-value series is broadcast across the complete schedule. Unknown targets, duplicate targets, nonfinite multipliers, and unsupported reactive updates are rejected during schedule compilation.

The exact file contract is defined in the operating-point schedule reference.

Compile and run the schedule

The following example loads the mixed system from the preceding chapter. The same functions accept a standalone GpfCase, DssCircuit, or compiled system:

import gpf

system = gpf.load_power_flow_manifest("system.toml")
schedule = gpf.load_operating_point_schedule("schedule.toml")
compiled = gpf.compile_time_series(system, schedule)
result = gpf.run_time_series(compiled, retain="final")

assert result.converged
assert result.steps[-1].solution is not None
assert all(step.solution is None for step in result.steps[:-1])

compile_time_series() prepares the source system when necessary and validates every profile target. run_time_series() then uses one PowerFlowSession for every step.

Understand continuation

run_schedule() resets the ordered sequence before its first point. The first point starts from the source initial values. Each later point starts from the previous accepted solution, which normally reduces repeated solution work.

The continuation state belongs to PowerFlowSession; it is not hidden global state. reset_sequence() restores the source initial values when a caller starts a new ordered sequence. A one-shot solve_power_flow() call creates a new session and therefore retains its independent-solve behavior.

Select result retention

The retain argument controls full result extraction:

"all"

Every completed step stores its complete formulation or mixed-system result.

"final"

Only the last scheduled step stores a complete result. Earlier steps retain status and iteration count.

"none"

No step materializes a complete result. Every step retains status and iteration count.

Compact retention avoids full terminal and report extraction when only convergence or the final operating point is required.

Handle failures

TimeSeriesResult.steps contains only completed steps. Each TimeSeriesStep reports its time coordinate, convergence state, iteration count, and optional solution.

stop_on_failure=True stops after the first failed point. A false value permits later scheduled points to run through the same sequence. The caller should inspect each step because TimeSeriesResult.converged is true only when every completed step converged.

The schedule layer does not invent missing physical controls or temporal device state. Delayed controllers, protection, dynamic state, and energy-management logic require explicit model support before their source profiles can be treated as more than resolved operating-point inputs.