Update specifications of the foundation models trained in MATLAB

README.md

@@ -1,3 +1,250 @@
 ---
 license: apache-2.0
+tags:
+- chemistry
+- pyrolysis
+- biomass
+- neural-network
+- surrogate-model
+- kinetic-modeling
+- thermogravimetry
+- matlab
+- machine-learning
+pretty_name: PyroBot Pyrolysis Foundation Models
 ---
+
+# PyroBot Pyrolysis Foundation Models (`bpDNN2Ea` & `bpDNN2Yield`)
+
+This repository contains the core neural network surrogate models of **PyroBot**, an autonomous, agentic framework designed for interpreting, optimizing, and simulating biomass pyrolysis. These foundation surrogates are trained to predict the apparent activation energy ($E_a$) and three-phase product yields (Char, Liquid, Gas) directly from multi-dimensional feedstock properties and process state variables.
+
+By utilizing these pre-trained Backpropagation Deep Neural Networks (BP-DNNs) as a fast and accurate surrogate "brain," PyroBot bypasses computationally expensive ab initio or multi-phase CFD simulations, enabling real-time closed-loop autonomous kinetic analysis and thermogravimetric (TG) curve reconstruction.
+
+---
+
+## 📂 Model Repository Structure
+
+The repository contains two trained neural networks saved in MATLAB format, along with their respective preprocessing parameters:
+
+```bash
+.
+├── README.md                  # This model card document
+├── .gitattributes             # Git LFS configurations tracking .mat files
+├── bpDNN2Ea/
+│   └── Results_trained.mat    # Apparent Activation Energy (Ea) network & scaling metadata
+└── bpDNN2Yield/
+    └── Results_trained.mat    # Pyrolysis Product Yield network & scaling metadata
+```
+
+Each `Results_trained.mat` file contains three core structures:
+1. `net`: The trained deep neural network (weights, biases, layer transfer functions).
+2. `PS`: Preprocessing struct (`mapminmax` scaling parameters for inputs).
+3. `TS`: Postprocessing struct (`mapminmax` scaling parameters for outputs).
+
+---
+
+## 🧠 Model Descriptions & Architectures
+
+### 1. `bpDNN2Ea` (Activation Energy Prediction)
+* **Goal**: Predicts the Apparent Activation Energy ($E_a$, in $\text{kJ/mol}$) as a function of biomass feedstock composition and the instantaneous conversion level ($\alpha$).
+* **Network Topology**: `256` (Input) $\rightarrow$ `42` (Hidden Layer 1) $\rightarrow$ `42` (Hidden Layer 2) $\rightarrow$ `1` (Output).
+* **Input Features (256 Dimensions)**:
+  * **Basic Feedstock Characteristics (19 Dimensions)**: Includes proximate analysis (volatile matter, fixed carbon, ash), ultimate analysis (C, H, O, N, S), and detailed ash compositions ($SiO_2$, $Al_2O_3$, etc.).
+  * **Pyrolysis Progress State (1 Dimension)**: The instantaneous degree of conversion ($\alpha$), ranging from `0.01` to `0.999`.
+  * **Feedstock Blending/Mixing Features (236 Dimensions)**: Captures complex multi-component feedstock mixtures, geographic source classifications, and blending ratio parameters.
+* **Output**: Apparent Activation Energy $E_a$ ($\text{kJ/mol}$).
+
+### 2. `bpDNN2Yield` (Product Yields Prediction)
+* **Goal**: Predicts the ultimate three-phase pyrolysis yields (Char, Liquid, Gas) under high-temperature conditions.
+* **Network Topology**: `259` (Input) $\rightarrow$ `45` $\rightarrow$ `45` $\rightarrow$ `45` $\rightarrow$ `45` $\rightarrow$ `45` $\rightarrow$ `3` (Outputs).
+* **Input Features (259 Dimensions)**:
+  * **Basic Feedstock Characteristics (19 Dimensions)**
+  * **Detailed Feedstock Blending/Mixing Features (240 Dimensions)**
+* **Outputs (3 Dimensions)**:
+  * Pyrolysis yields (expressed in weight percentages):
+    1. **Char Yield (%)** (used directly as the ultimate residue $w_{\infty}$ for TG scaling).
+    2. **Liquid/Bio-oil Yield (%)**
+    3. **Gas Yield (%)**
+
+---
+
+## 🧪 Downstream Application: TG Curve Synthesis & Kinetic Coupling
+
+In the PyroBot cognitive ecosystem, these two models are combined to reconstruct simulated Thermogravimetric (TG) curves with perfect physical and kinetic consistency:
+
+1. **Mass Loss Curve Platform ($w_{\infty}$)**:
+   The ultimate char yield predicted by `bpDNN2Yield` sets the lower boundary platform ($w_{\infty} = \text{Char Yield}/100$) of the mass-loss profile. For any degree of conversion $\alpha$, the remaining sample weight $w(\alpha)$ is calculated via mass balance:
+   $$w(\alpha) = 100 \times \bigl(1 - \alpha \cdot (1 - w_{\infty})\bigr)\%$$
+
+2. **Kinetic & Temperature Integration**:
+   The conversion-dependent apparent activation energy profile $E_a(\alpha)$ predicted by `bpDNN2Ea` is mapped to an adaptive kinetic solver. The system compares a library of 130 mechanisms (such as diffusion, nucleation, geometrical, and reaction-order models in series/parallel/hybrid modes) and uses a **Genetic Algorithm (GA)** coupled with non-linear optimization (`fmincon`) to solve the Kissinger-Arrhenius equations:
+   $$G(\alpha) = \int_{T_{0}}^{T} \frac{A}{\beta} \exp\left(-\frac{E_a(\alpha)}{R T}\right) dT$$
+   Solving this equation gives the temperature trajectory $T(\alpha)$ and pre-exponential factor $A$.
+   
+3. **Synthesis**:
+   Combining $T(\alpha)$ (from the $E_a$ network + kinetic solver) and $w(\alpha)$ (from the Yield network) yields the completed, publication-quality TG curve ($w$ vs. $T$) without requiring numerical interpolation.
+
+---
+
+## 📊 Comprehensive Feedstock Input Feature Map (19 Core Attributes)
+
+For reference, the 19 basic feedstock input characteristics representing the biomass sample are organized below:
+
+| Col Index | Feature Name | Description / Physical Meaning | Unit |
+| :--- | :--- | :--- | :--- |
+| **1** | Location / Source | Geographic region identifier | Class ID |
+| **2** | Volatile Matter | Proximate analysis of volatile substances | wt.% (dry-basis) |
+| **3** | Fixed Carbon | Proximate analysis of fixed carbon | wt.% (dry-basis) |
+| **4** | Ash Content | Proximate analysis of inorganic residue | wt.% (dry-basis) |
+| **5** | Carbon (C) | Ultimate analysis of elemental Carbon | wt.% (dry-basis) |
+| **6** | Hydrogen (H) | Ultimate analysis of elemental Hydrogen | wt.% (dry-basis) |
+| **7** | Oxygen (O) | Ultimate analysis of elemental Oxygen | wt.% (dry-basis) |
+| **8** | Nitrogen (N) | Ultimate analysis of elemental Nitrogen | wt.% (dry-basis) |
+| **9** | Sulfur (S) | Ultimate analysis of elemental Sulfur | wt.% (dry-basis) |
+| **10** | $SiO_2$ | Silica percentage in biomass ash | wt.% of ash |
+| **11** | $Al_2O_3$ | Alumina percentage in biomass ash | wt.% of ash |
+| **12** | $Fe_2O_3$ | Iron oxide percentage in biomass ash | wt.% of ash |
+| **13** | $CaO$ | Calcium oxide percentage in biomass ash | wt.% of ash |
+| **14** | $MgO$ | Magnesium oxide percentage in biomass ash | wt.% of ash |
+| **15** | $TiO_2$ | Titanium dioxide percentage in biomass ash | wt.% of ash |
+| **16** | $Na_2O$ | Sodium oxide percentage in biomass ash | wt.% of ash |
+| **17** | $K_2O$ | Potassium oxide percentage in biomass ash | wt.% of ash |
+| **18** | $P_2O_5$ | Phosphorus pentoxide percentage in biomass ash | wt.% of ash |
+| **19** | $SO_3$ | Sulfur trioxide percentage in biomass ash | wt.% of ash |
+
+*Note: For the $E_a$ network, column 20 is the degree of conversion ($\alpha$), and columns 21–256 contain mixed feedstock attributes. For the Yield network, columns 20–259 contain mixed feedstock attributes.*
+
+---
+
+## 💻 MATLAB Inference Implementation Code
+
+To run predictions using the trained `.mat` model cards locally, you can use the following MATLAB script:
+
+```matlab
+%% PyroBot Foundation Models: Inference Example
+% Clear workspace
+clear; clc;
+
+% Configure paths to find the bpDNN2Ea and bpDNN2Yield directories
+addpath('bpDNN2Ea');
+addpath('bpDNN2Yield');
+
+%% 1. Load the Pre-trained Surrogates
+fprintf('=== Loading PyroBot Foundation Models ===\n');
+
+EaModelStruct = load('bpDNN2Ea/Results_trained.mat');
+netEa = EaModelStruct.net;
+PS_Ea = EaModelStruct.PS;
+TS_Ea = EaModelStruct.TS;
+
+YieldModelStruct = load('bpDNN2Yield/Results_trained.mat');
+netYield = YieldModelStruct.net;
+PS_Y = YieldModelStruct.PS;
+TS_Y = YieldModelStruct.TS;
+
+fprintf('Models loaded successfully!\n\n');
+
+%% 2. Define Sample Biomass (e.g. Corn Stover Base Features)
+% Define the 19 core ultimate, proximate, and ash compositions
+basicBiomassFeatures = [ ...
+    1.00, ...  % Location ID
+    72.50, ... % Volatile Matter (%)
+    18.20, ... % Fixed Carbon (%)
+    9.30, ...  % Ash (%)
+    43.10, ... % C (%)
+    5.60, ...  % H (%)
+    41.50, ... % O (%)
+    0.45, ...  % N (%)
+    0.05, ...  % S (%)
+    35.20, ... % SiO2 (% of ash)
+    2.10, ...  % Al2O3 (% of ash)
+    1.80, ...  % Fe2O3 (% of ash)
+    12.40, ... % CaO (% of ash)
+    4.10, ...  % MgO (% of ash)
+    0.15, ...  % TiO2 (% of ash)
+    0.80, ...  % Na2O (% of ash)
+    18.50, ... % K2O (% of ash)
+    3.20, ...  % P2O5 (% of ash)
+    1.50 ...   % SO3 (% of ash)
+];
+
+% Construct blending/mixing parameters (zero-padded for single pure biomass)
+feedstockMixingEa = zeros(1, 236);
+feedstockMixingYield = zeros(1, 240);
+
+%% 3. Predict Pyrolysis Yields
+% Prepare input for Yield Network: (259 features x 1 sample)
+yieldInput = [basicBiomassFeatures, feedstockMixingYield]';
+
+% Switch global normalization handlers for nnpredict
+global PS TS
+PS = PS_Y;
+TS = TS_Y;
+
+% Run forward propagation through the Yield surrogate
+yieldPred = nnpredict(netYield, yieldInput);
+
+charYield = yieldPred(1);
+liquidYield = yieldPred(2);
+gasYield = yieldPred(3);
+
+fprintf('=== Predicted Pyrolysis Yields ===\n');
+fprintf('Char (Solid) Yield:  %.2f %%\n', charYield);
+fprintf('Liquid/Oil Yield:    %.2f %%\n', liquidYield);
+fprintf('Gas Yield:           %.2f %%\n', gasYield);
+fprintf('Sum Check:           %.2f %%\n\n', sum(yieldPred));
+
+%% 4. Predict Apparent Activation Energy (Ea) vs. Pyrolysis Progress (Alpha)
+% Define conversion levels (alpha from 0.02 to 0.98)
+alphaList = 0.02:0.02:0.98;
+numAlpha = length(alphaList);
+eaInputs = zeros(numAlpha, 256);
+
+for i = 1:numAlpha
+    % Ea input structure: [basicFeatures(1-19), alpha(20), feedstockMixing(21-256)]
+    eaInputs(i, :) = [basicBiomassFeatures, alphaList(i), feedstockMixingEa];
+end
+
+% Transpose to (256 features x numAlpha samples) for network evaluation
+sampleInpEa = eaInputs';
+
+% Switch global normalization handlers to Ea Network scaling
+PS = PS_Ea;
+TS = TS_Ea;
+
+% Run forward propagation through the Ea surrogate
+EaPred_kJ = nnpredict(netEa, sampleInpEa);
+
+fprintf('=== Predicted Apparent Activation Energies ===\n');
+fprintf('Alpha = 0.10: Ea = %.2f kJ/mol\n', EaPred_kJ(alphaList == 0.10));
+fprintf('Alpha = 0.50: Ea = %.2f kJ/mol\n', EaPred_kJ(alphaList == 0.50));
+fprintf('Alpha = 0.90: Ea = %.2f kJ/mol\n', EaPred_kJ(alphaList == 0.90));
+fprintf('Average Ea:  %.2f kJ/mol\n', mean(EaPred_kJ));
+
+%% 5. Reconstruct Monotonic Mass Loss (TG) Curve
+w_inf = charYield / 100; % Final residue mass fraction
+w_t = (1 - alphaList .* (1 - w_inf)) * 100; % Remaining mass percentage (%)
+
+fprintf('\nTG Curve Endpoint Platform (w_inf): %.2f %%\n', w_inf * 100);
+```
+
+To run this model, make sure you include the deep neural network framework helper utility files: `nnpreprocess.m`, `nnpostprocess.m`, and `nnpredict.m` which compute standard forward propagation, multi-layer activation maps (`logsig`, `tansig`), and apply scale scaling/restoration according to the matrices in `Results_trained.mat`.
+
+---
+
+## 📜 License & Citation
+
+These models are distributed under the **Apache License 2.0**. 
+
+If you use **PyroBot** or these foundation pyrolysis surrogate networks in your scientific publications or research, please cite our corresponding work:
+
+```bibtex
+@article{pyrobot2026,
+  title={PyroBot: An Autonomous Agent Framework powered by Foundation Surrogate Deep Neural Networks for Intelligent Biomass Pyrolysis Simulation},
+  author={Tang, Siqi and et al.},
+  journal={Journal of Analytical and Applied Pyrolysis / Fuel / Environmental Science},
+  year={2026},
+  volume={xx},
+  pages={xx},
+  doi={xx}
+}
+```