NodalBaseModel

API path: power_flow_relaxations.models.nodal_base_model

class NodalBaseModel(scenario, configuration, tolerances=None)

Bases: PowerFlowModel

Shared optimization scaffold for nodal power-flow relaxations.

This base class handles: - scenario normalization/parsing into indexed sets and tensors, - variable creation and common market/network constraints, - objective assembly for welfare or zonal-tracking modes, - solving, optional integrality forcing, and allocation extraction.

Subclasses provide relaxation-specific network equations by implementing power_constraints, reference_constraints, and get_V_vt_values.

Construct a nodal relaxation model from a scenario.

Parameters:

• scenario (Scenario) – Input market/network scenario.

• configuration (SolverConfiguration) – Solver configuration used for variable domains and runtime settings.

• tolerances (dict[str, float] | None) – Optional overrides for line/balance tolerance and penalty weights.

• is (Initialization order)

• setup. (variable creation -> network arrays -> tolerance)

bid_constraints(u_fixed=None)

Add buyer/seller bid, capacity, and unit-commitment constraints.

Enforces block limits, aggregate dispatch identities, real/reactive bounds, and minimum-uptime relations. If u_fixed is provided, commitment values are fixed per seller and period before constraint assembly.

Parameters:

u_fixed (dict | None)

bus_constraints()

Add nodal real/reactive balance constraints with imbalance slack.

For each node and period, enforces supply - demand - outgoing flow = 0 within weighted slack variables p_imb and q_imb.

collect_constraints(u_fixed=None, verbose=False)

Assemble the full model constraint set in canonical order.

Parameters:

• u_fixed (dict | None) – Optional commitment fixes passed to bid_constraints().

• verbose – If True, prints progress while adding constraint groups.

current_rating_constraints()

Impose conic apparent-power/current rating limits on each branch.

For each directed edge and period, constrains (p, q) flow magnitudes via a quadratic cone, with multiplicative slack through I_viol.

abstractmethod get_V_vt_values()

Get the values of the V_vt variable.

Returns:

Dictionary with (node, period) as keys and V_vt values as values.

Return type:

dict[tuple[int, int], tuple[float, float]]

get_allocation()

Build a lightweight allocation object from the solved model values.

Returns a RelaxAllocation object with buyer, seller, and network allocations, summary stats, helper methods for welfare and feasibility checks, and reconstructed voltage components V_vt.

Raises ValueError if solve status is missing or the solution is not feasible/optimal.

get_imbalance_objective(welfare_scale=1)

Return normalized penalty term for nodal real/reactive imbalance slack.

Uses aggregated p_imb and q_imb variables with scaling by welfare_scale and tensor sizes.

get_objective(zonal_allocation=None, min_vol=False)

Build the objective expression and objective sense.

If zonal_allocation is not provided, returns a welfare-maximization objective with imbalance and thermal-violation penalties. If zonal_allocation is provided, returns a deviation-minimization objective: either minimum-volume deviation (min_vol=True) or cost-weighted deviation plus commitment mismatch (min_vol=False).

Parameters:

• zonal_allocation (SellersAllocation | None)

• min_vol (bool | None)

Return type:

tuple

get_p_bt_values()

Get the values of the p_bt variable.

Returns:

Dictionary with (buyer, period) as keys and p_bt values as values.

Return type:

dict

get_p_btl_values()

Get the values of the p_btl variable.

Returns:

Dictionary with (buyer, period, block) as keys and p_btl values as values.

Return type:

dict

get_p_st_values()

Get the values of the p_st variable.

Returns:

Dictionary with (seller, period) as keys and p_st values as values.

Return type:

dict

get_p_stl_values()

Get the values of the p_stl variable.

Returns:

Dictionary with (seller, period, block) as keys and p_stl values as values.

Return type:

dict

get_p_vwt_values()

Get the values of the p_vwt variable.

Returns:

Dictionary with (node, neighbor, period) as keys and f_vwt values as values.

Return type:

dict

get_phi_st_values()

Get the values of the phi_st variable.

Returns:

Dictionary with (seller, period) as keys and phi_st values as values.

Return type:

dict

get_q_bt_values()

Get the values of the q_bt variable.

Returns:

Dictionary with (buyer, period) as keys and q_bt values as values.

Return type:

dict

get_q_st_values()

Get the values of the q_st variable.

Returns:

Dictionary with (seller, period) as keys and q_st values as values.

Return type:

dict

get_q_vwt_values()

Get the values of the q_vwt variable.

Returns:

Dictionary with (node, neighbor, period) as keys and q_vwt values as values.

Return type:

dict

get_thermal_limit_objective(welfare_scale=1)

Return normalized penalty term for current-limit violations.

The term is scaled by welfare_scale and averaged over the size of I_viol to keep magnitudes comparable across instances.

get_u_st_values(binary=True)

Get the values of the u_st variable.

Returns:

Dictionary with (seller, period) as keys and u_st values as values.

Return type:

dict

initialize_model(configuration)

Create the MOSEK model and declare common decision variables.

Includes buyer and seller block-dispatch variables, commitment/start-up variables, branch active/reactive flows, nodal imbalance slacks, and current-limit violation variables. Commitment is relaxed or binary based on configuration.relaxation.

initialize_network_arrays(enforce_sparse=False)

Build electrical parameter arrays from the scenario network.

Parameters:

• enforce_sparse – If True, store matrices as MOSEK sparse Matrix; otherwise NumPy arrays are used.

• V_min (Generates)

• V_max

• G (conductance)

• B (susceptance)

• branch

• F_max (ratings)

• S_max. (and derived apparent limits)

initialize_parameters()

Convert dictionary-based inputs into dense NumPy tensors.

Produces tensor/matrix representations for buyer values/sizes, seller costs/sizes, no-load costs, and real/reactive demand/supply bounds, all aligned with internal (entity, period, block) indexing.

abstractmethod power_constraints()

Add power flow constraints to the model. These constraints typically represent the power flow equations in the network. :return: set of power flow constraints

read_scenario(scenario)

Normalize and ingest a scenario into model-ready structures.

Harmonizes expected buyer/seller columns, creates index mappings for entities and periods, builds node-neighbor and node-agent mappings, and precomputes dictionary lookups for bids, capacities, and costs.

abstractmethod reference_constraints()

Add reference constraints to the model. These constraints typically set the voltage or power flow at a reference node to a specific value. To access the reference node use self.scenario.r_star :return: set of reference constraints

set_tolerances(

p_vwt_line_tol=0.0005,

q_vwt_line_tol=0.0005,

I_viol_weight=0.3,

p_imb_weight=0.3,

q_imb_weight=0.3,

)

Configure tolerance and penalty coefficients used across constraints.

Parameters control line-equation residual bands and scaling of slack variables for current-limit and nodal-balance violations.

solve(

results_file=None,

stats_file=None,

u_fixed=None,

min_vol=False,

zonal_allocation=None,

verbose=False,

force_integrality=True,

**kwargs,

)

Solve the relaxation and return an allocation-like result object.

Parameters:

• results_file (str | None) – Optional CSV path for raw variable dumps (or failure status).

• stats_file (str | None) – Optional path for computed run statistics.

• u_fixed (dict | None) – Optional fixed commitments to enforce during solve.

• min_vol (bool | None) – Objective mode flag for zonal-tracking formulations.

• zonal_allocation (SellersAllocation | None) – Optional target allocation for redispatch-style tracking objective.

• verbose (bool) – Enable MOSEK solver logs and build-step prints.

• force_integrality (bool) – If relaxed commitments produce fractional values, rerun once with rounded binary commitments fixed.

• **kwargs – Reserved for compatibility.

Returns:

Allocation-like object on success; lightweight error object otherwise.

Return type:

Allocation | Error