NBenchmark API

Full reference for NEMX.NBenchmark, the network-resolved nodal dispatch. See Network-resolved dispatch for the workflow.

NEMX.NBenchmark — Module
NEMX.NBenchmark

Network-resolved (nodal) dispatch driven by the same market inputs as the zonal benchmark.

The design idea is a consistency-preserving lift. NEMX.ZBenchmark solves the market on a copper plate, one balance constraint per region. NBenchmark takes the identical per-interval offers, availabilities, ramp rates, FCAS trapeziums and generic constraints, attaches every participant to a bus of a physical network model, and re-solves the same market problem as an optimal power flow. Because only the network representation changes, any difference in price is attributable to that change and to nothing else.

The power-flow model is supplied by PowerModels, so the whole family of formulations is available on one market problem: an exact DC model, the AC model, and the convex relaxations between them.

Layout

FolderContents
core/Solver configuration and the formulation registry, MATPOWER case loading, participant-to-bus mapping, offer-stack and constraint helpers
prob/build_market_opf (the market overlay on a PowerModels OPF), solve_network_dispatch (solve, retry, price extraction) and compare_formulations

Formulations

FORMULATIONS maps a name to a (PowerModels model type, optimizer factory) pair:

NameModelNotes
"DCP"DCPPowerModelLinear DC, solved with HiGHS
"DCP_MLF"DCPPowerModelDC with injections scaled by marginal loss factors
"LPACC"LPACCPowerModelLP AC approximation, cold-start
"SOCWR"SOCWRPowerModelSecond-order-cone relaxation in the W space
"QCRM"QCRMPowerModelQuadratic-convex relaxation
"ACP"ACPPowerModelFull AC in polar coordinates, solved with Ipopt

Typical workflow

using NEMX, Dates
const NB = NEMX.NBenchmark

result = NB.solve_network_dispatch(DateTime(2025, 9, 2, 12, 5), "DCP";
                                   mfile    = "data/snem2000_fixed.m",
                                   data_dir = "data/nemx_2025_09")
result.prices          # nodal and regional-reference prices
result.decomposition   # energy / congestion / loss components
result.binding         # active-constraint ledger

Behavioural flags

FlagDefaultEffect
NODAL_MLF_PRICE_REFERRALtrueRefer offer prices to the regional reference node by dividing by the unit's marginal loss factor, matching the zonal objective
BALANCE_SLACK_ENABLEDtrueAdd CVP-priced one-sided slack generators at each regional reference node so an infeasible interval prices rather than fails
NLP_RETRY_ENABLEDtrueOn a failed AC solve, retry once with a different barrier strategy and a different linear solver

Optional HSL linear solver

Ipopt's default MUMPS factorisation is the component most implicated in machine-dependent AC failures. If a CoinHSL build is unpacked at <package root>/vendor/coinhsl/lib/, or pointed at by ENV["NEMX_HSLLIB"], the primary AC solve uses MA57 and the retry uses MUMPS, making the second attempt genuinely independent of the first. HSL is licensed by STFC and is not redistributable, so it is discovered at run time and its absence is not an error — the package falls back to MUMPS throughout.

source
NEMX.NBenchmark.AREA_OF_REGION — Constant
AREA_OF_REGION

Map from NEM region id to the MATPOWER area number carried by the network case. The nodal model uses areas to place regional reference nodes, aggregate regional demand and attribute interconnector flows.

source
NEMX.NBenchmark.BALANCE_SLACK_ENABLED — Constant
BALANCE_SLACK_ENABLED

Ablation control for _add_balance_slack!. true (default) is the shipped behaviour; false restores the hard bus power balance so the effect of the slack on solver convergence can be measured rather than asserted.

Interior-point methods need a strictly feasible direction to work in. With the balance held as a hard equality at every bus, Ipopt has none, and on the tightest intervals its restoration phase fails outright – returning a status with duals that are not prices at all. The slack repairs that WITHOUT being used: it is zero in the converged solution on every interval tested, so it changes the search, not the answer.

source
NEMX.NBenchmark.NLP_RETRY_ENABLED — Constant
NLP_RETRY_ENABLED

Retry an interior-point solve once, along a different barrier path, when the first attempt fails outright.

The AC formulations occasionally return OTHER_ERROR or NUMERICAL_ERROR on a 2000-bus market OPF whose objective spans offer prices of order 1e2 and CVP coefficients of 2.6e6. Investigated on three such intervals (2025-09-02 06:40 and 23:10, 2025-09-03 03:10), the failures proved NOT to be properties of the interval: every one of them converges standalone, under the old and new solver settings alike, with and without the balance slack, and in the driver's full six-formulation sequence. What differs is the numerical path – Ipopt with MUMPS is sensitive to the build and to BLAS threading – so the same input can solve on one machine and fail restoration on another.

A retry is therefore the appropriate remedy: it costs nothing on the ~97% of intervals that already converge, and it gives the failures a second, different path rather than discarding the interval. The retry result is kept even if it also fails, because a failed first attempt leaves duals that are not prices, and because the downstream extraction reads values and duals from the JuMP model – so res and the model must describe the same solve. Both statuses are recorded in the result (status, first_status, solve_attempts), so a retry is never silent.

source
NEMX.NBenchmark.NODAL_MLF_PRICE_REFERRAL — Constant
NODAL_MLF_PRICE_REFERRAL

Whether the nodal energy objective divides offer prices by the unit's marginal loss factor, undoing the scaling get_processed_bids applied and referring the bid stack back to the regional reference node.

get_processed_bids multiplies case-file energy prices by lambda, so mkt.pb holds CONNECTION-POINT prices. The zonal benchmark divides by lambda again, making its objective reference-node-referred; the nodal model originally inherited the multiplication without the division, so its bid stack carried a per-unit lambda that the benchmark did not. Verified at coefficient level: over 3 766 non-zero energy bands at 2025-09-02 04:15, the processed price equals the case-file price times lambda with a maximum relative deviation of 0.0, and the nodal objective coefficient equals the zonal one times lambda exactly.

Lambda is not incidental. Over 568 unit-directions the median is 0.9815, the range 0.7917-1.0649, 81.3% differ from 1.0 and 26.9% sit below 0.95, so the scaling reorders merit rather than perturbing it.

true (default) applies the referral to EVERY formulation, so all of them share the benchmark's bid stack and any difference between them is attributable to the power-flow model alone. The MLF-scaled variant is not obtained by disabling this flag per formulation but by running the zonal engine with ZONAL_MLF_KEEP_SCALING, which yields the single reference series the study is measured against.

source
NEMX.NBenchmark.PKG_ROOT — Constant
PKG_ROOT

Absolute path to the package root, i.e. the directory holding Project.toml.

Resolved from this file's own location rather than from a caller's working directory, so anything discovered relative to the package (the optional HSL library, bundled test cases) is found however the package was loaded. This file sits at <root>/src/nbenchmark/core/, hence three levels up.

source
NEMX.NBenchmark.TAU — Constant
TAU

Dispatch interval length, in HOURS.

The ramp rates consumed here come from the market tables (bid @RampUpRate and SCADARampUpRate), which are MW/h. This has been verified empirically twice over: the copper-plate benchmark reproduces published prices exactly with rate * (5/60) movement windows, and a unit such as YWPS4 (355 MW coal) carries rate = 180, i.e. 3 MW/min — 180 MW/min would traverse the whole unit in two minutes. Setting TAU = 5 (treating the rates as MW/min) re-opens the 60x-loose windows behind the original under-pricing defect. If a data source with MW/min rates is ever added, convert at ingestion rather than changing this.

source
NEMX.NBenchmark._IPOPT_NLP_RETRY — Constant
_IPOPT_NLP_RETRY

Fallback barrier configuration, used once when the primary solve returns a genuine failure (see NLP_RETRY_ENABLED).

It differs from _IPOPT_NLP in the two parameters that decide which numerical path the solver takes: the barrier update and, where HSL is available, the linear solver. The primary configuration uses the adaptive barrier and MA57; this one reverts to the monotone barrier, pushes the starting point further inside its bounds, and factorises with MUMPS. The point is not that either choice is better – it is that a failure on this problem is a property of the path taken, not of the interval, so the retry has to be genuinely INDEPENDENT of the first attempt. Changing only the barrier strategy was not enough: 2025-09-03 03:10 failed both attempts while returning a point within $1.74/MWh of the consensus of the three relaxations.

source
NEMX.NBenchmark._hsl_primary — Method

Linear-solver options. MA57 is used when HSL is available and MUMPS otherwise.

The linear solver is the sparse symmetric-indefinite factorisation at the heart of every interior-point iteration, and it is the component most implicated in the machine-dependent AC failures: MUMPS is where "solves here, fails there" on identical input comes from. MA57 is markedly more robust on OPF-shaped KKT systems, so where it is present the primary solve uses it.

The RETRY deliberately uses the OTHER factorisation. A retry that changes only the barrier strategy still runs the same factorisation over the same KKT matrix, which is why 2025-09-03 03:10 defeated both attempts; changing the factorisation too makes the second attempt genuinely independent of the first.

source
NEMX.NBenchmark._scale_gen_bounds_for_mlf! — Method
_scale_gen_bounds_for_mlf!(data, mapping, mkt) -> Int

Put the network-side generator bounds into the same units as the variable they bound, when DCP_MLF is in force.

map_participants! writes pmin/pmax in MARKET MW - the unit's bid envelope and, when hard_down=true, its hard down-ramp floor init - dn*5/60. Under DCP_MLF the linkage constraint is pg * base == gamma * E (A8 layer (ii)), so the variable those bounds sit on is no longer E but gamma * E. Left unscaled they therefore assert E >= pmin/gamma - with a typical gamma near 0.9 that inflates the down-ramp FLOOR by about 11%, and a unit whose floor is already close to its up-ramp ceiling then has an empty feasible interval.

This was the entire DCP_MLF failure on 2025-09-02: 41 INFEASIBLE intervals in two blocks (06:10-08:15, 20:10-21:05), i.e. exactly the morning and evening peaks, when the fleet is most tightly ramp-bound. Plain DCP (gamma == 1) was unaffected and solved all 288.

Scaling both bounds by gamma restores the intended meaning: the network-side interval becomes gamma * [pmin, pmax], which is precisely the image of the market-MW interval under the linkage.

source
NEMX.NBenchmark.classify_generic — Method
classify_generic(id) -> String

Classify an AEMO generic constraint by its ID, following AEMO's Constraint Naming Guidelines. Classes: "thermal" — contains '>' : avoid overloading element A on trip of B (line ratings; the class a physical network model REPLACES); "voltage" — contains '^' : voltage-stability limits; "transient" — contains '-' after the region prefix or '*' : transient / oscillatory stability; "unitcap" — starts with '#' : unit-specific caps (semi-dispatch caps, runbacks) — KEEP, these act on units not the grid; "fcas" — starts with F or D_ : FCAS requirement / regulation procurement — KEEP (co-optimisation needs them); "other" — discretionary ('$'), non-conformance, ratings w/o marker.

source
NEMX.NBenchmark.compare_formulations — Method
compare_formulations(interval; forms, kwargs...) -> DataFrame

Run every requested formulation for one interval and tabulate objective, losses, solve time and the five RRN prices, alongside the copper-plate benchmark prices if data/nemx_2024_07/bdu_prices_julia_fixed.csv exists.

source
NEMX.NBenchmark.hsl_library_path — Method
hsl_library_path() -> String

Locate the HSL/CoinHSL shared library, or return "" if none is present.

Ipopt loads HSL at RUNTIME through its hsllib option, so no rebuild of Ipopt or Ipopt.jl is involved: the library only has to exist and match the platform. Search order:

  1. ENV["NEMX_HSLLIB"], an explicit override giving the full path to the library;
  2. <package root>/vendor/coinhsl/lib/libcoinhsl.<ext> (then libhsl.<ext>), where the CoinHSL binary distribution is unpacked.

HSL is licensed by STFC and is NOT redistributable, so the library is deliberately kept out of version control and discovered at run time; a checkout without it falls back to MUMPS and still works, just less robustly.

source
NEMX.NBenchmark.load_network — Method
load_network(mfile) -> (data, meta)

Parse the (fixed) snem2000 case with PowerModels and join the DUID/fuel/area side tables. In-memory fallbacks replicate fixsnem2000.jl if the raw file is used. meta carries genduid[i], storage rows, and per-area bus lists.

source
NEMX.NBenchmark.map_participants! — Method
map_participants!(data, meta, mkt) -> mapping::DataFrame

Attach every market participant (unit, dispatch_type) to a network bus and replace the synthetic generation fleet by market-driven injections: DUID match first (within the participant's area), then placement at the region's highest-voltage generator bus. Unmatched synthetic generators keep only their reactive capability (A2); synthetic storage becomes injection envelopes (A3); native loads are scaled to AEMO regional demand (A4). Each market unit becomes a PowerModels gen component whose pg the market layer drives; the returned mapping table records unit -> (gen id, bus, how).

source
NEMX.NBenchmark.solve_network_dispatch — Method
solve_network_dispatch(interval, formulation; kwargs...) -> Dict{String, Any}

Build and solve the market-overlaid network dispatch for formulation (a key of FORMULATIONS). Returns objective, solve status/time, total network losses, per-bus LMPs, regional-reference-node prices (A9) and the mapping. FCAS results are also returned: "fcas_enablement" (a DataFrame of committed MW per unit, dispatch_type, service) and "fcas_prices" (the dual/marginal price ($/MW) of each FCAS regional requirement, keyed by generic-constraint set with service/region labels; non-empty only when include_generic). LMPs are the duals of the nodal real-power balance constraints; for nonlinear formulations these are the local KKT multipliers reported by Ipopt, and for conic relaxations the conic duals (both standard practice). Models here are continuous, so no fix-and-reprice pass is required; if binaries are ever added, fix them and re-solve before reading duals (as the copper-plate model does).

source