API

OpenUtility public API.

class OpenUtility.BestConfigurationBenchmarkRecord(*args, **kwargs)[source]

Bases: Protocol

class OpenUtility.BoilerCandidate(name, vhp_header, size_fuel_coefficient, load_fuel_coefficient, min_capacity, max_capacity, minimum_load_fraction, blowdown_fraction=0.0, blowdown_enthalpy_delta=0.0, must_select=False)[source]

Bases: object

Candidate boiler unit feeding one VHP steam condition.

Parameters:

  • name (str)

  • vhp_header (str)

  • size_fuel_coefficient (float)

  • load_fuel_coefficient (float)

  • min_capacity (float)

  • max_capacity (float)

  • minimum_load_fraction (float)

  • blowdown_fraction (float)

  • blowdown_enthalpy_delta (float)

  • must_select (bool)

class OpenUtility.BilevelCandidateAssignment(assignment, source_label=None)[source]

Bases: object

A candidate binary assignment with optional source provenance.

Parameters:
class OpenUtility.BilevelDecompositionIteration(iteration_index, master_model, master_status, assignment, subproblem, incumbent, solution_pool, next_master_model, candidate_source_label=None)[source]

Bases: object

Result of one deterministic bilevel decomposition iteration.

Parameters:
class OpenUtility.BilevelDecompositionRun(iterations, solution_pool, stop_reason, skipped_candidate_count=0, skipped_candidates=())[source]

Bases: object

Result of a bounded bilevel decomposition run.

Parameters:
property converged: bool

Return whether the run stopped on a convergence criterion.

best_incumbent()[source]

Return the best incumbent in the final solution pool.

Return type:

BilevelIncumbent

class OpenUtility.BilevelIncumbent(label, objective_value, assignment, best_bound=None, elapsed_seconds=None, hit_time_limit=False, source_method=None)[source]

Bases: object

One incumbent solution found by a bilevel decomposition workflow.

Parameters:

  • label (str)

  • objective_value (float)

  • assignment (BilevelIntegerAssignment)

  • best_bound (float | None)

  • elapsed_seconds (float | None)

  • hit_time_limit (bool)

  • source_method (str | None)

property optimality_gap: float | None

Return incumbent-minus-bound gap for minimization problems.

exclusion_cut()[source]

Return a no-good cut for this incumbent’s assignment.

Return type:

BilevelIntegerCut

class OpenUtility.BilevelIntegerAssignment(values)[source]

Bases: object

Binary master-problem decision vector for one candidate configuration.

Parameters:

values (tuple[tuple[str, int], ...])

classmethod from_mapping(values)[source]

Create an assignment from a variable-to-binary-value mapping.

Parameters:

values (Mapping[str, int])

Return type:

BilevelIntegerAssignment

property selected_variables: tuple[str, ...]

Return variable names fixed to one.

property unselected_variables: tuple[str, ...]

Return variable names fixed to zero.

as_dict()[source]

Return a dictionary copy of the assignment.

Return type:

dict[str, int]

exclusion_cut()[source]

Return no-good-cut terms that exclude this exact assignment.

Return type:

BilevelIntegerCut

hamming_distance(other)[source]

Return the number of binary values that differ from another assignment.

Parameters:

other (BilevelIntegerAssignment)

Return type:

int

class OpenUtility.BilevelIntegerCut(selected_variables, unselected_variables, minimum_hamming_distance=1)[source]

Bases: object

No-good-cut terms for excluding a previous binary assignment.

Parameters:

  • selected_variables (tuple[str, ...])

  • unselected_variables (tuple[str, ...])

  • minimum_hamming_distance (int)

property variable_names: tuple[str, ...]

Return all variables referenced by the cut.

left_hand_side_value(assignment)[source]

Evaluate cut distance terms for a complete binary assignment.

Parameters:

assignment (BilevelIntegerAssignment)

Return type:

int

is_satisfied_by(assignment)[source]

Return whether the assignment satisfies the no-good cut.

Parameters:

assignment (BilevelIntegerAssignment)

Return type:

bool

excludes(assignment)[source]

Return whether the cut rejects this assignment.

Parameters:

assignment (BilevelIntegerAssignment)

Return type:

bool

class OpenUtility.BilevelSkippedCandidate(candidate_label, assignment, reason, source_label=None)[source]

Bases: object

A candidate assignment rejected after failed subproblem evaluation.

Parameters:
class OpenUtility.BilevelSolutionPool(incumbents=())[source]

Bases: object

Collection of unique bilevel incumbents for a minimization workflow.

Parameters:

incumbents (tuple[BilevelIncumbent, ...])

property best_objective_value: float

Return the objective value of the best incumbent.

best_incumbent()[source]

Return the incumbent with the smallest objective value.

Return type:

BilevelIncumbent

with_incumbent(incumbent)[source]

Return a new pool containing one additional incumbent.

Parameters:

incumbent (BilevelIncumbent)

Return type:

BilevelSolutionPool

exclusion_cuts()[source]

Return no-good cuts for all incumbent assignments in the pool.

Return type:

tuple[BilevelIntegerCut, …]

class OpenUtility.BilevelSubproblemResult(objective_value, best_bound=None, elapsed_seconds=None, status='unknown', hit_time_limit=False, source_method='bilevel')[source]

Bases: object

Slave/subproblem result for a fixed master binary assignment.

Parameters:

  • objective_value (float)

  • best_bound (float | None)

  • elapsed_seconds (float | None)

  • status (str)

  • hit_time_limit (bool)

  • source_method (str)

class OpenUtility.CoolingWaterConfig(unit_cost, process_cooling_load=0.0, utility_cooling_load=0.0)[source]

Bases: object

Cooling-water utility cost and fixed-load parameters.

Parameters:

  • unit_cost (float)

  • process_cooling_load (float)

  • utility_cooling_load (float)

class OpenUtility.CoolPropSteamPropertyProvider(*, fluid='Water')[source]

Bases: object

Steam-property provider backed by CoolProp water properties.

Pressures are supplied in bar, temperatures in degrees Celsius, and enthalpies are returned in MWh/t to match the utility-system model energy basis.

Parameters:

fluid (str)

enthalpy(*, pressure, temperature)[source]

Return specific enthalpy in MWh/t.

Parameters:

  • pressure (float)

  • temperature (float)

Return type:

float

temperature(*, pressure, enthalpy)[source]

Return temperature in degrees Celsius.

Parameters:

  • pressure (float)

  • enthalpy (float)

Return type:

float

saturated_enthalpies(*, pressure)[source]

Return saturated vapor and liquid enthalpies in MWh/t.

Parameters:

pressure (float)

Return type:

tuple[float, float]

isentropic_enthalpy_change(*, inlet_pressure, outlet_pressure, inlet_temperature)[source]

Return isentropic enthalpy drop in MWh/t.

Parameters:

  • inlet_pressure (float)

  • outlet_pressure (float)

  • inlet_temperature (float)

Return type:

float

class OpenUtility.DeaeratorConfig(feedwater_enthalpy, condensate_enthalpy, makeup_water_enthalpy, vent_enthalpy, condensate_return_fraction, vent_fraction=0.0)[source]

Bases: object

Steam deaerator feedwater, condensate, and makeup-water parameters.

Parameters:

  • feedwater_enthalpy (float)

  • condensate_enthalpy (float)

  • makeup_water_enthalpy (float)

  • vent_enthalpy (float)

  • condensate_return_fraction (float)

  • vent_fraction (float)

class OpenUtility.EquipmentCost(name, equipment_type, equipment_name, annualization_factor, installation_factor, variable_capital_cost, fixed_capital_cost, variable_maintenance_cost=0.0, fixed_maintenance_cost=0.0)[source]

Bases: object

Annualized capital and maintenance cost coefficients for equipment.

Parameters:

  • name (str)

  • equipment_type (str)

  • equipment_name (str)

  • annualization_factor (float)

  • installation_factor (float)

  • variable_capital_cost (float)

  • fixed_capital_cost (float)

  • variable_maintenance_cost (float)

  • fixed_maintenance_cost (float)

class OpenUtility.ElectricityCost(import_unit_cost=0.0, export_unit_price=0.0)[source]

Bases: object

Electricity import tariff and export revenue parameters.

Parameters:

  • import_unit_cost (float)

  • export_unit_price (float)

class OpenUtility.FlashSteamRecoveryConfig(levels, routes, condensate_return_fraction)[source]

Bases: object

Flash steam recovery network for process-heating use only.

Parameters:
class OpenUtility.FlashSteamRecoveryLevel(steam_level, saturated_vapor_enthalpy, saturated_liquid_enthalpy)[source]

Bases: object

Saturated flash-steam properties for one steam level.

Parameters:

  • steam_level (str)

  • saturated_vapor_enthalpy (float)

  • saturated_liquid_enthalpy (float)

class OpenUtility.FlashSteamRecoveryRoute(name, source_level, target_level, max_flow)[source]

Bases: object

Permitted condensate flash route from one steam level to another.

Parameters:

  • name (str)

  • source_level (str)

  • target_level (str)

  • max_flow (float)

class OpenUtility.FuelCost(name, equipment_type, equipment_name, unit_cost)[source]

Bases: object

Fuel operating cost coefficient for one fuel-consuming unit.

Parameters:

  • name (str)

  • equipment_type (str)

  • equipment_name (str)

  • unit_cost (float)

class OpenUtility.FuelConsumptionAccountingFactor(equipment_type, equipment_name, factor)[source]

Bases: object

Optional Table 2-9 fuel-consumption reporting factor for equipment.

Parameters:

  • equipment_type (str)

  • equipment_name (str)

  • factor (float)

class OpenUtility.GasTurbineCandidate(name, fuel_lhv, power_slope, power_intercept, min_fuel_flow, max_fuel_flow, minimum_load_fraction, must_select=False)[source]

Bases: object

Candidate gas turbine producing power and exhaust heat.

Parameters:

  • name (str)

  • fuel_lhv (float)

  • power_slope (float)

  • power_intercept (float)

  • min_fuel_flow (float)

  • max_fuel_flow (float)

  • minimum_load_fraction (float)

  • must_select (bool)

class OpenUtility.HeatIntervalProfile(intervals, source_heat, sink_heat)[source]

Bases: object

Source and sink heat content over shifted-temperature intervals.

Parameters:

  • intervals (tuple[TemperatureInterval, ...])

  • source_heat (dict[tuple[float, float], float])

  • sink_heat (dict[tuple[float, float], float])

class OpenUtility.HotOilConfig(fuel_unit_cost, thermal_efficiency, high_temperature_heat_demand=0.0, supply_temperature=None)[source]

Bases: object

Fired hot-oil utility cost and heat-load parameters.

Parameters:

  • fuel_unit_cost (float)

  • thermal_efficiency (float)

  • high_temperature_heat_demand (float)

  • supply_temperature (float | None)

class OpenUtility.HprCandidate(name, mode, map_id, source_node, sink_node=None, rejection_node=None, fixed_capacity=0.0, minimum_load_fraction=0.0, variable_operating_cost_per_q_useful=0.0, must_select=False, refrigeration_routing='rejection_only')[source]

Bases: object

Fixed-capacity HPR optimization candidate.

Parameters:

  • name (str)

  • mode (str)

  • map_id (str)

  • source_node (str)

  • sink_node (str | None)

  • rejection_node (str | None)

  • fixed_capacity (float)

  • minimum_load_fraction (float)

  • variable_operating_cost_per_q_useful (float)

  • must_select (bool)

  • refrigeration_routing (str)

class OpenUtility.HprPerformanceMap(schema_version, map_id, mode, units, reference_capacity, reference_capacity_basis, interpolation_topology, thermodynamic_backend, model_id, provenance, points, cop_convention, energy_balance_tolerance=1e-06, temperature_match_tolerance=1e-06)[source]

Bases: object

Versioned plain-data HPR performance map.

Parameters:

  • schema_version (str)

  • map_id (str)

  • mode (str)

  • units (Mapping[str, str])

  • reference_capacity (float)

  • reference_capacity_basis (str)

  • interpolation_topology (str)

  • thermodynamic_backend (str)

  • model_id (str)

  • provenance (Mapping[str, Any])

  • points (tuple[HprPerformancePoint, ...])

  • cop_convention (str)

  • energy_balance_tolerance (float)

  • temperature_match_tolerance (float)

class OpenUtility.HprPerformancePoint(name, curve_id, source_temperature, sink_temperature, load_fraction, q_source, q_sink, electric_power, cop=None)[source]

Bases: object

One HPR part-load point on a temperature-compatible curve.

Parameters:

  • name (str)

  • curve_id (str)

  • source_temperature (float)

  • sink_temperature (float)

  • load_fraction (float)

  • q_source (float)

  • q_sink (float)

  • electric_power (float)

  • cop (float | None)

OpenUtility.hpr_performance_map_from_mapping(values)[source]

Decode a versioned HPR performance map from plain mapping data.

Parameters:

values (Mapping[str, Any])

Return type:

HprPerformanceMap

class OpenUtility.HrsgCandidate(name, gas_turbine, vhp_header, steam_generation_efficiency, max_heat_input, supplementary_fuel_lhv=0.0, supplementary_firing_efficiency=1.0, max_supplementary_fuel_flow=0.0, must_select=False)[source]

Bases: object

Heat recovery steam generator linked to one gas turbine and VHP header.

Parameters:

  • name (str)

  • gas_turbine (str)

  • vhp_header (str)

  • steam_generation_efficiency (float)

  • max_heat_input (float)

  • supplementary_fuel_lhv (float)

  • supplementary_firing_efficiency (float)

  • max_supplementary_fuel_flow (float)

  • must_select (bool)

class OpenUtility.OperatingCostAccountingAdjustment(component, amount)[source]

Bases: object

Optional Table 2-9 operating-cost accounting adjustment.

Parameters:

  • component (str)

  • amount (float)

class OpenUtility.OperatingPeriod(name, hours, power_demand=0.0, electricity_import_unit_cost=0.0, electricity_export_unit_price=0.0, source_heat_available=None, heating_demand=None, cooling_demand=None, rejection_capacity=None, node_temperatures=None)[source]

Bases: object

One operating period with node-keyed thermal data.

Parameters:

  • name (str)

  • hours (float)

  • power_demand (float)

  • electricity_import_unit_cost (float)

  • electricity_export_unit_price (float)

  • source_heat_available (Mapping[str, float] | None)

  • heating_demand (Mapping[str, float] | None)

  • cooling_demand (Mapping[str, float] | None)

  • rejection_capacity (Mapping[str, float] | None)

  • node_temperatures (Mapping[str, float] | None)

class OpenUtility.SteamMainBackPressureTurbineCandidate(name, source_level, target_level, power_slope, power_intercept, min_capacity, max_capacity, minimum_load_fraction, must_select=False)[source]

Bases: object

Back-pressure turbine connecting one steam main level to a lower level.

Parameters:

  • name (str)

  • source_level (str)

  • target_level (str)

  • power_slope (float)

  • power_intercept (float)

  • min_capacity (float)

  • max_capacity (float)

  • minimum_load_fraction (float)

  • must_select (bool)

class OpenUtility.SteamLevelCandidate(name, steam_main, temperature, source_heat_available, sink_heat_demand, generation_enthalpy_delta, use_enthalpy_delta, source_heat_upper_bound=None, sink_heat_upper_bound=None, steam_enthalpy_for_use=None, generated_steam_enthalpy=None, main_steam_enthalpy=None, utility_steam_enthalpy=None, feedwater_enthalpy=0.0, steam_flow_upper_bound=None, annualized_level_cost=0.0, operating_cost_per_heat=0.0)[source]

Bases: object

Potential steam level located at a shifted-temperature interval.

Parameters:

  • name (str)

  • steam_main (str)

  • temperature (float)

  • source_heat_available (float)

  • sink_heat_demand (float)

  • generation_enthalpy_delta (float)

  • use_enthalpy_delta (float)

  • source_heat_upper_bound (float | None)

  • sink_heat_upper_bound (float | None)

  • steam_enthalpy_for_use (float | None)

  • generated_steam_enthalpy (float | None)

  • main_steam_enthalpy (float | None)

  • utility_steam_enthalpy (float | None)

  • feedwater_enthalpy (float)

  • steam_flow_upper_bound (float | None)

  • annualized_level_cost (float)

  • operating_cost_per_heat (float)

class OpenUtility.SteamLevelPropertyTarget(steam_level, pressure, main_temperature, minimum_temperature, process_generation_temperature=None, process_use_temperature=None)[source]

Bases: object

Calculated steam-main conditions used as pseudo-parameters.

Parameters:

  • steam_level (str)

  • pressure (float)

  • main_temperature (float)

  • minimum_temperature (float)

  • process_generation_temperature (float | None)

  • process_use_temperature (float | None)

class OpenUtility.SteamMainLetdownStationCandidate(name, source_level, target_level, max_flow)[source]

Bases: object

Let-down station connecting one steam main level to a lower level.

Parameters:

  • name (str)

  • source_level (str)

  • target_level (str)

  • max_flow (float)

class OpenUtility.SteamMainSuperheatingBalance(steam_level, pressure, minimum_temperature, source_steam_mass, utility_steam_mass, feedwater_mass, outlet_mass, inlet_heat, calculated_enthalpy, calculated_temperature)[source]

Bases: object

Stage 4 steam-main energy balance and calculated superheat temperature.

Parameters:

  • steam_level (str)

  • pressure (float)

  • minimum_temperature (float)

  • source_steam_mass (float)

  • utility_steam_mass (float)

  • feedwater_mass (float)

  • outlet_mass (float)

  • inlet_heat (float)

  • calculated_enthalpy (float)

  • calculated_temperature (float)

property superheat_margin: float

Temperature margin above the required minimum superheat temperature.

property minimum_temperature_satisfied: bool

Whether the calculated temperature satisfies the minimum superheat.

class OpenUtility.SteamPropertyProvider(*args, **kwargs)[source]

Bases: Protocol

Boundary for steam-table or equation-of-state property calculations.

enthalpy(*, pressure, temperature)[source]

Return specific enthalpy at the supplied pressure and temperature.

Parameters:

  • pressure (float)

  • temperature (float)

Return type:

float

temperature(*, pressure, enthalpy)[source]

Return temperature at the supplied pressure and specific enthalpy.

Parameters:

  • pressure (float)

  • enthalpy (float)

Return type:

float

isentropic_enthalpy_change(*, inlet_pressure, outlet_pressure, inlet_temperature)[source]

Return isentropic enthalpy change across a steam turbine.

Parameters:

  • inlet_pressure (float)

  • outlet_pressure (float)

  • inlet_temperature (float)

Return type:

float

saturated_enthalpies(*, pressure)[source]

Return saturated vapor and liquid enthalpies at the supplied pressure.

Parameters:

pressure (float)

Return type:

tuple[float, float]

class OpenUtility.SteamPropertySnapshot(level_temperatures, level_main_enthalpies, level_generation_enthalpies, level_use_enthalpies, vhp_temperatures, vhp_enthalpies, isentropic_enthalpy_deltas)[source]

Bases: object

Steam pseudo-parameters calculated for one MILP/property iteration.

Parameters:

  • level_temperatures (Mapping[str, float])

  • level_main_enthalpies (Mapping[str, float])

  • level_generation_enthalpies (Mapping[str, float])

  • level_use_enthalpies (Mapping[str, float])

  • vhp_temperatures (Mapping[str, float])

  • vhp_enthalpies (Mapping[str, float])

  • isentropic_enthalpy_deltas (Mapping[str, float])

class OpenUtility.SteamPropertyUpdate(data, snapshot)[source]

Bases: object

Updated utility-system data plus the calculated steam-property snapshot.

Parameters:
class OpenUtility.SteamPropertyUpdateSpec(levels=(), vhp_headers=(), turbines=())[source]

Bases: object

Property-update inputs extracted after a utility-system MILP solve.

Parameters:
class OpenUtility.SteamTurbinePropertyTarget(name, inlet_pressure, outlet_pressure, inlet_temperature)[source]

Bases: object

Steam turbine condition for isentropic enthalpy-difference updates.

Parameters:

  • name (str)

  • inlet_pressure (float)

  • outlet_pressure (float)

  • inlet_temperature (float)

class OpenUtility.ThermalNode(name, temperature, node_type, heating_unit_cost=0.0, cooling_unit_cost=0.0, rejection_unit_cost=0.0)[source]

Bases: object

Generic thermal service node used by HPR candidates.

Parameters:

  • name (str)

  • temperature (float)

  • node_type (str)

  • heating_unit_cost (float)

  • cooling_unit_cost (float)

  • rejection_unit_cost (float)

class OpenUtility.UtilitySystemBestConfigurationComparison(actual, benchmark, deviations)[source]

Bases: object

Comparison against a best-configuration benchmark row.

Parameters:
property within_tolerance: bool

Whether all compared fields are within tolerance.

property max_absolute_deviation: float

Largest absolute field deviation.

deviation_for(field)[source]

Return the deviation record for a named field.

Parameters:

field (str)

Return type:

UtilitySystemBenchmarkDeviation

class OpenUtility.UtilitySystemBenchmarkComparison(actual, benchmark, deviations)[source]

Bases: object

Comparison of an extracted static utility-system result against a source benchmark.

Parameters:
property within_tolerance: bool

Whether all compared fields are within tolerance.

property max_absolute_deviation: float

Largest absolute field deviation.

deviation_for(field)[source]

Return the deviation record for a named field.

Parameters:

field (str)

Return type:

UtilitySystemBenchmarkDeviation

class OpenUtility.UtilitySystemBenchmarkDeviation(field, actual, benchmark, absolute_deviation, within_tolerance)[source]

Bases: object

Field-level deviation between extracted and benchmark utility-system results.

Parameters:

  • field (str)

  • actual (float)

  • benchmark (float)

  • absolute_deviation (float)

  • within_tolerance (bool)

class OpenUtility.UtilitySystemFuelCapacityContext(equipment_family, equipment_name, selection_variable, selected, capacity_basis, actual_capacity_basis_value, capacity_value, capacity_utilization)[source]

Bases: object

Capacity context for one utility-system fuel-consuming equipment item.

Parameters:

  • equipment_family (str)

  • equipment_name (str)

  • selection_variable (str | None)

  • selected (bool | None)

  • capacity_basis (str | None)

  • actual_capacity_basis_value (float | None)

  • capacity_value (float | None)

  • capacity_utilization (float | None)

class OpenUtility.UtilitySystemFuelConsumptionEquipment(equipment_family, equipment_name, fuel_variable, fuel_multiplier, fuel_consumption, included_in_table_fuel_consumption)[source]

Bases: object

Fuel consumption attributed to one utility-system equipment item.

Parameters:

  • equipment_family (str)

  • equipment_name (str)

  • fuel_variable (str)

  • fuel_multiplier (float)

  • fuel_consumption (float)

  • included_in_table_fuel_consumption (bool)

class OpenUtility.UtilitySystemFuelConsumptionFamily(equipment_family, fuel_consumption, included_in_table_fuel_consumption)[source]

Bases: object

Fuel consumption attributed to one utility-system equipment family.

Parameters:

  • equipment_family (str)

  • fuel_consumption (float)

  • included_in_table_fuel_consumption (bool)

class OpenUtility.UtilitySystemOperatingCostComponent(component, operating_cost)[source]

Bases: object

Operating cost attributed to one reportable utility-system component bucket.

Parameters:

  • component (str)

  • operating_cost (float)

class OpenUtility.UtilitySystemResult(case_study, scenario, utility_steam_flow, fuel_consumption, power_generation, steam_turbine_power, gas_turbine_power, operating_cost, maintenance_cost, capital_cost, total_annualized_cost, fuel_cost=None, hot_oil_operating_cost=None)[source]

Bases: object

Compact solved-result summary for a static utility-system model.

Parameters:

  • case_study (str)

  • scenario (str)

  • utility_steam_flow (float)

  • fuel_consumption (float)

  • power_generation (float)

  • steam_turbine_power (float)

  • gas_turbine_power (float)

  • operating_cost (float)

  • maintenance_cost (float)

  • capital_cost (float)

  • total_annualized_cost (float)

  • fuel_cost (float | None)

  • hot_oil_operating_cost (float | None)

class OpenUtility.UtilitySystemBenchmarkRecord(*args, **kwargs)[source]

Bases: Protocol

class OpenUtility.UtilitySystemRunResult(scenario, model, solver, result, comparison)[source]

Bases: object

Built model, solve status, extracted result, and optional benchmark check.

Parameters:
class OpenUtility.UtilitySystemScenario(case_study, scenario, data, benchmark=None, absolute_tolerance=1e-06)[source]

Bases: object

Inputs and optional benchmark for one static utility-system run.

Parameters:
class OpenUtility.UtilitySystemScenarioCatalog(scenarios)[source]

Bases: object

Immutable lookup catalog for static utility-system scenario definitions.

Parameters:

scenarios (tuple[UtilitySystemScenario, ...])

keys()[source]

Return registered (case_study, scenario) keys in catalog order.

Return type:

tuple[tuple[str, str], …]

get(case_study, scenario)[source]

Return a registered scenario by case identifier and scenario name.

Parameters:

  • case_study (str)

  • scenario (str)

Return type:

UtilitySystemScenario

class OpenUtility.UtilitySystemSolverStatus(status='unknown', termination_condition=None, message=None)[source]

Bases: object

Solver status summary reported by a static utility-system solve callback.

Parameters:

  • status (str)

  • termination_condition (str | None)

  • message (str | None)

class OpenUtility.UtilitySystemModelData(steam_mains, steam_levels, power_demand, vhp_headers=(), vhp_sources=(), boilers=(), vhp_turbines=(), vhp_letdowns=(), steam_main_turbines=(), steam_main_letdowns=(), gas_turbines=(), hrsgs=(), deaerator=None, flash_steam_recovery=None, cooling_water=None, hot_oil=None, equipment_costs=(), fuel_costs=(), electricity_cost=None, water_cost=None, grid_import_limit=None, grid_export_limit=None, operating_hours=1.0, cost_scale=1.0, transmission_efficiency=1.0, source_heat_loss_fraction=0.0, sink_heat_loss_fraction=0.0, utility_steam_flow_adjustment=0.0, fuel_consumption_factors=(), operating_cost_adjustments=(), thermal_nodes=(), periods=(), hpr_performance_maps=(), hpr_candidates=())[source]

Bases: object

Static utility-system model input data for Pyomo construction.

Parameters:
class OpenUtility.SuccessiveMilpIteration(iteration, input_data, update, max_temperature_change, converged)[source]

Bases: object

One MILP solve followed by a steam-property pseudo-parameter update.

Parameters:
class OpenUtility.SuccessiveMilpRun(initial_update, iterations, final_update, converged)[source]

Bases: object

Result of a successive MILP steam-property update run.

Parameters:
class OpenUtility.TemperatureInterval(upper, lower)[source]

Bases: object

One descending shifted-temperature interval.

Parameters:

  • upper (float)

  • lower (float)

property key: tuple[float, float]

Return a stable dictionary key for this interval.

class OpenUtility.VhpBackPressureTurbineCandidate(name, vhp_header, steam_level, power_slope, power_intercept, min_capacity, max_capacity, minimum_load_fraction, must_select=False)[source]

Bases: object

Back-pressure turbine connecting a VHP header to a steam main.

Parameters:

  • name (str)

  • vhp_header (str)

  • steam_level (str)

  • power_slope (float)

  • power_intercept (float)

  • min_capacity (float)

  • max_capacity (float)

  • minimum_load_fraction (float)

  • must_select (bool)

class OpenUtility.VhpHeaderPropertyTarget(vhp_header, pressure, temperature, maximum_temperature=None)[source]

Bases: object

Calculated VHP header conditions used as pseudo-parameters.

Parameters:

  • vhp_header (str)

  • pressure (float)

  • temperature (float)

  • maximum_temperature (float | None)

class OpenUtility.VhpLetdownStationCandidate(name, vhp_header, steam_level, max_flow)[source]

Bases: object

Let-down station connecting a VHP header to a steam main.

Parameters:

  • name (str)

  • vhp_header (str)

  • steam_level (str)

  • max_flow (float)

class OpenUtility.VhpSteamCandidate(name, steam_enthalpy, feedwater_enthalpy, steam_flow_upper_bound)[source]

Bases: object

Potential very-high-pressure steam generation condition.

Parameters:

  • name (str)

  • steam_enthalpy (float)

  • feedwater_enthalpy (float)

  • steam_flow_upper_bound (float)

class OpenUtility.VhpSteamSourceCandidate(name, vhp_header, min_capacity, max_capacity, minimum_load_fraction, fuel_consumption_per_steam=0.0, must_select=False)[source]

Bases: object

Generic VHP steam source for calibration or external utility supply.

Parameters:

  • name (str)

  • vhp_header (str)

  • min_capacity (float)

  • max_capacity (float)

  • minimum_load_fraction (float)

  • fuel_consumption_per_steam (float)

  • must_select (bool)

class OpenUtility.WaterCost(unit_cost)[source]

Bases: object

Treated makeup-water unit cost.

Parameters:

unit_cost (float)

OpenUtility.add_bilevel_no_good_cuts(model, cuts, binary_variables, *, component_name='bilevel_no_good_cuts')[source]

Attach no-good-cut constraints to a Pyomo model or block.

Parameters:

  • model (Block)

  • cuts (Iterable[BilevelIntegerCut])

  • binary_variables (Any)

  • component_name (str)

Return type:

Constraint

OpenUtility.apply_steam_property_update(data, spec, properties)[source]

Return utility-system data with steam pseudo-parameters recalculated from spec.

Parameters:
Return type:

SteamPropertyUpdate

OpenUtility.best_configuration_comparison_rows(*, catalog, comparison)[source]

Flatten a best-configuration comparison into tabular rows.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.best_configuration_summary_row(*, catalog, comparison)[source]

Summarize one best-configuration comparison in one row.

Parameters:
Return type:

dict[str, Any]

OpenUtility.bilevel_candidate_audit_bundle_rows(candidates, *, run, accepted_assignment)[source]

Return a single audit table for candidate pool and skipped diagnostics.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_pool_rows(candidates)[source]

Return audit rows for a candidate assignment pool.

Parameters:

candidates (Iterable[BilevelCandidateAssignment])

Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_pool_comparison_rows(candidates, *, accepted_assignment)[source]

Compare candidate assignments with the accepted incumbent assignment.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_selection_delta_rows(candidates, *, accepted_assignment)[source]

Return binary-selection deltas from the accepted assignment.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_selection_delta_summary_rows(candidates, *, accepted_assignment)[source]

Summarize binary-selection deltas by component family.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_source_filter_detail_rows(candidates, *, variable_names)[source]

Return one source-filter detail row per candidate record.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_source_filter_summary_rows(candidates, *, variable_names)[source]

Summarize candidate records filtered by target master variables.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_candidate_source_filter_variable_rows(candidates, *, variable_names)[source]

Return variable-level diagnostics for incompatible candidate sources.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_decomposition_run_rows(run)[source]

Return flat trajectory rows for a bounded bilevel decomposition run.

Parameters:

run (BilevelDecompositionRun)

Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_skipped_candidate_rows(run)[source]

Return audit rows for candidates skipped after subproblem failure.

Parameters:

run (BilevelDecompositionRun)

Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_skipped_candidate_delta_summary_rows(run, *, accepted_assignment)[source]

Join skipped-candidate failures with component-level selection deltas.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.bilevel_incumbents_from_computational_results(results, *, assignment_factory, method='bilevel')[source]

Convert captured computational-result rows into bilevel incumbents.

Parameters:

  • results (Iterable[_ComputationalResultRecord])

  • assignment_factory (Callable[[_ComputationalResultRecord], BilevelIntegerAssignment])

  • method (str)

Return type:

tuple[BilevelIncumbent, …]

OpenUtility.bilevel_no_good_cut_expression(cut, binary_variables)[source]

Return a Pyomo expression for the left-hand side of a no-good cut.

Parameters:
Return type:

Any

OpenUtility.build_bilevel_master_with_no_good_cuts(build_master, solution_pool, *, binary_variables=None, component_name='bilevel_no_good_cuts')[source]

Build a master model and attach no-good cuts from a solution pool.

Parameters:

  • build_master (Callable[[], Block])

  • solution_pool (BilevelSolutionPool)

  • binary_variables (Any)

  • component_name (str)

Return type:

Block

OpenUtility.build_utility_system_binary_selection_master(data)[source]

Build a binary-only utility-system master from canonical selection variables.

Parameters:

data (UtilitySystemModelData)

Return type:

ConcreteModel

OpenUtility.build_utility_system_model(data)[source]

Build the current static utility-system Pyomo model slice.

Parameters:

data (UtilitySystemModelData)

Return type:

ConcreteModel

OpenUtility.compatible_bilevel_candidate_assignments(assignments, *, variable_names)[source]

Return candidate records whose assignment variables match target names.

Parameters:
Return type:

tuple[BilevelCandidateAssignment, …]

OpenUtility.compatible_bilevel_integer_assignments(assignments, *, variable_names)[source]

Return assignments whose variable set exactly matches target names.

Parameters:
Return type:

tuple[BilevelIntegerAssignment, …]

OpenUtility.build_temperature_intervals(streams, *, precision=10)[source]

Build descending intervals from shifted stream temperature kinks.

Parameters:

  • streams (Any | Iterable[Any])

  • precision (int)

Return type:

tuple[TemperatureInterval, …]

OpenUtility.compare_utility_system_result_to_best_configuration(result, benchmark, *, absolute_tolerance=1e-06)[source]

Compare extracted utility-system values to a Contribution 2 best-configuration row.

Parameters:
Return type:

UtilitySystemBestConfigurationComparison

OpenUtility.compare_utility_system_result_to_benchmark(result, benchmark, *, absolute_tolerance=1e-06)[source]

Compare extracted static utility-system values against a source benchmark row.

Parameters:
Return type:

UtilitySystemBenchmarkComparison

OpenUtility.extract_utility_system_result(model, *, case_study, scenario)[source]

Extract a compact static utility-system result summary from a solved Pyomo model.

Parameters:

  • model (ConcreteModel)

  • case_study (str)

  • scenario (str)

Return type:

UtilitySystemResult

OpenUtility.fix_utility_system_master_integer_assignment(model, assignment, *, component_names=('level_selected', 'hot_oil_selected', 'hot_oil_furnace_selected', 'vhp_selected', 'vhp_source_selected', 'boiler_selected', 'vhp_turbine_selected', 'steam_main_turbine_selected', 'gas_turbine_selected', 'hrsg_selected', 'hrsg_supplementary_firing_selected'))[source]

Fix utility-system master binary variables to a complete bilevel assignment.

Parameters:
Return type:

tuple[str, …]

OpenUtility.format_comparison_rows(rows, *, output_format)[source]

Format comparison rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_audit_bundle_rows(rows, *, output_format)[source]

Format candidate audit-bundle rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_pool_rows(rows, *, output_format)[source]

Format candidate-pool audit rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_pool_comparison_rows(rows, *, output_format)[source]

Format candidate-pool comparison rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_selection_delta_rows(rows, *, output_format)[source]

Format candidate-selection delta rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_selection_delta_summary_rows(rows, *, output_format)[source]

Format candidate-selection delta summary rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_source_filter_detail_rows(rows, *, output_format)[source]

Format candidate source-filter detail rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_source_filter_summary_rows(rows, *, output_format)[source]

Format candidate source-filter summary rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_candidate_source_filter_variable_rows(rows, *, output_format)[source]

Format candidate source-filter variable rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_decomposition_run_rows(rows, *, output_format)[source]

Format bilevel decomposition trajectory rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_skipped_candidate_rows(rows, *, output_format)[source]

Format skipped-candidate audit rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_bilevel_skipped_candidate_delta_summary_rows(rows, *, output_format)[source]

Format skipped-candidate delta summary rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_operating_cost_component_rows(rows, *, output_format)[source]

Format utility-system operating-cost component rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_operating_cost_target_rows(rows, *, output_format)[source]

Format utility-system operating-cost target rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_calibration_target_rows(rows, *, output_format)[source]

Format utility-system fuel calibration target rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_decomposition_objective_comparison_rows(rows, *, output_format)[source]

Format utility-system decomposition objective comparison rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_decomposition_skipped_candidate_rows(rows, *, output_format)[source]

Format utility-system skipped-candidate audit rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_decomposition_trajectory_rows(rows, *, output_format)[source]

Format utility-system decomposition trajectory rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_skipped_candidate_delta_summary_rows(rows, *, output_format)[source]

Format utility-system skipped-candidate delta summary rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_consumption_capacity_rows(rows, *, output_format)[source]

Format utility-system fuel-capacity context rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_consumption_diagnosis_rows(rows, *, output_format)[source]

Format utility-system fuel residual diagnosis rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_consumption_equipment_rows(rows, *, output_format)[source]

Format utility-system equipment-level fuel residual rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_consumption_family_rows(rows, *, output_format)[source]

Format utility-system fuel-family residual rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_fuel_consumption_residual_ranking_rows(rows, *, output_format)[source]

Format utility-system fuel-residual ranking rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_audit_bundle_rows(rows, *, output_format)[source]

Format utility-system candidate audit-bundle rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_pool_rows(rows, *, output_format)[source]

Format utility-system candidate-pool rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_pool_comparison_rows(rows, *, output_format)[source]

Format utility-system candidate-pool comparison rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_selection_delta_rows(rows, *, output_format)[source]

Format utility-system candidate-selection delta rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_selection_delta_summary_rows(rows, *, output_format)[source]

Format utility-system candidate-selection delta summary rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_source_filter_detail_rows(rows, *, output_format)[source]

Format utility-system candidate source-filter detail rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_source_filter_summary_rows(rows, *, output_format)[source]

Format utility-system candidate source-filter summary rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_utility_system_candidate_source_filter_variable_rows(rows, *, output_format)[source]

Format utility-system candidate source-filter variable rows.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.format_summary_rows(rows, *, output_format)[source]

Format comparison summary rows as CSV or JSON text.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • output_format (str)

Return type:

str

OpenUtility.heat_content_by_interval(streams, intervals)[source]

Calculate interval heat content from shifted stream temperatures.

Parameters:
Return type:

HeatIntervalProfile

OpenUtility.pyomo_utility_system_solver(solver_name, *, tee=False, options=None)[source]

Return a static utility-system solve callback using a Pyomo SolverFactory solver.

Parameters:

  • solver_name (str)

  • tee (bool)

  • options (Mapping[str, object] | None)

Return type:

Callable[[ConcreteModel], UtilitySystemSolverStatus | None]

OpenUtility.run_bilevel_decomposition(build_master, *, solve_master, solve_subproblem, max_iterations, solution_pool=None, absolute_gap_tolerance=None, binary_variables=None, assignment_from_model=None, component_name='bilevel_no_good_cuts')[source]

Run a bounded sequence of bilevel decomposition iterations.

Parameters:
Return type:

BilevelDecompositionRun

OpenUtility.run_bilevel_decomposition_iteration(build_master, *, solve_master, solve_subproblem, solution_pool=None, iteration_index=1, binary_variables=None, assignment_from_model=None, component_name='bilevel_no_good_cuts')[source]

Run one master/slave bilevel decomposition iteration.

Parameters:
Return type:

BilevelDecompositionIteration

OpenUtility.run_successive_milp_property_updates(data, *, initial_spec, solve, properties, convergence_tolerance, max_iterations)[source]

Repeat MILP solves and steam-property updates until temperatures converge.

Parameters:
Return type:

SuccessiveMilpRun

OpenUtility.run_utility_system_binary_selection_candidate_decomposition(scenario, *, candidates, solve_subproblem, max_iterations, absolute_gap_tolerance=None)[source]

Run binary-selection decomposition while cutting failed candidates.

Parameters:
Return type:

BilevelDecompositionRun

OpenUtility.run_utility_system_binary_selection_decomposition(scenario, *, solve_master, solve_subproblem, max_iterations, absolute_gap_tolerance=None)[source]

Run a separated binary utility-system master with fixed utility-system subproblems.

Parameters:
Return type:

BilevelDecompositionRun

OpenUtility.run_utility_system_fixed_assignment_decomposition(scenario, *, solve_master, solve_subproblem, max_iterations, absolute_gap_tolerance=None)[source]

Run the generic bilevel loop with utility-system master and fixed subproblem.

Parameters:
Return type:

BilevelDecompositionRun

OpenUtility.run_utility_system_scenario(scenario, *, solve)[source]

Build, solve, extract, and optionally benchmark one static utility-system scenario.

Parameters:
Return type:

UtilitySystemRunResult

OpenUtility.solve_utility_system_model_with_pyomo(model, solver_name, *, tee=False, options=None)[source]

Solve a static utility-system Pyomo model and normalize solver status metadata.

Parameters:

  • model (ConcreteModel)

  • solver_name (str)

  • tee (bool)

  • options (Mapping[str, object] | None)

Return type:

UtilitySystemSolverStatus

OpenUtility.steam_main_superheating_balances_from_model(data, model, *, level_targets, vhp_targets, properties, mechanical_efficiency=1.0, selection_tolerance=1e-06)[source]

Calculate Stage 4 steam-main superheating balances from solved flows.

Parameters:
Return type:

tuple[SteamMainSuperheatingBalance, …]

OpenUtility.steam_property_update_spec_from_stage4_model(data, model, *, level_targets, vhp_targets, properties, mechanical_efficiency=1.0, selection_tolerance=1e-06)[source]

Build a property update spec with Stage 4 calculated steam temperatures.

Parameters:
Return type:

SteamPropertyUpdateSpec

OpenUtility.steam_property_update_spec_from_model(data, model, *, level_targets, vhp_targets, selection_tolerance=1e-06)[source]

Extract selected steam-property update targets from a solved utility-system model.

Parameters:
Return type:

SteamPropertyUpdateSpec

OpenUtility.utility_system_fuel_capacity_context_by_equipment(model)[source]

Return capacity context for individual fuel-consuming equipment.

Parameters:

model (ConcreteModel)

Return type:

tuple[UtilitySystemFuelCapacityContext, …]

OpenUtility.utility_system_fuel_consumption_by_equipment(model)[source]

Return model fuel consumption by individual equipment item.

Parameters:

model (ConcreteModel)

Return type:

tuple[UtilitySystemFuelConsumptionEquipment, …]

OpenUtility.utility_system_fuel_consumption_by_family(model)[source]

Return model fuel consumption grouped by equipment family.

Parameters:

model (ConcreteModel)

Return type:

tuple[UtilitySystemFuelConsumptionFamily, …]

OpenUtility.utility_system_operating_cost_components(model)[source]

Return reportable operating-cost component buckets.

Parameters:

model (ConcreteModel)

Return type:

tuple[UtilitySystemOperatingCostComponent, …]

OpenUtility.utility_system_operating_cost_adjustment_map_from_target_rows(rows)[source]

Return scenario operating-cost adjustment maps from target rows.

Parameters:

rows (Iterable[dict[str, Any]])

Return type:

dict[str, dict[str, float]]

OpenUtility.utility_system_operating_cost_component_rows(*, catalog, scenario, model, benchmark)[source]

Return operating-cost component comparisons against a benchmark row.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_operating_cost_target_rows(rows, *, absolute_tolerance=1e-09)[source]

Return component adjustments that close total operating-cost residuals.

Parameters:

  • rows (Iterable[dict[str, Any]])

  • absolute_tolerance (float)

Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_calibration_target_rows(rows)[source]

Return fuel-consumption targets needed to close residuals.

Parameters:

rows (Iterable[dict[str, Any]])

Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_factor_map_from_calibration_target_rows(rows)[source]

Return scenario fuel-accounting factors from target rows.

Parameters:

rows (Iterable[dict[str, Any]])

Return type:

dict[str, dict[tuple[str, str], float]]

OpenUtility.utility_system_binary_selection_candidate_from_scenario(scenario, *, solve)[source]

Solve a static utility-system scenario and extract its binary master assignment.

Parameters:
Return type:

BilevelIntegerAssignment

OpenUtility.utility_system_binary_selection_candidate_records_from_scenarios(scenarios, *, solve, source_label_factory=None)[source]

Return unique solved binary-selection candidates with source labels.

Parameters:
Return type:

tuple[BilevelCandidateAssignment, …]

OpenUtility.utility_system_binary_selection_candidate_solver(candidates)[source]

Return a master callback that applies the first cut-feasible candidate.

Parameters:

candidates (Iterable[BilevelIntegerAssignment])

Return type:

Callable[[Block], str]

OpenUtility.utility_system_binary_selection_candidates_from_scenarios(scenarios, *, solve)[source]

Return unique solved binary-selection candidates in scenario order.

Parameters:
Return type:

tuple[BilevelIntegerAssignment, …]

OpenUtility.utility_system_binary_selection_master_assignment_from_model(model, *, threshold=0.5)[source]

Read a binary-selection master solution into an assignment.

Parameters:

  • model (Block)

  • threshold (float)

Return type:

BilevelIntegerAssignment

OpenUtility.utility_system_candidate_audit_bundle_rows(*, catalog, scenario, candidates, run, accepted_assignment)[source]

Return candidate audit-bundle rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_pool_rows(*, catalog, scenario, candidates)[source]

Return candidate-pool rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_pool_comparison_rows(*, catalog, scenario, candidates, accepted_assignment)[source]

Return candidate-pool comparison rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_selection_delta_rows(*, catalog, scenario, candidates, accepted_assignment)[source]

Return candidate-selection delta rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_selection_delta_summary_rows(*, catalog, scenario, candidates, accepted_assignment)[source]

Return grouped candidate-selection deltas with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_source_filter_detail_rows(*, catalog, scenario, candidates, variable_names)[source]

Return candidate source-filter detail rows with utility-system metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_source_filter_summary_rows(*, catalog, scenario, candidates, variable_names)[source]

Return candidate source-filter summary rows with utility-system metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_candidate_source_filter_variable_rows(*, catalog, scenario, candidates, variable_names)[source]

Return candidate source-filter variable rows with utility-system metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_decomposition_objective_comparison_rows(*, catalog, scenario, run, benchmark, absolute_tolerance=None)[source]

Compare decomposition objective values with Table 2-9 total costs.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_decomposition_skipped_candidate_rows(*, catalog, scenario, run)[source]

Return skipped-candidate audit rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_decomposition_trajectory_rows(*, catalog, scenario, run)[source]

Return decomposition trajectory rows with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_skipped_candidate_delta_summary_rows(*, catalog, scenario, run, accepted_assignment)[source]

Return skipped-candidate delta summaries with utility-system scenario metadata.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_capacity_rows(*, catalog, scenario, model, benchmark)[source]

Return equipment fuel-consumption rows with capacity context.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_diagnosis_rows(rows)[source]

Classify scenario-level physical-profile fuel residual drivers.

Parameters:

rows (Iterable[dict[str, Any]])

Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_equipment_rows(*, catalog, scenario, model, benchmark)[source]

Return equipment-level fuel-consumption residual trace rows.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_family_rows(*, catalog, scenario, model, benchmark)[source]

Return fuel-family rows compared with a Table 2-9 fuel benchmark.

Parameters:
Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fuel_consumption_residual_ranking_rows(rows)[source]

Rank scenarios by absolute fuel-consumption residual.

Parameters:

rows (Iterable[dict[str, Any]])

Return type:

tuple[dict[str, Any], …]

OpenUtility.utility_system_fixed_assignment_subproblem_result(scenario, assignment, *, solve)[source]

Solve a static utility-system model with master binaries fixed by assignment.

Parameters:
Return type:

BilevelSubproblemResult

OpenUtility.utility_system_master_binary_variables(model, *, component_names=('level_selected', 'hot_oil_selected', 'hot_oil_furnace_selected', 'vhp_selected', 'vhp_source_selected', 'boiler_selected', 'vhp_turbine_selected', 'steam_main_turbine_selected', 'gas_turbine_selected', 'hrsg_selected', 'hrsg_supplementary_firing_selected'))[source]

Return canonical utility-system master binary variable names and Pyomo variables.

Parameters:

  • model (Block)

  • component_names (Iterable[str])

Return type:

dict[str, Any]

OpenUtility.utility_system_master_integer_assignment_from_model(model, *, threshold=0.5, component_names=('level_selected', 'hot_oil_selected', 'hot_oil_furnace_selected', 'vhp_selected', 'vhp_source_selected', 'boiler_selected', 'vhp_turbine_selected', 'steam_main_turbine_selected', 'gas_turbine_selected', 'hrsg_selected', 'hrsg_supplementary_firing_selected'))[source]

Read current utility-system master binary values into a bilevel assignment.

Parameters:

  • model (Block)

  • threshold (float)

  • component_names (Iterable[str])

Return type:

BilevelIntegerAssignment

OpenUtility.utility_system_model_data_from_heat_profile(profile, *, steam_main, power_demand, generation_enthalpy_delta, use_enthalpy_delta, steam_enthalpy_for_use=None, feedwater_enthalpy=0.0, source_heat_loss_fraction=0.0, sink_heat_loss_fraction=0.0)[source]

Create single-main utility-system data from a shifted heat interval profile.

Parameters:

  • profile (HeatIntervalProfile)

  • steam_main (str)

  • power_demand (float)

  • generation_enthalpy_delta (float)

  • use_enthalpy_delta (float)

  • steam_enthalpy_for_use (float | None)

  • feedwater_enthalpy (float)

  • source_heat_loss_fraction (float)

  • sink_heat_loss_fraction (float)

Return type:

UtilitySystemModelData

OpenUtility.utility_system_model_data_from_heat_profile_for_steam_mains(profile, *, steam_mains, power_demand, generation_enthalpy_delta, use_enthalpy_delta, steam_enthalpy_for_use=None, feedwater_enthalpy=0.0, heat_load_steam_main=None, source_heat_loss_fraction=0.0, sink_heat_loss_fraction=0.0)[source]

Create physical interval candidates for each supplied steam main.

Parameters:

  • profile (HeatIntervalProfile)

  • steam_mains (tuple[str, ...])

  • power_demand (float)

  • generation_enthalpy_delta (float)

  • use_enthalpy_delta (float)

  • steam_enthalpy_for_use (float | None)

  • feedwater_enthalpy (float)

  • heat_load_steam_main (str | None)

  • source_heat_loss_fraction (float)

  • sink_heat_loss_fraction (float)

Return type:

UtilitySystemModelData