Utilities and I/O

These adapter, numerical, optimisation, and presentation modules are unsupported contributor APIs. They are documented to aid maintenance, not as compatibility promises.

The utilities layer supports the main targeting workflow with import/export helpers, physical-property utilities, optimisation routines, and plotting support. Several of these modules are also useful independently of the full OpenPinch workflow.

Data Conversion and Validation

These modules translate spreadsheet- or table-oriented data sources into the schema-compatible structures consumed by the service layer.

Infrastructure and third-party integration adapters.

Excel workbook ingestion helpers for OpenPinch problem/result data.

OpenPinch.adapters.io.workbook.get_problem_from_excel(excel_file, output_json=None)

Read workbook stream/utility sheets and return OpenPinch problem JSON.

OpenPinch.adapters.io.workbook.get_results_from_excel(excel_file, output_json, project_name)

Read workbook summary results and return structured target JSON.

CSV ingestion helpers that mirror the workbook-to-JSON conversion flow.

OpenPinch.adapters.io.csv.get_problem_from_csv(streams_csv, utilities_csv, output_json=None, *, row_units=1, row_data=2, encoding='utf-8-sig')

Read stream and utility CSV files into one OpenPinch input mapping.

Parameters:

• streams_csv (str | IO)

• utilities_csv (str | IO)

• output_json (str | None)

• row_units (int)

• row_data (int)

• encoding (str)

OpenPinch.adapters.io.csv.get_results_from_csv(summary_csv, output_json, project_name, *, row_units=2, row_data=4, encoding='utf-8-sig')

Read one summary CSV file into structured target JSON.

Parameters:

• summary_csv (str | IO)

• output_json (str | None)

• project_name (str)

• row_units (int)

• row_data (int)

• encoding (str)

Input normalisation helpers shared by Excel/CSV/JSON ingestion paths.

OpenPinch.adapters.io.records.validate_stream_data(sd)

Normalise stream records and fill missing names/zones with sensible defaults.

Parameters:

sd (DataFrame)

OpenPinch.adapters.io.records.validate_utility_data(ud)

Drop utility rows without a name.

Parameters:

ud (DataFrame)

Export and Reporting

Use the export helpers when you want the solved TargetOutput and Zone hierarchy written back to an Excel workbook for review or archiving.

Excel export utilities for OpenPinch targeting outputs.

OpenPinch.presentation.reporting.workbook.export_target_summary_to_excel_with_units(target_response, master_zone, out_dir='.')

Export solved targets and problem tables to an Excel workbook.

Parameters:

• target_response (TargetOutput) – Structured response returned by the high-level targeting service.

• master_zone (Zone) – Solved zone hierarchy used to export shifted and real problem tables for the master zone and all subzones. May be None when only the summary sheet is required.

• out_dir (str) – Destination directory for the workbook.

Returns:

Absolute or relative path to the workbook that was written.

Return type:

pathlib.Path

Notes

The workbook currently includes a summary sheet plus one or more problem- table sheets. Value-with-unit objects are flattened into adjacent (value) and (unit) columns for easy review in Excel.

Math, Optimisation, and Utility Helpers

These modules provide reusable numerical support for targeting and post- processing tasks.

Shared numerical helpers.

OpenPinch.analysis.numerics.delta_vals(x, descending_vals=True)

Compute difference between successive entries in a column.

Parameters:

• x (ndarray)

• descending_vals (bool)

Return type:

ndarray

OpenPinch.analysis.numerics.delta_with_zero_at_start(x)

Compute successive differences and prepend a zero entry.

Parameters:

x (ndarray)

Return type:

ndarray

OpenPinch.analysis.numerics.g_ineq_penalty(g, *, eta=0.01, rho=10, form=PenaltyForm.SQUARE)

Return a penalty value for an inequality-constraint residual.

Parameters:

• g (float | list | ndarray)

• eta (float)

• rho (float)

• form (PenaltyForm)

Return type:

float64

OpenPinch.analysis.numerics.interp_with_plateaus(h_vals, t_vals, targets, side, tol=1e-06)

Interpolate temperatures while respecting vertical curve segments.

Parameters:

• h_vals (ndarray)

• t_vals (ndarray)

• targets (ndarray)

• side (str)

• tol (float)

Return type:

ndarray

OpenPinch.analysis.numerics.linear_interpolation(xi, x1, x2, y1, y2)

Estimate y at xi using two known points and linear interpolation.

Parameters:

• xi (float)

• x1 (float)

• x2 (float)

• y1 (float)

• y2 (float)

Return type:

float

OpenPinch.analysis.numerics.make_monotonic(h_vals, side, tol=1e-06)

Adjust repeated values to become strictly increasing for interpolation.

Parameters:

• h_vals (ndarray)

• side (str)

• tol (float)

Return type:

ndarray

Method selection and validation for reusable scalar minimisation.

OpenPinch.optimisation.service.run_multistart_minimisation(problem, *, method=OptimisationMethod.DUAL_ANNEALING, options=None)

Run one reusable backend and return finite candidates in stable order.

Parameters:

• problem (OptimisationProblem)

• method (OptimisationMethod | str)

• options (OptimisationOptions | Mapping[str, object] | None)

Return type:

OptimisationResult

Immutable inputs and outputs for reusable scalar optimisation.

class OpenPinch.optimisation.models.OptimisationCandidate(objective, point)

Bases: object

One finite candidate ordered by objective and then coordinates.

Parameters:

• objective (float)

• point (tuple[float, ...])

class OpenPinch.optimisation.models.OptimisationMethod(*values)

Bases: StrEnum

Supported black-box minimisation methods.

class OpenPinch.optimisation.models.OptimisationOptions(n_runs=1, maxiter=300, seed=0, maxfun=1000000, cluster_tol=0.01, max_minima=4, local_method='SLSQP', backend_options=())

Bases: object

Backend-independent execution options plus explicit backend overrides.

Parameters:

• n_runs (int)

• maxiter (int)

• seed (int)

• maxfun (int)

• cluster_tol (float)

• max_minima (int | None)

• local_method (str)

• backend_options (tuple[tuple[str, Any], ...])

classmethod from_mapping(values=None)

Build options from the conventional keyword mapping form.

Parameters:

values (Mapping[str, Any] | None)

Return type:

OptimisationOptions

to_backend_kwargs()

Return a detached mapping suitable for one backend invocation.

Return type:

dict[str, Any]

class OpenPinch.optimisation.models.OptimisationProblem(objective, bounds, initial_points=(), args=(), constraints=())

Bases: object

A bounded scalar minimisation problem.

Parameters:

• objective (Callable[[...], float])

• bounds (tuple[tuple[float, float], ...])

• initial_points (tuple[tuple[float, ...], ...])

• args (tuple[Any, ...])

• constraints (Any)

class OpenPinch.optimisation.models.OptimisationResult(method, candidates)

Bases: object

Deterministically ordered candidates returned by one method.

Parameters:

• method (OptimisationMethod)

• candidates (tuple[OptimisationCandidate, ...])

property best: OptimisationCandidate

Return the lowest-objective candidate.

Generate piecewise-linear approximations for non-linear thermodynamic streams.

OpenPinch.domain._stream.linearisation.align_temperature_heat_profiles(profiles)

Interpolate period profiles onto their union cumulative-duty-fraction grid.

Return type:

tuple[ndarray, …]

OpenPinch.domain._stream.linearisation.build_segmented_stream_from_profile(*, name, profile, heat_scale=1.0, heat_unit='kW', is_hot_stream, minimum_temperature_span=0.01, **stream_kwargs)

Build one parent Stream from an ordered linearised profile.

Parameters:

• name (str)

• heat_scale (float)

• heat_unit (str)

• is_hot_stream (bool)

• minimum_temperature_span (float)

OpenPinch.domain._stream.linearisation.get_piecewise_data_points(curve, is_hot_stream, dt_diff_max=0.1)

Perform piecewise linearisation with the Ramer-Douglas-Peucker algorithm.

Parameters:

• curve (list) – Numpy array of plot points for th curve

• dt_diff_max (float) – Maximum allowed temperature differential tolerance

• is_hot_stream (bool)

Returns:

Numpy array of new curve points

Return type:

array

OpenPinch.domain._stream.linearisation.get_piecewise_linearisation_for_streams(streams, t_h_data, dt_diff_max=0.1)

Generate piecewise-linear T-H profiles for non-linear streams.

Parameters:

• streams (List[Any])

• t_h_data (list)

• dt_diff_max (float)

Return type:

dict[str, list[list[list[float]]]]

OpenPinch.domain._stream.linearisation.normalise_temperature_heat_profile(profile, *, is_hot_stream, minimum_temperature_span=0.01)

Preserve profile order while enforcing the sensible-stream span convention.

Parameters:

• is_hot_stream (bool)

• minimum_temperature_span (float)

Return type:

ndarray

Heat-exchanger performance correlations used by area targeting routines.

OpenPinch.analysis.heat_transfer.CalcAreaUE(Arrangement, U, C_p, T_p1, T_p2, T_u1, T_u2, Passes)

Estimate the exchanger area * U product from duty and temperatures.

OpenPinch.analysis.heat_transfer.Coth(R)

Convenience wrapper for the hyperbolic cotangent function.

OpenPinch.analysis.heat_transfer.CrossflowUnmixedEff1(Ntu, c)

Series approximation for cross-flow effectiveness with unmixed streams.

OpenPinch.analysis.heat_transfer.CrossflowUnmixedEff2(Ntu, c, Rows, Cmin_fluid)

Lookup-derived correlations for cross-flow exchangers with finite rows.

OpenPinch.analysis.heat_transfer.HX_Eff(Arrangement, Ntu, c, Passes=None, Rows=None, Cmin_Phase=None)

Return heat exchanger effectiveness for the specified arrangement/NTU/c ratio.

OpenPinch.analysis.heat_transfer.HX_NTU(Arrangement, eff, c, Passes=None)

Compute NTU for a target effectiveness and exchanger arrangement.

OpenPinch.analysis.heat_transfer.HX_NTU_Numerical(Arrangement, eff, c)

Solve for NTU numerically when closed-form expressions are unavailable.

OpenPinch.analysis.heat_transfer.MultiPassEff(eff, c, Passes)

Convert single-pass effectiveness into equivalent multi-pass effectiveness.

OpenPinch.analysis.heat_transfer.MultiPassNTU(Eff_p, c, Passes)

Convert multi-pass effectiveness back to an equivalent single-pass value.

OpenPinch.analysis.heat_transfer.compute_LMTD_from_dts(delta_T1, delta_T2)

Return the LMTD for a counterflow heat exchanger from end-point deltas.

Parameters:

• delta_T1 (float | list | ndarray)

• delta_T2 (float | list | ndarray)

Return type:

ndarray

OpenPinch.analysis.heat_transfer.compute_LMTD_from_ts(T_hot_in, T_hot_out, T_cold_in, T_cold_out)

Return the LMTD for a counterflow heat exchanger from temperatures.

Parameters:

• T_hot_in (float | list | ndarray)

• T_hot_out (float | list | ndarray)

• T_cold_in (float | list | ndarray)

• T_cold_out (float | list | ndarray)

Return type:

float

OpenPinch.analysis.heat_transfer.eNTU_slope_Numerical(Arrangement, Ntu, c, Passes)

Compute a finite-difference effectiveness slope with respect to NTU.

Utility helpers for equipment costing.

OpenPinch.analysis.economics.compute_capital_recovery_factor(interest_rate, years)

Calculate the capital recovery factor, also called annualisation.

Parameters:

• interest_rate (float)

• years (int)

Return type:

float

OpenPinch.analysis.economics.compute_capital_cost(area, num_units, fixed_cost_factor, variable_cost_factor, n_exp_factor)

Determine capital cost from installed capacity and unit-count assumptions.

Parameters:

• area (float)

• num_units (int)

• fixed_cost_factor (float)

• variable_cost_factor (float)

• n_exp_factor (float)

Return type:

Value

OpenPinch.analysis.economics.compute_annual_capital_cost(capital_cost, discount_rate, service_life)

Determine the annualised capital cost.

Parameters:

• capital_cost (Any)

• discount_rate (float)

• service_life (float)

Return type:

Value

OpenPinch.analysis.economics.compute_annual_energy_cost(power_kw, price_per_mwh, annual_hours)

Determine annual energy cost from power, price, and operating hours.

Parameters:

• power_kw (float)

• price_per_mwh (float)

• annual_hours (float)

Return type:

Value

Convenience wrappers around CoolProp for common water property queries.

OpenPinch.analysis.thermodynamics.water.Tsat_p(P)

Saturation temperature (degC) at pressure P (bar).

OpenPinch.analysis.thermodynamics.water.fromSIunit_T(Ins)

Convert Kelvin to degC.

OpenPinch.analysis.thermodynamics.water.fromSIunit_h(Ins)

Convert J/kg to kJ/kg.

OpenPinch.analysis.thermodynamics.water.fromSIunit_p(Ins)

Convert Pa to bar.

OpenPinch.analysis.thermodynamics.water.fromSIunit_s(Ins)

Identity conversion for entropy; maintained for API symmetry.

OpenPinch.analysis.thermodynamics.water.hL_p(P)

Liquid enthalpy (kJ/kg) at pressure P (bar).

OpenPinch.analysis.thermodynamics.water.hV_p(P)

Vapour enthalpy (kJ/kg) at pressure P (bar).

OpenPinch.analysis.thermodynamics.water.h_pT(P, T)

Specific enthalpy (kJ/kg) at (P, T) where P is bar and T is degC.

OpenPinch.analysis.thermodynamics.water.h_ps(P, s)

Specific enthalpy (kJ/kg) at pressure P (bar) and entropy s (kJ/kg/K).

OpenPinch.analysis.thermodynamics.water.psat_T(T)

Saturation pressure (bar) at temperature T (degC).

OpenPinch.analysis.thermodynamics.water.s_ph(P, H)

Specific entropy (kJ/kg/K) at pressure P (bar) and enthalpy H (kJ/kg).

OpenPinch.analysis.thermodynamics.water.toSIunit_T(Ins)

Convert degC to Kelvin.

OpenPinch.analysis.thermodynamics.water.toSIunit_h(Ins)

Convert kJ/kg to J/kg.

OpenPinch.analysis.thermodynamics.water.toSIunit_p(Ins)

Convert bar to Pa.

OpenPinch.analysis.thermodynamics.water.toSIunit_s(Ins)

Identity conversion for entropy; maintained for API symmetry.

Internal Optimiser Backends

The modules below back OpenPinch.optimisation.service.run_multistart_minimisation(). They are primarily useful when inspecting or extending optimiser implementations.

Concrete scalar optimisation backends.

Candidate ranking, clustering, and polishing for scalar optimisation.

Dual-annealing multi-start backend.

CMA-ES multi-start backend.

Bayesian-optimisation multi-start backend.

RBF-surrogate multi-start backend.

Plotting and Instrumentation

These helpers cover quick standalone plotting, execution-time measurement, and the richer Streamlit dashboard components used by streamlit_app.py.

Install openpinch[notebook] for the standalone Plotly plotting helpers and Excel-oriented utility modules. Install openpinch[dashboard] for the Streamlit dashboard path.

Plotly helper routines for quick temperature-enthalpy visual checks.

OpenPinch.presentation.graphs.simple.graph_simple_cc_plot(Tc, Hc, Th, Hh)

Render a quick Plotly plot of hot/cold composite curves for debugging.

OpenPinch.presentation.graphs.simple.plot_t_h_curve(points, title='Temperature vs. Enthalpy')

Plot Temperature vs. Enthalpy. :param points: tuple with columns ‘Temperature (K)’ and ‘Enthalpy (kJ/mol)’. :param title: Title of the graph. :returns: None

Parameters:

title (str)

Return type:

None

OpenPinch.presentation.graphs.simple.plot_t_h_curve_with_piecewise_and_bounds(points, piecewise_points, epsilon, title='Temperature vs. Enthalpy')

Plot the TH curve, its piecewise linearization, and a shaded ±epsilon band. :param points: Original TH curve points. :param piecewise_points: Simplified piecewise linear curve points. :param epsilon: Epsilon value for shading. :param title: Title of the graph.

Parameters:

• points (array)

• piecewise_points (array)

• epsilon (float)

• title (str)

Return type:

None

Application use-case orchestration.

Streamlit dashboard orchestration for solved OpenPinch zones.

OpenPinch.presentation.dashboard.rendering.render_streamlit_dashboard(zone, *, graph_data=None, page_title=None, value_rounding=2)

Render a basic Streamlit dashboard for zone.

Parameters:

• zone (Zone)

• graph_data (Mapping[str, Mapping[str, object]] | None)

• page_title (str | None)

• value_rounding (int)

Return type:

None