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.OPFFCASOptimal 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
| Folder | Contents |
|---|---|
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.
NEMX.OPFFCAS.MARKET_DATA_DIR — Constant
MARKET_DATA_DIRRoot 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.
NEMX.OPFFCAS.SCENARIO_DIR — Constant
SCENARIO_DIRDefault 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.
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
NEMX.OPFFCAS.build_acdcopfcas — Method
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.
NEMX.OPFFCAS.check_gen_cost_models — Method
Checks that all generator cost models are of the same type
NEMX.OPFFCAS.constraint_fcas_energy_regulating_capacity — Function
constraint_fcas_energy_regulating_capacity(pm, service, nw)Ensures that the combined energy and regulating fcas values are contained within the fcas trapezium
NEMX.OPFFCAS.constraint_fcas_energy_regulating_capacity — Function
do nothing, not required for contingency FCAS services
NEMX.OPFFCAS.constraint_fcas_joint_capacity — Function
do nothing, not required for regulating FCAS services
NEMX.OPFFCAS.constraint_fcas_joint_capacity — Function
constraint_fcas_joint_capacity(pm, service, nw)Ensures that the combined energy, regulating fcas and contingency fcas values are contained within the fcas trapezium
NEMX.OPFFCAS.constraint_fcas_max_available — Function
constraint_fcas_max_available(pm, service, nw)Simple constraint to ensure the calculated fcas for a generator/load is below the max fcas availability
NEMX.OPFFCAS.constraint_fcas_target — Function
constraint_fcas_target(pm, service, nw)Creates an equality constraint that sets an fcas service target
NEMX.OPFFCAS.constraint_power_balance_ac — Method
Shunt constraint using linearized voltage magnitude difference phi
sum(p) + sum(pconv_grid_ac) == sum(pg) - sum(pd) - sum(gs*(1.0 + 2*phi)NEMX.OPFFCAS.constraint_power_balance_ac — Method
constraint_power_balance_ac(pm, i; nw)Extends PowerModels constraintpowerbalance_ac by replacing the static load (pd) with a load variable for scheduled loads.
NEMX.OPFFCAS.export_fcas_data — Function
export_fcas_data(scenario, gens, loads)Generates a file in MatPower case format containing FCAS trapezium and cost data.
NEMX.OPFFCAS.export_fcas_target — Method
export_fcas_target(io)Generates data in MatPower case format containing the FCAS service targets.
NEMX.OPFFCAS.export_gen_cost — Method
export_gen_cost(participants, scenario)Generates a file in MatPower case format containing the generator cost data.
NEMX.OPFFCAS.export_gen_fcas_cost — Method
export_gen_fcas_cost(participants, io)Generates data in MatPower case format containing the generator FCAS costs.
NEMX.OPFFCAS.export_gen_fcas_trapezium — Method
export_gen_fcas_trapezium(gens, io)Generates data in MatPower case format containing the generator FCAS trapezium.
NEMX.OPFFCAS.export_load_cost — Method
export_load_cost(participants, io)Generates data in MatPower case format containing the load costs.
NEMX.OPFFCAS.export_load_data — Method
export_load_data(participants, scenario)Generates a file in MatPower case format containing the load limits and cost data.
NEMX.OPFFCAS.export_load_fcas_cost — Method
export_load_fcas_cost(participants, io)Generates data in MatPower case format containing the load FCAS costs.
NEMX.OPFFCAS.export_load_fcas_trapezium — Method
export_load_fcas_trapezium(loads, io)Generates data in MatPower case format containing the load FCAS trapezium.
NEMX.OPFFCAS.export_load_limits — Method
export_load_limits(participants, io)Generates data in MatPower case format containing the load power limits.
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 nodescenario::String: The scenario to store the MLF values against
NEMX.OPFFCAS.fcas_enabled — Method
fcas_enabled(service, data)Test if a participant is enabled for a specific FCAS service
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)
NEMX.OPFFCAS.gen_convert_to_pwl! — Method
gen_convert_to_pwl!(participants)Converts generator offer bands (each containing a quantity and price) to Piecewise Linear functions
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
NEMX.OPFFCAS.get_cost_data — Method
get_cost_data(model, participant)Returns the participant cost data when running a AC Model.
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.
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 DataFramemapping::Vector{Pair{String, String}}: maps a key in the dict to a new name in the DataFrame
NEMX.OPFFCAS.get_dispatchable_participants — Method
get_dispatchable_participants(participants)Returns only dispatchable participants (generators/loads)
NEMX.OPFFCAS.get_fcas_participants — Method
get_fcas_participants(participants, service)For a given set of participants, returns only those that are enabled for the specified FCAS service
NEMX.OPFFCAS.get_lines — Method
compute lines in m and b from from pwl cost models data is a list of components
NEMX.OPFFCAS.get_slack_generation — Method
get_slack_generation(ref, data)Calculates the change in generation at the reference bus specified by the ref argument.
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
NEMX.OPFFCAS.is_contingency_service — Method
is_contingency_service(service)Returns true if the FCAS service is a contingency service
NEMX.OPFFCAS.is_dispatchable — Method
is_dispatchable(participants)Returns true if a participant is dispatchable
NEMX.OPFFCAS.is_regulating_service — Method
is_regulating_service(service)Returns true if the FCAS service is a regulating service
NEMX.OPFFCAS.join_energy_prices — Method
join_energy_prices(participants, scenario)Joins BIDDAYOFFER energy bid/offeres to a generator/load based on the assigned DUID
NEMX.OPFFCAS.join_fcas_prices — Method
join_fcas_prices(participants, scenario)Joins BIDDAYOFFER FCAS bid/offeres to a generator/load based on the assigned DUID
NEMX.OPFFCAS.join_offers — Method
join_offers(participants, scenario)Joins BIDPEROFFER table values to a generator/load based on the assigned DUID
NEMX.OPFFCAS.load_convert_to_pwl! — Method
load_convert_to_pwl!(participants)Converts load bid bands (each containing a quantity and price) to Piecewise Linear functions
NEMX.OPFFCAS.load_security_constrained! — Method
load_security_constrained!() -> BoolLoad 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!()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.
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.
NEMX.OPFFCAS.merge_cost_data! — Method
merge_cost_data!(cost_row)Converts cost quantity values to p.u and merges the data with the gen/load dictionaries
NEMX.OPFFCAS.merge_fcas_cost_data! — Method
merge_fcas_data!(data)Merges fcas cost data with generator/load dictionaries
NEMX.OPFFCAS.merge_fcas_data! — Method
merge_fcas_data!(data)Merges fcas trapezium data with generator/load dictionaries
NEMX.OPFFCAS.merge_load_limit_data! — Method
merge_load_limit_data!(data)Merges scheduled load limit data with the load data dictionary
NEMX.OPFFCAS.objective_variable_fcas_cost — Function
objective_variable_fcas_cost(pm, report)Creates FCAS cost variables for generators and loads that are required by the model objective function
NEMX.OPFFCAS.objective_variable_pd_cost — Function
objective_variable_pd_cost(pm, report)Creates load cost variables required by the model objective function
NEMX.OPFFCAS.objective_variable_pg_cost — Function
objective_variable_pg_cost(pm, report)Creates generator cost variables required by the model objective function
NEMX.OPFFCAS.process_scenario_data! — Method
process_scenario_data!(data::Dict, scenario::AbstractString;
dir::AbstractString = SCENARIO_DIR) -> DictExtend 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 ofdirholding 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")NEMX.OPFFCAS.run_acdcopfcas — Method
NEMX.OPFFCAS.run_acdcopfcas_bf — Method
NEMX.OPFFCAS.run_mn_acdcopfcas — Method
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 dictionaryrefs::Vector{String}: A list of references bus indexes
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.
NEMX.OPFFCAS.slope_intercepts — Method
compute m and b from points pwl points
NEMX.OPFFCAS.solution_processor — Method
solution_processor(pm, solution)Can be used to add extra values to the solution result set
NEMX.OPFFCAS.variable_fcas — Function
variable_fcas(pm, nw, report)Creates variables for all enabled FCAS participants
NEMX.OPFFCAS.variable_gen_response_delta — Method
variable controling a linear genetor responce
NEMX.OPFFCAS.variable_load_power_real — Method
variable_load_power_real(pm; nw, bounded, report)Creates variables for load real/active power