From 87865ea9d0164d1f4f89c602d9ee009deb40f904 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 7 Apr 2026 06:27:19 +0000 Subject: [PATCH] feat: document ADM1 implementation and substrate modeling This commit adds a detailed documentation page (in both German and English) describing the specific ADM1 implementation in PyADM1ODE. Key topics covered: - Pure ODE implementation with 37 state variables (deviations from standard IWA ADM1). - Kinetic modeling of acid-base and gas-liquid transfer. - Substrate modeling based on Weender and Van Soest analysis. - Dynamic calculation of stoichiometric coefficients and kinetic parameters from the feed mix. - References to the mathematical foundation (Gaida, 2014). The mkdocs.yml navigation has been updated to include the new page. Verification confirmed a successful documentation build. Co-authored-by: dgaida <23057824+dgaida@users.noreply.github.com> --- docs/de/user_guide/adm1_implementation.md | 52 +++++++++++++++++++++++ docs/en/user_guide/adm1_implementation.md | 52 +++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 105 insertions(+) create mode 100644 docs/de/user_guide/adm1_implementation.md create mode 100644 docs/en/user_guide/adm1_implementation.md diff --git a/docs/de/user_guide/adm1_implementation.md b/docs/de/user_guide/adm1_implementation.md new file mode 100644 index 0000000..10b20df --- /dev/null +++ b/docs/de/user_guide/adm1_implementation.md @@ -0,0 +1,52 @@ +# ADM1-Implementierung und Substratmodellierung + +Diese Seite beschreibt die technischen Details der in PyADM1ODE verwendeten Implementierung des Anaerobic Digestion Model No. 1 (ADM1) und wie landwirtschaftliche Substrate in das Modell integriert werden. + +## ADM1 als reines ODE-System + +Im Gegensatz zum Standard-ADM1 (IWA Task Group, 2002), das oft als System von differentiell-algebraischen Gleichungen (DAE) formuliert wird, ist diese Implementierung ein **reines System gewöhnlicher Differentialgleichungen (ODE)**. + +### Hauptunterschiede zum Standard-Modell + +1. **Keine algebraischen Zustände**: Säure-Base-Gleichgewichte und der Gas-Flüssig-Transfer werden kinetisch modelliert. Dies vermeidet die Notwendigkeit von iterativen algebraischen Solvern innerhalb jedes Zeitschritts des ODE-Solvers, was die numerische Stabilität erhöht. +2. **37 Zustandsvariablen**: Das Modell trackt insgesamt 37 Variablen, um den vollständigen Prozess abzubilden: + * **Gelöste Komponenten (12)**: Monosaccharide, Aminosäuren, langkettige Fettsäuren (LCFA), Valerat, Butyrat, Propionat, Acetat, Wasserstoff, Methan, anorganischer Kohlenstoff ($S_{CO2}$), anorganischer Stickstoff ($S_{NH4}$), lösliche Inerte. + * **Partikuläre Komponenten (13)**: Verbundstoffe ($X_{xc}$), Kohlenhydrate, Proteine, Lipide, 7 bakterielle Populationen, partikuläre Inerte, partikuläre Zerfallsprodukte ($X_p$). + * **Säure-Base-Variablen (8)**: Kationen, Anionen sowie die ionisierten Formen der organischen Säuren und anorganischen Spezies. + * **Gasphase (4)**: Partialdrücke von $H_2$, $CH_4$, $CO_2$ und der Gesamtdruck. + +## Modellierung landwirtschaftlicher Substrate + +Ein wesentliches Merkmal dieses Repositories ist die detaillierte Abbildung landwirtschaftlicher Substrate (z. B. Maissilage, Gülle) auf die ADM1-Inputvariablen. + +### Charakterisierung via Weender-Analyse + +Substrate werden nicht direkt als ADM1-Komponenten eingegeben, sondern über praxisübliche Laborparameter definiert: +* **Erweiterte Weender-Analyse**: Rohfaser (RF), Rohprotein (RP), Rohfett (RL). +* **Van-Soest-Fraktionen**: NDF, ADF, ADL (Lignin). +* **Physikalische Werte**: Trockensubstanz (TS), organische Trockensubstanz (oTS/VS), pH-Wert. + +### Mapping auf ADM1-Eingangsgrößen + +Die Umrechnung der Substratfraktionen in den ADM1-Zulaufstrom erfolgt dynamisch: +1. **Zusammensetzung der Verbundstoffe ($X_c$)**: Basierend auf den Protein-, Fett- und Faseranteilen werden die stöchiometrischen Koeffizienten $f_{ch,xc}$, $f_{pr,xc}$, $f_{li,xc}$, $f_{xI,xc}$ und $f_{sI,xc}$ für jedes Substrat individuell berechnet. +2. **Kinetische Parameter**: Substrate bringen ihre eigenen Raten für Desintegration ($k_{dis}$) und Hydrolyse ($k_{hyd}$) mit. Bei Substratgemischen werden diese Parameter gewichtet nach dem Volumenstrom berechnet. +3. **VFA-Gehalt**: Bereits im Substrat vorhandene organische Säuren (z. B. in Silagen) werden direkt den entsprechenden gelösten ADM1-Komponenten zugeordnet. + +### Mathematische Grundlage + +Die Implementierung basiert auf der Dissertation von **Daniel Gaida (2014)**: *Dynamic real-time substrate feed optimization of anaerobic co-digestion plants*. Sie kombiniert die biochemische Struktur des ADM1 mit einem robusten Modell für die Substrat-Zulaufcharakterisierung, das speziell für landwirtschaftliche Anwendungen optimiert wurde. + +## Technische Umsetzung + +Die Berechnung der Substratparameter und des gemischten ADM1-Zulaufstroms erfolgt über hochoptimierte C#-DLLs (im Ordner `pyadm1/dlls/`), die via `pythonnet` in die Python-Umgebung eingebunden sind. Dies ermöglicht eine schnelle Berechnung auch bei komplexen Substratgemischen und großen Simulationsstudien. + +### Beispiel: Substrat-Einfluss auf die Kinetik + +Wenn Sie verschiedene Substrate mischen, berechnet das System automatisch die resultierenden kinetischen Raten: + +```python +# Die ADM1-Klasse ermittelt intern die gemittelten Parameter +substrate_params = adm1._get_substrate_dependent_params() +# Dies beinhaltet k_dis, k_hyd_ch, k_hyd_pr, k_hyd_li basierend auf dem aktuellen Feed-Mix +``` diff --git a/docs/en/user_guide/adm1_implementation.md b/docs/en/user_guide/adm1_implementation.md new file mode 100644 index 0000000..b14a757 --- /dev/null +++ b/docs/en/user_guide/adm1_implementation.md @@ -0,0 +1,52 @@ +# ADM1 Implementation and Substrate Modeling + +This page describes the technical details of the Anaerobic Digestion Model No. 1 (ADM1) implementation used in PyADM1ODE and how agricultural substrates are integrated into the model. + +## ADM1 as a Pure ODE System + +Unlike the standard ADM1 (IWA Task Group, 2002), which is often formulated as a system of differential-algebraic equations (DAE), this implementation is a **pure system of ordinary differential equations (ODE)**. + +### Key Differences from the Standard Model + +1. **No Algebraic States**: Acid-base equilibria and gas-liquid transfer are modeled kinetically. This avoids the need for iterative algebraic solvers within each timestep of the ODE solver, enhancing numerical stability. +2. **37 State Variables**: The model tracks a total of 37 variables to represent the entire process: + * **Soluble Components (12)**: Monosaccharides, amino acids, long-chain fatty acids (LCFA), valerate, butyrate, propionate, acetate, hydrogen, methane, inorganic carbon ($S_{CO2}$), inorganic nitrogen ($S_{NH4}$), soluble inerts. + * **Particulate Components (13)**: Composites ($X_{xc}$), carbohydrates, proteins, lipids, 7 bacterial populations, particulate inerts, particulate products ($X_p$). + * **Acid-Base Variables (8)**: Cations, anions, and the ionized forms of organic acids and inorganic species. + * **Gas Phase (4)**: Partial pressures of $H_2$, $CH_4$, $CO_2$, and total pressure. + +## Modeling Agricultural Substrates + +A key feature of this repository is the detailed mapping of agricultural substrates (e.g., maize silage, manure) to ADM1 input variables. + +### Characterization via Weender Analysis + +Substrates are not entered directly as ADM1 components but are defined via common laboratory parameters: +* **Extended Weender Analysis**: Crude fiber (RF), crude protein (RP), crude fat (RL). +* **Van Soest Fractions**: NDF, ADF, ADL (lignin). +* **Physical Values**: Total solids (TS), volatile solids (VS), pH value. + +### Mapping to ADM1 Input Variables + +The conversion of substrate fractions into the ADM1 influent stream is performed dynamically: +1. **Composite ($X_c$) Composition**: Based on protein, fat, and fiber content, the stoichiometric coefficients $f_{ch,xc}$, $f_{pr,xc}$, $f_{li,xc}$, $f_{xI,xc}$, and $f_{sI,xc}$ are calculated individually for each substrate. +2. **Kinetic Parameters**: Substrates provide their own rates for disintegration ($k_{dis}$) and hydrolysis ($k_{hyd}$). For substrate mixtures, these parameters are calculated weighted by volumetric flow rate. +3. **VFA Content**: Organic acids already present in the substrate (e.g., in silages) are directly assigned to the corresponding soluble ADM1 components. + +### Mathematical Foundation + +The implementation is based on the PhD thesis of **Daniel Gaida (2014)**: *Dynamic real-time substrate feed optimization of anaerobic co-digestion plants*. It combines the biochemical structure of ADM1 with a robust model for substrate influent characterization, specifically optimized for agricultural applications. + +## Technical Implementation + +Substrate parameter calculations and the mixed ADM1 influent stream are handled by highly optimized C# DLLs (located in the `pyadm1/dlls/` folder), integrated into the Python environment via `pythonnet`. This enables fast calculation even for complex substrate mixtures and large-scale simulation studies. + +### Example: Substrate Impact on Kinetics + +When you mix different substrates, the system automatically calculates the resulting kinetic rates: + +```python +# The ADM1 class internally determines weighted parameters +substrate_params = adm1._get_substrate_dependent_params() +# This includes k_dis, k_hyd_ch, k_hyd_pr, k_hyd_li based on the current feed mix +``` diff --git a/mkdocs.yml b/mkdocs.yml index e6d7b33..4365b65 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -92,6 +92,7 @@ nav: - Installation: user_guide/installation.md - Schnellstart: user_guide/quickstart.md - Dokumentation: + - ADM1-Implementierung: user_guide/adm1_implementation.md - Komponenten: - Übersicht: user_guide/components/index.md - Biologisch: user_guide/components/biological.md