Schemas and Config

OpenPinch has two distinct but closely related typed surfaces:

  • schema models for external inputs and returned results

  • a runtime Configuration object attached to each prepared zone

Together they define the stable wire format and the per-zone analysis behavior that the rest of the package consumes.

What Each Layer Does

TargetInput and related schemas

Define the public request format for process streams, utilities, and the optional zone tree.

TargetOutput and target/result schemas

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

Configuration

Stores runtime knobs for targeting flags, heat pump parameters, utility assumptions, costing inputs, and turbine settings. 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 import 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, TARGETING_* flags for default target selection, OUTPUT_UNIT_* fields for report units, and HPR_* fields for heat-pump and refrigeration workflows.

Configuration

class OpenPinch.lib.config.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

classmethod options_catalog()[source]

Return declarative metadata for all supported flat option keys.

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.lib.schemas.io.TargetInput(*, streams, utilities=<factory>, options=None, zone_tree=None)[source]

Bases: BaseModel

Validated top-level input data for pinch_analysis_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:
model_config = {}

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

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

Bases: BaseModel

Top-level response data returned by OpenPinch.pinch_analysis_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:
model_config = {}

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

class OpenPinch.lib.schemas.io.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:
model_config = {'extra': 'forbid', 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}

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

class OpenPinch.lib.schemas.io.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:
model_config = {'extra': 'forbid', 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

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

class OpenPinch.lib.schemas.io.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:
model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

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

class OpenPinch.lib.schemas.io.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:
model_config = {'extra': 'forbid'}

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

class OpenPinch.lib.schemas.io.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:
model_config = {'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}

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

class OpenPinch.lib.schemas.io.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:
model_config = {}

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

Heat Exchanger Network Design Results

TargetOutput.design stores a HeatExchangerNetworkSynthesisResult after problem.design.enhanced_synthesis_method(quality_tier=...), problem.design.open_hens_method(), problem.design.heat_exchanger_network_synthesis(), or one of the direct method accessors runs. The selected network is available as design.network and the ranked unique network candidates are available as design.ranked_networks.

The same HeatExchangerNetworkDesignMethod enum is used for public dispatch and task/result method metadata. HENDesignMethod is the short public alias. design.design_method records the user-facing design service that was requested, such as HENDesignMethod.OpenHENS. design.method records the task method that produced the selected network, such as HENDesignMethod.NetworkEvolution for a normal OpenHENS sequence result. design.manifest.method_sequence records the executed task-level method sequence. For OpenHENS tiered runs, design.manifest.synthesis_quality_tier records the call-local or configured tier, selected_pathway_id records the winning pathway, and selected_protected_pathway indicates whether the selected network came from a protected fallback route.

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_synthesis_method(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 also 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.

Use design.get_n_best_networks(n) to read the first n ranked candidates. Use design.select_network(solution_rank=...) to make another ranked candidate the selected design.network. solution_rank is 1-based.

The problem-level design accessor exposes convenience totals for the selected network at problem.design.network: total_heat_recovery, total_hot_utility, total_cold_utility, and utility(name).

Grid diagrams for the selected network are created with design.network.build_grid_diagram(period_id=...). The standalone OpenPinch.services.network_grid_diagram.build_grid_diagram() service still accepts one or more HeatExchangerNetwork objects, and design.grid_diagram(solution_rank=..., period_id=...) remains available as a convenience wrapper that selects a ranked network first. 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.lib.schemas.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].

grid_diagram(solution_rank=1, *, period_id=None, stream_line_width=5.0, temperature_scaled=False)[source]

Return an OpenHENS-style grid diagram for one ranked solution.

Parameters:

  • solution_rank (int)

  • period_id (str | None)

  • stream_line_width (float)

  • temperature_scaled (bool)

get_n_best_networks(n=None)[source]

Return the best ranked network outcomes with duplicates removed.

Parameters:

n (int | None)

select_network(solution_rank=1)[source]

Select network from the ranked network list and return this result.

Parameters:

solution_rank (int)

Return type:

Self

class OpenPinch.lib.schemas.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.lib.schemas.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:
model_config = {'extra': 'forbid', 'validate_assignment': True}

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

class OpenPinch.lib.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.lib.schemas.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:
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].

to_target_results(isTotal=False)[source]

Convert the runtime target into the exported reporting schema.

Parameters:

isTotal (bool)

Return type:

TargetResults

serialize_json(isTotal=False)[source]

Serialise the reporting-schema view of this target to plain Python.

Parameters:

isTotal (bool)

Return type:

dict[str, Any]

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 public units $ and $/y.

class OpenPinch.lib.schemas.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:
model_config = {'arbitrary_types_allowed': True}

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

class OpenPinch.lib.schemas.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:
model_config = {'arbitrary_types_allowed': True}

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

class OpenPinch.lib.schemas.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.lib package also re-exports enums used across the public API, including stream types, target labels, HPR cycle selectors, and turbine model choices.

Typed configuration primitives and schemas for OpenPinch.

The OpenPinch.lib package exposes enumerations, configuration helpers, and the Pydantic schema models that define the wire format used by the public API. They are re-exported here for consumers that need to construct or inspect inputs programmatically.

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.