Core API
========

The core API is the supported front door to OpenPinch. It is intentionally
small: one high-level service function, two convenience wrapper classes, and a
small number of lower-level orchestration helpers for callers that need to
operate on prepared zone trees directly.

Recommended Usage
-----------------

For new code, prefer one of these two patterns:

1. Build a :class:`~OpenPinch.lib.schemas.io.TargetInput` input object and call
   :func:`~OpenPinch.main.pinch_analysis_service`.
2. Load a problem file into
   :class:`~OpenPinch.classes.pinch_problem.PinchProblem`, call
   :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.target`, and inspect or
   export the cached results.
3. Use :class:`~OpenPinch.classes.pinch_workspace.PinchWorkspace` when the
   study needs named baseline and variant cases rather than one case at a
   time.

The lower-level helpers documented on this page are still useful when you want
to separate validation, preparation, targeting, and result extraction into
distinct steps.

Service-Layer Example
---------------------

.. code-block:: python

   from OpenPinch import pinch_analysis_service
   from OpenPinch.lib.schemas.io import StreamSchema, TargetInput

   input_data = TargetInput(
       streams=[
           StreamSchema(
               zone="Process",
               name="Hot Feed",
               t_supply=180.0,
               t_target=80.0,
               heat_flow=2500.0,
               dt_cont=10.0,
           )
       ],
       utilities=[],
   )

   result = pinch_analysis_service(input_data, project_name="Example")

Top-Level Package Re-Exports
----------------------------

The :mod:`OpenPinch` package re-exports the small subset of classes and helpers
that are intended to be imported most often. This makes it practical to work
from ``from OpenPinch import ...`` in notebooks and scripts without traversing
the full package layout.

In particular, the package root exposes:

- :class:`~OpenPinch.classes.pinch_problem.PinchProblem`
- :class:`~OpenPinch.classes.pinch_workspace.PinchWorkspace`
- :func:`~OpenPinch.main.pinch_analysis_service`
- :func:`~OpenPinch.utils.multiscale_targeting.get_targets_for_zone_and_sub_zones`
- :func:`~OpenPinch.utils.multiscale_targeting.extract_results`
- :func:`~OpenPinch.utils.stream_linearisation.get_piecewise_linearisation_for_streams`

Package Entrypoints
-------------------

.. automodule:: OpenPinch
   :no-members:

.. autofunction:: OpenPinch.main.pinch_analysis_service

.. autoclass:: OpenPinch.classes.pinch_problem.PinchProblem
   :members:

.. autoclass:: OpenPinch.classes.pinch_workspace.PinchWorkspace
   :members:

Core Service Functions
----------------------

:mod:`OpenPinch.main` is the thin orchestration layer above the analysis
modules.

- :func:`~OpenPinch.main.pinch_analysis_service` validates the incoming input data,
  prepares the zone hierarchy, runs the appropriate direct and indirect
  targeting steps, and returns a structured response.
- :func:`~OpenPinch.utils.multiscale_targeting.get_targets_for_zone_and_sub_zones` accepts an already prepared
  :class:`~OpenPinch.classes.zone.Zone` tree and dispatches it to the correct
  zone-level targeting routine.
- :func:`~OpenPinch.utils.multiscale_targeting.extract_results` converts the solved in-memory zone
  hierarchy into the dictionary structure consumed by
  :class:`~OpenPinch.lib.schemas.io.TargetOutput`.

.. automodule:: OpenPinch.main
   :no-members:

PinchProblem Convenience Wrapper
--------------------------------

:class:`~OpenPinch.classes.pinch_problem.PinchProblem` adds file loading,
cached execution state, tabular summaries, graph generation, Excel export, and
Streamlit dashboard integration on top of the core service layer.

Those rendered graph, Excel, and dashboard surfaces require the
``openpinch[notebook]`` or ``openpinch[dashboard]`` extra.

Use it when you want:

- a single object that owns the problem definition and solved result
- support for JSON, workbook, and CSV-bundle inputs
- simple summary, graph, export, and dashboard hooks without manually wiring the lower-level
  functions

The main user-facing methods are:

- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.target`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.validate`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.summary_frame`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.plot.composite_curve`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.plot.grand_composite_curve`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.compare_to`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.export_excel`
- :meth:`~OpenPinch.classes.pinch_problem.PinchProblem.show_dashboard`

The wrapper is intentionally light. Once targeting has run, the same solved
:class:`~OpenPinch.classes.zone.Zone` hierarchy and
:class:`~OpenPinch.lib.schemas.io.TargetOutput` objects remain available for direct
inspection.

The ``problem.target.*`` accessor is the explicit advanced post-processing
entrypoint family. Each named workflow returns the affected
:class:`~OpenPinch.lib.schemas.targets.BaseTargetModel` and refreshes cached
:class:`~OpenPinch.lib.schemas.io.TargetOutput` results on the same
:class:`~OpenPinch.classes.pinch_problem.PinchProblem` instance. Heat pump and
refrigeration targets also surface HPR summary fields such as ``hpr_cycle``,
``hpr_utility_total``, ``hpr_work``, ``hpr_external_utility``, and
``StreamCollection`` objects on ``hpr_hot_streams`` and ``hpr_cold_streams``.
For stateful input data, the same named entry points also accept
``state_id=...`` and the refreshed summaries, exports, and graph metadata carry
that selected state context forward.