Schemas and Config

OpenPinch has two distinct but closely related internal typed surfaces:

  • schema models for external inputs and returned results

  • a runtime Configuration object attached to each prepared zone

Together they implement the transport format used by OpenPinch.PinchProblem and the per-zone analysis behaviour.

What Each Layer Does

TargetInput and related schemas

Define the request format for process streams, utilities, the optional zone tree, and an optional serialized heat exchanger network.

TargetOutput and target/result schemas

Define the structured response returned by the top-level service boundary.

Configuration

Stores numerical and engineering defaults for heat pumps, utilities, costing, turbines, and solvers. It does not select core methods. Each prepared Zone owns one config object.

Discovering Options

Use config_options() or Configuration.options_catalog() to inspect the supported flat TargetInput.options keys, their groups, runtime status, enum choices, numeric bounds, and config paths:

from OpenPinch.presentation.configuration import configuration_options as config_options

options = config_options()
hpr_options = [field for field in options if field.group == "hpr"]

Common options include THERMAL_DT_CONT for minimum contribution temperature, OUTPUT_UNIT_* fields for report units, and numerical HPR_* fields for heat-pump and refrigeration workflows. Configuration does not contain target-method selectors; the descriptive problem.target.* or problem.design.* callable selects the analysis.

Configuration

class OpenPinch.domain.configuration.Configuration(options=None, top_zone_name='Site', top_zone_identifier='Site')[source]

Bases: object

Runtime configuration translated from flat user-facing option keys.

Initialise defaults and optionally apply validated flat options.

Parameters:

  • options (dict | None)

  • top_zone_name (str)

  • top_zone_identifier (str)

classmethod from_options(options=None, *, top_zone_name='Site', top_zone_identifier='Site')[source]

Build a runtime configuration from flat user-facing options.

Parameters:

  • options (dict | None)

  • top_zone_name (str)

  • top_zone_identifier (str)

Return type:

Configuration

for_period(period_id=None, period_idx=None)[source]

Return a lightweight period context for this configuration.

Parameters:

  • period_id (str | None)

  • period_idx (int | None)

property input_unit_overrides: dict[str, str]

Return input unit overrides in the unit-system mapping format.

property output_unit_overrides: dict[str, str]

Return output unit overrides in the unit-system mapping format.

Input and Output Schemas

class OpenPinch.contracts.input.TargetInput(*, streams, utilities=<factory>, options=None, zone_tree=None, network=None, plant_profile_data=<factory>)[source]

Bases: BaseModel

Validated top-level input data for PinchProblem.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • streams (List[StreamSchema])

  • utilities (List[UtilitySchema])

  • options (dict | None)

  • zone_tree (ZoneTreeSchema | None)

  • network (HeatExchangerNetworkSchema | None)

  • plant_profile_data (List[PlantProfileSchema])

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

TargetInput.network accepts the mapping emitted by a runtime HeatExchangerNetwork, while remaining an independent transport schema:

from OpenPinch.contracts.input import TargetInput

network_payload = network.model_dump(mode="json")
input_data = TargetInput.model_validate(
    {
        "streams": [],
        "utilities": [],
        "network": network_payload,
    }
)

assert input_data.model_dump(mode="json")["network"] == network_payload

Use model_dump(mode="json") for this bridge. model_dump_json() returns an encoded string and must be decoded before it can be supplied as the nested network value. The network is retained in canonical input data, but it is not automatically consumed as a synthesis seed. Endpoint classifications use the exact StreamID values Process and Utility; lowercase legacy values and Unassigned are rejected.

class OpenPinch.contracts.input.HeatExchangerNetworkSchema(*, exchangers=<factory>, run_id=None, task_id=None, period_id=None, method=None, stage_count=None, objective_value=None, total_annual_cost=None, utility_cost=None, capital_cost=None, summary_metrics=<factory>)[source]

Bases: BaseModel

JSON transport contract for a runtime heat exchanger network dump.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • exchangers (list[HeatExchangerSchema])

  • run_id (str | None)

  • task_id (str | None)

  • period_id (str | None)

  • method (str | None)

  • stage_count (int | None)

  • objective_value (float | None)

  • total_annual_cost (float | None)

  • utility_cost (float | None)

  • capital_cost (float | None)

  • summary_metrics (dict[str, float | int | str | bool | None])

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.HeatExchangerSchema(*, exchanger_id=None, kind, source_stream, sink_stream, source_stream_role, sink_stream_role, stage=None, period_states, area=None, match_allowed=True, capital_cost=None, segment_area_contributions=<factory>)[source]

Bases: BaseModel

JSON transport contract for one runtime heat exchanger dump.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • exchanger_id (str | None)

  • kind (HeatExchangerKind)

  • source_stream (str)

  • sink_stream (str)

  • source_stream_role (StreamID)

  • sink_stream_role (StreamID)

  • stage (int | None)

  • period_states (Annotated[list[HeatExchangerPeriodStateSchema], MinLen(min_length=1)])

  • area (float | None)

  • match_allowed (bool)

  • capital_cost (float | None)

  • segment_area_contributions (list[HeatExchangerAreaSliceSchema])

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.HeatExchangerPeriodStateSchema(*, period_id, period_idx, duty, active=True, approach_temperatures=<factory>, source_split_fraction=None, sink_split_fraction=None, source_inlet_temperature=None, source_outlet_temperature=None, sink_inlet_temperature=None, sink_outlet_temperature=None)[source]

Bases: BaseModel

JSON-visible operating state for one exchanger and period.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • period_id (str)

  • period_idx (int)

  • duty (float)

  • active (bool)

  • approach_temperatures (list[float])

  • source_split_fraction (float | None)

  • sink_split_fraction (float | None)

  • source_inlet_temperature (float | None)

  • source_outlet_temperature (float | None)

  • sink_inlet_temperature (float | None)

  • sink_outlet_temperature (float | None)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.HeatExchangerAreaSliceSchema(*, period, hot_segment_identity, cold_segment_identity, duty, hot_inlet_temperature, hot_outlet_temperature, cold_inlet_temperature, cold_outlet_temperature, hot_htc, cold_htc, overall_htc, lmtd, area)[source]

Bases: BaseModel

JSON-visible area contribution for one exchanger segment pair.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • period (str)

  • hot_segment_identity (str)

  • cold_segment_identity (str)

  • duty (float)

  • hot_inlet_temperature (float)

  • hot_outlet_temperature (float)

  • cold_inlet_temperature (float)

  • cold_outlet_temperature (float)

  • hot_htc (float)

  • cold_htc (float)

  • overall_htc (float)

  • lmtd (float)

  • area (float)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.output.TargetOutput(*, name='Site', period_id=None, targets, graphs=None, design=None)[source]

Bases: BaseModel

Top-level cached targeting output for PinchProblem.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • name (str)

  • period_id (str | None)

  • targets (List[TargetResults])

  • graphs (Dict[str, GraphSet] | None)

  • design (HeatExchangerNetworkSynthesisResult | None)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.StreamSchema(*, zone, name, segments=None, profile=None, t_supply=None, t_target=None, p_supply=None, p_target=None, h_supply=None, h_target=None, heat_flow=None, heat_capacity_flowrate=None, dt_cont=0.0, htc=1.0, fluid_name=None, fluid_phase=None, active=True)[source]

Bases: BaseModel

Process stream definition supplied to the targeting service.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • zone (str)

  • name (str)

  • segments (List[StreamSegmentSchema] | None)

  • profile (TemperatureHeatProfileSchema | None)

  • t_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • t_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • p_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • p_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • heat_flow (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • heat_capacity_flowrate (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • dt_cont (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • htc (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • fluid_name (str | None)

  • fluid_phase (FluidPhase | None)

  • active (bool)

model_config = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.StreamSegmentSchema(*, name=None, t_supply, t_target, heat_flow, p_supply=None, p_target=None, h_supply=None, h_target=None, dt_cont=None, htc=None, price=None)[source]

Bases: BaseModel

One ordered linear interval in a variable-CP stream profile.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • name (str | None)

  • t_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights)

  • t_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights)

  • heat_flow (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights)

  • p_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • p_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • dt_cont (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • htc (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • price (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

model_config = {'extra': 'forbid', 'use_enum_values': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.TemperatureHeatPointSchema(*, cumulative_heat, temperature)[source]

Bases: BaseModel

One temperature and cumulative-heat coordinate in an ordered profile.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • cumulative_heat (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights)

  • temperature (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.TemperatureHeatProfileSchema(*, points, linearisation_tolerance=0.1)[source]

Bases: BaseModel

Ordered temperature-cumulative-heat data for one physical stream.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • points (List[TemperatureHeatPointSchema])

  • linearisation_tolerance (float)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.UtilitySchema(*, name, type, segments=None, profile=None, t_supply=None, t_target=None, p_supply=None, p_target=None, h_supply=None, h_target=None, heat_flow=None, dt_cont=0.0, htc=1.0, price=1.0, fluid_name=None, fluid_phase=None, active=True)[source]

Bases: BaseModel

Utility definition including thermal and optional economic attributes.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • name (str)

  • type (StreamType)

  • segments (List[StreamSegmentSchema] | None)

  • profile (TemperatureHeatProfileSchema | None)

  • t_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • t_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • p_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • p_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_supply (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • h_target (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • heat_flow (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • dt_cont (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • htc (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • price (float | ValueWithUnit | PeriodValueWithUnit | PeriodValueWithUnitAndWeights | None)

  • fluid_name (str | None)

  • fluid_phase (FluidPhase | None)

  • active (bool)

model_config = {'extra': 'forbid', 'use_enum_values': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.input.ZoneTreeSchema(*, name, type, dt_cont_multiplier=None, children=None)[source]

Bases: BaseModel

Recursive description of the zone hierarchy for the analysis.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • name (str)

  • type (str)

  • dt_cont_multiplier (float | None)

  • children (List[ZoneTreeSchema] | None)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Heat Exchanger Network Design Results

Every problem.design.* call returns an explicit design view. Inspect its selected network with design.selected_network, choose a ranked candidate with design.network(rank=...), list candidates with design.top(n), or render one with design.grid(rank=...). Convenience totals and design.utility(name) always refer to selected_network.

The complete serializable synthesis result is design.result and is also stored at problem.results.design. Serialize it explicitly:

design = problem.design.heat_exchanger_network()
payload = design.result.model_dump(mode="json")

The result’s ranked_networks, manifest, diagnostics, task metadata, design_method, and task method remain available through design.result. The design view does not forward unknown attributes and is not itself a Pydantic model.

The HeatExchangerNetworkDesignMethod enum is the single method identity used for dispatch and result metadata. design.result.manifest.method_sequence records the executed task sequence. For tiered OpenHENS runs, the manifest also records the synthesis quality tier, selected pathway, and protected-fallback status.

HENS_SYNTHESIS_QUALITY_TIER remains a persistent configuration field with a default of tier 1 for prepared-problem workflows. User code should prefer problem.design.enhanced_heat_exchanger_network(quality_tier=...) for method-level tier selection because it applies a call-local override without mutating the loaded problem configuration. Runtime options passed to design accessors are reserved for runtime context and do not accept persistent HENS_* overrides.

Method-level inputs and outputs are Pydantic models. Their shared input contract contains run/problem metadata, settings, optional seed network, optional seed-network index, and trace metadata. Their shared output contract contains status, accepted networks, ranked networks, diagnostics, trace metadata, and an optional manifest.

Ranks passed to design.network(...) and design.grid(...) are one-based.

Grid diagrams for the selected network are created with OpenPinch.presentation.network_grid.service.build_grid_diagram(). The service accepts one or more HeatExchangerNetwork objects. Select a ranked network first when needed. Multiperiod networks require an explicit period for duties, temperatures, diagrams, exports, and controllability; omission is accepted only for a single-period network. The returned object wraps the Plotly fig, a lightweight drawing adapter ax, the selected network, and the normalized grid_model used to draw the topology.

class OpenPinch.contracts.synthesis.result.HeatExchangerNetworkSynthesisResult(*, network, run_id, task_id=None, problem_id=None, workspace_variant=None, period_id=None, solver_name=None, solver_status=None, design_method=None, method=None, stage_count=None, objective_values=<factory>, ranked_networks=<factory>, manifest=None, diagnostic_references=<factory>)[source]

Bases: BaseModel

Problem-owned heat exchanger network synthesis result data.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • network (HeatExchangerNetwork)

  • run_id (str)

  • task_id (str | None)

  • problem_id (str | None)

  • workspace_variant (str | None)

  • period_id (str | None)

  • solver_name (str | None)

  • solver_status (str | None)

  • design_method (HeatExchangerNetworkDesignMethod | None)

  • method (HeatExchangerNetworkDesignMethod | None)

  • stage_count (int | None)

  • objective_values (dict[str, float])

  • ranked_networks (tuple[HeatExchangerNetworkSynthesisTaskOutcome, ...])

  • manifest (HeatExchangerNetworkSynthesisManifest | None)

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

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.synthesis.method.HeatExchangerNetworkSynthesisMethodInput(*, task_id=None, run_id, method, approach_temperature, derivative_threshold=None, stage_count=None, problem_id=None, workspace_variant=None, period_id=None, settings=<factory>, seed_network=None, seed_network_index=None, parent_task_id=None, metadata=<factory>, topology_restrictions=<factory>)[source]

Bases: BaseModel

Validated input for one PDM, TDM, or evolution method run.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • task_id (str | None)

  • run_id (str)

  • method (HeatExchangerNetworkDesignMethod)

  • approach_temperature (float)

  • derivative_threshold (float | None)

  • stage_count (int | None)

  • problem_id (str | None)

  • workspace_variant (str | None)

  • period_id (str | None)

  • settings (dict[str, Any])

  • seed_network (HeatExchangerNetwork | None)

  • seed_network_index (int | None)

  • parent_task_id (str | None)

  • metadata (dict[str, Any])

  • topology_restrictions (tuple[HeatExchangerNetworkTopologyRestriction, ...])

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

generate_task_id()[source]

Return the deterministic identifier for this task definition.

Return type:

str

class OpenPinch.contracts.synthesis.method.HeatExchangerNetworkSynthesisMethodOutput(*, method=None, task=None, status, network=None, accepted_networks=<factory>, ranked_networks=<factory>, task_manifest=None, objective_value=None, solver_status=None, error=None, diagnostics=<factory>, trace=<factory>, diagnostic_references=<factory>)[source]

Bases: BaseModel

Validated output for one PDM, TDM, or evolution method run.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • method (HeatExchangerNetworkDesignMethod | None)

  • task (HeatExchangerNetworkSynthesisMethodInput | None)

  • status (Literal['pending', 'success', 'failed', 'skipped'])

  • network (HeatExchangerNetwork | None)

  • accepted_networks (tuple[HeatExchangerNetwork, ...])

  • ranked_networks (tuple[HeatExchangerNetwork, ...])

  • task_manifest (HeatExchangerNetworkSynthesisManifest | None)

  • objective_value (float | None)

  • solver_status (str | None)

  • error (str | None)

  • diagnostics (dict[str, Any])

  • trace (dict[str, Any])

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

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.domain.enums.HeatExchangerNetworkDesignMethod(*values)[source]

Bases: str, Enum

User-selectable heat exchanger network design service methods.

Target Models

Solved targets are normalized through the target schema layer before they are returned to users or exported.

class OpenPinch.domain.targets.BaseTargetModel(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True)[source]

Bases: BaseModel

Shared metadata for all solved target objects.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • zone_name (str | None)

  • period_id (str | None)

  • period_idx (int | None)

  • name (str)

  • type (str)

  • parent_zone (Any)

  • config (Configuration)

  • active (bool)

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

HPR Schemas

The HPR schema layer carries the prepared configuration values, parsed backend state, and simulated-cycle annualized cost accounting used by the targeting services. Report-facing HPR cost fields use Value instances with serialized units $ and $/y. Internal parsed-state and backend-result records are attribute-only; call model_dump() only when mapping data is required. HPR optimiser configuration accepts the exact identifiers dual_annealing, cmaes, bo, and rbf_surrogate.

class OpenPinch.contracts.hpr.HPRParsedState(*, Q_amb_hot=0.0, Q_amb_cold=0.0, Q_amb_hot_direct=0.0, Q_amb_cold_direct=0.0, Q_amb_hot_residual=0.0, Q_amb_cold_residual=0.0, T_cond=None, T_evap=None, dT_subcool=None, dT_superheat=None, dT_ihx_gas_side=None, T_comp_out=None, dT_gc=None, dT_comp=None, Q_heat=None, Q_cool=None, Q_heat_base=None, Q_cool_base=None, x_heat_split=None, x_cool_split=None, Q_heat_available=None, Q_cool_available=None, x_mvr_source_split=None, x_mvr_process_split=None)[source]

Bases: BaseModel

Internal parsed optimisation-state data across HPR backends.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • Q_amb_hot (float)

  • Q_amb_cold (float)

  • Q_amb_hot_direct (float)

  • Q_amb_cold_direct (float)

  • Q_amb_hot_residual (float)

  • Q_amb_cold_residual (float)

  • T_cond (ndarray | None)

  • T_evap (ndarray | None)

  • dT_subcool (ndarray | None)

  • dT_superheat (ndarray | None)

  • dT_ihx_gas_side (ndarray | None)

  • T_comp_out (ndarray | None)

  • dT_gc (ndarray | None)

  • dT_comp (ndarray | None)

  • Q_heat (ndarray | None)

  • Q_cool (ndarray | None)

  • Q_heat_base (float | None)

  • Q_cool_base (float | None)

  • x_heat_split (ndarray | None)

  • x_cool_split (ndarray | None)

  • Q_heat_available (ndarray | None)

  • Q_cool_available (ndarray | None)

  • x_mvr_source_split (float | None)

  • x_mvr_process_split (ndarray | None)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.hpr.HeatPumpTargetInputs(*, hpr_type, Q_hpr_target, Q_heat_max, Q_cool_max, z_amb_hot, z_amb_cold, dt_range_max, T_hot, H_hot, T_cold, H_cold, n_cond, n_evap, n_mvr, eta_comp, eta_mvr_comp, eta_motor, eta_exp, dtcont_hp, dt_hp_ihx, dt_cascade_hx, dt_phase_change, heat_to_power_ratio, cold_to_power_ratio, ele_price, annual_op_time, discount_rate, serv_life, hpr_comp_fixed_cost, hpr_comp_variable_cost, hpr_comp_cost_exp, hpr_hx_fixed_cost, hpr_hx_variable_cost, hpr_hx_cost_exp, is_heat_pumping, max_multi_start, T_env, dt_env_cont, eta_ii_hpr_carnot, eta_ii_he_carnot, refrigerant_ls, mvr_fluid_ls, do_refrigerant_sort, initialise_simulated_cycle, allow_integrated_expander, bckgrd_hot_streams, bckgrd_cold_streams, bb_minimiser, eta_penalty, rho_penalty, period_idx=0, debug)[source]

Bases: BaseModel

Parameter bundle for heat pump and refrigeration targeting routines.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • hpr_type (str)

  • Q_hpr_target (float)

  • Q_heat_max (float)

  • Q_cool_max (float)

  • z_amb_hot (ndarray)

  • z_amb_cold (ndarray)

  • dt_range_max (float)

  • T_hot (ndarray)

  • H_hot (ndarray)

  • T_cold (ndarray)

  • H_cold (ndarray)

  • n_cond (int)

  • n_evap (int)

  • n_mvr (int)

  • eta_comp (float)

  • eta_mvr_comp (float)

  • eta_motor (float)

  • eta_exp (float)

  • dtcont_hp (float)

  • dt_hp_ihx (float)

  • dt_cascade_hx (float)

  • dt_phase_change (float)

  • heat_to_power_ratio (float)

  • cold_to_power_ratio (float)

  • ele_price (float)

  • annual_op_time (float)

  • discount_rate (float)

  • serv_life (float)

  • hpr_comp_fixed_cost (float)

  • hpr_comp_variable_cost (float)

  • hpr_comp_cost_exp (float)

  • hpr_hx_fixed_cost (float)

  • hpr_hx_variable_cost (float)

  • hpr_hx_cost_exp (float)

  • is_heat_pumping (bool)

  • max_multi_start (int)

  • T_env (float)

  • dt_env_cont (float)

  • eta_ii_hpr_carnot (float)

  • eta_ii_he_carnot (float)

  • refrigerant_ls (List[str])

  • mvr_fluid_ls (List[str])

  • do_refrigerant_sort (bool)

  • initialise_simulated_cycle (bool)

  • allow_integrated_expander (bool)

  • bckgrd_hot_streams (StreamCollection)

  • bckgrd_cold_streams (StreamCollection)

  • bb_minimiser (str)

  • eta_penalty (float)

  • rho_penalty (float)

  • period_idx (int)

  • debug (bool)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.hpr.HPRBackendResult(*, obj, utility_tot, w_net, Q_ext_heat, Q_ext_cold, hpr_operating_cost=None, hpr_capital_cost=None, hpr_annualized_capital_cost=None, hpr_total_annualized_cost=None, hpr_compressor_capital_cost=None, hpr_heat_exchanger_capital_cost=None, feasibility_penalty=0.0, Q_amb_hot, Q_amb_cold, success=True, w_hpr=None, w_he=None, heat_recovery=None, cop_h=None, eta_he=None, amb_streams=None, T_cond=None, T_evap=None, Q_cond=None, Q_evap=None, Q_cond_he=None, Q_evap_he=None, dT_subcool=None, dT_superheat=None, T_comp_out=None, dT_gc=None, dT_comp=None, Q_heat=None, Q_cool=None, failure_reason=None, artifacts=None, period_outputs=None, weighted_output=None, design_vector=None, period_ids=None, period_weights=None)[source]

Bases: BaseModel

Internal backend result before public schema validation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • obj (float)

  • utility_tot (float)

  • w_net (float | list | ndarray)

  • Q_ext_heat (float)

  • Q_ext_cold (float)

  • hpr_operating_cost (Any)

  • hpr_capital_cost (Any)

  • hpr_annualized_capital_cost (Any)

  • hpr_total_annualized_cost (Any)

  • hpr_compressor_capital_cost (Any)

  • hpr_heat_exchanger_capital_cost (Any)

  • feasibility_penalty (float)

  • Q_amb_hot (float)

  • Q_amb_cold (float)

  • success (bool)

  • w_hpr (float | list | ndarray | None)

  • w_he (float | list | ndarray | None)

  • heat_recovery (float | list | ndarray | None)

  • cop_h (float | list | ndarray | None)

  • eta_he (float | list | ndarray | None)

  • amb_streams (StreamCollection | None)

  • T_cond (ndarray | None)

  • T_evap (ndarray | None)

  • Q_cond (ndarray | None)

  • Q_evap (ndarray | None)

  • Q_cond_he (ndarray | None)

  • Q_evap_he (ndarray | None)

  • dT_subcool (ndarray | None)

  • dT_superheat (ndarray | None)

  • T_comp_out (ndarray | None)

  • dT_gc (ndarray | None)

  • dT_comp (ndarray | None)

  • Q_heat (ndarray | None)

  • Q_cool (ndarray | None)

  • failure_reason (str | None)

  • artifacts (HPRThermoArtifacts | None)

  • period_outputs (dict[str, Any] | None)

  • weighted_output (Any)

  • design_vector (ndarray | None)

  • period_ids (list[str] | None)

  • period_weights (list[float] | None)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.contracts.hpr.SimulatedHPRAnnualizedCostAccounting(*, hpr_operating_cost, hpr_capital_cost, hpr_annualized_capital_cost, hpr_total_annualized_cost, hpr_compressor_capital_cost, hpr_heat_exchanger_capital_cost, feasibility_penalty)[source]

Bases: BaseModel

Unit-aware annualized cost accounting for simulated HPR candidates.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • hpr_operating_cost (Value)

  • hpr_capital_cost (Value)

  • hpr_annualized_capital_cost (Value)

  • hpr_total_annualized_cost (Value)

  • hpr_compressor_capital_cost (Value)

  • hpr_heat_exchanger_capital_cost (Value)

  • feasibility_penalty (Value)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Enums and Typed Constants

The OpenPinch.domain.enums module owns stream types, target labels, HPR cycle selectors, turbine model choices, and other canonical identifiers.

Enumerations and lightweight typed contracts used across OpenPinch.

These enums standardize zone types, stream classifications, Problem Table column names, graph labels, and options keys used by configuration and schemas.

class OpenPinch.domain.enums.ArrowHead(*values)[source]

Bases: Enum

Position of arrow head

class OpenPinch.domain.enums.BB_Minimiser(*values)[source]

Bases: str, Enum

Supported optimisation backends for multistart black-box search.

class OpenPinch.domain.enums.CogenerationTarget(*args, **kwargs)[source]

Bases: Protocol

Compatible target surface required by cogeneration analysis helpers.

class OpenPinch.domain.enums.FluidPhase(*values)[source]

Bases: str, Enum

Supported stream fluid-phase flags.

classmethod from_code_or_description(value)[source]

Resolve a phase from its short code or descriptive label.

Parameters:

value (str | 'FluidPhase')

Return type:

FluidPhase

class OpenPinch.domain.enums.GraphType(*values)[source]

Bases: Enum

Graph groups available in OpenPinch reporting data.

class OpenPinch.domain.enums.HeatExchangerKind(*values)[source]

Bases: str, Enum

Supported heat-transfer link families in a heat exchanger network design.

class OpenPinch.domain.enums.HeatExchangerNetworkLabel(*values)[source]

Bases: Enum

Heat exchanger network metric labels for labelled accessors.

class OpenPinch.domain.enums.HeatExchangerNetworkDesignMethod(*values)[source]

Bases: str, Enum

User-selectable heat exchanger network design service methods.

class OpenPinch.domain.enums.HeatExchangerTypes(*values)[source]

Bases: Enum

Heat exchanger flow arrangements

class OpenPinch.domain.enums.HeatFlowUnits(*values)[source]

Bases: Enum

Heat flow units

class OpenPinch.domain.enums.HeatPump(*values)[source]

Bases: Enum

Heat pump components

class OpenPinch.domain.enums.HeatPumpAndRefrigerationCycle(*values)[source]

Bases: str, Enum

Supported heat pump targeting model families.

class OpenPinch.domain.enums.LegendSeries(*values)[source]

Bases: Enum

Legend labels for multi-series graphs.

class OpenPinch.domain.enums.LineColour(*values)[source]

Bases: Enum

Line colour selection

class OpenPinch.domain.enums.PenaltyForm(*values)[source]

Bases: Enum

Canonical inequality-constraint penalty algorithms.

class OpenPinch.domain.enums.ProblemTableLabel(*values)[source]

Bases: Enum

Problem table column header labels

class OpenPinch.domain.enums.StreamID(*values)[source]

Bases: str, Enum

Stream identity

class OpenPinch.domain.enums.StreamDataLabel(*values)[source]

Bases: Enum

Stream data column header labels

class OpenPinch.domain.enums.StreamType(*values)[source]

Bases: Enum

Steam type

class OpenPinch.domain.enums.StreamLoc(*values)[source]

Bases: Enum

Stream set identity

class OpenPinch.domain.enums.SummaryRowType(*values)[source]

Bases: Enum

Row semantics for tabular summary output.

class OpenPinch.domain.enums.TargetType(*values)[source]

Bases: Enum

Different target calculation categories.

class OpenPinch.domain.enums.TurbineModel(*values)[source]

Bases: Enum

Alternative turbine performance correlations used in power targeting.

class OpenPinch.domain.enums.ZoneType(*values)[source]

Bases: Enum

Types of zones used to divide the problem.

Design Notes

The schema layer should be the source of truth for external input contracts. The configuration layer should be the source of truth for runtime toggles and per-zone behavior. Keeping those roles distinct is what makes the package predictable when used from notebooks, services, and the CLI.