Transmission rights#

clear_ftr_auction(case, bids, *, existing=None, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, include_circulation=True, max_iterations=100, cuts_per_iteration=100)#

Clear an FTR auction under the requested feasibility criteria.

Parameters:

  • case -- Case that supplies the network and ratings.

  • bids -- Iterable of FtrBid values. Bid labels must be unique.

  • existing -- Existing FtrPosition values. A sell bid must have matching held capacity on its path and right type.

  • contingencies -- The outages to evaluate: branch sweeps and named branch outages. The default sweeps every in-service branch.

  • contingency_rating -- Use "emergency" ratings after outages or the default "normal" ratings throughout. The selected tier is exact, so an unset emergency rating stays unset.

  • monitored -- Branch identities to check. None selects all branches with a positive applicable rating.

  • points -- Settlement points keyed by customer name.

  • include_circulation -- Count the case's phase-shifter circulation against available facility capacity when true.

  • max_iterations -- Maximum number of feasibility review passes.

  • cuts_per_iteration -- Maximum number of newly enforced facility limits added during one pass.

Returns:

Award MW and clearing price by bid label, total cleared value, binding facilities, failed contingencies, and feasibility status.

Raises:

DCOPFError -- Data is invalid, optional optimization support is absent, or the existing positions are infeasible.

clear_ftr_auction_multiperiod(periods, bids, *, existing=None, include_circulation=True, max_iterations=100, cuts_per_iteration=100, points=None)#

Clear one FTR auction across the requested operating periods.

Parameters:

  • periods -- Nonempty sequence of uniquely named PeriodSpec values.

  • bids -- Iterable of FtrBid values. One award applies across every period that each bid names. An empty bid period list selects all periods.

  • existing -- Existing FtrPosition values with the same period rules.

  • include_circulation -- Count each case's phase-shifter circulation against available facility capacity when true.

  • max_iterations -- Maximum number of feasibility review passes.

  • cuts_per_iteration -- Maximum number of newly enforced facility limits added per period during one pass.

  • points -- Settlement points keyed by customer name.

Returns:

Shared award MW, total and per-period clearing prices, binding facilities by period, failed contingencies, and feasibility status.

Raises:

DCOPFError -- Periods or bids are invalid, optional optimization support is absent, or existing positions are infeasible in a period.

check_simultaneous_feasibility(case, portfolio, *, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, include_circulation=True, max_violations=1000)#

Check a fixed FTR portfolio against the requested network criteria.

Parameters:

  • case -- Case that supplies the network and ratings.

  • portfolio -- FtrPortfolio or iterable of FtrPosition values.

  • contingencies -- The outages to evaluate: branch sweeps and named branch outages. The default sweeps every in-service branch.

  • contingency_rating -- Use "emergency" ratings after outages or the default "normal" ratings throughout. The selected tier is exact, so an unset emergency rating stays unset.

  • monitored -- Branch identities to check. None selects all branches with a positive applicable rating.

  • points -- Settlement points keyed by customer name.

  • include_circulation -- Count the case's phase-shifter circulation against available facility capacity when true.

  • max_violations -- Maximum number of highest-overload violations to retain. The result statistics report the complete violation count.

Returns:

Feasibility status, retained violations in MW, failed contingencies, and coverage statistics.

Raises:

DCOPFError -- A position, settlement point, contingency, or network selection is invalid.

value_ftr_portfolio(portfolio, congestion, *, net=None, theta=None, points=None)#

Value an FTR portfolio against one or more dispatches.

One obligation pays MW * (congestion_sink - congestion_source). An option floors this spread at zero. A settlement point uses the weighted average congestion price of its member buses.

Parameters:

  • portfolio -- FtrPortfolio or iterable of FtrPosition values.

  • congestion -- One {bus: dollars_per_MWh} mapping per scenario. Security-constrained results must use the full non-energy price, lmp - lmp_energy.

  • net -- Optional settlement DcNetwork for a revenue-adequacy check.

  • theta -- Bus-angle mapping for each scenario. Supply this value with net to run the adequacy check.

  • points -- Settlement points keyed by customer name.

Returns:

Mean payout by position, total mean payout, per-scenario payouts, and the requested revenue-adequacy results.

Raises:

DCOPFError -- Labels, congestion inputs, or settlement points are invalid.

value_over_scenarios(portfolio, results, *, net=None, points=None)#

Return portfolio payout over one or more solved dispatch results.

Parameters:

  • portfolio -- FtrPortfolio or iterable of FtrPosition values.

  • results -- One result or a list of DCOPFResult, ScopfResult, or ScedResult values. Each SCED period becomes one settlement scenario.

  • net -- Optional settlement DcNetwork. When supplied, the valuation checks revenue adequacy for every scenario period.

  • points -- SettlementPoint values keyed by names used as position endpoints.

Returns:

An FtrValuation. payout contains the mean dollar payout for each labeled position. total_payout contains their sum. per_scenario contains dollar payouts for each scenario period. Revenue-adequacy fields are populated when net is supplied.

Raises:

DCOPFError -- A position, settlement point, label, or dispatch result is invalid for settlement.

class FtrBid(source, sink, mw, price, kind='obligation', label='', side='buy', periods=())#

Declare one FTR auction bid.

source and sink accept bus numbers or settlement-point names. mw is the requested capacity in MW. price is the reservation price in dollars per MW-period. kind is "obligation" for a signed payout or "option" for a payout floored at zero. side is "buy" to acquire capacity or "sell" to release a matching held position. periods selects named auction periods. An empty period list applies to every period.

property is_option#

Return true when the bid is an option.

property side_sign#

Return 1 for a buy and -1 for a sell.

class FtrPosition(source, sink, mw, kind='obligation', label='', periods=())#

Declare one held or awarded FTR position.

source and sink accept bus numbers or settlement-point names. mw is the held capacity in MW. kind is "obligation" for a signed payout or "option" for a payout floored at zero. periods selects the applicable named periods. An empty period list applies to every period.

property is_option#

Return true when the position is an option.

class FtrPortfolio(positions=<factory>)#

A set of held FTR positions, valued and feasibility-checked as a whole.

to_json()#

Return a JSON-compatible FTR portfolio.

class SettlementPoint(name, weights)#

Define a hub or load zone as a weighted set of buses.

weights maps bus numbers to shares and must sum to 1.0.

to_json()#

Return a JSON-compatible settlement point.

class ARRRequest(source, sink, mw, kind='obligation', priority=1.0, label='')#

Declare one auction revenue right request.

source and sink accept bus numbers or settlement-point names. mw is the requested capacity in MW. priority selects the customer's relative allocation priority. A higher positive value receives less reduction when requests exceed a facility limit.

class FtrAuctionResult(objective, feasible, awards=<factory>, clearing_prices=<factory>, binding=<factory>, failed=<factory>, iterations=0, stats=<factory>, contingencies=None, contingency_rating=None)#

Store FTR awards, clearing prices, and feasibility results.

The result reports the objective value, award MW by bid, clearing prices, binding customer facilities, failed contingencies, and feasibility status.

as_tables()#

Row-table for the SQL query surface: awards (one row per bid -- awarded MW and per-path clearing price $/MW).

classmethod column_quantities()#

Return the quantity each awards column binds, keyed by table then column. The clearing price prices capacity held for the auction period, so it binds the FTR price rather than the energy price.

class FtrFeasibility(feasible, violations=<factory>, failed=<factory>, stats=<factory>, contingencies=None, contingency_rating=None)#

Report feasibility, binding facilities, and any failed contingency.

to_json()#

Return a JSON-compatible feasibility result.

class FtrValuation(payout=<factory>, total_payout=0.0, per_scenario=<factory>, congestion_rent=<factory>, revenue_adequate=None, adequacy_ratio=<factory>, stats=<factory>)#

Store portfolio payout and requested revenue-adequacy results.

payout contains the mean payout by position across the supplied scenarios. total_payout is the sum of those mean values. per_scenario retains each scenario's position payouts. The remaining fields report a requested revenue-adequacy check.

doc()#

Return the result document: the scalar header, with the column bindings for the payout row-table. The table lives on the queryable slot and is queried in SQL.

as_tables()#

Row-table for the SQL query surface: payout (one row per position -- expected (mean-over-scenario) payout in dollars).

classmethod column_quantities()#

Return the quantity each payout column binds, keyed by table then column. A payout is an amount of money and not a price, so it binds its own quantity.

class MultiPeriodAuctionResult(objective, feasible, awards=<factory>, clearing_prices=<factory>, clearing_prices_by_period=<factory>, binding=<factory>, failed=<factory>, iterations=0, stats=<factory>)#

Store FTR auction results for multiple operating periods.

The result reports awards, total and per-period clearing prices, binding customer facilities, failed contingencies, and feasibility status.

as_tables()#

Row-tables for the SQL query surface: awards (shared award MW + total clearing price $/MW per bid) and clearing_by_period (the clearing price $/MW per bid per period).

classmethod column_quantities()#

Return the quantity each projected column binds, keyed by table then column. clearing_by_period prices one bid in one period, so it carries the period beside the award table's price.

class PeriodSpec(name, case, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None)#

Declare one operating period for a multi-period FTR auction.

case supplies the period network and ratings. The remaining options select contingencies, monitored facilities, and the rating set.

class ArrAllocationResult(feasible, allocated=<factory>, binding=<factory>, paths=<factory>, failed=<factory>, stats=<factory>, contingencies=None, contingency_rating=None)#

Store ARR grants, binding customer facilities, and feasibility status.

to_json()#

Return a JSON-compatible ARR allocation result.

scenario_congestion(result)#

Extract FTR settlement inputs from a solved dispatch result.

Parameters:

result -- DCOPFResult, ScopfResult, or ScedResult. The result must contain nodal LMP, energy-price, and bus-angle values.

Returns:

(congestion, theta). Each list contains one bus mapping per operating period. Congestion values equal lmp - lmp_energy in dollars per MWh. theta values are bus voltage angles in radians. DC-OPF and SCOPF return one entry. SCED returns one entry per period.

allocate_arrs(case, requests, *, existing=None, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, include_circulation=True, max_iterations=100)#

Allocate ARR entitlements within the requested feasibility limits.

Parameters:

  • case -- Case that supplies the network and ratings.

  • requests -- Iterable of uniquely labeled ARRRequest values.

  • existing -- Existing FtrPosition values that consume capacity.

  • contingencies -- The outages to evaluate: branch sweeps and named branch outages. The default sweeps every in-service branch.

  • contingency_rating -- Use "emergency" ratings after outages or the default "normal" ratings throughout. The selected tier is exact, so an unset emergency rating stays unset.

  • monitored -- Branch identities to check. None selects all branches with a positive applicable rating.

  • points -- Settlement points keyed by customer name.

  • include_circulation -- Count the case's phase-shifter circulation against available facility capacity when true.

  • max_iterations -- Maximum number of allocation review passes.

Returns:

Granted MW by request label, binding facilities, failed contingencies, and feasibility status.

Raises:

DCOPFError -- Requests, settlement points, contingencies, or network data are invalid.

self_schedule(allocation, *, price_taker=1000000.0, as_bids=True)#

Convert positive ARR grants to labeled FTR auction entries.

Parameters:

  • allocation -- ARR allocation that supplies granted MW and path identities.

  • price_taker -- Bid price in dollars per MW-period when as_bids is true. A high positive value requests the awarded quantity whenever it is feasible.

  • as_bids -- Return FtrBid values when true. Return held FtrPosition values when false.

Returns:

One obligation bid or position for each positive grant. Each entry retains the allocation label, source, sink, type, and granted MW.

arr_revenue(allocation, auction_result)#

Calculate ARR revenue from an FTR auction result.

Parameters:

  • allocation -- ARR allocation with granted MW keyed by request label.

  • auction_result -- Auction result with clearing_prices keyed by the same labels. Prices use dollars per MW-period. A missing label uses a zero price.

Returns:

Mapping from allocation label to revenue in dollars for the auction period.