README.md

---
license: apache-2.0
tags:
- chemistry
- pyrolysis-thermochemistry
- biomass-energy-feedstocks
- thermodynamics-and-kinetic-modeling
- physics-informed-neural-networks
- monte-carlo-bootstrapped-uncertainty
- autonomous-agent-precision-pyrolysis
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 (Ea) 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 (Ea, in kJ/mol) as a function of biomass feedstock composition and the instantaneous conversion level (α).
* **Network Topology**: `256` (Input) → `42` (Hidden Layer 1) → `42` (Hidden Layer 2) → `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₂, Al₂O₃, etc.).
  * **Pyrolysis Progress State (1 Dimension)**: The instantaneous degree of conversion (α), 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 Ea (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) → `45` → `45` → `45` → `45` → `45` → `3` (Outputs).
* **Input Features (259 Dimensions)**:
  * **Basic Feedstock Characteristics (19 Dimensions)**: Proximate, ultimate, and ash components.
  * **Pyrolysis Process Conditions (4 Dimensions)**: Target temperature (°C), Reaction time (min), Heating rate (K/min), and Reactor type.
  * **Detailed Feedstock Blending/Mixing Features (236 Dimensions)**: Feedstock combinations and ratios.
* **Outputs (3 Dimensions)**:
  * Pyrolysis yields (expressed in weight percentages):
    1. **Char Yield (%)** (used directly as the ultimate residue w_inf 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_inf)**:
   The ultimate char yield predicted by `bpDNN2Yield` sets the lower boundary platform (w_inf = Char Yield / 100) of the mass-loss profile. For any degree of conversion α, the remaining sample weight w(α) is calculated via mass balance:
   
   w(α) = 100 × [1 - α · (1 - w_inf)] %

2. **Kinetic & Temperature Integration**:
   The conversion-dependent apparent activation energy profile Ea(α) 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(α) = ∫ (A/β) · exp(-Ea(α) / RT) dT
   
   Solving this equation gives the temperature trajectory T(α) and pre-exponential factor A.
   
3. **Synthesis**:
   Combining T(α) (from the Ea network + kinetic solver) and w(α) (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₂ | Silica percentage in biomass ash | wt.% of ash |
| **11** | Al₂O₃ | Alumina percentage in biomass ash | wt.% of ash |
| **12** | Fe₂O₃ | 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₂ | Titanium dioxide percentage in biomass ash | wt.% of ash |
| **16** | Na₂O | Sodium oxide percentage in biomass ash | wt.% of ash |
| **17** | K₂O | Potassium oxide percentage in biomass ash | wt.% of ash |
| **18** | P₂O₅ | Phosphorus pentoxide percentage in biomass ash | wt.% of ash |
| **19** | SO₃ | Sulfur trioxide percentage in biomass ash | wt.% of ash |

*Note: For the Ea network, column 20 is the degree of conversion (α), and columns 21–256 contain mixed feedstock attributes. For the Yield network, columns 20–23 contain pyrolysis process conditions, and columns 24–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)
];

% Define Pyrolysis Process Conditions (4 features specific to Yield network)
% 1. Target Temperature (°C), 2. Reaction Time (min), 3. Heating Rate (K/min), 4. Reactor Type
processConditions = [600, 30, 20, 1];

% Construct blending/mixing parameters (zero-padded for single pure biomass)
feedstockMixingFeatures = zeros(1, 236);

%% 3. Predict Pyrolysis Yields
% Prepare input for Yield Network: (259 features x 1 sample)
yieldInput = [basicBiomassFeatures, processConditions, feedstockMixingFeatures]';

% 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), feedstockMixingFeatures];
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
@misc{tang2026pyrobot,
  author = {Tang, Siqi and others},
  title = {PyroBot_FoundationModel: Pre-trained Deep Neural Network Surrogate Models for Biomass Pyrolysis},
  year = {2026},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/TANG-Research-Group/PyroBot_FoundationModel}}
}
```