From b4ddb6b8dfbb431bf23f9e07840f39018a400144 Mon Sep 17 00:00:00 2001
From: "p.vanderwilt" <p.van.der.wilt@brabantsedelta.nl>
Date: Mon, 7 Jul 2025 11:08:11 +0200
Subject: [PATCH] Enhance documentation for ASM3 class and its parameters

---
 src/asm3_class.js | 45 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/src/asm3_class.js b/src/asm3_class.js
index f5ac1df..ab272dc 100644
--- a/src/asm3_class.js
+++ b/src/asm3_class.js
@@ -1,11 +1,16 @@
 const math = require('mathjs')
 
+/**
+ * ASM3 class for the Activated Sludge Model No. 3 (ASM3).
+ */
 class ASM3 {
 
   constructor() {
+    /**
+     * Kinetic parameters for ASM3 at 20 C.
+     * @property {Object} kin_params - Kinetic parameters
+     */
     this.kin_params = {
-      // Kinetic parameters (20 C for now)
-
       // Hydrolysis
       k_H:      3.,   // hydrolysis rate constant       [g X_S g-1 X_H d-1]
       K_X:      1.,   // hydrolysis saturation constant [g X_S g-1 X_H] 
@@ -31,9 +36,13 @@ class ASM3 {
       b_A_O:    0.15, // aerobic respiration rate       [d-1]
       b_A_NO:   0.05  // anoxic respiration rate        [d-1]
     };
-    this.stoi_params = {
-      // Stoichiometric and composition parameters
 
+    /**
+     * Stoichiometric and composition parameters for ASM3.
+     * @property {Object} stoi_params - Stoichiometric parameters
+     */
+    this.stoi_params = {
+      // Fractions
       f_SI:     0.,   // fraction S_I from hydrolysis   [g S_I g-1 X_S]
       f_XI:     0.2,  // fraction X_I from decomp X_H   [g X_I g-1 X_H]
       // Yields
@@ -63,6 +72,10 @@ class ASM3 {
     this.stoi_matrix = this._initialise_stoi_matrix();
   }
 
+  /**
+   * Initialises the stoichiometric matrix for ASM3.
+   * @returns {Array} - The stoichiometric matrix for ASM3. (2D array)
+   */
   _initialise_stoi_matrix() { // initialise stoichiometric matrix
     const { f_SI, f_XI, Y_STO_O, Y_STO_NO, Y_H_O, Y_H_NO, Y_A, i_CODN, i_CODNO, i_NSI, i_NSS, i_NXI, i_NXS, i_NBM, i_TSXI, i_TSXS, i_TSBM, i_TSSTO, i_cNH, i_cNO } = this.stoi_params;
 
@@ -84,15 +97,32 @@ class ASM3 {
     return stoi_matrix[0].map((col, i) => stoi_matrix.map(row => row[i])); // transpose matrix
   }
 
+  /**
+   * Computes the Monod equation rate value for a given concentration and half-saturation constant.
+   * @param {number} c - Concentration of reaction species.
+   * @param {number} K - Half-saturation constant for the reaction species.
+   * @returns {number} - Monod equation rate value for the given concentration and half-saturation constant.
+   */
   _monod(c, K){
     return c / (K + c);
   }
 
+  /**
+   * Computes the inverse Monod equation rate value for a given concentration and half-saturation constant. Used for inhibition.
+   * @param {number} c - Concentration of reaction species.
+   * @param {number} K - Half-saturation constant for the reaction species. 
+   * @returns {number} - Inverse Monod equation rate value for the given concentration and half-saturation constant.
+   */
   _inv_monod(c, K){
     return K / (K + c);
   }
 
-  compute_rates(state) { // computes reaction rates. state is optional
+  /**
+   * Computes the reaction rates for each process reaction based on the current state.
+   * @param {Array} state - State vector containing concentrations of reaction species.
+   * @returns {Array} - Reaction rates for each process reaction.
+   */
+  compute_rates(state) {
     // state: S_O, S_I, S_S, S_NH, S_N2, S_NO, S_HCO, X_I, X_S, X_H, X_STO, X_A, X_TS
     const rates = Array(12);
     const [S_O, S_I, S_S, S_NH, S_N2, S_NO, S_HCO, X_I, X_S, X_H, X_STO, X_A, X_TS] = state;
@@ -119,6 +149,11 @@ class ASM3 {
     return rates;
   }
 
+  /**
+   * Computes the change in concentrations of reaction species based on the current state.
+   * @param {Array} state - State vector containing concentrations of reaction species.
+   * @returns {Array} - Change in reaction species concentrations.
+   */
   compute_dC(state) { // compute changes in concentrations
     // state: S_O, S_I, S_S, S_NH, S_N2, S_NO, S_HCO, X_I, X_S, X_H, X_STO, X_A, X_TS
     return math.multiply(this.stoi_matrix, this.compute_rates(state));