Input Formats and Validation

OpenPinch supports multiple input styles over the same analysis engine. This guide explains which one to use and how validation fits into the workflow.

Supported Source Shapes

The high-level wrappers accept these source shapes today:

JSON file: Best for reproducible version-controlled studies and programmatic generation.
Packaged sample-case name: A *.json name such as basic_pinch.json or crude_preheat_train.json. This resolves the packaged asset only when no local file with the same name exists.
Workbook file: Best when starting from an established spreadsheet-oriented workflow. The loader accepts .xlsx, .xls, .xlsb, and .xlsm.
CSV directory: A directory containing streams.csv and utilities.csv.
CSV tuple: A (streams_csv, utilities_csv) tuple when the two files are already known separately.
Schema-first Python input: Best for application integration and typed construction in code.
Plain mapping: Useful when another part of your application already assembled the payload in memory.

Core Data Contract

The main programmatic contract is:

At minimum, a solve requires process streams. Utilities and zone hierarchies may be explicit or synthesized depending on the workflow.

Validation Stages

OpenPinch validation happens in layers:

schema validation
semantic validation and warnings
input preparation into a runtime Zone tree

This means input data can be structurally valid but still produce warnings about assumptions or unusual thermal conditions.

Recommended Validation Workflow

Validation is a Python-side workflow. For wrapper-based usage:

from OpenPinch import PinchProblem

problem = PinchProblem("basic_pinch.json")
input_data = problem.validate()

For schema-first usage:

from OpenPinch.lib.schemas.io import TargetInput

input_data = TargetInput.model_validate(payload)

Configuration Inputs

Package configuration belongs on canonical option keys and the runtime zone.config fields built from those options.

Practical implications:

use the documented TargetInput / Configuration field names
use zone_tree when you need explicit hierarchy control
use the high-level wrappers when you want validation context and source normalization handled for you

Preparation Boundary

After validation, OpenPinch prepares a runtime Zone tree. That stage assigns streams to zones, applies dt_cont_multiplier values from the zone hierarchy, synthesizes utility placement context, and leaves the result ready for direct, indirect, HPR, or cogeneration targeting.

If you need that boundary directly, use OpenPinch.services.data_preprocessing_service().

When To Use Which Input Style

Use JSON when:

you want stable, explicit, reviewable inputs

Use workbook input when:

the source of truth is still spreadsheet-driven

Use schema-first inputs when:

you are integrating OpenPinch into another Python system

Use CSV bundles when:

streams and utilities originate from separate tabular data exports

Use a packaged sample-case name when:

you want a maintained known-good example without shipping example files in your own repository

Next Steps

For the user-facing service boundary, see Service Layer.
For the main schemas and config model, see Schemas and Config.