Master Problem

Master-problem orchestration for Euphemia optimization, iterations, and outputs.

API path: apem.order_book_based_model.euphemia.master_problem.master_problem

class MasterProblem(config)

Bases: object

Formulate and solve the Euphemia master problem.

Parameters:

config (EuphemiaConfig)

add_MIC_complex_cut(single=False)

Add a cut that rejects one or more near-MIC complex orders.

Parameters:

single (bool | None) – When True, reject one randomly chosen candidate. When False, reject every candidate returned by get_MIC_complex_orders().

Returns:

True when at least one cut was added, otherwise False.

Return type:

bool

add_MIC_scalable_cut(single=False)

Add a cut that rejects one or more near-MIC scalable complex orders.

Parameters:

single (bool | None) – When True, reject one randomly chosen candidate. When False, reject every candidate returned by get_MIC_scalable_orders().

Returns:

True when at least one cut was added, otherwise False.

Return type:

bool

add_acceptance_variables_to_dataframe()

Attach each Gurobi acceptance variable to the corresponding order dataframe row.

Return type:

None

add_block_cut(single=False)

Add a cut that rejects one or more near-PAB block orders.

Parameters:

single (bool | None) – When True, reject one randomly chosen candidate. When False, reject every candidate returned by get_block_bids().

Returns:

True when at least one cut was added, otherwise False.

Return type:

bool

compute_block_overlaps()

Compute block-order overlap sets for price-based cut generation.

Two block orders overlap when they both inject or withdraw non-zero volume in at least one common period. The returned mapping is keyed by block order id.

Return type:

dict[int, set[int]]

get_MIC_complex_orders(threshold=False, reinsertion=False)

Return accepted complex orders that fail or nearly fail their MIC or MP condition.

Parameters:

• threshold (bool | None) – When True, apply the beta_MIC tolerance and return marginally infeasible orders. When False, return orders whose MIC or MP condition is already violated at the current prices.

• reinsertion (bool | None) – Whether to evaluate the reinsertion price map.

Returns:

Complex order ids that match the requested filter.

Return type:

list[int]

get_MIC_scalable_orders(threshold=False, reinsertion=False)

Return accepted scalable complex orders that fail or nearly fail MIC or MP.

Parameters:

• threshold (bool | None) – When True, apply the beta_MIC tolerance and return marginally infeasible orders. When False, return orders whose MIC or MP condition is already violated at the current prices.

• reinsertion (bool | None) – Whether to evaluate the reinsertion price map.

Returns:

Scalable complex order ids that match the requested filter.

Return type:

list[int]

get_block_bids(threshold, reinsertion=False)

Return accepted block orders that violate or nearly violate the PAB condition.

Parameters:

• threshold (bool) – When True, return in-the-money block orders within delta_PAB of becoming paradoxically accepted. When False, return currently paradoxically accepted block orders.

• reinsertion (bool | None) – Whether to evaluate the reinsertion price map.

Returns:

Block order ids that satisfy the requested filter.

Return type:

list[int]

get_load_gradient_orders(threshold=False, reinsertion=False, complex=True)

Return accepted load-gradient orders with negative surplus.

Parameters:

• threshold (bool | None) – When True, only return orders whose surplus is below -delta_load_gradient. When False, return all orders with negative surplus.

• reinsertion (bool | None) – Whether to evaluate the reinsertion price map.

• complex (bool) – When True, inspect complex orders. When False, inspect scalable complex orders.

Returns:

Order ids whose surplus violates the requested threshold.

Return type:

list[int]

get_objective()

Return the current master-problem objective value.

Return type:

float

get_order_zone(df, order_id)

Return the normalized zone assigned to a specific order row.

Parameters:

• df (DataFrame)

• order_id (object)

Return type:

str

get_price_value(t, zone=None, reinsertion=False)

Return the clearing price for a period.

Parameters:

• t (int) – Market period.

• zone (str | None) – Optional zone label for zonal pricing runs.

• reinsertion (bool | None) – Whether to use the reinsertion price map.

Returns:

Clearing price for the requested period and zone.

Return type:

float

master_problem_callback(callback_model, where)

Process incumbent integer solutions produced by the master problem.

For each MIP solution, the callback updates the in-memory allocation tables, solves the pricing subproblem, stores a new incumbent when prices are feasible, or adds the configured lazy cut when the pricing problem is infeasible.

Parameters:

• callback_model (gurobipy.Model)

• where (int)

Return type:

None

resolve_zone(zone)

Normalize a raw zone label and fall back to the default zone when needed.

Parameters:

zone (object)

Return type:

str

set_prices(prices, reinsertion=False)

Store clearing prices from the pricing subproblem.

Parameters:

• prices (dict[Any, float]) – Mapping keyed either by period t or by (zone, t) for zonal pricing runs.

• reinsertion (bool | None) – Whether the prices belong to the reinsertion pass.

Return type:

None

solve_master_problem()

Optimize the master problem and evaluate incumbents through the callback.

Return type:

None

update_order_dataframes()

Populate the order dataframes with acceptance values from the current incumbent.

Return type:

None

volume_indeterminacy_subproblem()

Placeholder for a future volume-indeterminacy subproblem implementation.

Return type:

None