Schema and Configuration

The OpenPinch.lib package defines the typed contract between external callers and the analysis engine. If you are building an application around OpenPinch, this is the package that tells you what inputs are accepted, what outputs are returned, and which enumerated labels and configuration flags are expected throughout the workflow.

Configuration and Numeric Conventions

OpenPinch.lib.config provides the runtime configuration object and the global constants used across multiple modules. Many option names intentionally mirror the long-standing Excel workbook so workbook and Python workflows can share the same mental model.

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.

Configuration defaults and global numerical constants for OpenPinch.

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.

Enumerations and Labels

The enums module centralises the canonical names used for zones, targets, streams, graph series, heat exchanger network design methods, and workbook-compatible option keys. Refer to these when you need stable identifiers instead of free-form strings. Heat exchanger network synthesis uses HeatExchangerNetworkDesignMethod for both public dispatch and task/result method metadata, with HENDesignMethod as the shorter alias.

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.lib.enums.ArrowHead(*values)[source]

Bases: Enum

Position of arrow head

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

Bases: str, Enum

Supported optimisation backends for multistart black-box search.

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

Bases: Protocol

Compatible target surface required by cogeneration analysis helpers.

class OpenPinch.lib.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.lib.enums.GraphType(*values)[source]

Bases: Enum

Graph groups available in OpenPinch reporting data.

OpenPinch.lib.enums.GT

alias of GraphType

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

Bases: str, Enum

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

OpenPinch.lib.enums.HEN

alias of HeatExchangerNetworkLabel

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

Bases: Enum

Heat exchanger network metric labels for labelled accessors.

class OpenPinch.lib.enums.HeatExchangerStreamRole(*values)[source]

Bases: str, Enum

Identity class for the source and sink streams on an exchanger link.

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

Bases: Enum

Heat exchanger flow arrangements

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

Bases: Enum

Heat flow units

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

Bases: Enum

Heat pump components

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

Bases: str, Enum

Supported heat pump targeting model families.

OpenPinch.lib.enums.HPRcycle

alias of HeatPumpAndRefrigerationCycle

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

Bases: Enum

Legend labels for multi-series graphs.

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

Bases: Enum

Line colour selection

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

Bases: Enum

Problem table column header labels

OpenPinch.lib.enums.PT

alias of ProblemTableLabel

OpenPinch.lib.enums.ResultsType

alias of GraphType

OpenPinch.lib.enums.SID

alias of StreamID

OpenPinch.lib.enums.SD

alias of StreamDataLabel

OpenPinch.lib.enums.ST

alias of StreamType

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

Bases: Enum

Stream data column header labels

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

Bases: Enum

Stream identity

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

Bases: Enum

Stream set identity

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

Bases: Enum

Steam type

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

Bases: Enum

Row semantics for tabular summary output.

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

Bases: Enum

Different target calculation categories.

OpenPinch.lib.enums.TT

alias of TargetType

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

Bases: Enum

Alternative turbine performance correlations used in power targeting.

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

Bases: Enum

Types of zones used to divide the problem.

OpenPinch.lib.enums.ZT

alias of ZoneType

Pydantic Schemas

The schema layer is the primary programmatic interface to OpenPinch. It is now split by concern under OpenPinch.lib.schemas rather than concentrated in one large module.

The main schema modules are:

Common request models include:

Common response and reporting models include:

Heat pump integration helper models include:

Specialised helper models also capture lower-level Heat Pump optimisation inputs/outputs, integrated Heat Pump screening comparisons, piecewise stream linearisation requests, and structured targeting/graph outputs.

Concern-based schema package for OpenPinch.

Common schema primitives and shared type aliases.

class OpenPinch.lib.schemas.common.PeriodValueWithUnit(*, values, unit=None)[source]

Bases: BaseModel

Container storing multi-period magnitudes, weights, and a shared unit.

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.common.PeriodValueWithUnitAndWeights(*, values, unit=None, weights=None)[source]

Bases: BaseModel

Container storing multi-period magnitudes, weights, and a shared unit.

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.common.ValueWithUnit(*, value=None, unit=None)[source]

Bases: BaseModel

Container storing a magnitude and its associated unit string.

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:

  • value (float | None)

  • unit (str | None)

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].

Graph data schemas.

class OpenPinch.lib.schemas.graphs.DataPoint(*, x, y)[source]

Bases: BaseModel

Coordinate used to construct composite curves and other plots.

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.graphs.Graph(*, type, segments=<factory>)[source]

Bases: BaseModel

Collection of segments representing a single graph (e.g., GCC).

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 = {'use_enum_values': True}

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

class OpenPinch.lib.schemas.graphs.GraphSet(*, name='GraphSet', target_type=None, period_id=None, zone_name=None, zone_address=None, graphs=<factory>)[source]

Bases: BaseModel

Named group of graphs emitted for a particular zone or context.

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)

  • target_type (str | None)

  • period_id (str | None)

  • zone_name (str | None)

  • zone_address (str | None)

  • graphs (List[Graph])

model_config = {}

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

class OpenPinch.lib.schemas.graphs.Segment(*, title=None, colour=None, arrow=None, data_points=<factory>)[source]

Bases: BaseModel

Continuous plot segment optionally annotated with colour/arrows.

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].

Schemas used by heat pump and refrigeration solvers.

class OpenPinch.lib.schemas.hpr.HPRPeriodCase(*, period_id, period_idx, weight, args)[source]

Bases: BaseModel

Prepared single-period case evaluated by a shared HPR design vector.

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.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.HeatPumpTargetOutputs(*, utility_tot, w_net, w_hpr=None, w_he=None, heat_recovery=None, Q_ext, 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, Q_amb_hot, Q_amb_cold, cop_h=None, eta_he=None, obj, success, hpr_hot_streams, hpr_cold_streams, amb_streams, 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, model=None, period_outputs=None, weighted_output=None, design_vector=None, period_ids=None, period_weights=None)[source]

Bases: BaseModel

Normalized output contract for HPR 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, 'extra': 'forbid'}

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

class OpenPinch.lib.schemas.hpr.MultiPeriodHPRTargetInputs(*, period_cases, selected_period_id, selected_period_idx, hpr_type, max_multi_start, bb_minimiser, debug=False)[source]

Bases: BaseModel

Prepared all-period HPR optimisation inputs.

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].

class OpenPinch.lib.schemas.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:
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.HPRThermoArtifacts(*, hpr_streams=None, model=None, debug_figure=None)[source]

Bases: BaseModel

Optional solved thermodynamic artefacts attached to a backend result.

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].

Schemas for external inputs, outputs, and user-facing I/O data.

class OpenPinch.lib.schemas.io.NonLinearStream(*, t_supply, t_target, p_supply, p_target, h_supply, h_target, composition)[source]

Bases: BaseModel

Nonlinear stream definition used by piecewise linearisation utilities.

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.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.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].

Schemas for serialized summaries and report-facing data.

class OpenPinch.lib.schemas.reporting.GraphAvailability(*, graph_id, graph_set_id, target_name, zone_name=None, zone_address=None, target_type=None, graph_type=None, graph_name, index)[source]

Bases: BaseModel

One graph available from a solved report 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:

  • graph_id (str)

  • graph_set_id (str)

  • target_name (str)

  • zone_name (str | None)

  • zone_address (str | None)

  • target_type (str | None)

  • graph_type (str | None)

  • graph_name (str)

  • index (int)

model_config = {}

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

class OpenPinch.lib.schemas.reporting.HeatUtility(*, name, heat_flow)[source]

Bases: BaseModel

Report-friendly representation of a utility contribution.

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, 'json_encoders': {<class 'OpenPinch.classes.value.Value'>: <function <lambda>>}}

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

class OpenPinch.lib.schemas.reporting.ProblemReport(*, project_name, solved, validation, targets=<factory>, metrics=<factory>, graph_catalog=<factory>, warnings=<factory>)[source]

Bases: BaseModel

Typed report data for script, notebook, and export workflows.

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.reporting.ReportMetric(*, target_name, metric, label, value=None, unit=None, period_id=None)[source]

Bases: BaseModel

One numeric report metric resolved for a target and optional state.

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:

  • target_name (str)

  • metric (str)

  • label (str)

  • value (Any)

  • unit (str | None)

  • period_id (str | None)

model_config = {}

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

class OpenPinch.lib.schemas.reporting.TargetResults(*, name, period_idx=None, period_id=None, degree_of_integration=None, Qh, Qc, Qr, utility_cost=None, row_type=None, hot_utilities=<factory>, cold_utilities=<factory>, pinch_temp, work_target=None, process_component_work_target=None, turbine_efficiency_target=None, area=None, num_units=None, capital_cost=None, total_cost=None, exergy_sources=None, exergy_sinks=None, ETE=None, exergy_req_min=None, exergy_des_min=None, hpr_cycle=None, hpr_utility_total=None, hpr_work=None, hpr_external_utility=None, hpr_ambient_hot=None, hpr_ambient_cold=None, hpr_cop=None, hpr_eta_he=None, 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, hpr_success=None, hpr_hot_streams=None, hpr_cold_streams=None)[source]

Bases: BaseModel

Summary metrics for a single zone/target returned by 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 = {'arbitrary_types_allowed': True, 'json_encoders': {<class 'OpenPinch.classes.value.Value'>: <function <lambda>>}}

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

class OpenPinch.lib.schemas.reporting.PinchTemp(*, cold_temp=None, hot_temp=None)[source]

Bases: BaseModel

Hot and cold pinch temperatures attached to a targeting record.

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:

  • cold_temp (Value | None)

  • hot_temp (Value | None)

model_config = {'arbitrary_types_allowed': True, 'json_encoders': {<class 'OpenPinch.classes.value.Value'>: <function <lambda>>}}

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

Concrete heat exchanger network synthesis schema modules.

Runtime target schemas used by OpenPinch analysis services.

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]

class OpenPinch.lib.schemas.targets.DirectHeatPumpTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target=0.0, cold_utility_target=0.0, heat_recovery_target=0.0, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None, hpr_cycle, hpr_utility_total, hpr_work, hpr_external_utility, hpr_ambient_hot, hpr_ambient_cold, hpr_cop, hpr_eta_he, 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, hpr_success, hpr_hot_streams, hpr_cold_streams, hpr_details)[source]

Bases: HeatPumpTargetBase

Direct heat pump targeting result.

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].

class OpenPinch.lib.schemas.targets.DirectIntegrationTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target, cold_utility_target, heat_recovery_target, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, pt_real, utility_heat_recovery_target=None, area=None, num_units=None, capital_cost=None, total_cost=None, work_target=None, turbine_efficiency_target=None)[source]

Bases: GraphBackedTarget, UtilitySummaryTarget

Detailed direct-integration runtime target.

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:
to_target_results(isTotal=False)[source]

Return the reporting data including DI-only cost and work fields.

Parameters:

isTotal (bool)

Return type:

TargetResults

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].

class OpenPinch.lib.schemas.targets.DirectRefrigerationTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target=0.0, cold_utility_target=0.0, heat_recovery_target=0.0, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None, hpr_cycle, hpr_utility_total, hpr_work, hpr_external_utility, hpr_ambient_hot, hpr_ambient_cold, hpr_cop, hpr_eta_he, 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, hpr_success, hpr_hot_streams, hpr_cold_streams, hpr_details)[source]

Bases: HeatPumpTargetBase

Direct refrigeration targeting result.

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].

class OpenPinch.lib.schemas.targets.EnergyTransferTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target, cold_utility_target, heat_recovery_target, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, base_target_type, base_target_name, heat_surplus_deficit_table=<factory>, energy_transfer_diagram=<factory>)[source]

Bases: GraphBackedTarget, UtilitySummaryTarget

Energy transfer diagram and heat-surplus/deficit table target.

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].

class OpenPinch.lib.schemas.targets.HeatPumpTargetBase(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target=0.0, cold_utility_target=0.0, heat_recovery_target=0.0, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None, hpr_cycle, hpr_utility_total, hpr_work, hpr_external_utility, hpr_ambient_hot, hpr_ambient_cold, hpr_cop, hpr_eta_he, 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, hpr_success, hpr_hot_streams, hpr_cold_streams, hpr_details)[source]

Bases: GraphBackedTarget, UtilitySummaryTarget

Base contract for advanced HPR targets from explicit target_* methods.

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:
to_target_results(isTotal=False)[source]

Return the reporting data for explicit HPR target results.

Parameters:

isTotal (bool)

Return type:

TargetResults

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].

class OpenPinch.lib.schemas.targets.IndirectHeatPumpTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target=0.0, cold_utility_target=0.0, heat_recovery_target=0.0, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None, hpr_cycle, hpr_utility_total, hpr_work, hpr_external_utility, hpr_ambient_hot, hpr_ambient_cold, hpr_cop, hpr_eta_he, 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, hpr_success, hpr_hot_streams, hpr_cold_streams, hpr_details)[source]

Bases: HeatPumpTargetBase

Indirect heat pump targeting result.

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].

class OpenPinch.lib.schemas.targets.IndirectRefrigerationTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target=0.0, cold_utility_target=0.0, heat_recovery_target=0.0, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None, hpr_cycle, hpr_utility_total, hpr_work, hpr_external_utility, hpr_ambient_hot, hpr_ambient_cold, hpr_cop, hpr_eta_he, 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, hpr_success, hpr_hot_streams, hpr_cold_streams, hpr_details)[source]

Bases: HeatPumpTargetBase

Indirect refrigeration targeting result.

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].

class OpenPinch.lib.schemas.targets.TotalProcessTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target, cold_utility_target, heat_recovery_target, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None)[source]

Bases: UtilitySummaryTarget

Aggregated process-level utility summary built from solved subzones.

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].

class OpenPinch.lib.schemas.targets.TotalSiteTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target, cold_utility_target, heat_recovery_target, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None, graphs=<factory>, pt, work_target=None, turbine_efficiency_target=None)[source]

Bases: GraphBackedTarget, UtilitySummaryTarget

Total Site / indirect integration target with site Problem Tables and graphs.

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:
to_target_results(isTotal=False)[source]

Return the reporting data including Total Site work fields.

Parameters:

isTotal (bool)

Return type:

TargetResults

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].

class OpenPinch.lib.schemas.targets.UtilitySummaryTarget(*, zone_name=None, period_id=None, period_idx=None, name, type, parent_zone=None, config=<factory>, active=True, hot_utilities=<factory>, cold_utilities=<factory>, hot_utility_target, cold_utility_target, heat_recovery_target, heat_recovery_limit=None, degree_of_int=None, utility_cost=0.0, hot_pinch=None, cold_pinch=None, process_component_work_target=None, exergy_sinks=None, exergy_sources=None, exergy_des_min=None, exergy_req_min=None, ETE=None)[source]

Bases: BaseTargetModel

Target that returns utility duties and recovered-heat summaries.

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:
property utility_streams: StreamCollection

Return hot and cold utilities as one combined collection.

calc_utility_cost()[source]

Calculate and cache the total utility cost across attached utilities.

Return type:

float

to_target_results(isTotal=False)[source]

Return the common reporting data for utility-summary targets.

Parameters:

isTotal (bool)

Return type:

TargetResults

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].

Schemas for turbine solve outputs.

class OpenPinch.lib.schemas.turbine.TurbineSolveResult(*, mode, turbine_model, load_frac, mech_eff, min_eff, is_high_p_cond_flash, total_work, total_isentropic_work, overall_efficiency, total_process_duty, steam_mass_flow_in=None, inlet_pressure=None, inlet_temperature=None, sink_pressure=None, sink_temperature=None, stage_temperatures=<factory>, stage_heat_flows=<factory>, stages=<factory>)[source]

Bases: BaseModel

Validated output for a multi-stage turbine targeting solve.

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.turbine.TurbineStageResult(*, stage, source_index, stage_type, temperature, process_duty, pressure_in, pressure_out, mass_flow_in, mass_flow_extracted, mass_flow_out, enthalpy_in, enthalpy_out, condensate_enthalpy, saturation_enthalpy, dh_isentropic, work_actual, work_isentropic, isentropic_efficiency, turbine_model)[source]

Bases: BaseModel

Detailed result for one solved turbine stage.

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].