Quickstart

Pipeline (recommended)

The simplest way to run a full evaluation is via run_evaluation, which chains all seven pipeline layers and returns a serialisable HtcieReport:

from htcie.core.pipeline import run_evaluation
from htcie.core.registry import CorrelationRegistry
from htcie.core.state import (
    EngineeringState, FluidProperties, Geometry,
    BoundaryConditions, FlowState,
)

state = EngineeringState(
    fluid=FluidProperties(
        density=998.2,
        viscosity=1.002e-3,
        thermal_conductivity=0.598,
        heat_capacity=4182,
    ),
    geometry=Geometry(
        geometry_type="circular_tube",
        characteristic_length=0.025,
        hydraulic_diameter=0.025,
    ),
    boundary=BoundaryConditions(boundary_type="constant_wall_temperature"),
    flow=FlowState(velocity=0.4),
)

registry = CorrelationRegistry()
registry.load_from_dir("data/correlations")

report = run_evaluation(state, registry)
if report:
    print(report.explanation.to_text())   # human-readable recommendation
    print(report.to_dict())               # full JSON-serialisable audit trail

Python API (step-by-step)

For finer control, call each engine directly:

from htcie.core.applicability import ApplicabilityEngine
from htcie.core.evaluator import EvaluationEngine
from htcie.core.ranking import RankingEngine

applicable = ApplicabilityEngine().evaluate(state, registry.all())
evaluations = [EvaluationEngine().evaluate(state, m) for m in applicable.applicable]
ranked = RankingEngine().rank(state, applicable.applicable)

print(f"Best method: {ranked[0].key} (score: {ranked[0].score:.3f})")
for key, reason in [(m.key, r) for m, r in applicable.excluded]:
    print(f"  Excluded {key}: {reason}")

CLI

# Run evaluation from a JSON file, print JSON result
htcie evaluate state.json

# Save as Markdown report
htcie evaluate state.json --output report.md --markdown

# Browse available correlations
htcie methods list
htcie methods list --family convection_internal
htcie methods show internal.gnielinski

REST API

Start the server:

uvicorn htcie.api.main:app --reload

# Or with a custom data directory:
HTCIE_DATA_DIR=/path/to/data uvicorn htcie.api.main:app

Available endpoints:

# Run evaluation
POST /evaluate       body: {"state": {...}}

# Browse correlations
GET  /methods
GET  /methods?family=convection_internal
GET  /methods/families
GET  /methods/internal.gnielinski

# Health check
GET  /health

Web GUI

htcie gui

Opens the NiceGUI interface at http://localhost:8080. Requires the nicegui extra (uv add nicegui).

Report output

HtcieReport.to_dict() returns a JSON-serialisable dict containing:

• applicable — list of correlation keys that passed applicability checks

• excluded — list of {key, reason} dicts for filtered-out correlations

• evaluations — list of {key, value, metadata} Nusselt-number results

• ranking — list of {key, score, breakdown} with per-factor scores

• spread — inter-method spread statistics (mean, stdev, relative_spread)

• confidence — "high", "medium", or "low"

• explanation — structured recommendation with text rendering

evaluations entries also include h, h_low, h_high, uncertainty_pct, and uncertainty_note from the uncertainty engine.

Save as JSON, Markdown, or self-contained HTML:

from htcie.reports.serializers import (
    dump_json_report,
    dump_markdown_report,
    dump_html_report,
)

dump_json_report(report, "result.json")
dump_markdown_report(report, "result.md")
dump_html_report(report, "result.html")  # self-contained, no external deps