swat-model · debpal · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/README.md b/README.md
@@ -35,10 +35,12 @@
 
 ## ✨ Key Features
 
-- Modify model parameters through the `calibration.cal` file.
-- Run SWAT+ simulations seamlessly.
-- Compute performance metrics using widely adopted indicators.
-- Perform sensitivity analysis on model parameters using the [SALib](https://github.com/SALib/SALib) Python package, with support for parallel computation; currently, only Sobol sampling and Sobol indices are supported.
+- Run `SWAT+` simulations by modifying model parameters through the  `calibration.cal` file..
+- Evaluate model performance against observed data using widely recognized statistical indicators.
+- Perform sensitivity analysis on model parameters using the [`SALib`](https://github.com/SALib/SALib) Python package.
+- Calibrate model parameters through multi-objective optimization and evolutionary algorithms using the [`pymoo`](https://github.com/anyoptimization/pymoo) Python package. 
+- Execute sensitivity analysis and model calibration through high-level interfaces with built-in parallel computation support.
+- Analyze outputs from model simulations, sensitivity analyses, and calibrations.
 
 
 ## 📥 Install pySWATPlus

diff --git a/docs/api/calibration.md b/docs/api/calibration.md
@@ -0,0 +1,2 @@
+::: pySWATPlus.Calibration
+
diff --git a/docs/api/types.md b/docs/api/types.md
diff --git a/docs/index.md b/docs/index.md
@@ -8,10 +8,12 @@
 
 ## ✨ Key Features
 
-- Modify model parameters through the `calibration.cal` file.
-- Run SWAT+ simulations seamlessly.
-- Compute performance metrics using widely adopted indicators.
-- Perform sensitivity analysis on model parameters using the [SALib](https://github.com/SALib/SALib) Python package, with support for parallel computation; currently, only Sobol sampling and Sobol indices are supported.
+- Run `SWAT+` simulations by modifying model parameters through the  `calibration.cal` file..
+- Evaluate model performance against observed data using widely recognized statistical indicators.
+- Perform sensitivity analysis on model parameters using the [`SALib`](https://github.com/SALib/SALib) Python package.
+- Calibrate model parameters through multi-objective optimization and evolutionary algorithms using the [`pymoo`](https://github.com/anyoptimization/pymoo) Python package. 
+- Execute sensitivity analysis and model calibration through high-level interfaces with built-in parallel computation support.
+- Analyze outputs from model simulations, sensitivity analyses, and calibrations.
 
 
 ## 📥 Install pySWATPlus

diff --git a/docs/userguide/data_analysis.md b/docs/userguide/data_analysis.md
@@ -20,10 +20,22 @@ output = pySWATPlus.DataManager().simulated_timeseries_df(
     usecols=['name', 'flo_out'],
     json_file=r"C:\Users\Username\output_folder\tmp.json"
 )
-
-print(output)
 ```
 
+## Statistics from Daily Time Series
+
+Monthly and yearly statistics such as maximum, minimum, mean, and standard deviation derived from daily time series data help summarize and interpret simulation variability over time.
+The following interface computes monthly and yearly statistical summaries for a Hydrological Response Unit (HRU) based on daily simulated flow discharge data. These metrics provide insight into seasonal patterns, flow extremes, and overall hydrological stability.
+
+```python
+output = pySWATPlus.DataManager().simulated_timeseries_df(
+    sim_file=r"C:\Users\Username\custom_folder\channel_sd_day.txt",
+    has_units=True,
+    gis_id=561,
+    sim_col='flo_out',
+    output_dir=r"C:\Users\Username\output_dir"
+)
+```
 
 ## Read Sensitivity Simulation Data
 
@@ -49,14 +61,6 @@ output = pySWATPlus.DataManager().read_sensitive_dfs(
 
 For a selected `DataFrame`, scenario metrics across all simulations can be computed by comparing model outputs with observed data.
 
-NSE: Nash–Sutcliffe Efficiency
-KGE: Kling–Gupta Efficiency
-MSE: Mean Squared Error
-RMSE: Root Mean Squared Error
-PBIAS: Percent Bias
-MARE: Mean Absolute Relative Error
-
-
 
 - To get the mapping between available indicators and their abbreviations:
 

diff --git a/docs/userguide/model_calibration.md b/docs/userguide/model_calibration.md
@@ -0,0 +1,122 @@
+# Model Calibration
+
+This tutorial demonstrates how to perform `SWAT+` model calibration to optimize sensitive parameters based on observed data.
+
+Before running the calibration, ensure the model is properly configured. This includes setting the simulation timeline, managing file outputs, and fixing non-sensitive parameters so that they remain constant across all scenarios. A detailed explanation of these steps is provided in the [`Configuration Settings`](https://swat-model.github.io/pySWATPlus/userguide/sensitivity_interface/#configuration-settings) section.
+
+Leveraging the multi-objective optimization and evolutionary algorithms available in the [`pymoo`](https://github.com/anyoptimization/pymoo) Python package,
+the calibration interface offers flexible options for optimizing model parameters:
+
+- Single- or multi-objective optimization (e.g., single objective such as flow discharge, or multiple objectives such as flow discharge and nitrogen concentration together).  
+- Multiple algorithm options for both single- and multi-objective optimization:
+
+    - Single-objective algorithms
+
+        - Genetic Alogorithm
+        - [Differential Evolution Algorithm](https://doi.org/10.1007/3-540-31306-0)
+
+    - Multi-objective algorithms
+
+        - [Non-dominated sorted Genetic Algorithm-II](https://doi.org/10.1109/4235.996017)
+
+- Five indicators for comparing simulated and observed values:
+
+    - Nash–Sutcliffe Efficiency
+    - Kling–Gupta Efficiency
+    - Mean Squared Error
+    - Root Mean Squared Error
+    - Mean Absolute Relative Error
+
+- Parallel computation support for faster processing.
+
+- Automatic saving of optimization history for each generation, enabling analysis of optimization progress, convergence trends, performance indicators, and visualization.
+
+
+The interface provides a [`Calibration`](https://swat-model.github.io/pySWATPlus/api/model_calibration/) class that must be initialized with the required parameters.
+This class includes the `parameter_optimization` method, which performs parameter optimization using multi-objective algorithms, evolutionary strategies, and parallel computation.
+
+The following code provides an example of optimizing flow discharge for both daily and monthly time-series data using multi-objective evolutionary computation.
+The usage of both daily and monthly flow discharge is just for illustrative purposes on how multi-objective optimization can be performed. Users should replace monthly flow
+discharge by nitorgen or phosporus concentration according to their needs.
+
+
+```python
+# Calibration parameter space
+parameters = [
+    {
+        'name': 'esco',
+        'change_type': 'absval',
+        'lower_bound': 0,
+        'upper_bound': 1
+    },
+    {
+        'name': 'perco',
+        'change_type': 'absval',
+        'lower_bound': 0,
+        'upper_bound': 1
+    }
+]
+
+
+# Extract data configuration
+extract_data = {
+    'channel_sd_day.txt': {
+        'has_units': True,
+        'apply_filter': {'name': ['cha561']}
+    },
+    'channel_sd_mon.txt': {
+        'has_units': True,
+        'ref_day': 1,
+        'apply_filter': {'name': ['cha561']}
+    }
+}
+
+# Observe data configuration
+observe_data = {
+    'channel_sd_day.txt': {
+        'obs_file': r"C:\Users\Username\observed_folder\discharge_daily.csv",
+        'date_format': '%Y-%m-%d'
+    },
+    'channel_sd_mon.txt': {
+        'obs_file': r"C:\Users\Username\observed_folder\discharge_monthly.csv",
+        'date_format': '%Y-%m-%d'
+    }
+}
+
+# Objective configuration
+objectives = {
+    'channel_sd_day.txt': {
+        'sim_col': 'flo_out',
+        'obs_col': 'discharge',
+        'indicator': 'NSE'
+    },
+    'channel_sd_mon.txt': {
+        'sim_col': 'flo_out',
+        'obs_col': 'mean',
+        'indicator': 'RMSE'
+    }
+}
+
+# Model calibration
+if __name__ == '__main__':
+    calibration = pySWATPlus.Calibration(
+        parameters=parameters,
+        calsim_dir=r"C:\Users\Username\simulation_calibration",
+        txtinout_dir=r"C:\Users\Username\project\Scenarios\Default\TxtInOut",
+        extract_data=extract_data,
+        observe_data=observe_data,
+        objectives=objectives,
+        algorithm='NSGA2',
+        n_gen=2,
+        pop_size=5
+    )
+
+    output = calibration.parameter_optimization()
+```
+
+
+!!! tip "Troubleshooting Parallel Processing Errors"
+    If you encounter an error related to `concurrent.futures.ProcessPoolExecutor` and  `multiprocessing` without a clear description,
+    try closing the current command terminal and restarting it. This issue can occasionally occur due to lingering background processes
+    or locked resources from previous runs.
+
diff --git a/docs/userguide/sensitivity_interface.md b/docs/userguide/sensitivity_interface.md
@@ -1,12 +1,12 @@
 # Sensitivity Interface
 
-Sensitivity interface helps quantify how variation in input parameters affects model outputs. This tutorial demonstrates how to perform sensitivity analysis on SWAT+ model parameters.  
+The sensitivity interface helps quantify how variations in input parameters affect `SWAT+` model outputs. This tutorial demonstrates how to perform sensitivity analysis on selected parameters.  
 
 
 ## Configuration Settings
 
-Before running a sensitivity simulation, you must define the necessary configuration settings.  
-These settings specify key parameters such as the simulation timeline, output print options, and other essential model controls.
+Before running a sensitivity simulation, configure the necessary settings, such as the simulation period, output print options, and non-targeted parameters,
+so that these parameters remain fixed across all scenarios.
 
 
 ```python
@@ -108,6 +108,12 @@ if __name__ == '__main__':
     print(output)
 ```
 
+
+!!! tip "Troubleshooting Parallel Processing Errors"
+    If you encounter an error related to `concurrent.futures.ProcessPoolExecutor` and  `multiprocessing` without a clear description,
+    try closing the current command terminal and restarting it. This issue can occasionally occur due to lingering background processes
+    or locked resources from previous runs.
+
 ## Sensitivity Indices
 
 Sensitivity indices (first, second, and total orders) are computed using the indicators available in the `pySWATPlus.PerformanceMetrics` class, along with their confidence intervals.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -38,14 +38,15 @@ nav:
   - User Guide:
     - SWAT+ Simulation: userguide/swatplus_simulation.md
     - Sensitivity Interface: userguide/sensitivity_interface.md
+    - Model Calibration: userguide/model_calibration.md
     - Data Analysis: userguide/data_analysis.md
 
   - API Reference:
     - TxtinoutReader: api/txtinout_reader.md
-    - DataManager: api/data_manager.md
-    - SensitivityAnalyzer: api/sensitivity_analyzer.md
     - PerformanceMetrics: api/performance_metrics.md
-    - pySWATPlus.types: api/types.md
+    - SensitivityAnalyzer: api/sensitivity_analyzer.md
+    - Calibration: api/calibration.md
+    - DataManager: api/data_manager.md
 
   - Contributor Guide: CONTRIBUTING.md
 

diff --git a/pySWATPlus/__init__.py b/pySWATPlus/__init__.py
@@ -2,6 +2,7 @@
 from .data_manager import DataManager
 from .sensitivity_analyzer import SensitivityAnalyzer
 from .performance_metrics import PerformanceMetrics
+from .calibration import Calibration
 from importlib.metadata import version, PackageNotFoundError
 
 try:
@@ -16,5 +17,6 @@
     'DataManager',
     'SensitivityAnalyzer',
     'PerformanceMetrics',
+    'Calibration',
     '__version__'
 ]