Entrypoints and Assets

This page documents the repository-level entrypoints and packaged assets that support the main OpenPinch workflows outside the core analysis modules.

CLI and Packaged Resources

Command-line helpers for packaged OpenPinch notebook assets.

OpenPinch.__main__.build_parser()[source]

Create the CLI argument parser.

Return type:

ArgumentParser

OpenPinch.__main__.main(argv=None)[source]

Execute the OpenPinch CLI.

Parameters:

argv (list[str] | None)

Return type:

int

Helpers for accessing packaged OpenPinch sample cases and notebooks.

class OpenPinch.resources.NotebookMetadata(name, title, description, topics=())[source]

Bases: object

Description of one packaged notebook.

Parameters:
class OpenPinch.resources.SampleCaseMetadata(name, title, description, topics=())[source]

Bases: object

Description of one packaged sample case.

Parameters:
OpenPinch.resources.copy_notebook(name, destination)[source]

Copy a packaged notebook to destination.

Parameters:
Return type:

Path

OpenPinch.resources.copy_sample_case(name, destination)[source]

Copy a packaged sample case to destination.

Parameters:
Return type:

Path

OpenPinch.resources.list_notebooks()[source]

Return the packaged notebook filenames.

Return type:

list[str]

OpenPinch.resources.list_sample_cases()[source]

Return the packaged sample-case filenames.

Return type:

list[str]

OpenPinch.resources.notebook_metadata(name=None)[source]

Return metadata for one or all packaged notebooks.

Parameters:

name (str | None)

OpenPinch.resources.read_sample_case(name)[source]

Return the text of a packaged sample case.

Parameters:

name (str)

Return type:

str

OpenPinch.resources.sample_case_metadata(name=None)[source]

Return metadata for one or all packaged sample cases.

Parameters:

name (str | None)

Packaged Data Assets

Packaged data assets for examples and notebooks.

Packaged sample cases for OpenPinch user workflows.

Packaged example notebooks for OpenPinch user workflows.

Heat Exchanger Network Synthesis

These modules back the public problem.design HEN synthesis accessors. The entry module owns dispatch and problem result caching; targeting service modules own method-specific orchestration.

Service entry and dispatch for heat exchanger network synthesis.

OpenPinch.services.heat_exchanger_network_synthesis.heat_exchanger_network_synthesis_entry.heat_exchanger_network_evolution_method_service(problem, *, initial_networks=None, options=None, workspace_variant=None, executor=None)[source]

Run only seeded network evolution and update the problem cache.

Parameters:
Return type:

HeatExchangerNetworkSynthesisResult

OpenPinch.services.heat_exchanger_network_synthesis.heat_exchanger_network_synthesis_entry.heat_exchanger_network_open_hens_method_service(problem, *, options=None, workspace_variant=None, executor=None)[source]

Run the original tier-1 OpenHENS PDM -> TDM -> EVM sequence.

Parameters:
Return type:

HeatExchangerNetworkSynthesisResult

OpenPinch.services.heat_exchanger_network_synthesis.heat_exchanger_network_synthesis_entry.heat_exchanger_network_pinch_design_method_service(problem, *, options=None, workspace_variant=None, executor=None)[source]

Run only the pinch design method and update the problem cache.

Parameters:
Return type:

HeatExchangerNetworkSynthesisResult

OpenPinch.services.heat_exchanger_network_synthesis.heat_exchanger_network_synthesis_entry.heat_exchanger_network_synthesis_service(problem, *, method=None, initial_networks=None, options=None, workspace_variant=None, executor=None)[source]

Dispatch one HEN design method and update the problem cache.

Parameters:
Return type:

HeatExchangerNetworkSynthesisResult

OpenPinch.services.heat_exchanger_network_synthesis.heat_exchanger_network_synthesis_entry.heat_exchanger_network_thermal_derivative_method_service(problem, *, initial_networks=None, options=None, workspace_variant=None, executor=None)[source]

Run only seeded TDM and update the problem cache.

Parameters:
Return type:

HeatExchangerNetworkSynthesisResult

OpenHENS workflow orchestration for HEN synthesis.

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.open_hens_method.execute_open_hens_method(problem, settings, *, executor=None)[source]

Generate, execute, and collect the PDM -> TDM -> EVM task graph.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • executor (SynthesisExecutor | None)

Return type:

SynthesisWorkflowResult

Pinch design method orchestration for HEN synthesis.

class OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.pinch_design_method.PinchDesignDecomposition(*, pinch_location, period_targets, z_i_active, z_j_active, z_i_active_by_period, z_j_active_by_period, clipped_hot_supply_temperatures_by_period, clipped_hot_target_temperatures_by_period, clipped_cold_supply_temperatures_by_period, clipped_cold_target_temperatures_by_period, S, K, manual_stage_selection, hot_stream_identities, cold_stream_identities, unit_conventions, dt_cont_convention)[source]

Bases: BaseModel

OpenPinch-native PDM fields that shape downstream TDM/ESM tasks.

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', 'frozen': True, 'validate_assignment': True}

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

class OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.pinch_design_method.PinchDesignTarget(*, period_id, period_idx, hot_utility_target, cold_utility_target, heat_recovery_target, hot_pinch, cold_pinch, shifted_pinch_temperature, target_access_contract=('OpenPinch direct_heat_integration on copied Zone', 'Zone.process_streams', 'Stream.dt_cont clamped to dTmin / 2 minimum'))[source]

Bases: BaseModel

Semantic OpenPinch target values used by PDM decomposition.

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)

  • hot_utility_target (float)

  • cold_utility_target (float)

  • heat_recovery_target (float)

  • hot_pinch (float | None)

  • cold_pinch (float | None)

  • shifted_pinch_temperature (float | None)

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

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

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

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.pinch_design_method.build_pinch_design_decomposition(problem, dTmin, *, pinch_location, stage_selection='automated')[source]

Return PDM decomposition fields from OpenPinch-owned problem state.

The stable contract is prepared PinchProblem in, copied and convention-normalized Zone targeting, and identity-preserving structural PDM fields out. The helper is private so it cannot become a public synthesis entry point or bypass the migration replacement gate.

Parameters:
Return type:

PinchDesignDecomposition

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.pinch_design_method.build_pinch_design_method_tasks(settings, *, problem=None)[source]

Generate root PDM tasks by sweeping configured approach temperatures.

Parameters:

settings (SynthesisWorkflowSettings)

Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.pinch_design_method.execute_pinch_design_method_stage(problem, settings, *, executor=None)[source]

Build and execute one pinch-design stage.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • executor (SynthesisExecutor | None)

Thermal derivative method orchestration for HEN synthesis.

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.thermal_derivative_method.build_seeded_thermal_derivative_method_tasks(settings, seed_networks)[source]

Generate standalone TDM tasks from existing seed-network topologies.

Parameters:
Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.thermal_derivative_method.build_thermal_derivative_method_tasks(settings, pdm_outcomes)[source]

Fan successful PDM topologies out over derivative thresholds.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • pdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.thermal_derivative_method.execute_seeded_thermal_derivative_method_stage(problem, settings, seed_networks, *, executor=None)[source]

Build and execute one standalone seeded TDM stage.

Parameters:
OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.thermal_derivative_method.execute_thermal_derivative_method_stage(problem, settings, pdm_outcomes, *, parent_outcomes, executor=None)[source]

Build and execute one TDM stage from PDM parent outcomes.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • pdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

  • parent_outcomes (dict[str, HeatExchangerNetworkSynthesisTaskOutcome])

  • executor (SynthesisExecutor | None)

Network evolution method orchestration for HEN synthesis.

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.build_direct_network_evolution_method_tasks(settings)[source]

Generate ESM tasks without Couenne-backed PDM/TDM parent tasks.

Parameters:

settings (SynthesisWorkflowSettings)

Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.build_network_evolution_method_tasks(settings, tdm_outcomes)[source]

Generate one ESM refinement task for each successful TDM topology.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • tdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.build_network_evolution_method_tasks_from_pinch_design_method(pdm_outcomes, *, settings=None)[source]

Generate ESM tasks directly from PDM when TDM is unavailable.

Parameters:

  • pdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

  • settings (SynthesisWorkflowSettings | None)

Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.build_seeded_network_evolution_method_tasks(settings, seed_networks)[source]

Generate standalone evolution tasks from existing seed-network topologies.

Parameters:
Return type:

tuple[HeatExchangerNetworkSynthesisTask, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.execute_direct_network_evolution_method_stage(problem, settings, *, executor=None)[source]

Build and execute evolution without PDM/TDM parent tasks.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • executor (SynthesisExecutor | None)

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.execute_network_evolution_method_from_pinch_design_stage(problem, settings, pdm_outcomes, *, parent_outcomes, executor=None)[source]

Build and execute evolution directly from successful PDM outcomes.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • pdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

  • parent_outcomes (dict[str, HeatExchangerNetworkSynthesisTaskOutcome])

  • executor (SynthesisExecutor | None)

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.execute_network_evolution_method_stage(problem, settings, tdm_outcomes, *, parent_outcomes, executor=None)[source]

Build and execute one evolution stage from TDM parent outcomes.

Parameters:

  • settings (SynthesisWorkflowSettings)

  • tdm_outcomes (Sequence[HeatExchangerNetworkSynthesisTaskOutcome])

  • parent_outcomes (dict[str, HeatExchangerNetworkSynthesisTaskOutcome])

  • executor (SynthesisExecutor | None)

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.network_evolution_method.execute_seeded_network_evolution_method_stage(problem, settings, seed_networks, *, executor=None)[source]

Build and execute one standalone seeded evolution stage.

Parameters:

Canonical topology helpers for HEN synthesis task generation.

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.topology.canonical_stage_count(restrictions)[source]

Return the stage count implied by canonical restrictions.

Parameters:

restrictions (Iterable[HeatExchangerNetworkTopologyRestriction])

Return type:

int

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.topology.canonical_topology_restrictions(restrictions, *, hot_stream_order=None, cold_stream_order=None)[source]

Return restrictions in canonical grid-stage form.

Empty recovery-stage gaps are removed. Within each occupied original stage, independent match groups are split into consecutive stages, while matches that share a process hot or cold stream stay in the same canonical stage.

Parameters:
Return type:

tuple[HeatExchangerNetworkTopologyRestriction, …]

OpenPinch.services.heat_exchanger_network_synthesis.targeting_services.topology.topology_restriction_signature(restrictions)[source]

Return a duty-independent topology signature.

Parameters:

restrictions (Iterable[HeatExchangerNetworkTopologyRestriction])

Return type:

tuple[tuple[str, str, int], …]

Internal quality-tier pathway planning for OpenHENS workflows.

Tier semantics:

  • 0: fastest compact PDM directly to EVM.

  • 1: exact standard OpenHENS PDM -> TDM -> EVM route.

  • 2: protected tiers 0/1 plus base-dTmin compact/direct and raw/TDM routes.

  • 3: base and doubled-dTmin compact/direct and raw/TDM routes.

  • 4: tier-3 dTmin routes with wider EVM branch exploration.

  • 5: experimental reduced/base/doubled-dTmin search at tier-4 breadth.

class OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.TierPathway(pathway_id, tier_origin, pathway_kind, pdm_mode, multiplier, uses_tdm, evm_n_ad_branches, evm_n_rm_branches, evm_no_improvement_patience, protected, exact_open_hens=False)[source]

Bases: object

One protected or expanded route through the OpenHENS workflow.

Parameters:

  • pathway_id (str)

  • tier_origin (int)

  • pathway_kind (str)

  • pdm_mode (Literal['compact', 'raw', 'standard'])

  • multiplier (float | None)

  • uses_tdm (bool)

  • evm_n_ad_branches (int)

  • evm_n_rm_branches (int)

  • evm_no_improvement_patience (int | None)

  • protected (bool)

  • exact_open_hens (bool)

OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.pathway_metadata(pathways)[source]

Return compact task metadata for one or more pathway specs.

Parameters:

pathways (Iterable[TierPathway])

Return type:

dict[str, object]

OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.pathways_from_metadata(metadata)[source]

Rehydrate pathway specs stored on task metadata.

Parameters:

metadata (dict)

Return type:

tuple[TierPathway, …]

OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.tier_evm_branch_breadth(tier)[source]

Return default add/remove EVM branch breadth for one tier.

Parameters:

tier (int)

Return type:

int

OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.tier_pathways(settings)[source]

Return the monotonic pathway set for the configured quality tier.

Return type:

tuple[TierPathway, …]

OpenPinch.services.heat_exchanger_network_synthesis.common.execution.pathways.tier_pdm_multipliers(tier)[source]

Return tier-generated dt-cont multipliers for expanded PDM paths.

Parameters:

tier (int)

Return type:

tuple[float, …]

Streamlit App

Streamlit entry point for exploring OpenPinch analysis results.

Run with streamlit run streamlit_app.py to load the bundled demonstration case and launch the interactive dashboard defined in OpenPinch.streamlit_webviewer.web_graphing.

streamlit_app.validate_problem_path(problem_path)[source]

Stop the Streamlit app early when the configured problem file is missing.

Return type:

None

Repository Maintenance Scripts

Build the local Sphinx documentation tree.

scripts.build_docs.build_parser()[source]

Create the CLI parser for docs builds.

Return type:

ArgumentParser

scripts.build_docs.main(argv=None)[source]

Build the HTML documentation tree into docs/_build/html by default.

Parameters:

argv (list[str] | None)

Return type:

int

Build the local source and wheel distributions.

scripts.build_dist.build_parser()[source]

Create the CLI parser for distribution builds.

Return type:

ArgumentParser

scripts.build_dist.main(argv=None)[source]

Build the package into dist/ by default.

Parameters:

argv (list[str] | None)

Return type:

int

Format the repository with Ruff.

scripts.format_repo.main()[source]

Run the repository formatter through the local uv toolchain.

Return type:

int

Smoke checks for the published optional install surfaces.

scripts.optional_install_smoke.build_parser()[source]

Create the CLI parser for smoke checks.

Return type:

ArgumentParser

scripts.optional_install_smoke.main(argv=None)[source]

Run the selected smoke-check surface.

Parameters:

argv (list[str] | None)

Return type:

int

Update the project Python runtime and lockfile to the latest compatible versions.

scripts.update_toolchain.main()[source]

Refresh the pinned Python toolchain, lockfile, and synced dev env.

Return type:

int