ThermoCraft

Process Thermal Simulation Platform — Python-native, parameterized, optimizable, and extensible simulation toolkit for coupled heat + mass transfer + reaction kinetics in food, pharmaceutical, and chemical process industries. Includes built-in uncertainty quantification (Morris / Sobol / Monte Carlo / PCE), regulatory compliance reporting (FDA 21 CFR 113, EU 853, GB 8950), and production scheduling.

Features

Core physics (suite-agnostic)

• 1D/2D transient heat conduction (explicit / implicit / Crank-Nicolson / enthalpy) + optional FEniCSx 2D/3D FEM backend
• Reaction kinetics: Bigelow first-order, Weibull, advanced kinetic & quality models (Arrhenius)
• Mass transfer, convective mass transfer, drying (GAB sorption), evaporation, thermo-mass coupling, multiphase domains, particle generation, headspace modelling
• Consistent unit handling (thermocraft.core.units) and material property models

Application suites — Food

• Sterilization (C1): Ball formula & numerical F₀, quality degradation, retort profile, process deviation analysis, continuous equipment (hydrostatic sterilizer, rotary retort, scraped-surface HX, ohmic heating), microwave heating (Lambert's law)
• Freezing (C2): Plank (1913) & numerical freezing time, enthalpy / apparent-heat-capacity phase change
• UHT (C5): tubular / plate heat-exchanger design (LMTD / ε-NTU), residence time distribution, F₀ / Pu
• Shelf-life: Baranyi-Roberts growth + Ratkowsky temperature dependence, ASLT (Q₁₀); spoilage / pathogen database
• Scheduling: greedy LPT list scheduler + Optuna search (capacity, cleaning, steam-feasibility)

Analysis & UQ

• Morris screening (μ* / σ) and Sobol global sensitivity (Saltelli S1/ST + bootstrap CI + convergence)
• Monte Carlo UQ (LHS sampling, parallel evaluation, P(F₀ < target), CI)
• Polynomial Chaos Expansion (PCE) with orthonormal Hermite / Legendre bases
• Analytic / full sterilization surrogate models for fast UQ

Application suites — Pharma (Phase 2)

• Lyophilization (C3): end-to-end freeze-drying (freezing / primary / secondary) with a moving-boundary (Stefan) solver, Knudsen + molecular vapour transport, four in-solver safety constraints (collapse / meltback / condenser overload / choked flow), cycle-time optimisation, Pikal / Velardi literature validation
• Lyophilization — Tier 1 commercial physics: pressure-dependent vial heat transfer Kv(P), QbD design-space scan (lyo design-space), dried-layer resistance Rp(X), pressure-rise test with MTM inversion (lyo prt), and parameter estimation (lyo calibrate)
• Lyophilization — Tier 2 batch & chamber system: batch / vial-position model with edge-vial effect (lyo simulate --batch, weighted P50/P95/P99 envelope), chamber-pressure closed loop with condenser mass balance (lyo simulate --chamber-closed-loop), and cGMP-style batch record (lyo report, MD/PDF + electronic batch-record fields)
• Lyophilization — Tier 3 freezing structure, calibration & secondary drying: freeze-recipe model (controlled nucleation / anneal hold / frozen-fraction trajectory), nucleation→ice-crystal→pore→Rp structure linkage, mannitol JMAK crystallization raising the effective collapse temperature, Bayesian calibration (lyo calibrate --bayesian, Laplace posterior + 95 % credible intervals), robust design space (lyo design-space --robust, Monte-Carlo parameter uncertainty with a 0.95 feasibility boundary), and spatially-resolved secondary drying (1-D diffusion-desorption PDE, water-activity GAB/BET/Oswin endpoint)
• Lyophilization — Tier 4 PAT & intelligent control: synthesized PAT sensors (lyo simulate --pat: Pirani/CM ratio, wireless probe), multi-criterion endpoint detection (lyo endpoint, ratio/temperature/PRT/fusion < 10 % error), model-based adaptive control (lyo control: feedforward + PI shelf/pressure control with anti-collapse override, ~4× faster than the open-loop baseline), per-batch energy & cost (lyo energy + optimizer min_energy), and lyo-specific sensitivity analysis (lyo sensitivity: Morris/Sobol over kv/rp/P/T_shelf/nucleation_T)
• Fluid-bed drying (C4): two-phase (emulsion + bubble) drying model with Wen & Yu / Mori & Wen / Gunn / Sit & Grace correlations, U/Umf reporting, falling-rate kinetics (Page / Henderson-Pabis / linear), drying-time optimisation

Application suites — Thermal Systems

• Heat pumps & district networks: vapour-compression design point (CoolProp), AHRI 540 compressor fits, fin-and-tube heat-exchanger sizing (Wang / Shah / Gungor-Winterton), multi-standard seasonal performance (GB IPLV / EU SCOP + energy label / US SEER-HSPF), cross-option LCOH (heat pump vs boiler vs district), ground-source borefield sizing (Kavanaugh + cylindrical-source G-factor, ASHRAE / GB 50366), transcritical CO₂ cycles (gas cooler + IHX), defrost model + COP maps, equipment catalog with COP-vs-capacity interpolation, Hardy-Cross / Newton-Raphson district-network hydraulics + Optuna pipe sizing, and transient network heat transport with weather compensation and storage tanks
• Furnaces & waste-heat recovery: stoichiometric combustion + adiabatic flame temperature (NIST Shomate), closed-form heat balance, multi-layer refractory walls (ISO 6946, optional FEM), flue-gas recovery (air preheater / waste-heat boiler / heat pipe) with acid-dew-point protection, hydrogen / ammonia fuel switching with zonal uniformity, in-furnace gas radiation, O₂-trim combustion control, transient batch thermal cycles, Optuna efficiency optimisation
• Building HVAC: CTF-based peak loads, ASHRAE solar geometry, dual annual-energy engines (fast bin method + full-year hourly 8760 h), carbon accounting + TOU / demand-cost tariffs, 3-objective Pareto optimisation (energy × carbon × cost), UQ sensitivity screening (Morris / Sobol), future-climate SSP scenarios (2050/2080), ASHRAE 62.1 ventilation + CO₂ DCV, Fanger PMV/PPD thermal comfort (ASHRAE 55), VAV / DOAS system energy models, three-standard compliance (GB 50189 / ASHRAE 90.1 / EU ERP), engineering report PDF, thermal bridges (ISO 10211, optional FEniCSx FEM), envelope scan & optimisation

Compliance & reporting

• FDA 21 CFR 113, EU 853 (F₀ ≥ 3, EN/FR/DE), GB 8950 (中文) reports → Jinja2 + reportlab PDF
• Batch compliance validation from CSV (FDA / EU / GB criteria)

Data

• 1,265 food property entries (8 categories; USDA SR Legacy + ASHRAE Ch.19 curated expansion, each with provenance source = usda_<FDC_ID> / ashrae_2022), 118 microbial kinetics entries, 48 quality kinetics entries, 99 growth-kinetics entries (CSV-backed, cross-validated against USDA PMP boundaries; microbes carry T_range_C and D-value uncertainty_pct; derived freeze-point/latent-heat correlations documented in workspace/calibration_database/tools/)
• Thermal / built-environment data (source-keyed CSVs, literature-calibrated by benchmarks/validation_thermal_data.py against ISO / AHRI / JANAF / ASHRAE anchors): 43 thermal materials (49 registered — Ch.33 insulations, masonry, metals, woods, soils, stones, ice), 22 surface radiation properties (emissivity / solar absorptivity, Ch.4), 27 equipment catalog entries across 10 categories (chillers, heat pumps, VRF, boilers, furnaces, AHU, pumps, cooling towers), 9 occupancy schedules, engineering defaults (heat-pump / furnace / thermal-bridge Psi / ground / ventilation / combustion / carbon pricing); Ch.1 psychrometrics cross-validated against the ASHRAE saturation tables

Quick Start

# From PyPI (after the v0.2.0 release) or from source:
pip install thermocraft            # or: pip install -e ".[dev]"
thermocraft --version              # smoke check: prints v0.2.0

# Sterilization simulation + plot
thermocraft sterilize --config examples/canned_tuna_sterilization.yaml --plot

# Freezing simulation
thermocraft freeze  --config examples/frozen_peas_blast_freezer.yaml --plot

# UHT simulation
thermocraft uht     --config examples/uht_milk_137C.yaml --plot

# Uncertainty quantification (Monte Carlo)
thermocraft uq run --config examples/canned_tuna_sterilization.yaml --n-samples 2000

# Regulatory compliance report (FDA / EU / GB)
thermocraft compliance report --config examples/canned_tuna_sterilization.yaml \
    --regulations fda_113,eu_853,gb_8950
thermocraft compliance-batch batch_plan.csv --regulations fda_113,eu_853,gb_8950

# Production scheduling demo
thermocraft schedule --config examples/process_system/scheduling_demo.yaml

# Lyophilization (freeze-drying) simulation + safety report
 thermocraft lyo simulate --config examples/lyo_sucrose_5pct.yaml --plot
 thermocraft lyo safety-check --config examples/lyo_sucrose_5pct.yaml
 thermocraft lyo optimize --config examples/lyo_sucrose_5pct.yaml --n-trials 50
 thermocraft lyo design-space --config examples/lyo_sucrose_5pct.yaml --no-plot
 thermocraft lyo prt --config examples/lyo_sucrose_5pct.yaml --no-plot
 thermocraft lyo calibrate --config examples/lyo_sucrose_5pct.yaml --params "h_shelf,rp"
# Tier 2 — batch, closed-loop chamber, batch record
 thermocraft lyo simulate --config examples/lyo_sucrose_5pct.yaml --batch --vials-per-shelf 1000 --n-shelves 10
 thermocraft lyo simulate --config examples/lyo_sucrose_5pct.yaml --chamber-closed-loop
 thermocraft lyo report --config examples/lyo_sucrose_5pct.yaml --batch --format pdf --batch-id B01
# Tier 3 — Bayesian calibration, robust design space
 thermocraft lyo calibrate --config examples/lyo_sucrose_5pct.yaml --params "h_shelf,rp" --bayesian --n-samples 500
 thermocraft lyo design-space --config examples/lyo_sucrose_5pct.yaml --robust --n-mc 100 --no-plot
# Tier 4 — PAT sensors, endpoint, adaptive control, energy, sensitivity
 thermocraft lyo simulate --config examples/lyo_sucrose_5pct.yaml --pat
 thermocraft lyo endpoint --config examples/lyo_sucrose_5pct.yaml --method fusion
 thermocraft lyo control --config examples/lyo_sucrose_5pct.yaml --T-int-setpoint -36
 thermocraft lyo energy --config examples/lyo_sucrose_5pct.yaml
 thermocraft lyo sensitivity --config examples/lyo_sucrose_5pct.yaml --method morris

# Fluid-bed drying simulation + optimisation
 thermocraft fbd simulate --config examples/fbd_paracetamol.yaml --plot
 thermocraft fbd optimize --config examples/fbd_paracetamol.yaml --n-trials 50

# Thermal Systems — heat pumps, networks, furnaces, building HVAC
 thermocraft hp design --config examples/thermal/hp_r32_office.yaml --with-hex
 thermocraft hp annual --config examples/thermal/hp_r32_office.yaml --carbon
 thermocraft hp ground --config examples/thermal/hp_ground_source.yaml
 thermocraft hp lcoh --config examples/thermal/hp_vs_boiler_vs_network.yaml
 thermocraft network solve --config examples/thermal/district_heating.yaml
 thermocraft furnace design --config examples/thermal/tunnel_kiln_ceramic.yaml --fuel hydrogen
 thermocraft furnace balance --config examples/thermal/tunnel_kiln_ceramic.yaml --transient
 thermocraft furnace recovery --config examples/thermal/tunnel_kiln_ceramic.yaml
 thermocraft hvac load --config examples/thermal/office_beijing.yaml
 thermocraft hvac energy --config examples/thermal/office_beijing.yaml --method hourly --carbon --cost
 thermocraft hvac energy --config examples/thermal/office_beijing.yaml --sensitivity sobol
 thermocraft hvac optimize --config examples/thermal/office_beijing.yaml --objective pareto --n-trials 60
 thermocraft hvac compliance --config examples/thermal/office_beijing.yaml \
     --standard gb50189-2015,ashrae90.1-2022,eu-erp-en14825 --report pdf

CLI Commands

thermocraft sterilize   Food sterilization simulation / optimization
thermocraft freeze      Freezing simulation / optimization
thermocraft uht         UHT heat-exchanger simulation
thermocraft validate    Run validation benchmarks
thermocraft db          Food / kinetics database queries
thermocraft shelf-life  Shelf-life prediction
thermocraft deviation   Process deviation analysis (FDA 21 CFR 113)
thermocraft continuous  Continuous equipment (hydrostatic / rotary / SSHE / ohmic)
thermocraft schedule    Batch scheduling
thermocraft sensitivity Morris / Sobol sensitivity analysis
thermocraft uq          Uncertainty quantification (MC / PCE)
thermocraft compliance  Compliance report generation (fda / eu / gb)
thermocraft compliance-batch  Batch compliance validation
thermocraft lyo          Lyophilization suite (simulate / optimize / validate / safety-check)
thermocraft fbd          Fluid-bed drying suite (simulate / optimize / validate)
thermocraft hp           Heat-pump suite (design / annual / seasonal / ground / lcoh / optimize)
thermocraft network      District heating/cooling network (solve / optimize)
thermocraft furnace      Furnace suite (design / balance / recovery / optimize)
thermocraft hvac         Building HVAC suite (load / energy / scan / optimize / thermal-bridge / compliance / design)
thermocraft --version   Show version

Architecture

thermocraft/
├── core/        # Suite-agnostic physics engines (heat transfer, kinetics, units, PDE solvers, solver dispatcher)
├── suites/
│   ├── food/    # Sterilization, Freezing, UHT, Shelf-life, Scheduling
│   ├── pharma/  # Lyophilization, Granulation
│   └── thermal/ # Heat pumps & district networks, Furnaces & recovery, Building HVAC
├── analysis/    # Sensitivity (Morris/Sobol), UQ (MC/PCE), surrogate models
├── compliance/  # FDA 21 CFR 113 / EU 853 / GB 8950 report generation, batch validator
├── io/          # Export (CSV/JSON), matplotlib plotting, retort profiles
├── config/      # Pydantic schemas + YAML defaults
├── data/        # Food property & kinetics databases
└── cli/         # Typer command-line interface

Layering is strictly inward: cli → suites/analysis/compliance → core. New solvers register through solver_dispatcher; new reports through ReportFactory — no changes to existing modules required.

Running Tests & Benchmarks

# Fast unit-test set (default; ~5-6 min, 1800+ tests).  Full-precision
# integration cases (Bayesian / robust design space / closed-loop control /
# Optuna Pareto / calibration fits) are marked `slow` and run in a dedicated
# CI job: `pytest -m slow`.
python -m pytest tests -q -m "not slow"

# Full-precision slow set (dedicated CI job)
python -m pytest tests -q -m slow

# Validation benchmarks (physical-simulation / process-system / advanced-
# analysis / thermal-systems / multi-source, auto-collected)
python -m pytest benchmarks -q

# Analytical-solution benchmarks (script-based, run explicitly)
python benchmarks/validation_ball_1923.py
python benchmarks/validation_plank_1913.py
python benchmarks/validation_literature.py

# Lint & type check
python -m ruff check src
python -m ruff format --check src
python -m mypy src

Benchmarks named validation_*.py are not auto-collected by pytest; run them explicitly as above (also wired into CI).

Documentation

Hosted docs: https://thermocraft.readthedocs.io (auto-built from main and versioned by git tags).

Full documentation (RST / Sphinx) lives in docs/source/: theory (sterilization, freezing, UHT, heat pumps, furnaces, building HVAC), suite overviews (food / pharma / thermal systems), advanced guides (sensitivity analysis, uncertainty quantification, compliance, thermal design-space optimisation, HVAC compliance) and tutorials (food & pharma + thermal systems). See docs/source/index.rst.

Requirements

• Python ≥ 3.11
• NumPy ≥ 1.26, SciPy ≥ 1.12, pandas ≥ 2.1, matplotlib ≥ 3.8
• CoolProp ≥ 6.6 (thermophysical properties)
• Pydantic ≥ 2.5, PyYAML ≥ 6.0
• Typer ≥ 0.12, Click ≥ 8.1
• Optuna ≥ 3.5 (optimization)
• Optional: FEniCSx / dolfinx ≥ 0.8 + mpi4py (2D/3D FEM backend; requires WSL2 on Windows)

License

Apache-2.0