Feat/document adm1 implementation and substrates v1 8042139006703194449

docs/de/user_guide/adm1_implementation.md

@@ -15,11 +15,29 @@ Im Gegensatz zum Standard-ADM1 (IWA Task Group, 2002), das oft als System von di
     *   **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
+### pH-Wert Berechnung
 
-Ein wesentliches Merkmal dieses Repositories ist die detaillierte Abbildung landwirtschaftlicher Substrate (z. B. Maissilage, Gülle) auf die ADM1-Inputvariablen.
+In der Original-Publikation des ADM1 wird der pH-Wert oft über eine algebraische Ladungsbilanz gelöst, die eine iterative Bestimmung der Wasserstoffionen-Konzentration $[H^+]$ erfordert.
 
-### Charakterisierung via Weender-Analyse
+In dieser Implementierung wird der pH-Wert direkt aus der Ladungsbilanz der **dynamischen Ionen-Zustände** berechnet. Da Kationen ($S_{cat}$), Anionen ($S_{an}$) und die ionisierten Formen der organischen Säuren sowie des anorganischen Kohlenstoffs/Stickstoffs als eigene Zustandsvariablen im ODE-System geführt werden, kann der pH-Wert in jedem Schritt explizit bestimmt werden. Dieser Ansatz erhöht die numerische Stabilität (Robustheit) des Solvers, da keine algebraischen Gleichungen innerhalb des Integrationsschritts gelöst werden müssen.
+
+## Erweiterungen für landwirtschaftliche Substrate
+
+Die Implementierung enthält wichtige Erweiterungen, die speziell für die Vergärung von Energiepflanzen und Gülle optimiert wurden (nach **Koch et al., 2010**):
+
+### Einfluss des TS-Gehalts auf die Hydrolyse
+
+In landwirtschaftlichen Biogasanlagen mit hohen Feststoffgehalten (TS) ist die Hydrolyse oft der ratenlimitierende Schritt. Das Modell sieht hierfür eine Korrekturfunktion vor:
+$$ hydro\_factor = \frac{1}{1 + (\frac{TS}{K_{hyd}})^{n_{hyd}}} $$
+
+!!! info "Hinweis zur aktuellen Implementierung"
+    Obwohl die mathematische Struktur zur TS-abhängigen Hydrolysekorrektur im Code implementiert ist (siehe `adm_equations.py`), ist sie in der aktuellen Version standardmäßig **deaktiviert**. Der `hydro_factor` wird beim Aufruf der Prozessraten fest auf `1.0` gesetzt, sodass die Korrekturgleichung im Standardbetrieb übersprungen wird.
+
+### Modellierung von Zerfallsprodukten ($X_p$)
+
+Analog zum ASM1 (Activated Sludge Model) wurde ein separater Zustand für partikuläre Zerfallsprodukte ($X_p$) eingeführt. Dies ermöglicht eine präzisere Schließung der Stickstoffbilanz und beschreibt die Akkumulation von inerten organischen Stoffen aus abgestorbener Biomasse genauer.
+
+## 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).
@@ -31,22 +49,13 @@ Substrate werden nicht direkt als ADM1-Komponenten eingegeben, sondern über pra
 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.
+Die Implementierung basiert auf den Arbeiten von:
+*   **Gaida, D. (2014)**: *Dynamic real-time substrate feed optimization of anaerobic co-digestion plants*. PhD thesis, Leiden University.
+*   **Koch, K. et al. (2010)**: *Biogas from grass silage – Measurements and modeling with ADM1*. Bioresource Technology.
 
 ## 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

@@ -15,11 +15,29 @@ Unlike the standard ADM1 (IWA Task Group, 2002), which is often formulated as a
     *   **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
+### pH Calculation
 
-A key feature of this repository is the detailed mapping of agricultural substrates (e.g., maize silage, manure) to ADM1 input variables.
+In the original ADM1 publication, the pH value is often solved via an algebraic charge balance, requiring an iterative determination of the hydrogen ion concentration $[H^+]$.
 
-### Characterization via Weender Analysis
+In this implementation, the pH value is calculated directly from the charge balance of the **dynamic ion states**. Since cations ($S_{cat}$), anions ($S_{an}$), and the ionized forms of organic acids and inorganic carbon/nitrogen are maintained as separate state variables within the ODE system, the pH value can be explicitly determined at each step. This approach increases the numerical stability (robustness) of the solver, as no algebraic equations need to be solved within the integration step.
+
+## Enhancements for Agricultural Substrates
+
+The implementation includes important enhancements specifically optimized for the digestion of energy crops and manure (based on **Koch et al., 2010**):
+
+### Influence of Solids (TS) Content on Hydrolysis
+
+In agricultural biogas plants with high total solids (TS) content, hydrolysis is often the rate-limiting step. The model provides a correction function for this:
+$$ hydro\_factor = \frac{1}{1 + (\frac{TS}{K_{hyd}})^{n_{hyd}}} $$
+
+!!! info "Note on Current Implementation"
+    While the mathematical structure for TS-dependent hydrolysis correction is implemented in the code (see `adm_equations.py`), it is currently **disabled** by default. The `hydro_factor` is set to `1.0` when calculating process rates, meaning the correction equation is bypassed in standard operation.
+
+### Modeling Decay Products ($X_p$)
+
+Similar to the ASM1 (Activated Sludge Model), a separate state for particulate decay products ($X_p$) was introduced. This allows for a more precise closing of the nitrogen balance and describes the accumulation of inert organic matter from decayed biomass more accurately.
+
+## 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).
@@ -31,22 +49,13 @@ Substrates are not entered directly as ADM1 components but are defined via commo
 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.
+The implementation is based on the research of:
+*   **Gaida, D. (2014)**: *Dynamic real-time substrate feed optimization of anaerobic co-digestion plants*. PhD thesis, Leiden University.
+*   **Koch, K. et al. (2010)**: *Biogas from grass silage – Measurements and modeling with ADM1*. Bioresource Technology.
 
 ## 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
-```