Metadata-Version: 2.5
Name: thermocraft
Version: 0.2.0
Summary: ThermoCraft — Process Thermal Simulation Platform for food, pharma, and chemical industries.
Project-URL: Homepage, https://github.com/thermocraft/thermocraft
Project-URL: Documentation, https://thermocraft.readthedocs.io
Project-URL: Repository, https://github.com/thermocraft/thermocraft
Author: Chen Zhang
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: fluid-bed-drying,food-engineering,freeze-drying,freezing,heat-transfer,lyophilization,pharmaceutical,simulation,sterilization,thermal-processing,uht
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: coolprop>=6.6
Requires-Dist: jinja2>=3.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: optuna>=3.5
Requires-Dist: pandas>=2.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0
Requires-Dist: scipy>=1.12
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: cython>=3.0; extra == 'all'
Requires-Dist: furo>=2024.0; extra == 'all'
Requires-Dist: mypy>=1.8; extra == 'all'
Requires-Dist: pytest-cov>=5.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.6; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff==0.16.0; extra == 'all'
Requires-Dist: sphinx>=7.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: cython>=3.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: fem
Requires-Dist: fenics-dolfinx>=0.8; extra == 'fem'
Requires-Dist: gmsh>=4.11; extra == 'fem'
Requires-Dist: meshio>=5.0; extra == 'fem'
Requires-Dist: mpi4py; extra == 'fem'
Requires-Dist: numpy-stl>=3.0; extra == 'fem'
Provides-Extra: fenicsx
Requires-Dist: fenics-dolfinx>=0.8; extra == 'fenicsx'
Requires-Dist: mpi4py; extra == 'fenicsx'
Description-Content-Type: text/markdown

# 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

```bash
# 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

```bash
# 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/`](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
