@@ -22,13 +25,13 @@ Willkommen bei PyADM1ODE - Einem Python-Framework zur Modellierung, Simulation u
[:octicons-arrow-right-24: Installations-Anleitung](user_guide/installation.md)
-- :material-book-open-variant:{ .lg .middle } __Komponenten-Leitfaden__
+- :material-book-open-variant:{ .lg .middle } __Handbuch__
---
- Erfahren Sie mehr über Fermenter, BHKWs, Pumpen und mehr
+ Erfahren Sie mehr über das Framework, Komponenten und Substrate
- [:octicons-arrow-right-24: Komponentendokumentation](user_guide/components/index.md)
+ [:octicons-arrow-right-24: Handbuch](user_guide/adm1_implementation.md)
- :material-code-braces:{ .lg .middle } __Beispiele__
@@ -49,71 +52,6 @@ PyADM1ODE ist ein umfassendes Python-Framework für die Modellierung landwirtsch
- **Praxisnähe**: Validiert mit Daten von in Betrieb befindlichen Biogasanlagen.
- **Python-Ökosystem**: Integriert mit NumPy, SciPy, Pandas und Visualisierungsbibliotheken.
-### Hauptmerkmale
-
-✨ **Umfassende Komponentenbibliothek**
-
-- Biologisch: Ein-/mehrstufige Fermenter, Hydrolysetanks, Separatoren
-- Energie: BHKW-Einheiten, Heizsysteme, Gasspeicher, Fackeln
-- Mechanisch: Pumpen, Rührwerke mit realistischem Stromverbrauch
-- Fütterung: Substratlagerung, automatisierte Dosiersysteme
-
-🔧 **Flexible Anlagenkonfiguration**
-
-- Erstellen Sie komplexe Anlagen programmatisch oder über Vorlagen
-- Automatische Komponentenverbindung und Validierung
-- Speichern/Laden von Konfigurationen als JSON
-
-📊 **Fortgeschrittene Simulation**
-
-- Parallele Ausführung für Parameterstudien und Monte-Carlo-Analysen
-- Adaptive ODE-Solver, optimiert für steife Biogassysteme
-- Zeitreihen-Datenverarbeitung und Ergebnisanalyse
-
-🎓 **Bildung & Professionell**
-
-- Geeignet für die Lehre im Bereich Biogasanlagendesign
-- Forschungswerkzeug zur Prozessoptimierung
-- Engineering-Anwendungen für die Anlagenplanung
-
-## Systemarchitektur
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ PyADM1ODE Framework │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ Biologische │ │ Energie- │ │ Mechanische │ │
-│ │ Komponenten │ │ Komponenten │ │ Komponenten │ │
-│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
-│ │ • Fermenter │ │ • BHKW │ │ • Pumpen │ │
-│ │ • Hydrolyse │ │ • Heizung │ │ • Rührwerke │ │
-│ │ • Separatoren│ │ • Speicher │ │ │ │
-│ │ │ │ • Fackeln │ │ │ │
-│ └──────────────┘ └──────────────┘ └──────────────┘ │
-│ │
-│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ Fütterung │ │ Sensoren │ │ Konfigurator │ │
-│ │ Komponenten │ │ (geplant) │ │ │ │
-│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
-│ │ • Lagerung │ │ • pH │ │ • Builder │ │
-│ │ • Dosierer │ │ • VFA │ │ • Vorlagen │ │
-│ │ │ │ • Gas │ │ • Validator │ │
-│ └──────────────┘ └──────────────┘ └──────────────┘ │
-│ │
-├─────────────────────────────────────────────────────────────────┤
-│ Kern-ADM1-Engine │
-│ • 37 Zustandsvariablen • pH-Dynamik • Gas-Flüssig-Transfer │
-│ • Temperaturabhängige Kinetik • Inhibitionsmodellierung │
-├─────────────────────────────────────────────────────────────────┤
-│ Substratmanagement │
-│ • 10 vorkonfigurierte landwirtschaftliche Substrate │
-│ • Automatische ADM1-Input-Strom-Generierung │
-│ • Zeitlich variierende Fütterungspläne │
-└─────────────────────────────────────────────────────────────────┘
-```
-
## Kurzes Beispiel
Erstellen und simulieren Sie eine komplette Biogasanlage in nur wenigen Zeilen:
@@ -155,21 +93,14 @@ print(f"Methan: {final['Q_ch4']:.1f} m³/d")
print(f"pH: {final['pH']:.2f}")
```
-**Ausgabe:**
-```
-Biogas: 1245.3 m³/d
-Methan: 748.2 m³/d
-pH: 7.28
-```
-
-## Typische Anwendungen
-
-### 1. Anlagendesign und Optimierung
+---
-### 2. Substratoptimierung
+## Community und Support
-### 3. Energiebilanzanalyse
+- **GitHub Repository**: [dgaida/PyADM1ODE](https://github.com/dgaida/PyADM1ODE)
+- **Issue Tracker**: [Bugs melden oder Features anfragen](https://github.com/dgaida/PyADM1ODE/issues)
+- **Discussions**: [Fragen stellen und Ideen austauschen](https://github.com/dgaida/PyADM1ODE/discussions)
-### 4. Zweistufiges Prozessdesign
+## Lizenz
-(Details siehe englische Version oder Unterseiten)
+PyADM1ODE ist Open-Source-Software unter der MIT-Lizenz.
diff --git a/docs/de/user_guide/advanced_features.md b/docs/de/user_guide/advanced_features.md
new file mode 100644
index 0000000..ecb4537
--- /dev/null
+++ b/docs/de/user_guide/advanced_features.md
@@ -0,0 +1,38 @@
+# Fortgeschrittene Funktionen
+
+PyADM1ODE bietet fortgeschrittene Funktionen für umfangreiche Studien und das Konfigurationsmanagement.
+
+## Parallele Simulation
+
+Führen Sie mehrere Szenarien gleichzeitig aus, um Parameterstudien oder Monte-Carlo-Simulationen zu beschleunigen.
+
+```python
+from pyadm1.simulation import ParallelSimulator
+
+# Parameterstudie
+parallel = ParallelSimulator(adm1, n_workers=4)
+scenarios = [
+ {"k_dis": 0.5, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
+ {"k_dis": 0.6, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
+ {"k_dis": 0.7, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]}
+]
+
+results = parallel.run_scenarios(scenarios, duration=30, initial_state=state)
+```
+
+Weitere Details finden Sie im [Beispiel für parallele Simulation](../examples/parallel_simulation.md).
+
+## Konfigurationsmanagement
+
+Speichern und verwenden Sie Anlagendesigns mithilfe der JSON-Serialisierung wieder.
+
+```python
+# Konfiguration speichern
+plant.to_json("zweistufige_anlage.json")
+
+# Später laden
+from pyadm1.configurator import BiogasPlant
+plant = BiogasPlant.from_json("zweistufige_anlage.json", feedstock)
+plant.initialize()
+results = plant.simulate(duration=30, dt=1/24)
+```
diff --git a/docs/de/user_guide/applications.md b/docs/de/user_guide/applications.md
new file mode 100644
index 0000000..c9279ab
--- /dev/null
+++ b/docs/de/user_guide/applications.md
@@ -0,0 +1,72 @@
+# Typische Anwendungen
+
+PyADM1ODE kann für eine Vielzahl von Aufgaben eingesetzt werden, vom Anlagendesign bis hin zur Echtzeitoptimierung.
+
+## 1. Anlagendesign und Optimierung
+
+Testen Sie verschiedene Anlagenkonfigurationen, um das optimale Setup für Ihre Bedürfnisse zu finden.
+
+```python
+from pyadm1.configurator import BiogasPlant, PlantConfigurator
+from pyadm1.substrates import Feedstock
+
+# Test verschiedener Fermentergrößen
+for V_liq in [1500, 2000, 2500]:
+ plant = BiogasPlant(f"Anlage_{V_liq}")
+ feedstock = Feedstock()
+ configurator = PlantConfigurator(plant, feedstock)
+ configurator.add_digester("dig1", V_liq=V_liq, Q_substrates=[15, 10, 0, 0, 0, 0, 0, 0, 0, 0])
+
+ plant.initialize()
+ results = plant.simulate(duration=30, dt=1/24)
+
+ final = results[-1]["components"]["dig1"]
+ print(f"V={V_liq} m³ → CH4={final['Q_ch4']:.1f} m³/d")
+```
+
+## 2. Substratoptimierung
+
+Vergleichen Sie verschiedene Substratbelegungen, um die Methanproduktion zu maximieren oder die Kosten zu minimieren.
+
+```python
+# Vergleich verschiedener Substratbelegungen
+mixes = {
+ 'high_energy': [20, 5, 0, 0, 0, 0, 0, 0, 0, 0],
+ 'balanced': [15, 10, 0, 0, 0, 0, 0, 0, 0, 0],
+ 'waste_based': [0, 15, 0, 0, 0, 0, 0, 0, 10, 5]
+}
+
+for name, Q in mixes.items():
+ # ... konfigurieren und simulieren ...
+ print(f"{name}: {final['Q_ch4']:.1f} m³/d Methan")
+```
+
+## 3. Energiebilanzanalyse
+
+Analysieren Sie die Nettoenergieerzeugung und den Eigenverbrauch Ihrer Anlage.
+
+```python
+# Berechnung der Nettoenergieerzeugung
+chp_power = results[-1]["components"]["chp_main"]["P_el"]
+mixer_power = results[-1]["components"]["mixer_1"]["P_consumed"]
+pump_power = results[-1]["components"]["pump_1"]["P_consumed"]
+
+eigenverbrauch = mixer_power + pump_power
+netto_leistung = chp_power - eigenverbrauch
+
+print(f"Nettoleistung: {netto_leistung:.1f} kW")
+print(f"Eigenverbrauchsquote: {eigenverbrauch/chp_power:.1%}")
+```
+
+## 4. Zweistufiges Prozessdesign
+
+Modellieren Sie fortgeschrittene Anlagendesigns wie die temperaturgestufte anaerobe Vergärung (TPAD).
+
+```python
+# Temperaturgestufte anaerobe Vergärung (TPAD)
+configurator.add_digester("hydrolyse", V_liq=500, T_ad=318.15) # 45°C
+configurator.add_digester("hauptfermenter", V_liq=2000, T_ad=308.15) # 35°C
+configurator.connect("hydrolyse", "hauptfermenter", "liquid")
+
+# Verbesserte Hydrolyse in Stufe 1, stabile Methanogenese in Stufe 2
+```
diff --git a/docs/de/user_guide/substrates.md b/docs/de/user_guide/substrates.md
new file mode 100644
index 0000000..40a412a
--- /dev/null
+++ b/docs/de/user_guide/substrates.md
@@ -0,0 +1,28 @@
+# Vorkonfigurierte Substrate
+
+PyADM1ODE enthält 10 landwirtschaftliche Substrate mit in der Literatur validierten Parametern.
+
+## Verfügbare Substrate
+
+| Substrat | Typ | Typische Verwendung | Biogaspotenzial |
+|----------|-----|--------------------|-----------------|
+| **Maissilage** | Energiepflanze | Hauptsubstrat | Hoch (600-700 L/kg VS) |
+| **Gülle** | Tierische Abfälle | Co-Substrat | Mittel (200-400 L/kg VS) |
+| **Grünroggen** | Energiepflanze | Frühernte | Mittel-Hoch |
+| **Grassilage** | Grünland | Erneuerbar | Mittel (400-550 L/kg VS) |
+| **Weizen** | Getreide | Energiepflanze | Hoch |
+| **GPS** | Ganzpflanzensilage | Ganze Pflanze | Hoch |
+| **CCM** | Corn-Cob-Mix | Energiepflanze | Hoch |
+| **Futterkalk** | Zusatzstoff | pH-Puffer | N/V |
+| **Rindergülle** | Tierische Abfälle | Co-Substrat | Mittel (200-350 L/kg VS) |
+| **Zwiebeln** | Abfall | Gemüseabfälle | Mittel-Hoch |
+
+## Substratcharakterisierung
+
+Alle Substrate sind charakterisiert durch:
+- Trockensubstanz (TS) und organische Trockensubstanz (oTS)
+- ADM1-Fraktionierung (Kohlenhydrate, Proteine, Lipide)
+- Biochemisches Methanpotenzial (BMP)
+- pH-Wert und Alkalinität
+
+Weitere Details zur Abbildung auf ADM1 finden Sie auf der Seite [ADM1-Implementierung](adm1_implementation.md).
diff --git a/docs/en/index.md b/docs/en/index.md
index d1d7e40..54f06c3 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -3,6 +3,9 @@
Welcome to PyADM1ODE - A Python framework for modeling, simulating, and optimizing agricultural biogas plants based on the Anaerobic Digestion Model No. 1 (ADM1).
## 🎯 Quick Links
+
+
+
@@ -22,13 +25,13 @@ Welcome to PyADM1ODE - A Python framework for modeling, simulating, and optimizi
[:octicons-arrow-right-24: Installation Guide](user_guide/installation.md)
-- :material-book-open-variant:{ .lg .middle } __Components Guide__
+- :material-book-open-variant:{ .lg .middle } __User Guide__
---
- Learn about digesters, CHP units, pumps, and more
+ Learn about the framework, components, and substrates
- [:octicons-arrow-right-24: Component Documentation](user_guide/components/index.md)
+ [:octicons-arrow-right-24: Handbuch](user_guide/adm1_implementation.md)
- :material-code-braces:{ .lg .middle } __Examples__
@@ -44,75 +47,10 @@ Welcome to PyADM1ODE - A Python framework for modeling, simulating, and optimizi
PyADM1ODE is a comprehensive Python framework for agricultural biogas plant modeling that combines:
-- **Scientific accuracy**: Based on IWA's ADM1 model, the international standard for anaerobic digestion
-- **Modular architecture**: Mix and match components (digesters, CHP units, pumps, mixers) to build any plant configuration
-- **Real-world applicability**: Validated with data from operating biogas plants
-- **Python ecosystem**: Integrates with NumPy, SciPy, Pandas, and visualization libraries
-
-### Key Features
-
-✨ **Comprehensive Component Library**
-
-- Biological: Single/multi-stage digesters, hydrolysis tanks, separators
-- Energy: CHP units, heating systems, gas storage, flares
-- Mechanical: Pumps, mixers with realistic power consumption
-- Feeding: Substrate storage, automated dosing systems
-
-🔧 **Flexible Plant Configuration**
-
-- Build complex plants programmatically or via templates
-- Automatic component connection and validation
-- Save/load configurations as JSON
-
-📊 **Advanced Simulation**
-
-- Parallel execution for parameter sweeps and Monte Carlo analysis
-- Adaptive ODE solvers optimized for stiff biogas systems
-- Time-series data handling and result analysis
-
-🎓 **Educational & Professional**
-
-- Suitable for teaching biogas plant design
-- Research tool for process optimization
-- Engineering applications for plant planning
-
-## System Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ PyADM1ODE Framework │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ Biological │ │ Energy │ │ Mechanical │ │
-│ │ Components │ │ Components │ │ Components │ │
-│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
-│ │ • Digesters │ │ • CHP Units │ │ • Pumps │ │
-│ │ • Hydrolysis │ │ • Heating │ │ • Mixers │ │
-│ │ • Separators │ │ • Storage │ │ │ │
-│ │ │ │ • Flares │ │ │ │
-│ └──────────────┘ └──────────────┘ └──────────────┘ │
-│ │
-│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ Feeding │ │ Sensors │ │ Configurator │ │
-│ │ Components │ │ (planned) │ │ │ │
-│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
-│ │ • Storage │ │ • pH │ │ • Builder │ │
-│ │ • Feeders │ │ • VFA │ │ • Templates │ │
-│ │ │ │ • Gas │ │ • Validator │ │
-│ └──────────────┘ └──────────────┘ └──────────────┘ │
-│ │
-├─────────────────────────────────────────────────────────────────┤
-│ Core ADM1 Engine │
-│ • 37 state variables • pH dynamics • Gas-liquid transfer │
-│ • Temperature-dependent kinetics • Inhibition modeling │
-├─────────────────────────────────────────────────────────────────┤
-│ Substrate Management │
-│ • 10 pre-configured agricultural substrates │
-│ • Automatic ADM1 input stream generation │
-│ • Time-varying feed schedules │
-└─────────────────────────────────────────────────────────────────┘
-```
+- **Scientific accuracy**: Based on IWA's ADM1 model, the international standard for anaerobic digestion.
+- **Modular architecture**: Mix and match components (digesters, CHP units, pumps, mixers) to build any plant configuration.
+- **Real-world applicability**: Validated with data from operating biogas plants.
+- **Python ecosystem**: Integrates with NumPy, SciPy, Pandas, and visualization libraries.
## Quick Example
@@ -155,308 +93,14 @@ print(f"Methane: {final['Q_ch4']:.1f} m³/d")
print(f"pH: {final['pH']:.2f}")
```
-**Output:**
-```
-Biogas: 1245.3 m³/d
-Methane: 748.2 m³/d
-pH: 7.28
-```
-
-## Typical Applications
-
-### 1. Plant Design and Optimization
-
-```python
-# Test different digester sizes
-for V_liq in [1500, 2000, 2500]:
- plant = BiogasPlant(f"Plant_{V_liq}")
- configurator = PlantConfigurator(plant, feedstock)
- configurator.add_digester("dig1", V_liq=V_liq, Q_substrates=[15, 10, 0, 0, 0, 0, 0, 0, 0, 0])
-
- plant.initialize()
- results = plant.simulate(duration=30, dt=1/24)
-
- final = results[-1]["components"]["dig1"]
- print(f"V={V_liq} m³ → CH4={final['Q_ch4']:.1f} m³/d")
-```
-
-### 2. Substrate Optimization
-
-```python
-# Compare different substrate mixes
-mixes = {
- 'high_energy': [20, 5, 0, 0, 0, 0, 0, 0, 0, 0],
- 'balanced': [15, 10, 0, 0, 0, 0, 0, 0, 0, 0],
- 'waste_based': [0, 15, 0, 0, 0, 0, 0, 0, 10, 5]
-}
-
-for name, Q in mixes.items():
- # ... configure and simulate ...
- print(f"{name}: {final['Q_ch4']:.1f} m³/d methane")
-```
-
-### 3. Energy Balance Analysis
-
-```python
-# Calculate net energy production
-chp_power = results[-1]["components"]["chp_main"]["P_el"]
-mixer_power = results[-1]["components"]["mixer_1"]["P_consumed"]
-pump_power = results[-1]["components"]["pump_1"]["P_consumed"]
-
-parasitic_load = mixer_power + pump_power
-net_power = chp_power - parasitic_load
-
-print(f"Net power: {net_power:.1f} kW")
-print(f"Parasitic ratio: {parasitic_load/chp_power:.1%}")
-```
-
-### 4. Two-Stage Process Design
-
-```python
-# Temperature-phased anaerobic digestion (TPAD)
-configurator.add_digester("hydrolysis", V_liq=500, T_ad=318.15) # 45°C
-configurator.add_digester("main", V_liq=2000, T_ad=308.15) # 35°C
-configurator.connect("hydrolysis", "main", "liquid")
-
-# Enhanced hydrolysis in stage 1, stable methanogenesis in stage 2
-```
-
-## Component Categories
-
-### Biological Components
-
-Model the core biological processes:
-
-- **[Digester](user_guide/components/biological.md#digester)**: Main fermenter with ADM1 model
- - Single or multi-stage configurations
- - Temperature control (psychrophilic, mesophilic, thermophilic)
- - Automatic gas storage creation
- - Calibration parameter support (using [PyADM1ODE_calibration](https://github.com/dgaida/PyADM1ODE_calibration))
-
-- **[Hydrolysis](user_guide/components/biological.md#hydrolysis)**: Pre-treatment tank (planned)
-- **[Separator](user_guide/components/biological.md#separator)**: Digestate processing (planned)
-
-### Energy Components
-
-Complete energy integration:
-
-- **[CHP](user_guide/components/energy.md#chp-combined-heat-and-power)**: Combined heat and power generation
- - Variable efficiency curves
- - Load-following operation
- - Automatic flare creation
-
-- **[Heating](user_guide/components/energy.md#heating)**: Temperature control systems
- - CHP waste heat utilization
- - Auxiliary heating calculation
-
-- **[Gas Storage](user_guide/components/energy.md#gas-storage)**: Biogas buffering
- - Low-pressure (membrane, dome) and high-pressure options
- - Automatic pressure management
- - Safety venting
-
-- **[Flare](user_guide/components/energy.md#flare)**: Safety gas combustion
- - 98% methane destruction efficiency
- - Automatic activation on overpressure
-
-### Mechanical Components
-
-Material handling and process control:
-
-- **[Pump](user_guide/components/mechanical.md#pump)**: Substrate and digestate transfer
- - Progressive cavity, centrifugal, piston types
- - Power consumption modeling
- - Variable frequency drive support
-
-- **[Mixer](user_guide/components/mechanical.md#mixer)**: Digester agitation
- - Propeller, paddle, jet mixer types
- - Intermittent operation for energy savings
- - Reynolds number and mixing time calculation
-
-### Feeding Components
-
-Substrate management:
-
-- **[Substrate Storage](user_guide/components/feeding.md#substrate-storage)**: Material inventory
- - Multiple storage types (silos, tanks, bunkers)
- - Quality degradation modeling
- - Capacity and utilization tracking
-
-- **[Feeder](user_guide/components/feeding.md#feeder)**: Automated dosing
- - Screw, piston, progressive cavity feeders
- - Realistic dosing accuracy and noise
- - Blockage detection
-
-## Pre-configured Substrates
-
-PyADM1ODE includes 10 agricultural substrates with literature-validated parameters:
-
-| Substrate | Type | Typical Use | Biogas Potential |
-|-----------|------|-------------|------------------|
-| **Corn silage** | Energy crop | Main feedstock | High (600-700 L/kg VS) |
-| **Liquid manure** | Animal waste | Co-substrate | Medium (200-400 L/kg VS) |
-| **Green rye** | Energy crop | Early harvest | Medium-High |
-| **Grass silage** | Grassland | Renewable | Medium (400-550 L/kg VS) |
-| **Wheat** | Cereal | Energy crop | High |
-| **GPS** | Grain silage | Whole-crop | High |
-| **CCM** | Corn-cob-mix | Energy crop | High |
-| **Feed lime** | Additive | pH buffer | N/A |
-| **Cow manure** | Animal waste | Co-substrate | Medium (200-350 L/kg VS) |
-| **Onions** | Waste | Vegetable waste | Medium-High |
-
-All substrates are characterized with:
-- Dry matter (DM) and volatile solids (VS) content
-- ADM1 fractionation (carbohydrates, proteins, lipids)
-- Biochemical methane potential (BMP)
-- pH and alkalinity
-
-## Advanced Features
-
-### Parallel Simulation
-
-Run multiple scenarios concurrently (see [Example: Parallel Simulation](examples/parallel_simulation.md)):
-
-```python
-from pyadm1.simulation import ParallelSimulator
-
-# Parameter sweep
-parallel = ParallelSimulator(adm1, n_workers=4)
-scenarios = [
- {"k_dis": 0.5, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
- {"k_dis": 0.6, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
- {"k_dis": 0.7, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]}
-]
-
-results = parallel.run_scenarios(scenarios, duration=30, initial_state=state)
-```
-
-### Configuration Management
-
-Save and reuse plant designs:
-
-```python
-# Save configuration
-plant.to_json("two_stage_plant.json")
-
-# Load later
-plant = BiogasPlant.from_json("two_stage_plant.json", feedstock)
-plant.initialize()
-results = plant.simulate(duration=30, dt=1/24)
-```
-
-## Scientific Foundation
-
-PyADM1ODE is based on the **Anaerobic Digestion Model No. 1 (ADM1)**, developed by the International Water Association (IWA) Task Group:
-
-- **37 state variables**: Complete representation of liquid and gas phases
-- **19 biochemical processes**: Disintegration, hydrolysis, acidogenesis, acetogenesis, methanogenesis
-- **Temperature-dependent kinetics**: Arrhenius relationships for all rate constants
-- **pH dynamics**: Full acid-base equilibrium with 6 ionic species
-- **Gas-liquid transfer**: Henry's law implementation for H₂, CH₄, CO₂
-- **Inhibition modeling**: pH, ammonia, and hydrogen inhibition
-
-**Key References:**
-
-- Batstone, D.J., et al. (2002). *Anaerobic Digestion Model No. 1 (ADM1)*. IWA Publishing.
-- Sadrimajd, P., et al. (2021). *[PyADM1](https://github.com/CaptainFerMag/PyADM1): a Python implementation of Anaerobic Digestion Model No. 1*. bioRxiv.
-
-## Installation
-
-Install PyADM1ODE via pip (not yet existing):
-
-```bash
-pip install pyadm1ode
-```
-
-For development or the latest features:
-
-```bash
-git clone https://github.com/dgaida/PyADM1ODE.git
-cd PyADM1ODE
-pip install -e .
-```
-
-**Platform-specific requirements:**
-- **Linux/macOS**: Mono runtime (for C# DLLs)
-- **Windows**: .NET Framework (usually pre-installed)
-
-See the [Installation Guide](user_guide/installation.md) for detailed instructions.
-
-## Getting Started
-
-1. **[Install PyADM1ODE](user_guide/installation.md)** on your system
-2. **[Follow the Quickstart](user_guide/quickstart.md)** to run your first simulation
-3. **[Explore Components](user_guide/components/index.md)** to understand available building blocks
-4. **[Study Examples](examples/basic_digester.md)** for real-world applications
-
-## Extension Packages
-
-### PyADM1ODE_mcp - LLM-Driven Plant Design
-
-Natural language interface for biogas plant modeling:
-
-```bash
-git clone https://github.com/dgaida/PyADM1ODE_mcp.git
-cd PyADM1ODE_mcp
-pip install -e .
-```
-
-**Features:**
-- Interact with Claude or other LLMs to design plants via natural language
-- MCP server for seamless LLM integration
-- Automated configuration parsing and validation
-
-**Use case:** *"Design a two-stage biogas plant with 2000 m³ main digester, 500 m³ hydrolysis tank at 45°C, and a 500 kW CHP unit. Use corn silage and cattle manure as substrates."*
-
-### PyADM1ODE_calibration - Parameter Estimation
-
-Automated model calibration from measurement data:
-
-```bash
-git clone https://github.com/dgaida/PyADM1ODE_calibration.git
-cd PyADM1ODE_calibration
-pip install -e .
-```
-
-**Features:**
-- Initial calibration from historical data
-- Online re-calibration during operation
-- Multiple optimization algorithms (Differential Evolution, PSO, Nelder-Mead)
-- Comprehensive validation metrics
-
-**Use case:** Fit ADM1 parameters to real plant measurements for accurate predictions.
+---
## Community and Support
- **GitHub Repository**: [dgaida/PyADM1ODE](https://github.com/dgaida/PyADM1ODE)
- **Issue Tracker**: [Report bugs or request features](https://github.com/dgaida/PyADM1ODE/issues)
- **Discussions**: [Ask questions and share ideas](https://github.com/dgaida/PyADM1ODE/discussions)
-- **Email**: daniel.gaida@th-koeln.de
## License
PyADM1ODE is open-source software licensed under the MIT License.
-
-## Citation
-
-If you use PyADM1ODE in your research, please cite:
-
-```bibtex
-@software{gaida2025pyadm1ode,
- author = {Gaida, Daniel; Nordhoff, Tim Yago},
- title = {PyADM1ODE: Python Framework for Agricultural Biogas Plant Modeling},
- year = {2026},
- url = {https://github.com/dgaida/PyADM1ODE}
-}
-```
-
-## Acknowledgments
-
-PyADM1ODE builds upon:
-
-- **IWA ADM1 Task Group** - Original model development
-- **[PyADM1](https://github.com/CaptainFerMag/PyADM1)** by Sadrimajd et al. - Initial Python implementation
-- **SIMBA#biogas** - Substrate characterization and validation data
-
----
-
-**Ready to start?** Head over to the [Quickstart Guide](user_guide/quickstart.md) and build your first biogas plant in minutes! 🚀
diff --git a/docs/en/user_guide/advanced_features.md b/docs/en/user_guide/advanced_features.md
new file mode 100644
index 0000000..88ed20c
--- /dev/null
+++ b/docs/en/user_guide/advanced_features.md
@@ -0,0 +1,38 @@
+# Advanced Features
+
+PyADM1ODE provides advanced features for large-scale studies and configuration management.
+
+## Parallel Simulation
+
+Run multiple scenarios concurrently to speed up parameter sweeps or Monte Carlo simulations.
+
+```python
+from pyadm1.simulation import ParallelSimulator
+
+# Parameter sweep
+parallel = ParallelSimulator(adm1, n_workers=4)
+scenarios = [
+ {"k_dis": 0.5, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
+ {"k_dis": 0.6, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]},
+ {"k_dis": 0.7, "Q": [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]}
+]
+
+results = parallel.run_scenarios(scenarios, duration=30, initial_state=state)
+```
+
+See the [Parallel Simulation Example](../examples/parallel_simulation.md) for more details.
+
+## Configuration Management
+
+Save and reuse plant designs using JSON serialization.
+
+```python
+# Save configuration
+plant.to_json("two_stage_plant.json")
+
+# Load later
+from pyadm1.configurator import BiogasPlant
+plant = BiogasPlant.from_json("two_stage_plant.json", feedstock)
+plant.initialize()
+results = plant.simulate(duration=30, dt=1/24)
+```
diff --git a/docs/en/user_guide/applications.md b/docs/en/user_guide/applications.md
new file mode 100644
index 0000000..cd7eb97
--- /dev/null
+++ b/docs/en/user_guide/applications.md
@@ -0,0 +1,72 @@
+# Typical Applications
+
+PyADM1ODE can be used for a wide range of tasks, from plant design to real-time optimization.
+
+## 1. Plant Design and Optimization
+
+Test different plant configurations to find the optimal setup for your needs.
+
+```python
+from pyadm1.configurator import BiogasPlant, PlantConfigurator
+from pyadm1.substrates import Feedstock
+
+# Test different digester sizes
+for V_liq in [1500, 2000, 2500]:
+ plant = BiogasPlant(f"Plant_{V_liq}")
+ feedstock = Feedstock()
+ configurator = PlantConfigurator(plant, feedstock)
+ configurator.add_digester("dig1", V_liq=V_liq, Q_substrates=[15, 10, 0, 0, 0, 0, 0, 0, 0, 0])
+
+ plant.initialize()
+ results = plant.simulate(duration=30, dt=1/24)
+
+ final = results[-1]["components"]["dig1"]
+ print(f"V={V_liq} m³ → CH4={final['Q_ch4']:.1f} m³/d")
+```
+
+## 2. Substrate Optimization
+
+Compare different substrate mixes to maximize methane production or minimize costs.
+
+```python
+# Compare different substrate mixes
+mixes = {
+ 'high_energy': [20, 5, 0, 0, 0, 0, 0, 0, 0, 0],
+ 'balanced': [15, 10, 0, 0, 0, 0, 0, 0, 0, 0],
+ 'waste_based': [0, 15, 0, 0, 0, 0, 0, 0, 10, 5]
+}
+
+for name, Q in mixes.items():
+ # ... configure and simulate ...
+ print(f"{name}: {final['Q_ch4']:.1f} m³/d methane")
+```
+
+## 3. Energy Balance Analysis
+
+Analyze the net energy production and parasitic loads of your plant.
+
+```python
+# Calculate net energy production
+chp_power = results[-1]["components"]["chp_main"]["P_el"]
+mixer_power = results[-1]["components"]["mixer_1"]["P_consumed"]
+pump_power = results[-1]["components"]["pump_1"]["P_consumed"]
+
+parasitic_load = mixer_power + pump_power
+net_power = chp_power - parasitic_load
+
+print(f"Net power: {net_power:.1f} kW")
+print(f"Parasitic ratio: {parasitic_load/chp_power:.1%}")
+```
+
+## 4. Two-Stage Process Design
+
+Model advanced plant designs like Temperature-Phased Anaerobic Digestion (TPAD).
+
+```python
+# Temperature-phased anaerobic digestion (TPAD)
+configurator.add_digester("hydrolysis", V_liq=500, T_ad=318.15) # 45°C
+configurator.add_digester("main", V_liq=2000, T_ad=308.15) # 35°C
+configurator.connect("hydrolysis", "main", "liquid")
+
+# Enhanced hydrolysis in stage 1, stable methanogenesis in stage 2
+```
diff --git a/docs/en/user_guide/substrates.md b/docs/en/user_guide/substrates.md
new file mode 100644
index 0000000..57bab16
--- /dev/null
+++ b/docs/en/user_guide/substrates.md
@@ -0,0 +1,28 @@
+# Pre-configured Substrates
+
+PyADM1ODE includes 10 agricultural substrates with literature-validated parameters.
+
+## Available Substrates
+
+| Substrate | Type | Typical Use | Biogas Potential |
+|-----------|------|-------------|------------------|
+| **Corn silage** | Energy crop | Main feedstock | High (600-700 L/kg VS) |
+| **Liquid manure** | Animal waste | Co-substrate | Medium (200-400 L/kg VS) |
+| **Green rye** | Energy crop | Early harvest | Medium-High |
+| **Grass silage** | Grassland | Renewable | Medium (400-550 L/kg VS) |
+| **Wheat** | Cereal | Energy crop | High |
+| **GPS** | Grain silage | Whole-crop | High |
+| **CCM** | Corn-cob-mix | Energy crop | High |
+| **Feed lime** | Additive | pH buffer | N/A |
+| **Cow manure** | Animal waste | Co-substrate | Medium (200-350 L/kg VS) |
+| **Onions** | Waste | Vegetable waste | Medium-High |
+
+## Substrate Characterization
+
+All substrates are characterized with:
+- Dry matter (DM) and volatile solids (VS) content
+- ADM1 fractionation (carbohydrates, proteins, lipids)
+- Biochemical methane potential (BMP)
+- pH and alkalinity
+
+For more details on how these are mapped to ADM1, see the [ADM1 Implementation](adm1_implementation.md) page.
diff --git a/examples/colab_01_basic_digester.ipynb b/examples/colab_01_basic_digester.ipynb
new file mode 100644
index 0000000..b35c448
--- /dev/null
+++ b/examples/colab_01_basic_digester.ipynb
@@ -0,0 +1,155 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# PyADM1ODE: Basic Digester Example\n",
+ "\n",
+ "This notebook demonstrates the simplest possible PyADM1 configuration: a single digester with substrate feed and integrated gas storage.\n",
+ "\n",
+ "[](https://colab.research.google.com/github/dgaida/PyADM1ODE/blob/master/examples/colab_01_basic_digester.ipynb)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 1. Setup Environment\n",
+ "\n",
+ "We need to install the necessary dependencies, including Mono (for .NET compatibility) and the `pyadm1` package."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Install Mono and other dependencies\n",
+ "!apt-get update\n",
+ "!apt-get install -y mono-devel\n",
+ "\n",
+ "# Clone the repository and install pyadm1\n",
+ "!git clone https://github.com/dgaida/PyADM1ODE.git\n",
+ "%cd PyADM1ODE\n",
+ "!pip install -e ."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 2. Import Libraries"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "from pathlib import Path\n",
+ "import numpy as np\n",
+ "from pyadm1.configurator.plant_builder import BiogasPlant\n",
+ "from pyadm1.substrates.feedstock import Feedstock\n",
+ "from pyadm1.core.adm1 import get_state_zero_from_initial_state\n",
+ "from pyadm1.configurator.plant_configurator import PlantConfigurator"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 3. Run Simulation"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Setup paths\n",
+ "data_path = Path(\"data/initial_states\")\n",
+ "initial_state_file = data_path / \"digester_initial8.csv\"\n",
+ "\n",
+ "# 1. Create feedstock\n",
+ "feeding_freq = 48\n",
+ "feedstock = Feedstock(feeding_freq=feeding_freq)\n",
+ "\n",
+ "# 2. Load initial state from CSV\n",
+ "adm1_state = get_state_zero_from_initial_state(str(initial_state_file))\n",
+ "\n",
+ "# 3. Create biogas plant\n",
+ "plant = BiogasPlant(\"Quickstart Plant\")\n",
+ "configurator = PlantConfigurator(plant, feedstock)\n",
+ "\n",
+ "# 4. Define substrate feed (Corn silage: 15 m³/d, Manure: 10 m³/d)\n",
+ "Q_substrates = [15, 10, 0, 0, 0, 0, 0, 0, 0, 0]\n",
+ "\n",
+ "# 5. Add digester\n",
+ "configurator.add_digester(\n",
+ " digester_id=\"main_digester\",\n",
+ " V_liq=2000.0,\n",
+ " V_gas=300.0,\n",
+ " T_ad=308.15, # 35°C\n",
+ " name=\"Main Digester\",\n",
+ " load_initial_state=True,\n",
+ " initial_state_file=str(initial_state_file),\n",
+ " Q_substrates=Q_substrates,\n",
+ ")\n",
+ "\n",
+ "# 6. Initialize and simulate\n",
+ "plant.initialize()\n",
+ "results = plant.simulate(duration=5.0, dt=1.0/24.0, save_interval=1.0)\n",
+ "\n",
+ "print(\"\\nSimulation completed successfully!\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 4. Analyze Results"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "for result in results:\n",
+ " time = result[\"time\"]\n",
+ " comp_results = result[\"components\"][\"main_digester\"]\n",
+ " print(f\"Day {time:.1f}:\")\n",
+ " print(f\" Biogas: {comp_results.get('Q_gas', 0):>8.1f} m³/d\")\n",
+ " print(f\" Methane: {comp_results.get('Q_ch4', 0):>8.1f} m³/d\")\n",
+ " print(f\" pH: {comp_results.get('pH', 0):>8.2f}\")"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython",
+ "version": "3.10.12"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/examples/colab_02_complex_plant.ipynb b/examples/colab_02_complex_plant.ipynb
new file mode 100644
index 0000000..04bc22d
--- /dev/null
+++ b/examples/colab_02_complex_plant.ipynb
@@ -0,0 +1,161 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# PyADM1ODE: Complex Two-Stage Plant Example\n",
+ "\n",
+ "This notebook demonstrates a two-stage biogas plant with mechanical components (pumps, mixers) and energy integration (CHP, heating).\n",
+ "\n",
+ "[](https://colab.research.google.com/github/dgaida/PyADM1ODE/blob/master/examples/colab_02_complex_plant.ipynb)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 1. Setup Environment"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Install Mono and other dependencies\n",
+ "!apt-get update\n",
+ "!apt-get install -y mono-devel\n",
+ "\n",
+ "# Clone the repository and install pyadm1\n",
+ "!git clone https://github.com/dgaida/PyADM1ODE.git\n",
+ "%cd PyADM1ODE\n",
+ "!pip install -e ."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 2. Import Libraries"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "from pathlib import Path\n",
+ "from pyadm1.configurator.plant_builder import BiogasPlant\n",
+ "from pyadm1.substrates.feedstock import Feedstock\n",
+ "from pyadm1.configurator.plant_configurator import PlantConfigurator\n",
+ "from pyadm1.components.mechanical.mixer import Mixer\n",
+ "from pyadm1.components.mechanical.pump import Pump"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 3. Configure and Run Simulation"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "initial_state_file = \"data/initial_states/digester_initial8.csv\"\n",
+ "\n",
+ "# 1. Create feedstock\n",
+ "feedstock = Feedstock(feeding_freq=48)\n",
+ "plant = BiogasPlant(\"Two-Stage Plant\")\n",
+ "configurator = PlantConfigurator(plant, feedstock)\n",
+ "\n",
+ "# 2. Add Stage 1 (Hydrolysis)\n",
+ "configurator.add_digester(\n",
+ " digester_id=\"digester_1\",\n",
+ " V_liq=1977.0,\n",
+ " V_gas=304.0,\n",
+ " T_ad=318.15, # 45°C\n",
+ " load_initial_state=True,\n",
+ " initial_state_file=initial_state_file,\n",
+ " Q_substrates=[15, 10, 0, 0, 0, 0, 0, 0, 0, 0]\n",
+ ")\n",
+ "\n",
+ "# 3. Add Stage 2 (Methanogenesis)\n",
+ "configurator.add_digester(\n",
+ " digester_id=\"digester_2\",\n",
+ " V_liq=1000.0,\n",
+ " V_gas=150.0,\n",
+ " T_ad=308.15, # 35°C\n",
+ " load_initial_state=True,\n",
+ " initial_state_file=initial_state_file,\n",
+ " Q_substrates=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]\n",
+ ")\n",
+ "\n",
+ "# 4. Add CHP and Heating\n",
+ "configurator.add_chp(\"chp_1\", P_el_nom=500.0)\n",
+ "configurator.add_heating(\"heating_1\", target_temperature=318.15)\n",
+ "configurator.add_heating(\"heating_2\", target_temperature=308.15)\n",
+ "\n",
+ "# 5. Connect components\n",
+ "configurator.connect(\"digester_1\", \"digester_2\", \"liquid\")\n",
+ "configurator.auto_connect_digester_to_chp(\"digester_1\", \"chp_1\")\n",
+ "configurator.auto_connect_digester_to_chp(\"digester_2\", \"chp_1\")\n",
+ "configurator.auto_connect_chp_to_heating(\"chp_1\", \"heating_1\")\n",
+ "configurator.auto_connect_chp_to_heating(\"chp_1\", \"heating_2\")\n",
+ "\n",
+ "# 6. Initialize and simulate\n",
+ "plant.initialize()\n",
+ "results = plant.simulate(duration=5.0, dt=1.0/24.0, save_interval=1.0)\n",
+ "\n",
+ "print(\"\\nSimulation completed successfully!\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 4. Analyze Results"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "final = results[-1][\"components\"]\n",
+ "print(f\"Total Biogas: {final['digester_1']['Q_gas'] + final['digester_2']['Q_gas']:.1f} m³/d\")\n",
+ "print(f\"Total Methane: {final['digester_1']['Q_ch4'] + final['digester_2']['Q_ch4']:.1f} m³/d\")\n",
+ "print(f\"CHP Power: {final['chp_1']['P_el']:.1f} kW\")"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython",
+ "version": "3.10.12"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index 4365b65..78d8f31 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -88,10 +88,9 @@ markdown_extensions:
nav:
- Home: index.md
- - Erste Schritte:
+ - Handbuch:
- 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
@@ -100,16 +99,18 @@ nav:
- Fütterung: user_guide/components/feeding.md
- Mechanisch: user_guide/components/mechanical.md
- Sensoren: user_guide/components/sensors.md
- - Beispiele:
- - Basis-Fermenter: examples/basic_digester.md
- - Zweistufige Anlage: examples/two_stage_plant.md
- - Parallele Simulation: examples/parallel_simulation.md
+ - Substrate: user_guide/substrates.md
+ - Anwendungen: user_guide/applications.md
+ - Fortgeschrittene Funktionen: user_guide/advanced_features.md
- Architektur: architecture/index.md
- - Entwicklung:
- - Styleguide: development/style_guide.md
- - Fehlerbehebung: user_guide/troubleshooting.md
- - Metriken: metrics.md
- - Changelog: CHANGELOG.md
+ - Fehlerbehebung: user_guide/troubleshooting.md
+ - Beispiele:
+ - Basis-Fermenter: examples/basic_digester.md
+ - Zweistufige Anlage: examples/two_stage_plant.md
+ - Parallele Simulation: examples/parallel_simulation.md
+ - Entwicklung:
+ - Styleguide: development/style_guide.md
+ - Metriken: metrics.md
- API-Referenz:
- Core: api/core.md
- Biologisch: api/biological.md
@@ -119,6 +120,7 @@ nav:
- Konfigurator: api/configurator.md
- Simulation: api/simulation.md
- Substrate: api/substrates.md
+ - Changelog: CHANGELOG.md
extra:
social: