######################################## **12. Frequently Asked Questions (FAQ)** ######################################## .. contents:: :depth: 2 =========================================================== Community Water Model (CWatM) - Frequently Asked Questions =========================================================== .. contents:: Table of Contents :depth: 3 :local: :backlinks: top Introduction and Overview ========================= **Q: What is CWatM?** ---------------------- A: CWatM (Community Water Model) is a hydrological model that simulates the water cycle daily at global and local levels, both historically and into the future. It's maintained by IIASA's Water Security research group and is designed to assess water availability, water demand, and environmental needs. **Q: Who developed CWatM?** --------------------------- A: CWatM was developed by the IIASA (International Institute for Applied Systems Analysis) Water Security program, with the current version being 1.10 as of October 2025. **Q: What is the main purpose of CWatM?** ------------------------------------------ A: The model is designed for assessing water availability, water demand, and environmental needs. It includes an accounting of how future water demands will evolve in response to socioeconomic change and how water availability will change in response to climate. **Q: Why was CWatM created?** ------------------------------ A: The Community Water Model will help to develop a next-generation hydro-economic modeling tool that represents the economic trade-offs among water supply technologies and demands. The tool will track water use from all sectors and will identify the least-cost solutions for meeting future water demands under policy constraints. Installation and Setup ====================== **Q: What are the system requirements for CWatM?** --------------------------------------------------- A: CWatM requires: * Python 3.7 or higher * Operating Systems: Windows, Linux, macOS * Python libraries: numpy, scipy, netCDF4, GDAL, pandas, xarray **Q: How do I install CWatM?** ------------------------------- A: CWatM can be cloned through the CWatM GitHub repository. For those new to GitHub, using GitHub desktop is recommended. **Q: What Python packages are required?** ------------------------------------------ A: Essential packages include: * numpy (version 1.26 recommended) * scipy * GDAL (version 3.8) * netCDF4 * pandas * xarray Additional packages for post-processing: * Jupyter Notebook * plotly * XlsxWriter For CWatM-MODFLOW coupling: * FloPy * xmipy **Q: How do I run CWatM?** --------------------------- A: Use the command: python cwatm.py settings.ini (You may need to adjust the path to your python version and to cwatm.py). You need either to add Python to the PATH Environmental Variable or start Python with full path. **Q: Can I use a virtual environment?** ---------------------------------------- A: Yes, virtual environments are useful for controlling package versions but are totally optional. The virtual environment helps maintain specific package versions for your code while allowing different versions for other projects. **Q: Are there pre-compiled libraries available?** --------------------------------------------------- A: For computationally demanding parts like routing, CWatM comes with a C++ library. A pre-compiled version is included for Windows and Linux. CWatM detects automatically which system is running and which compiled version is needed. Technical Specifications ======================== **Q: What resolution can CWatM run at?** ----------------------------------------- A: CWatM can be run at daily resolution globally from 5 arcminutes to 0.5 degrees, or separately for any basin or region. For some regions CWatM has version with 1km or 1 arcmin resoution. Sub-grid resolution taking topography and land cover into account. **Q: What programming language is CWatM written in?** ------------------------------------------------------ A: CWatM is open source in the Python programming environment and has a modular structure. It uses global, freely available data in the netCDF4 file format for reading, storage, and production of data. **Q: Is CWatM open source?** ----------------------------- A: Yes, CWatM is open source and available on GitHub. Its modular structure facilitates integration with other models. The source code of CWatM is freely available under the GNU General Public License V3. **Q: What is the modular structure of CWatM?** ----------------------------------------------- A: Each module is identically composed of an initialization class and a dynamic class operating through time. Alternative descriptions of processes can be included in a module as different initial and dynamic classes. Model Features and Capabilities ================================ **Q: What processes does CWatM simulate?** ------------------------------------------- A: CWatM includes general surface and groundwater hydrological processes but also takes into account human activities, such as water use and reservoir regulation, by calculating water demands, water use, and return flows. Reservoirs and lakes are included in the model scheme. **Q: How does CWatM handle soil processes?** --------------------------------------------- A: CWatM uses the Van Genuchten model for soil water transport. Soil hydraulic parameters are derived via pedotransfer functions from standard soil properties. The soil moisture equation is solved iteratively on a subdaily time step. **Q: Can CWatM simulate groundwater?** --------------------------------------- A: Yes, CWatM includes groundwater simulation. CWatM can integrate with MODFLOW for detailed groundwater modeling. The coupled CWatM-MODFLOW version requires creating a MODFLOW grid and defining the resolution and coordinate systems. **Q: How are lakes and reservoirs handled?** --------------------------------------------- A: CWatM differentiates between big lakes and reservoirs connected inside the river network and smaller ones that are part of a single grid cell. The HydroLakes database provides 1.4 million global lakes and reservoirs with surface area ≥10ha. **Q: What routing method does CWatM use?** ------------------------------------------- A: CWatM applies the kinematic wave approximation of the Saint-Venant equations for routing water through channels. Soil and river routing runs on 10 time-steps per day for improved accuracy. Model Integration ================= **Q: Can CWatM be integrated with other models?** -------------------------------------------------- A: Yes, CWatM is designed to be flexible and link to different aspects of the water-energy-food nexus. It will be coupled to existing IIASA models, including EPIC, MESSAGE, GLOBIOM, and the Global Hydro-Economic Model. **Q: How does model coupling work?** ------------------------------------- A: Linking to other models can be done by transfer via input and output files. Every global variable of CWatM can be written as annual, monthly, or daily time series as text files for specific points, aggregated to basins, or as maps. **Q: Can CWatM work with MODFLOW?** ------------------------------------ A: Yes, CWatM can integrate with MODFLOW. This requires creating a MODFLOW grid using Main_Preprocess_ModFlow.py with your CWatM mask map and topographic map, defining the resolution and coordinate systems. Climate and Data ================ **Q: What climate data can CWatM use?** ---------------------------------------- A: CWatM can use different datasets of meteorological forcing for current climate (e.g., MSWEP, WFDEI, PGMFD, GSWP3, or EWEMBI) or future climate projections from different general circulation models (GCMs). **Q: What data formats does CWatM use?** ----------------------------------------- A: CWatM uses the netCDF4 file format for reading, storage, and production of data in a compact way. As long as the forcing data use the CF 1.6 Convention, CWatM takes care of different names of input variables. **Q: How does CWatM track data sources?** ------------------------------------------ A: CWatM implements FAIR data principles - model data used (name and date) is stored in discharge netcdf files, complete settings files are stored in netcdf outputs, and version numbers with GitHub hash are tracked in global attributes. Calibration =========== **Q: Is CWatM calibrated?** ---------------------------- A: Calibrating CWatM is of major importance, as the model is developed to quantify water demand versus availability for detailed regional water resources assessments that will act as the basis for interactions with stakeholders and regional policy development. **Q: What parameters can be calibrated?** ------------------------------------------ A: Calibration parameters include: Snowmelt coefficient, Crop factor, Soil depth factor, Preferential bypass flow, Infiltration capacity parameter, Interflow factor, Recession coefficient factor, and Runoff concentration factor. **Q: Is there a calibration tool available?** ---------------------------------------------- A: Yes, CWatM includes a dedicated calibration tool with accompanying tutorial documentation. The calibration uses DEAP (Distributed Evolutionary Algorithms in Python) and can run multiple parameter combinations. **Q: What performance metrics are used?** ------------------------------------------ A: CWatM uses metrics like Nash-Sutcliffe Efficiency (NSE) and Kling-Gupta Efficiency (KGE) for model calibration and validation. Applications and Use Cases ========================== **Q: What are the main applications of CWatM?** ------------------------------------------------ A: CWatM helps develop next-generation hydro-economic modeling tools that represent economic trade-offs among water supply technologies and demands. It tracks water use from all sectors and identifies least-cost solutions for meeting future water demands under policy constraints. **Q: Can CWatM be used for regional studies?** ----------------------------------------------- A: Yes, CWatM can simulate hydrology both globally and regionally at different resolutions from 30 arcmin to 30 arcsec at daily time steps. It can be run for any specific basin or region. **Q: Does CWatM consider environmental needs?** ------------------------------------------------ A: Yes, the tool incorporates environmental flow requirements to ensure sufficient water for environmental needs. **Q: How does CWatM handle water demand?** ------------------------------------------- A: Water demand is estimated for irrigation, livestock, industry and energy, and households. Irrigation water demand estimates account for soil moisture, seasonal variability, irrigation methods and climatic conditions. **Q: Can CWatM be used for climate change studies?** ----------------------------------------------------- A: Yes, CWatM can be used to evaluate hydrological effects of climate change by employing different climate scenarios (SSPs) and can simulate both historical and future periods. Model Output ============ **Q: What output variables does CWatM provide?** ------------------------------------------------- A: CWatM provides numerous output variables including: * Discharge (river flow) * Evapotranspiration * Soil moisture * Groundwater storage * Snow cover and SWE * Total water storage * Lake and reservoir storage * Water demand by sector * Return flows **Q: How can I control output frequency?** ------------------------------------------- A: Output can be generated as daily (OUT_TSS_Daily), monthly average (OUT_TSS_MonthAvg), or at other temporal resolutions as specified in the settings file. **Q: Can I get spatially aggregated outputs?** ----------------------------------------------- A: Yes, outputs can be written as text files for specific points, aggregated to basins, or as maps showing the value for each cell. Documentation and Support ========================= **Q: Where can I find the model documentation?** ------------------------------------------------- A: The complete user manual and model documentation is available at https://cwatm.iiasa.ac.at, which includes tutorials, setup instructions, error handling guides, and example applications. **Q: Where can I get help with CWatM?** ---------------------------------------- A: You can start a discussion on the GitHub forum and check out CWatM tutorials on YouTube. The website also includes a forum section for community support. **Q: Are there tutorials available?** -------------------------------------- A: Yes, CWatM tutorials are available on YouTube, and the documentation website includes detailed tutorial sections. **Q: What should I do if I encounter errors?** ----------------------------------------------- A: CWatM captures a number of possible wrong inputs and provides error numbers. Check the Error handling section of the documentation for specific error codes and solutions. Future Development ================== **Q: What future developments are planned for CWatM?** ------------------------------------------------------- A: The vision for the short to medium term includes introducing a water quality component (e.g., salinization in deltas and eutrophication associated with mega cities) and considering how to include qualitative and quantitative measures of transboundary river and groundwater governance. **Q: How does CWatM contribute to nexus analysis?** ---------------------------------------------------- A: The modular structure makes linking CWatM with other IIASA models possible to develop an integrated assessment modeling framework for nexus issues (water-food-energy) or hydro-economic modeling for quantifying water infrastructure investment options. **Q: Will CWatM include water quality modeling?** -------------------------------------------------- A: Yes, future development includes adding water quality components such as salinization in deltas and eutrophication associated with mega cities. Settings and Configuration ========================== **Q: What is a settings file?** -------------------------------- A: The model needs a settings file as an argument. This .ini file contains all configuration parameters including paths, time periods, calibration parameters, and output specifications. **Q: Can I use Excel for settings?** ------------------------------------- A: Yes, cwatm4r provides a convenient way to define all model parameters using a settings.xlsx spreadsheet, which can be converted to the required .ini file format. **Q: How do I set the simulation period?** ------------------------------------------- A: In the settings file, specify StepStart (start date), SpinUp (warm-up period), and StepEnd (end date) in the TIME-RELATED_CONSTANTS section. **Q: Can I save and load model states?** ----------------------------------------- A: Yes, you can save initial conditions (save_initial = True) and load them for warm starts (load_initial = True) using netCDF files. Performance and Requirements ============================ **Q: How computationally intensive is CWatM?** ----------------------------------------------- A: For computationally demanding parts like routing, CWatM uses C++ libraries for speed. The model includes pre-compiled versions for Windows and Linux. **Q: Can CWatM run in parallel?** ---------------------------------- A: Yes, the calibration tool supports multiprocessing (use_multiprocessing parameter) for running multiple simulations in parallel. **Q: What is the typical runtime?** ------------------------------------ A: Runtime depends on: * Spatial resolution * Temporal extent * Domain size * Number of processes simulated * Hardware specifications Higher resolution and longer periods increase computational time. Comparison with Other Models ============================ **Q: How does CWatM compare to other hydrological models?** ------------------------------------------------------------ A: CWatM is used in the framework of the Inter-Sectoral Impact Model Intercomparison Project (ISIMIP), which compares global model outputs. Studies have compared CWatM (as a Large-scale Hydrologic Model) with watershed models like VIC, showing similar performance for water balance variables. **Q: What makes CWatM unique?** -------------------------------- A: Key features include: * Open source with modular structure * Integration capability with economic models * Global to local scale applicability * Human water use representation * Water-energy-food nexus focus * FAIR data principles implementation License and Access ================== **Q: What license is CWatM released under?** --------------------------------------------- A: The source code of CWatM is freely available under the GNU General Public License. **Q: Where can I download CWatM?** ----------------------------------- A: CWatM is available from: * GitHub repository: https://github.com/iiasa/CWatM * Documentation: https://cwatm.iiasa.ac.at/ * Input data: https://github.com/iiasa/CWatM-Earth-30min **Q: Is there a cost to use CWatM?** ------------------------------------- A: No, CWatM is free and open source. The source code is free, but support is limited due to limited person power. Additional Resources ==================== **Q: Where can I find example applications?** ---------------------------------------------- A: The documentation includes example applications such as the Zambezi basin case study. Various studies have used CWatM for basins like the Aga-Foua-Djilas basin and the Liard River basin. **Q: Are there scientific publications about CWatM?** ------------------------------------------------------ A: Yes, the main reference is: Burek P., et al. (2020). "Development of the Community Water Model (CWatM v1.04) – a high-resolution hydrological model for global and regional assessment of integrated water resources management". Geoscientific Model Development 13(7): 3267-3298. **Q: Can CWatM be used for educational purposes?** --------------------------------------------------- A: Yes, CWatM is suitable for education and research. Tutorials, documentation, and the open-source nature make it accessible for learning hydrological modeling. .. note:: This FAQ is based on CWatM version 1.06 (October 2024). Features and specifications may change in newer versions. Always refer to the official documentation for the most current information. .. seealso:: - Official Website: https://cwatm.iiasa.ac.at/ - GitHub Repository: https://github.com/iiasa/CWatM - IIASA Water Security: https://iiasa.ac.at/models-tools-data/cwatm - YouTube Tutorials: Search for "CWatM tutorials" .. warning:: While CWatM is free to use, technical support is limited due to resource constraints. Users are encouraged to use the GitHub forum for community support.