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.

Configuration

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

Bases: object

Runtime configuration defaults used throughout OpenPinch.

The attributes on this class combine global numerical settings, workbook- compatible feature flags, and advanced-analysis parameters such as heat pump or costing options. A Configuration instance is attached to each Zone so workflows can vary behaviour by hierarchy level if needed.

Initialise defaults and optionally apply user-provided options.

Parameters:

options (dict | None)
top_zone_name (str)
top_zone_identifier (str)

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:

streams (List[StreamSchema])
utilities (List[UtilitySchema])
options (dict | None)
zone_tree (ZoneTreeSchema | None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.lib.schemas.io.TargetOutput(*, name='Site', state_id=None, targets, graphs=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:

name (str)
state_id (str | None)
targets (List[TargetResults])
graphs (Dict[str, GraphSet] | None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.lib.schemas.io.StreamSchema(*, zone, name, t_supply, t_target, heat_flow, dt_cont=0.0, htc=1.0, 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)
t_supply (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights)
t_target (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights)
heat_flow (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights)
dt_cont (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
htc (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
active (bool)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.lib.schemas.io.UtilitySchema(*, name, type, t_supply, t_target=None, heat_flow=None, dt_cont=0.0, htc=1.0, price=1.0, 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)
t_supply (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights)
t_target (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
heat_flow (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
dt_cont (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
htc (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
price (float | ValueWithUnit | StatefulValueWithUnit | StatefulValueWithUnitAndWeights | None)
active (bool)

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

name (str)
type (str)
dt_cont_multiplier (float | None)
children (List[ZoneTreeSchema] | None)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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, state_id=None, state_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)
state_id (str | None)
state_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].

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]

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.