Add ADM1 Implementation and Substrate Modeling Documentation

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
+```

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
+```

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