OPFFCAS API

Full reference for NEMX.OPFFCAS, AC/DC optimal power flow with FCAS co-optimisation. See OPF with FCAS for the workflow.

Only the names this submodule exports appear here. The problem builders, formulation-specific methods and visualisation helpers are reached as NEMX.OPFFCAS.name; see the source tree described in Architecture.

NEMX.OPFFCAS — Module
NEMX.OPFFCAS

Optimal power flow with co-optimised frequency control ancillary services, on AC/DC networks.

Where NEMX.ZBenchmark and NEMX.NBenchmark reconstruct an existing market's dispatch from published data, this submodule is a modelling library: it extends PowerModels and PowerModelsACDC with the variables, constraints and objectives needed to co-optimise energy and the eight-to-ten FCAS products against a network model, across several power-flow formulations and a branch-flow (bf) family suitable for distribution-style cases.

Layout

FolderContents
core/Model types, variable and constraint declarations, constraint templates, objectives, and the data layer that reads NEM market CSVs into a PowerModels case
form/Formulation-specific method definitions — acp, dcp, lpac, ivr, bf, wr, and cross-formulation shared
prob/Problem builders: opfcas, opfcas_bf, opfcas_ivr, mn_opfcas (multi-network)
itr/Iterative drivers built on those problems
eval/Post-solve evaluation, including contingency checking
util/Small helpers (solution selection, shift-factor evaluation)
vis/PlotlyJS result plotting
scopf/Security-constrained variants — not loaded by default, see below

Model types

CPPowerModel and the FCASService type hierarchy (FCASRegulatingService, FCASContingencyService) are declared in core/types.jl. Problem builders follow the PowerModels convention: build_* assembles a model on a pm object, run_*/solve_* wraps building and solving.

Optional: security-constrained problems

prob/scopfcas_bf.jl, itr/scopfcas_bf_itr.jl and eval/scopf_cont_check.jl depend on PowerModelsACDCsecurityconstrained, which is not in Julia's General registry. They are therefore kept in scopf/ and are not included when the package loads, so that Pkg.add("NEMX") and Pkg.test("NEMX") work with registered dependencies only.

To use them, install that package into your environment and call:

using NEMX, PowerModelsACDCsecurityconstrained
NEMX.OPFFCAS.load_security_constrained!()

which evaluates the three files into this module. The call throws with an explanatory message if the dependency is absent, and is a no-op if the files have already been loaded.

source
NEMX.OPFFCAS.MARKET_DATA_DIR — Constant
MARKET_DATA_DIR

Root directory for the raw AEMO market CSVs (participants.csv, BIDPEROFFER.csv, BIDDAYOFFER.csv) that the scenario-building helpers read, and for the .m scenario files they write.

This is a Ref rather than a constant because these helpers are a data preparation pipeline run against whatever download the user has on disk, which is not something the package can know at load time:

NEMX.OPFFCAS.MARKET_DATA_DIR[] = "/data/aemo/2025-09"

Every function that touches it also accepts a dir keyword, so a one-off can override it without mutating global state. Nothing in the package writes to this location unless you call an export_* function.

source
NEMX.OPFFCAS.SCENARIO_DIR — Constant
SCENARIO_DIR

Default root for market-scenario data read by process_scenario_data!.

Resolved from the package's own location rather than from the caller's working directory, so a scenario bundled with the package is found however the package was loaded. Point process_scenario_data! at your own directory with its dir keyword instead of changing this.

source
NEMX.OPFFCAS.assign_participant — Method
assign_participant(participants, participant_type, selector)

Maps an NEM participant DUID to a generator/load

Arguments

  • selector::Function: used to select participants based on their type
source
NEMX.OPFFCAS.calc_pwl_points — Method

cleans up raw pwl cost points in preparation for building a mathamatical model.

The key mathematical properties,

  • the first and last points are strictly outside of the pmin-to-pmax range
  • pmin and pmax occur in the first and last line segments.
source
NEMX.OPFFCAS.export_mlfs — Method
export_mlfs(mlfs, scenario)

Generates a file in MatPower case format containing the calculated MLF values.

Arguments

  • mlfs::Vector{Tuple{Float64,Float64}}: List of power and mlf values for each node
  • scenario::String: The scenario to store the MLF values against
source
NEMX.OPFFCAS.finite_difference — Function
finite_difference(fx, f, x, [h])

Used to estimate the change in a function (in this case the generation at the reference bus) based on a change the input (in this case a small injection of power at a specified load)

source
NEMX.OPFFCAS.get_capacity — Method
get_capacity(participant_type::String)

Reads the maximum capacity for each participant and adds it to the Data Frame.

Arguments

  • participant_type::String: eg. Generator/Load
source
NEMX.OPFFCAS.get_cost_data — Method
get_cost_data(model, participant)

Returns the participant cost data when running a DC Model. Use MLF values if available.

source
NEMX.OPFFCAS.get_df_from_dict — Function
get_df_from_dict(data::Dict, columns::Vector{String}, mapping::Vector{Pair{String, String}}=Pair{String, String}[])

Creates a DataFrame from a dictionary

Arguments

  • columns::Vector{String}: dictionary keys to using in DataFrame
  • mapping::Vector{Pair{String, String}}: maps a key in the dict to a new name in the DataFrame
source
NEMX.OPFFCAS.inject_load — Method
inject_load(extra_p, idx, ref, data, solver, setting)

Inject a small load at the bus specified by idx and measure the change in generation at the reference bus specified by the ref argument

source
NEMX.OPFFCAS.join_offers — Method
join_offers(participants, scenario)

Joins BIDPEROFFER table values to a generator/load based on the assigned DUID

source
NEMX.OPFFCAS.load_security_constrained! — Method
load_security_constrained!() -> Bool

Load the security-constrained problem family into this module.

These problems depend on PowerModelsACDCsecurityconstrained, which is not in the General registry, so they are not part of the default load path — see the module docstring. This function evaluates them into NEMX.OPFFCAS, after which build_scopfcas_bf, the iterative driver and the contingency checker are available exactly as if they had always been included.

Returns

true when the files are loaded (or were already loaded).

Throws

ErrorException if PowerModelsACDCsecurityconstrained is not importable, with a message naming the missing dependency.

Example

using NEMX, PowerModelsACDCsecurityconstrained
NEMX.OPFFCAS.load_security_constrained!()
source
NEMX.OPFFCAS.map_cost_data — Method
map_cost_data(cost_row)

Cost data in a MatPower file does not have column names due to the variable width of the cost data. This function converts the parsed MatPower cost data and maps it to a standard cost data dictionary format.

source
NEMX.OPFFCAS.map_fcas_cost_data — Method
map_fcas_cost_data(cost_row)

Cost data in a MatPower file does not have column names due to the variable width of the cost data. This function converts the parsed MatPower cost data and maps it to fcas cost data dictionary format.

source
NEMX.OPFFCAS.process_scenario_data! — Method
process_scenario_data!(data::Dict, scenario::AbstractString;
                       dir::AbstractString = SCENARIO_DIR) -> Dict

Extend a standard MATPOWER case with the market data a NEM dispatch needs: generator and load cost curves, FCAS offers and enablement limits, and marginal loss factors.

Each of the four inputs is optional. A file that is absent is skipped silently, so a scenario can supply only what it has — a case with no FCAS data simply produces a model with no FCAS.

Arguments

  • data::Dict: a parsed MATPOWER case, modified in place.
  • scenario::AbstractString: scenario name, i.e. the subdirectory of dir holding that scenario's files ("s1", "s2", ...).

Keywords

  • dir::AbstractString = SCENARIO_DIR: root directory of the scenario library. Defaults to the scenarios bundled with the package.

Files read

$dir/$scenario/ may contain any of fcas.m, gencost.m, loadcost.m and mlf.m.

Returns

data, extended in place.

Example

data = PowerModels.parse_file("case.m")
NEMX.OPFFCAS.process_scenario_data!(data, "s1")
NEMX.OPFFCAS.process_scenario_data!(data, "peak"; dir = "/path/to/my/scenarios")
source
NEMX.OPFFCAS.set_reference_bus — Method
set_reference_bus(data, refs)

Set each bus in the refs argument as reference/slack buses

Arguments

  • data::Dict{String, Any}: The network data dictionary
  • refs::Vector{String}: A list of references bus indexes
source
NEMX.OPFFCAS.show_figure — Method
show_figure(fig)

Display a figure, but only where there is something to display it on.

PlotlyJS renders through an Electron window, which does not exist on a headless machine — a CI runner, a batch job, a container. A plotting function that calls display unconditionally therefore cannot be called from a script at all, which is how a full 2000-bus OPFFCAS run used to die at its last line after twenty minutes of solving.

So the display is attempted only in an interactive session, and any failure is downgraded to a warning. The figure is always RETURNED either way, so a caller can save it with PlotlyJS.savefig regardless of the environment.

Set NEMX_NO_DISPLAY=1 to suppress the attempt even when interactive.

source