management_modules package

Data management

data_handling module

Managing data and data handling

cwatm.management_modules.data_handling.addtoversiondate(filename, history='')

Generate version and timestamp information for output files.

Creates standardized version metadata that includes git information, build timestamp, and model version. This information is embedded in output NetCDF files to ensure full traceability and reproducibility of model results.

Parameters

• filename (str) – Name of the file being created (used in history string).

• history (str, optional) – Additional history information to include. Default is empty string.

Returns

Formatted history string containing version, timestamp, and git info.

Return type

str

Notes

The version string includes: - CWatM version number - Git commit hash and branch information - Whether the build has uncommitted changes (“dirty” vs “verified”) - Build timestamp - User-provided history information

This ensures complete provenance tracking for all model outputs.

cwatm.management_modules.data_handling.cbinding(inBinding)

Process configuration binding with validation and type conversion.

Core function for processing configuration bindings, performing type conversion, validation, and error handling. Ensures that configuration values are properly formatted and valid for use throughout the model.

Parameters

inBinding (str) – Configuration binding key to process.

Returns

Processed configuration value with appropriate type conversion.

Return type

varies

Notes

• Central function for configuration value processing

• Handles type conversion and validation

• Provides consistent error handling and reporting

• Used extensively throughout CWatM configuration pipeline

cwatm.management_modules.data_handling.checkMeteo_Wordclim(meteodata, wordclimdata)

Validate consistency between meteorological and WorldClim climatology data.

Performs quality control checks to ensure that meteorological forcing data is reasonable compared to long-term climatological averages from WorldClim. This helps detect data quality issues and potential errors in meteorological inputs.

Parameters

• meteodata (numpy.ndarray) – Current meteorological data values.

• wordclimdata (numpy.ndarray) – WorldClim climatological reference values.

Returns

Validation results indicating data quality status.

Return type

bool or numpy.ndarray

Notes

• Compares current values against climatological norms

• Helps identify unrealistic meteorological data

• Supports quality assurance in operational modeling

• Can flag potential data processing errors

cwatm.management_modules.data_handling.checkOption(inBinding, checkfirst=False)

Validate and process configuration option values.

Performs validation and type checking for configuration options, ensuring that values are appropriate for their intended use. Provides error handling and default value assignment for configuration processing.

Parameters

• inBinding (str) – Configuration binding key to check and process.

• checkfirst (bool, optional) – If True, perform preliminary validation checks. Default is False.

Returns

Processed and validated configuration value.

Return type

varies

Notes

• Validates configuration option values and types

• Provides error handling for invalid configurations

• Supports default value assignment

• Used throughout configuration processing pipeline

cwatm.management_modules.data_handling.compressArray(map, name='None', zeros=0.0)

Compress 2D array to 1D format by removing inactive cells.

Core data compression function that converts full 2D spatial arrays to the efficient 1D compressed format used throughout CWatM. This compression removes NoData cells and cells outside the model domain, significantly reducing memory usage and computational overhead.

Parameters

• map (numpy.ndarray) – 2D spatial array to be compressed.

• name (str, optional) – Variable name for error reporting. Default is “None”.

• zeros (float, optional) – Value to use for replacing zero values. Default is 0.0.

Returns

1D compressed array containing only active model cells.

Return type

numpy.ndarray

Notes

• Uses global maskinfo for determining active cells

• Preserves spatial relationships through index mapping

• Essential for CWatM’s memory-efficient spatial operations

• All hydrological calculations use this compressed format

• Zero replacement helps avoid numerical issues in computations

cwatm.management_modules.data_handling.decompress(map)

Expand compressed 1D array back to full 2D spatial format.

Inverse operation of compressArray, converting CWatM’s internal 1D compressed format back to full 2D spatial arrays for output, visualization, or interface with external tools. Inactive cells are filled with NoData values.

Parameters

map (numpy.ndarray) – 1D compressed array from CWatM internal processing.

Returns

2D spatial array with full model domain dimensions.

Return type

numpy.ndarray

Notes

• Uses global maskinfo and maskmapAttr for spatial reconstruction

• Inactive cells filled with -9999 (NoData value)

• Preserves spatial relationships and coordinate system

• Required for creating output files and maps

• Inverse operation of compressArray function

cwatm.management_modules.data_handling.divideValues(x, y, default=0.0)

Perform safe division with handling of zero denominators.

Utility function for array division operations that handles division by zero cases gracefully. Provides default values when division is undefined, preventing numerical errors in hydrological calculations.

Parameters

• x (numpy.ndarray) – Numerator array.

• y (numpy.ndarray) – Denominator array.

• default (float, optional) – Default value to use when denominator is zero. Default is 0.0.

Returns

Result of safe division operation.

Return type

numpy.ndarray

Notes

• Prevents division by zero errors in hydrological calculations

• Provides consistent handling of undefined mathematical operations

• Used throughout CWatM for ratio and rate calculations

• Maintains numerical stability in model computations

cwatm.management_modules.data_handling.getmeta(key, varname, alternative)

Retrieve metadata attributes for NetCDF variable creation.

Looks up variable metadata from the global metaNetcdfVar dictionary to ensure proper CF-compliant attributes in output NetCDF files. Provides fallback values when specific metadata is not available.

Parameters

• key (str) – Metadata attribute key (e.g., ‘unit’, ‘long_name’, ‘standard_name’).

• varname (str) – Variable name to look up in metadata dictionary.

• alternative (str) – Default value to use if metadata not found for the variable.

Returns

Metadata value for the specified key and variable.

Return type

str

Notes

• Searches global metaNetcdfVar dictionary populated from XML metadata

• Ensures consistent metadata across all model outputs

• Supports CF convention compliance for scientific data exchange

• Falls back to sensible defaults when specific metadata unavailable

cwatm.management_modules.data_handling.loadmap(name, lddflag=False, compress=True, local=False, cut=True)

Load spatial data from various file formats into CWatM arrays.

Universal data loading function that handles NetCDF, GeoTIFF, and other raster formats. Performs coordinate checking, data validation, format conversion, and optional compression. This is the primary interface for loading static spatial data (parameters, initial conditions) in CWatM.

Parameters

• name (str) – Configuration binding key or file path for the data to load.

• lddflag (bool, optional) – If True, treat as Local Drain Direction data with special handling. Default is False.

• compress (bool, optional) – If True, return data in compressed 1D format. If False, return 2D array. Default is True.

• local (bool, optional) – If True, load data relative to local directory. Default is False.

• cut (bool, optional) – If True, clip data to model domain. Default is True.

Returns

Loaded spatial data, either as 2D array or compressed 1D format.

Return type

numpy.ndarray

Raises

• CWATMFileError – If file cannot be found or read.

• CWATMError – If spatial dimensions don’t match the model domain. If coordinate systems are incompatible.

Notes

• Automatically detects file format (NetCDF vs GeoTIFF)

• Performs spatial consistency checks against clone map

• Handles coordinate system transformations

• Supports both static parameters and time-varying data

• LDD flag enables special processing for flow direction data

cwatm.management_modules.data_handling.loadsetclone(self, name)

Load and set the clone map that defines the model domain.

The clone map is the fundamental spatial reference for CWatM, defining the model grid, coordinate system, and computational domain. This function loads the clone map from various formats (NetCDF, GeoTIFF), extracts spatial attributes, and sets up the global spatial reference system used throughout the model.

Parameters

name (str) – Path to the clone map file. Can be NetCDF or GeoTIFF format. The binding key for the clone map in the configuration.

Returns

Sets up global spatial reference and mask attributes.

Return type

None

Notes

The clone map determines: - Model grid dimensions and spatial resolution - Coordinate reference system and geotransformation - Active model domain (non-NoData cells) - Spatial attributes for all subsequent data loading

This function must be called before any other spatial data operations. It populates the global maskmapAttr dictionary and sets the model’s spatial framework.

cwatm.management_modules.data_handling.mapattrNetCDF(name, check=True)

Extract complete spatial attributes from NetCDF files.

Comprehensive function for reading all spatial metadata from NetCDF files including dimensions, coordinates, projection, and extent. Provides complete spatial reference information needed for data alignment and processing.

Parameters

• name (str) – Path to NetCDF file or configuration binding key.

• check (bool, optional) – If True, validate spatial consistency with model domain. Default is True.

Returns

Complete spatial attribute dictionary with coordinate information, dimensions, and transformation parameters.

Return type

dict

Notes

• Handles both meteorological and static NetCDF files

• Extracts coordinate reference system information

• Validates spatial consistency when check=True

• Used for proper data alignment and processing

cwatm.management_modules.data_handling.mapattrNetCDFMeteo(name, check=True)

Extract spatial attributes specifically for meteorological NetCDF files.

Specialized version of mapattrNetCDF optimized for meteorological data files, which often have specific conventions and temporal dimensions. Handles time-series data with proper temporal coordinate processing.

Parameters

• name (str) – Path to meteorological NetCDF file or configuration binding key.

• check (bool, optional) – If True, validate spatial and temporal consistency. Default is True.

Returns

Spatial and temporal attribute dictionary for meteorological data.

Return type

dict

Notes

• Optimized for time-series meteorological data

• Handles temporal dimension metadata

• Supports various meteorological data conventions

• Essential for proper forcing data integration

cwatm.management_modules.data_handling.mapattrTiff(nf2)

Extract spatial attributes from GeoTIFF files using GDAL.

Reads complete spatial reference information from GeoTIFF files including geotransform, projection, dimensions, and extent. Provides unified spatial metadata extraction for raster data.

Parameters

nf2 (gdal.Dataset) – Opened GDAL dataset object for the GeoTIFF file.

Returns

Spatial attribute dictionary containing coordinate reference information, dimensions, and transformation parameters.

Return type

dict

Notes

• Extracts geotransform coefficients

• Reads projection and coordinate system information

• Handles various GeoTIFF conventions and formats

• Provides foundation for raster data integration

cwatm.management_modules.data_handling.maskfrompoint(mask2D, xleft, yup)

Convert 2D mask array to compressed 1D format for CWatM processing.

Transforms a full 2D boolean mask to the compressed 1D format used internally by CWatM. This compression removes NoData cells and creates efficient storage for hydrological computations, significantly reducing memory usage and computation time for sparse domains.

Parameters

• mask2D (numpy.ndarray) – 2D boolean array where True indicates active model cells.

• xleft (float) – X-coordinate of the left edge of the domain.

• yup (float) – Y-coordinate of the upper edge of the domain.

Returns

1D compressed mask array containing only active cells.

Return type

numpy.ndarray

Notes

• Uses global spatial reference attributes from maskmapAttr

• Creates mapping between 2D grid positions and 1D compressed indices

• Essential for CWatM’s efficient spatial data handling

• All subsequent spatial operations use this compressed format

cwatm.management_modules.data_handling.metaNetCDF()

Generate standard NetCDF metadata attributes for CWatM outputs.

Creates a dictionary of global attributes that provide essential information about the model run, including version, contact information, and data description. These attributes ensure proper documentation and traceability of CWatM output files.

Returns

Dictionary of NetCDF global attributes including title, institution, source, history, and contact information.

Return type

dict

Notes

Standard attributes include: - title: Descriptive name for the dataset - institution: Organization responsible for the data - source: Model version and configuration information - history: Processing history and timestamps - contact: Maintainer contact information

These attributes follow CF conventions and support data discovery and provenance tracking in scientific workflows.

cwatm.management_modules.data_handling.multinetdf(meteomaps, usebuffer, startcheck='dateBegin')

Set up multiple NetCDF meteorological files for efficient reading.

Initializes data structures and index mappings for reading from multiple meteorological NetCDF files. Optimizes data access patterns and supports buffering strategies for improved I/O performance during long model runs.

Parameters

• meteomaps (list) – List of meteorological variable names to process.

• usebuffer (bool) – If True, enable data buffering for improved performance.

• startcheck (str, optional) – Date key to use for temporal validation. Default is ‘dateBegin’.

Returns

Sets up global data structures for efficient meteorological data access.

Return type

None

Notes

• Optimizes I/O patterns for multiple meteorological files

• Sets up buffering strategies based on available memory

• Handles temporal indexing across file boundaries

• Critical for efficient forcing data processing

cwatm.management_modules.data_handling.readCalendar(name)

Extract calendar information from NetCDF time dimensions.

Reads time coordinate metadata to determine the calendar system used in NetCDF files. This is essential for proper temporal alignment and date calculations in CWatM.

Parameters

name (str) – Path to NetCDF file or configuration binding key.

Returns

Calendar type (‘standard’, ‘gregorian’, ‘365_day’, etc.).

Return type

str

Notes

• Supports CF-compliant calendar conventions

• Defaults to ‘standard’ calendar if not specified

• Critical for accurate temporal data processing

• Used by date conversion and time indexing functions

cwatm.management_modules.data_handling.readCoord(name)

Read coordinate information from various raster file formats.

Extracts spatial reference information including extent, resolution, and coordinate system from raster files. Supports multiple formats and provides unified coordinate information for spatial data alignment.

Parameters

name (str) – Path to the raster file or configuration binding key.

Returns

Coordinate information (extent, resolution, projection details).

Return type

tuple

Notes

• Supports GeoTIFF, NetCDF, and other GDAL-supported formats

• Extracts geotransform and projection information

• Used for spatial consistency checking and data alignment

• Provides foundation for coordinate transformations

cwatm.management_modules.data_handling.readCoordNetCDF(name, check=True)

Read coordinate system information from NetCDF files.

Specialized function for extracting spatial reference information from NetCDF files, including dimension sizes, coordinate variables, and geospatial metadata. Handles both CF-compliant and legacy NetCDF spatial conventions.

Parameters

• name (str) – Path to NetCDF file or configuration binding key.

• check (bool, optional) – If True, perform spatial consistency checks. Default is True.

Returns

Spatial reference information including dimensions, coordinates, and transformation parameters.

Return type

tuple

Notes

• Handles various NetCDF coordinate conventions

• Supports both regular and irregular grids

• Performs coordinate system validation when check=True

• Essential for proper NetCDF data integration

cwatm.management_modules.data_handling.readmeteodata(name, date, value='None', addZeros=False, zeros=0.0, mapsscale=True, buffering=False, extendback=False)

Read meteorological forcing data for specific time steps.

Primary function for loading time-varying meteorological data during model execution. Handles temporal indexing, data extraction, scaling, and format conversion for various meteorological variables. Supports efficient buffering and caching strategies for improved performance.

Parameters

• name (str) – Variable name or configuration binding key for meteorological data.

• date (datetime-like) – Target date for data extraction.

• value (str, optional) – NetCDF variable name if different from binding key. Default is ‘None’.

• addZeros (bool, optional) – If True, replace missing values with zeros value. Default is False.

• zeros (float, optional) – Value to use when addZeros=True. Default is 0.0.

• mapsscale (bool, optional) – If True, apply scaling factors and offsets. Default is True.

• buffering (bool, optional) – If True, use buffered reading for performance. Default is False.

• extendback (bool, optional) – If True, extend data backward in time if needed. Default is False.

Returns

Meteorological data array for the specified date, in compressed 1D format or 2D depending on configuration.

Return type

numpy.ndarray

Notes

• Handles various temporal conventions and calendars

• Supports data scaling and unit conversions

• Implements efficient caching and buffering

• Critical for model forcing data integration

• Manages memory usage during long simulations

cwatm.management_modules.data_handling.readnetcdf12month(name, month, value='None')

Read monthly climatological data from 12-month NetCDF files.

Specialized reader for climatological data organized as 12-month time series. Commonly used for seasonal parameters, climatologies, and cyclic forcing data that varies by month but not by year.

Parameters

• name (str) – Configuration binding key or file path.

• month (int) – Month number (1-12) for data extraction.

• value (str, optional) – NetCDF variable name. Default is “None”.

Returns

Monthly climatological data in compressed format.

Return type

numpy.ndarray

Notes

• Handles seasonal and climatological data

• Assumes 12-month temporal dimension

• Used for cyclic parameters and seasonal forcing

• Supports monthly varying model parameters

cwatm.management_modules.data_handling.readnetcdf2(namebinding, date, useDaily='daily', value='None', addZeros=False, cut=True, zeros=0.0, meteo=False, usefilename=False, compress=True)

Generic NetCDF data reader with flexible temporal and spatial options.

Versatile function for reading NetCDF data with various temporal aggregation options, spatial clipping, and format conversions. Supports both meteorological and static data with comprehensive error handling and data validation.

Parameters

• namebinding (str) – Configuration binding key or file path.

• date (datetime-like) – Target date for temporal data extraction.

• useDaily (str, optional) – Temporal aggregation method (‘daily’, ‘monthly’, etc.). Default is ‘daily’.

• value (str, optional) – NetCDF variable name. Default is ‘None’.

• addZeros (bool, optional) – Replace missing values with zeros value. Default is False.

• cut (bool, optional) – Clip data to model domain. Default is True.

• zeros (float, optional) – Replacement value for missing data. Default is 0.0.

• meteo (bool, optional) – True if reading meteorological data. Default is False.

• usefilename (bool, optional) – Use filename as variable name. Default is False.

• compress (bool, optional) – Return compressed 1D format. Default is True.

Returns

Extracted data in requested format (1D compressed or 2D).

Return type

numpy.ndarray

Notes

• Supports multiple temporal aggregation methods

• Handles various NetCDF conventions and structures

• Provides comprehensive error handling and validation

• Used throughout CWatM for diverse data loading needs

cwatm.management_modules.data_handling.readnetcdfInitial(name, value, default=0.0)

Read initial condition data with fallback defaults.

Specialized function for loading initial conditions and state variables at model startup. Provides fallback to default values when initial condition files are not available, enabling model cold starts.

Parameters

• name (str) – Configuration binding key for initial condition file.

• value (str) – Variable name within the NetCDF file.

• default (float, optional) – Default value to use if file not found. Default is 0.0.

Returns

Initial condition data or default values in compressed format.

Return type

numpy.ndarray

Notes

• Essential for model initialization and warm starts

• Provides graceful handling of missing initial condition files

• Supports both warm starts (from files) and cold starts (defaults)

• Used for hydrological state variables and storage initialization

cwatm.management_modules.data_handling.readnetcdfWithoutTime(name, value='None', counter=0)

Read static (time-independent) data from NetCDF files.

Specialized function for loading static spatial data that does not have a temporal dimension. Used for parameters, initial conditions, and other time-invariant model inputs.

Parameters

• name (str) – Configuration binding key or file path.

• value (str, optional) – NetCDF variable name. Default is “None”.

• counter (int, optional) – Array index for multi-layer data. Default is 0.

Returns

Static spatial data in compressed format.

Return type

numpy.ndarray

Notes

• Optimized for static data without temporal dimensions

• Handles multi-layer datasets with counter parameter

• Performs spatial consistency checking

• Used for loading parameters and initial conditions

cwatm.management_modules.data_handling.report(valueIn, name, compr=True)

Generate standardized output reports for model variables.

Universal reporting function that handles output formatting, spatial decompression, and file writing for various CWatM outputs. Supports multiple output formats and handles the conversion between internal compressed format and standard output formats.

Parameters

• valueIn (numpy.ndarray) – Input data to report (typically 1D compressed format).

• name (str) – Variable name for output identification.

• compr (bool, optional) – If True, input data is in compressed format. Default is True.

Returns

Generates output files according to configuration settings.

Return type

None

Notes

• Handles various output formats (NetCDF, GeoTIFF, text)

• Manages spatial decompression and coordinate information

• Supports temporal aggregation and statistical reporting

• Central function for all model output generation

cwatm.management_modules.data_handling.returnBool(inBinding)

Convert configuration strings to boolean values.

Utility function for parsing boolean configuration options from the settings file. Handles various string representations of boolean values and provides consistent boolean interpretation throughout CWatM.

Parameters

inBinding (str) – Configuration value string to convert to boolean.

Returns

Boolean interpretation of the input string.

Return type

bool

Notes

• Handles common boolean string representations

• Provides consistent boolean parsing across CWatM

• Used for processing configuration file options

• Supports case-insensitive boolean interpretation

cwatm.management_modules.data_handling.setmaskmapAttr(x, y, col, row, cell)

Set global spatial reference attributes for the model domain.

Defines the spatial reference system parameters that are used throughout CWatM for coordinate transformations, data alignment, and spatial operations. These attributes are stored in the global maskmapAttr dictionary and used by all spatial data processing functions.

Parameters

• x (float) – X-coordinate of the upper-left corner of the model domain. Typically longitude in decimal degrees or projected coordinate.

• y (float) – Y-coordinate of the upper-left corner of the model domain. Typically latitude in decimal degrees or projected coordinate.

• col (int) – Number of columns in the raster grid.

• row (int) – Number of rows in the raster grid.

• cell (float) – Cell size (spatial resolution) in the same units as x,y coordinates.

Returns

Results stored in global maskmapAttr dictionary.

Return type

None

Notes

The function performs precision adjustments to handle floating-point arithmetic issues in coordinate calculations: - Calculates inverse cell size for efficient coordinate transformations - Rounds coordinates to appropriate precision based on magnitude - Handles edge cases where getgeotransform provides limited precision

Global variables modified: - maskmapAttr: Dictionary with keys ‘x’, ‘y’, ‘col’, ‘row’, ‘cell’, ‘invcell’

This spatial reference is used by functions like valuecell(), loadmap(), and coordinate transformation routines throughout the model.

cwatm.management_modules.data_handling.valuecell(coordx, coordstr, returnmap=True)

Convert geographic coordinates to raster cell values for gauge placement.

This function creates a raster map with numbered cells corresponding to gauge locations specified by coordinates. It performs coordinate validation, converts geographic coordinates to raster row/column indices, and creates a compressed array suitable for CWatM processing. Essential for linking point observations to the model grid.

Parameters

• coordx (list) – List of coordinate values in alternating x,y or lon/lat format. Even indices are x-coordinates, odd indices are y-coordinates.

• coordstr (str) – String representation of coordinates for error reporting.

• returnmap (bool, optional) – If True, return compressed 1D array. If False, return column/row indices. Default is True.

Returns

If returnmap=True: 1D compressed array with gauge numbers (1-based indexing). If returnmap=False: tuple of (column_indices, row_indices) lists.

Return type

numpy.ndarray or tuple

Raises

CWATMError – If coordinate strings cannot be converted to float values. If any coordinate falls outside the model domain (mask map bounds).

Notes

• Uses maskmapAttr global dictionary for spatial reference information

• Coordinates outside domain trigger detailed error message with boundary box

• Background cells are set to -9999 (NoData value)

• Gauge cells are numbered sequentially starting from 1

• Coordinate transformation uses inverse cell size for efficiency

cwatm.management_modules.data_handling.writeIniNetcdf(netfile, varlist, inputlist)

Write initial condition NetCDF files for model restart.

Creates NetCDF files containing model state variables for warm start and restart capabilities. Saves hydrological state information that can be used to initialize subsequent model runs, enabling operational workflows and long-term simulations.

Parameters

• netfile (str) – Output NetCDF file path for initial conditions.

• varlist (list) – List of variable names to include in the file.

• inputlist (list) – List of corresponding data arrays (1D compressed format).

Returns

Creates NetCDF initial condition file with state variables.

Return type

None

Notes

• Essential for model restart and warm start capabilities

• Saves complete hydrological state information

• Enables operational modeling and long simulations

• Includes spatial decompression and proper metadata

cwatm.management_modules.data_handling.writenetcdf(netfile, prename, addname, varunits, inputmap, timeStamp, posCnt, flag, flagTime, nrdays=None, dateunit='days', netcdfindex=False)

Write CWatM results to NetCDF output files with proper metadata.

Primary output function for writing model results to CF-compliant NetCDF files. Handles spatial decompression, temporal indexing, metadata attribution, and file management for various output types including maps, time series, and aggregated results.

Parameters

• netfile (str) – Output NetCDF file path.

• prename (str) – Variable name prefix for organization.

• addname (str) – Additional name component for the variable.

• varunits (str) – Physical units for the variable.

• inputmap (numpy.ndarray) – Data array to write (1D compressed format).

• timeStamp (datetime-like) – Timestamp for the data.

• posCnt (int) – Position counter for time indexing.

• flag (str) – Output type flag (‘end’, ‘sum’, ‘avg’, etc.).

• flagTime (str) – Temporal aggregation flag (‘daily’, ‘monthly’, etc.).

• nrdays (int, optional) – Number of days for averaging calculations. Default is None.

• dateunit (str, optional) – Time unit specification. Default is “days”.

• netcdfindex (bool, optional) – Use NetCDF indexing format. Default is False.

Returns

Writes data to NetCDF file with proper formatting and metadata.

Return type

None

Notes

• Creates CF-compliant NetCDF files with full metadata

• Handles spatial decompression from 1D to 2D format

• Supports various temporal aggregation methods

• Includes version tracking and provenance information

• Essential for model output and result distribution

timestep module

Managing time

cwatm.management_modules.timestep.Calendar(input, errorNo=0)

Parse and validate date strings from configuration settings.

Robust date parser that handles multiple date formats commonly used in configuration files. Converts various date representations to datetime objects while providing specific error messages for different contexts (start dates, initialization dates, etc.).

Parameters

• input (str or float) – Date string or numeric value from settings file. Supports formats: dd/mm/yyyy, dd-mm-yyyy, dd.mm.yyyy, or numeric.

• errorNo (int, optional) – Error context identifier: - 0: Start/end date validation (default) - 1: Initialization date validation - >1: Returns -99999 for invalid dates instead of raising error

Returns

• datetime.datetime: Successfully parsed date

• float: Numeric input passed through unchanged

• int: Special return value (-99999) for invalid dates when errorNo > 1

Return type

datetime.datetime or float or int

Raises

CWATMError – If date parsing fails and errorNo <= 1, with context-specific messages.

Notes

Date format handling: - Automatically detects 2-digit vs 4-digit years - Handles various separators (/, -, .) - Supports both European (dd/mm/yyyy) and numeric formats - Provides flexibility for international date conventions

Used throughout the temporal configuration system for parsing start dates, end dates, and initialization timestamps.

cwatm.management_modules.timestep.addmonths(d, x)

Add months to a date with proper handling of month boundaries.

Performs date arithmetic that correctly handles month addition across year boundaries and varying month lengths. Ensures that invalid dates (e.g., February 30) are adjusted to valid dates by using the last valid day of the target month.

Parameters

• d (datetime.datetime) – Starting date for the addition operation.

• x (int) – Number of months to add (can be negative for subtraction).

Returns

New date with the specified number of months added.

Return type

datetime.datetime

Notes

Month addition algorithm: - Calculates target month and year accounting for wraparound - Handles leap years and varying month lengths correctly - Adjusts day to last valid day if original day exceeds month length

For example: - January 31 + 1 month = February 28 (or 29 in leap years) - December 15 + 2 months = February 15 - May 31 + 1 month = June 30

Used in initialization date calculations and temporal sequence generation for save state operations and periodic output scheduling.

cwatm.management_modules.timestep.checkifDate(start, end, spinup, name)

Validate temporal configuration and initialize date variables.

Comprehensive validation of simulation temporal bounds, including start/end dates, spinup period, and calendar system setup. Extracts calendar information from meteorological data files and performs extensive date consistency checks. Critical for proper temporal framework initialization.

Parameters

• start (str) – Configuration key for simulation start date.

• end (str) – Configuration key for simulation end date.

• spinup (str) – Configuration key for spinup end date (when outputs begin).

• name (str) – Path to meteorological file for calendar system extraction.

Returns

Populates global dateVar dictionary with temporal parameters.

Return type

None

Raises

• CWATMFileError – If meteorological file cannot be found or accessed.

• CWATMError – If date validation fails or temporal bounds are inconsistent.

Notes

The function performs: 1. NetCDF calendar and units extraction from meteorological data 2. Unit conversion factor calculation (daily, hourly, etc.) 3. Date parsing and validation for start, end, and spinup dates 4. Temporal consistency checks (start < spinup <= end) 5. Calendar-specific day counting and period calculations

Global dateVar dictionary populated with: - Date objects: dateBegin, dateStart, dateEnd - Integer offsets: intStart, intEnd, intSpin - Calendar info: calendar, unit, unitConv - Temporal markers: checked list for month/year boundaries - Period counts: diffdays, diffMonth, diffYear

Essential for all subsequent temporal operations in CWatM.

cwatm.management_modules.timestep.ctbinding(inBinding)

Check and retrieve configuration binding with error handling.

Validates that a configuration parameter exists in the settings file and retrieves its value. Provides helpful error messages with closest matches when parameters are not found, assisting with debugging configuration issues.

Parameters

inBinding (str) – Configuration parameter name to look up in the binding dictionary.

Returns

Value of the configuration parameter from the binding dictionary.

Return type

str

Raises

CWATMError – If the parameter is not found in the binding dictionary. Error message includes closest matching parameter names for debugging.

Notes

• Used specifically for time-related configuration parameters

• Provides fuzzy matching suggestions using difflib for typo detection

• Part of the configuration validation system

• Essential for robust parameter handling in temporal calculations

The function helps ensure that all required time-related parameters are properly configured before model execution begins.

cwatm.management_modules.timestep.date2indexNew(date, nctime, calendar, select='nearest', name='')

Enhanced date-to-index conversion for NetCDF files with extended time unit support.

Extends the standard NetCDF4 date2index functionality to handle monthly and yearly time units that are not supported by the original implementation. Critical for accessing climatological data with non-daily temporal resolution commonly used in hydrological modeling.

Parameters

• date (datetime.datetime) – Target date to find in the NetCDF time dimension.

• nctime (netCDF4.Variable) – NetCDF time variable containing units and values.

• calendar (str) – Calendar system used in the NetCDF file.

• select (str, optional) – Selection method for nearest date matching. Default is ‘nearest’.

• name (str, optional) – Dataset name for enhanced error reporting. Default is empty string.

Returns

Array index corresponding to the specified date in the NetCDF time dimension.

Return type

int

Notes

Supported time units: - DAYS: Standard daily resolution (uses original netCDF4.date2index) - MONTHS: Monthly resolution with year-month indexing - YEARS: Annual resolution with year indexing

For monthly/yearly data, the function: - Calculates temporal offset from reference date in units - Handles cases where requested date exceeds available data range - Issues warnings when using boundary data for out-of-range requests - Performs array lookup to find matching time indices

Essential for accessing diverse climatological datasets with varying temporal resolutions in hydrological modeling applications.

cwatm.management_modules.timestep.date2str(date)

Convert datetime object to standardized date string format.

Converts a datetime object to a consistent string representation used throughout CWatM for output formatting, logging, and user display. The format is day/month/year with zero padding.

Parameters

date (datetime.datetime) – Date to convert to string representation.

Returns

Date string in format “dd/mm/yyyy” (e.g., “27/12/2018”).

Return type

str

Notes

• Uses zero-padding for single-digit days and months

• Provides consistent date formatting across all CWatM outputs

• Handles dates before 1900 that cause issues with strftime()

• Used in progress reporting, output headers, and user interfaces

cwatm.management_modules.timestep.datenum(date)

Convert date to integer number based on NetCDF calendar and units.

Converts a datetime object to an integer representation based on the calendar system and time units defined in the NetCDF meteorological data files. This enables consistent temporal indexing across different calendar systems (standard, 360-day, noleap) used in climate data.

Parameters

date (datetime.datetime) – Date to convert to numeric representation.

Returns

Integer representation of the date in NetCDF time units. Adjusted for the unit conversion factor (daily, hourly, etc.).

Return type

int

Notes

Uses global dateVar dictionary containing: - unit: NetCDF time units (e.g., “days since 1901-01-01”) - calendar: Calendar system (‘standard’, ‘360_day’, ‘noleap’, etc.) - unitConv: Conversion factor for different time resolutions

The function applies rounding to handle NetCDF files that use 12:00 as the starting time, which results in half-day offsets.

cwatm.management_modules.timestep.datetoInt(dateIn, begin, both=False)

Convert date to integer offset from reference date.

Calculates the integer number of days between a given date and a reference date, handling various calendar systems. This is fundamental for CWatM’s internal time indexing system, enabling consistent temporal calculations across different calendar types.

Parameters

• dateIn (str or float) – Input date string or numeric value to convert.

• begin (datetime.datetime) – Reference date for calculating the offset.

• both (bool, optional) – If True, returns both integer offset and string representation. Default is False (returns only integer).

Returns

If both=False: Integer day offset from reference date (1-based). If both=True: Tuple of (integer_offset, date_string).

Return type

int or tuple

Notes

The function handles two input types: 1. Date strings: Parsed using Calendar() and converted to day offsets 2. Numeric values: Used directly as integer offsets

The offset is 1-based, meaning the reference date itself returns 1. This aligns with CWatM’s internal timestep numbering system.

Critical for: - Converting configuration dates to internal timesteps - Temporal indexing in meteorological data - Simulation period calculations

cwatm.management_modules.timestep.datetosaveInit(initdates, begin, end)

Calculate and validate initialization save dates for model state output.

Processes a list of dates or date patterns to determine when the model should save its internal state for initialization purposes. Supports both explicit dates and periodic patterns (yearly, monthly, daily). This is critical for model restarts and warm start capabilities.

Parameters

• initdates (list) – List of date specifications that can include: - Explicit date strings - Numeric offsets - Periodic patterns (e.g., “2y”, “6m”, “30d”)

• begin (datetime.datetime) – Reference start date for the simulation period.

• end (datetime.datetime) – End date limiting the save date generation.

Returns

Populates global dateVar[‘intInit’] list with integer timesteps.

Return type

None

Raises

CWATMError – If date patterns are malformed or numeric values are invalid.

Notes

Periodic pattern formats: - “Ny”: Every N years (e.g., “2y” = every 2 years) - “Nm”: Every N months (e.g., “6m” = every 6 months) - “Nd”: Every N days (e.g., “30d” = every 30 days)

The function generates sequences of save dates starting from the first specified date and continuing until the simulation end date. This enables flexible state saving strategies for long simulations.

Global variables modified: - dateVar[‘intInit’]: List of integer timesteps for state saving

cwatm.management_modules.timestep.numdate(num, add=0)

Convert integer to date based on NetCDF calendar and units.

Converts an integer representation back to a datetime object using the calendar system and time units from NetCDF meteorological files. This is the inverse operation of datenum() and maintains temporal consistency across different calendar systems.

Parameters

• num (int or float) – Numeric representation of the date in NetCDF time units.

• add (int, optional) – Additional days to add to the resulting date. Default is 0.

Returns

Datetime object corresponding to the numeric representation.

Return type

datetime.datetime

Notes

Uses global dateVar dictionary for calendar and unit information. The function handles various NetCDF time representations and calendar systems commonly used in meteorological and climate data.

Used primarily for: - Converting NetCDF time indices back to calendar dates - Temporal calculations requiring date arithmetic - Output timestamp generation

cwatm.management_modules.timestep.timemeasure(name, loops=0, update=False, sample=1)

Measure execution time for model subroutines and components.

Records high-precision timestamps for performance profiling of CWatM components. Enables detailed analysis of computational bottlenecks and optimization of model performance. Part of the timing infrastructure used when the printtime flag is enabled.

Parameters

• name (str) – Name of the subroutine or component being measured.

• loops (int, optional) – Loop counter appended to name for repeated calls. Default is 0.

• update (bool, optional) – Flag for updating measurements (currently unused). Default is False.

• sample (int, optional) – Sampling parameter (currently unused). Default is 1.

Returns

Appends timestamp and identifier to global timing arrays.

Return type

None

Notes

Uses global arrays: - timeMes: List of high-precision timestamps (perf_counter) - timeMesString: List of corresponding subroutine identifiers

When loops > 0, the identifier becomes “name_N” where N is the loop number. This allows tracking of iterative processes and repeated function calls.

Timing information is processed and reported when the model completes if the printtime command-line option is specified.

cwatm.management_modules.timestep.timestep_dynamic(self)

Update temporal state variables during dynamic model execution.

Core temporal processing function called at each timestep to advance the model’s temporal state. Updates current date, calculates temporal markers (month/year boundaries), and maintains counters for output scheduling and temporal aggregation. Essential for coordinating all time-dependent model processes.

Parameters

self (object) – Model instance (parameter not used but maintains method signature).

Returns

Updates global dateVar dictionary with current temporal state.

Return type

None

Notes

The function updates dateVar with: - currDate: Current simulation date (datetime object) - currDatestr: Current date as formatted string - doy: Day of year (1-366) - 10day, 30day: Dekadal and monthly period indices - laststep: Boolean flag for final timestep - newStart, newMonth, newYear: Boolean flags for temporal boundaries - currMonth, currYear: Cumulative month/year counters for output - daysInMonth, daysInYear: Current period lengths for averaging

Temporal boundary detection: - Identifies first timestep, month start, year start - Enables conditional execution of periodic processes - Supports flexible output scheduling and aggregation

Called once per timestep during the main simulation loop, providing the temporal framework for all model components.

configuration module

Loading and parsing of the settings file

class cwatm.management_modules.configuration.ExtParser(*args, **kwargs)

Bases: configparser.ConfigParser

Extended configuration parser with placeholder replacement functionality.

This class extends the standard ConfigParser to support cross-section and same-section variable substitution using a custom placeholder syntax. Enables dynamic path construction and parameter referencing in configuration files, which is essential for maintaining flexible and maintainable CWatM model configurations.

Variables

• cur_depth (int) –

• recursion depth for nested placeholder replacements. (Current) –

• to prevent infinite recursion during variable substitution. (Used) –

Notes

Placeholder syntax:

• Cross-section: $(SECTION:OPTION) - references option in different section

• Same-section: $(OPTION) - references option in current section

The parser respects MAX_INTERPOLATION_DEPTH from configparser to prevent infinite recursion in circular references.

get(section, option, raw=False, vars=None, **kwargs)

Retrieve configuration value with placeholder replacement.

This method extends the standard ConfigParser.get() to perform recursive placeholder substitution. It processes both cross-section $(SECTION:OPTION) and same-section $(OPTION) placeholders.

Parameters

• section (str) – Configuration file section name containing the option.

• option (str) – Configuration option name to retrieve.

• raw (bool, optional) – If True, return raw value without placeholder substitution. Default is False.

• vars (dict, optional) – Dictionary of additional variables for interpolation. Default is None.

• **kwargs (dict) – Additional keyword arguments for ConfigParser compatibility.

Returns

Configuration value with all placeholders replaced.

Return type

str

Raises

• CWATMError – If the requested option is not found. Provides closest match suggestions using difflib for debugging assistance.

• InterpolationDepthError – If placeholder replacement exceeds maximum recursion depth, indicating circular references.

Notes

The method uses regular expressions to identify and replace placeholders: - r’$((w*):(w*))’ for cross-section references - r’$((w*))’ for same-section references

Recursion depth tracking prevents infinite loops in circular references.

cwatm.management_modules.configuration.parse_configuration(settingsFileName)

Parse CWatM configuration file and populate global parameter dictionaries.

This function is the main entry point for configuration processing. It reads the INI-format settings file, processes all sections and options, and populates the global dictionaries that control model behavior. Separates parameters into model bindings, boolean/integer options, and output specifications.

Parameters

settingsFileName (str) – Absolute or relative path to the CWatM configuration file (.ini format).

Returns

Results are stored in global dictionaries: - binding: Model parameters and file paths - option: Boolean and integer configuration flags - outTss, outMap: Time series and map output specifications - outDir: Output directory mappings - outsection: List of sections with output definitions - outputDir: Global output directory list

Return type

None

Raises

CWATMFileError – If the settings file does not exist or cannot be read.

Notes

Configuration file structure: - [OPTIONS] section contains boolean/integer flags - Output parameters follow naming convention: out_*, out_tss_*, *_dir - All other parameters become model bindings - Supports UTF-8 encoding for international file paths - Uses case-sensitive option names (optionxform = str)

Global variables modified: - binding: Main parameter dictionary - option: Boolean/integer options dictionary - outTss: Time series output specifications - outMap: Map output specifications - outDir: Output directory per section - outsection: Sections with output definitions - outputDir: Global output directory list

cwatm.management_modules.configuration.read_metanetcdf(name)

Parse XML metadata file for NetCDF variable attributes.

Reads an XML metadata file containing variable attributes for NetCDF output. The metadata includes units, long names, standard names, and other CF-compliant attributes required for proper scientific data documentation. This information is essential for creating self-describing NetCDF files that comply with climate and hydrological data standards.

Parameters

name (str) – Filename of the XML metadata file, typically ‘metaNetcdf.xml’. Path is resolved relative to the parent directory of this module.

Returns

Results stored in global metaNetcdfVar dictionary.

Return type

None

Raises

CWATMError – If XML file cannot be parsed due to syntax errors or encoding issues. If metadata file cannot be found at the expected location.

Notes

Expected XML structure: <CWATM>

<metanetcdf varname=”variable_name” unit=”units” long_name=”description”

standard_name=”cf_standard_name” …/>

</CWATM>

Global variables modified: - metaNetcdfVar: Dictionary mapping variable names to their metadata attributes

The metadata is used during NetCDF file creation to ensure proper documentation and CF compliance for output variables.

management_modules.messages module

Error handling - giving out messages

Error handling and user communication system for CWatM.

This module provides a comprehensive error handling framework for the Community Water Model, including specialized error classes for different types of failures and user communication. The system provides clear, formatted error messages with diagnostic information to help users identify and resolve issues.

Classes

CWATMError : Base error class for general CWatM errors CWATMFileError : Specialized error class for file-related issues CWATMDirError : Specialized error class for directory-related issues CWATMWarning : Warning class for non-fatal issues CWATMRunInfo : Information class for simulation status messages

Notes

All error classes automatically extract error numbers from message strings and provide formatted output with consistent headers. The system suppresses Python traceback information to provide cleaner error messages for end users.

exception cwatm.management_modules.messages.CWATMDirError(filename, msg='', sname='')

Bases: cwatm.management_modules.messages.CWATMError

Specialized error handling class for directory-related errors.

This class extends CWATMError to provide detailed diagnostics for directory access issues, helping users identify problems with output directories, input data directories, and path configuration in settings files.

Parameters

• filename (str) – Full path to the problematic directory

• msg (str, optional) – Error message string, by default “”

• sname (str, optional) – Setting name or context where the error occurred, by default “”

Notes

Provides enhanced diagnostics by: - Checking if the directory exists but has permission or other issues - Verifying if the parent directory exists but the target subdirectory doesn’t - Identifying which settings section contains the problematic directory path - Suggesting potential solutions for common directory problems

This is particularly useful for output directory configuration where users may specify non-existent paths or lack write permissions.

exception cwatm.management_modules.messages.CWATMError(msg)

Bases: Warning

Base error handling class for CWatM errors.

This class provides standardized error reporting with formatted output and automatic error number extraction. It suppresses Python tracebacks to provide cleaner error messages for end users.

Parameters

msg (str) – Error message string, optionally containing error number in format “Error XXX: message” where XXX is a 3-digit error code

Notes

Error numbers are automatically extracted from message strings that follow the pattern “Error XXX:” where XXX is a 3-digit number. If no valid error number is found, defaults to error code 100.

The class prints formatted error messages with a distinctive header and suppresses Python traceback information by setting sys.tracebacklimit = 0.

exception cwatm.management_modules.messages.CWATMFileError(filename, msg='', sname='')

Bases: cwatm.management_modules.messages.CWATMError

Specialized error handling class for file-related errors.

This class extends CWATMError to provide detailed diagnostics for file access issues, including path validation and suggestions for common file problems in CWatM.

Parameters

• filename (str) – Full path to the problematic file

• msg (str, optional) – Error message string, by default “”

• sname (str, optional) – Setting name or context where the error occurred, by default “”

Notes

Provides enhanced diagnostics by: - Checking if the file exists but has other issues - Verifying if the directory path exists but filename is wrong - Suggesting common file extension alternatives (.nc4, .nc) - Providing context about which settings section caused the error

The diagnostic information helps users quickly identify whether the issue is a missing directory, incorrect filename, or file permission problem.

exception cwatm.management_modules.messages.CWATMRunInfo(outputS)

Bases: Warning

Information display class for CWatM simulation status and settings.

This class provides formatted information messages about simulation progress, output locations, and configuration details. Used to communicate important information to users without indicating errors or warnings.

Parameters

outputS (list) – List containing output information, typically [settings_file, output_directory]

Returns

Formatted information message with header and simulation details

Return type

str

Notes

This class is used to provide users with: - Confirmation of simulation settings and output locations - Progress updates during long model runs - Summary information about completed simulations - Configuration validation results

The message format is designed to be informative and easy to locate in model output logs.

exception cwatm.management_modules.messages.CWATMWarning(msg)

Bases: Warning

Warning handling class for non-fatal CWatM issues.

This class provides standardized warning messages for situations that don’t stop model execution but should be brought to the user’s attention. Unlike error classes, warnings don’t terminate the program.

Parameters

msg (str) – Warning message to be displayed to the user

Notes

Warnings are formatted with a distinctive header and temporarily suppress traceback information during initialization. The traceback limit is restored after initialization to maintain normal Python error handling for other issues.

Use this class for: - Parameter values outside recommended ranges - Missing optional input data - Deprecated feature usage - Performance-related advisories

Handling output of CWatM

management_modules.output module

class cwatm.management_modules.output.outputTssMap(model)

Bases: object

Main CWatM output system class handling time series and map output generation.

This class manages all output operations for the CWatM hydrological model, including NetCDF map writing, time series extraction at gauge points, CSV/TSS file generation, and progress reporting. It handles various temporal aggregations (daily, monthly, annual) and spatial aggregations (point values, catchment averages/sums).

Global variables

Variable [self.var]	Type	Description	Unit
dirUp	Array	river network in upstream direction	–
meteo	Array	store all meteo data in memeory for warm start (eg calibration)	compl
sampleAdresses	List	outflowpoints as 1D index	–
outpoints	List	output points (Gauges)	–
noOutpoints	Number	number of output points	–
evalCatch	Array	indeces of a subbasin in the mask	–
catcharea	Array	catchment area of the subbaSIN	m2
netcdfasindex	Flag	save netcdf file in a compressed way - for splitting runs in several b	bool
firstout	Number	discharge of the first gauge	m3/s
discharge	Array	Channel discharge	m3/s
cellArea	Array	Area of cell	m2

Variables

• var (object) – Reference to model variable container with hydrological state variables

• model (object) – Reference to main CWatM model instance

Notes

The output system supports multiple output formats: - NetCDF maps for spatial data with temporal aggregation - Time series files (TSS/CSV) for gauge point data - Text dumps for debugging and analysis - Progress monitoring for GUI integration

Output timing is controlled by dateVar configuration and supports: - Daily outputs - Month-end, monthly totals, monthly averages - Annual outputs with various aggregations - Simulation-total aggregations

dynamic(ef=False)

Execute dynamic output operations for current time step.

This is the main output execution method called at each time step to: - Write NetCDF maps with appropriate temporal aggregation - Extract and accumulate time series data at gauge points - Handle monthly/annual aggregation and reset cycles - Update progress reporting for GUI and console output - Manage file writing for completed aggregation periods

Parameters

ef (bool, optional) – Environmental flow flag indicating if processing environmental flow calculations, by default False

Notes

Processes all configured outputs based on current date and timing rules. Handles temporal aggregation by accumulating values and writing outputs at appropriate intervals (month-end, year-end, etc.). Updates progress displays and manages memory by resetting aggregation variables after writing outputs.

initial()

Initialize output system configuration, gauge locations, and file structures.

This method sets up the complete output system including: - Processing gauge coordinates and creating sample addresses - Configuring catchment boundaries for area-based aggregations - Setting up NetCDF and time series file structures - Validating output variable names and timing specifications - Initializing progress reporting system

Notes

Must be called before any dynamic output operations. Processes settings file configuration to determine output locations, variables, and timing. Creates catchment delineation for gauges requiring area-based statistics. Validates all output variable names against available model variables.

management_modules.checks module

Checking maps if they fit in

Input validation and data quality control for CWatM.

This module provides comprehensive validation and diagnostic functions for CWatM input data, including spatial data checking, file verification, and detailed reporting of data characteristics. The validation system helps ensure data quality and compatibility before model execution.

Key Functions

decompress : Convert 1D compressed arrays to 2D display format counted : Decorator for counting function calls checkmap : Comprehensive validation and reporting for spatial data save_check : Save validation results to CSV files load_global_attribute : Extract NetCDF global attributes

The module supports comparison against reference datasets and provides detailed statistics about spatial data including: - Spatial dimensions and valid cell counts - Value ranges, means, and distributions - Missing value patterns and data completeness - File modification dates and version tracking

cwatm.management_modules.checks.checkmap(*args, **kwargs)

cwatm.management_modules.checks.counted(fn)

Decorator to count the number of times a function is called.

This decorator adds a call counter to any function, which is useful for tracking how many times validation functions are executed during model initialization and for generating sequential output.

Parameters

fn (callable) – Function to be wrapped with call counting functionality

Returns

Wrapped function with added ‘called’ attribute for call count

Return type

callable

Notes

The wrapper function maintains the original function name and adds a ‘called’ attribute that increments each time the function is invoked. This is particularly useful for the checkmap function to provide sequential numbering in validation output.

The call counter starts at 0 and increments before each function call.

cwatm.management_modules.checks.decompress(map)

Decompress 1D array without missing values to 2D array with missing values.

This function converts compressed 1D arrays used internally by CWatM back to full 2D spatial arrays for display, analysis, and output. The function properly handles different data types and missing value conventions.

Parameters

map (numpy.ndarray) – 1D compressed array containing only valid (non-masked) values

Returns

2D spatial array with proper dimensions and missing value handling

Return type

numpy.ndarray

Notes

The function uses global maskinfo to determine: - Original spatial dimensions (maskinfo[‘shape’]) - Location of valid cells (maskinfo[‘maskflat’]) - Base mask array structure (maskinfo[‘maskall’])

Missing values are set according to data type: - Integer types (int16, int32): -9999 - int8 types: Negative values set to 0 - All other types: -9999

This function is essential for converting CWatM’s internal compressed storage format back to standard spatial raster format.

cwatm.management_modules.checks.save_check()

Save validation results to CSV file.

This function writes accumulated validation results from checkmap calls to a CSV file for external analysis. The output location is determined from command-line arguments stored in the versioning system.

Notes

The function handles two argument patterns: 1. Three arguments: settings.ini, reference.nc, output.csv 2. Two arguments: settings.ini, output.csv

File saving occurs only when: - Valid arguments are provided with .csv extension - Validation results have been accumulated in versioning[‘check’]

After saving, the checkmap call counter is reset to 0 for potential future validation runs. The CSV output includes headers and formatted data for each validated input.

The saved file can be analyzed externally to: - Compare multiple model setups - Track data quality over time - Validate input data consistency - Document model configuration for reproducibility

Program management

Global definition of variables

globals module

Global definition of variables

Global variables and initialization functions for the Community Water Model (CWatM).

This module defines and manages all global variables, dictionaries, and data structures used throughout CWatM execution. It provides centralized state management for:

• Model configuration and settings

• Spatial domain information and masking

• Time stepping and model execution flow

• Input/output data management

• Meteorological data handling

• Initial conditions and state variables

• Output reporting and NetCDF metadata

• Cross-platform shared library loading

• Command-line flag processing

The module also handles platform-specific initialization of shared libraries for kinematic wave routing and other computational routines.

Key Global Variables

settingsfilelist

Storage for settings file paths

maskinfodict

Spatial mask and domain information

modelStepslist

Model time step configuration

bindingdict

Variable bindings from settings files

optiondict

Configuration options and parameters

Flagsdict

Command-line execution flags

versioningdict

Version control and build information

dateVardict

Date and time variable management

outDir, outMap, outTssdict

Output directory and file specifications

meteofilesdict

Meteorological input file tracking

domain, indexesdict

Spatial domain and indexing for MODFLOW coupling

Platform Detection

The module automatically detects the operating system and loads appropriate shared libraries for computational routines, supporting Windows, Linux, macOS, and Cygwin environments.

cwatm.management_modules.globals.FlagName = ['quiet', 'veryquiet', 'loud', 'checkfiles', 'printtime', 'warranty', 'calib', 'warm', 'gui']

Valid flag names for command-line argument parsing. Used by getopt to recognize valid command-line options.

Type

list

cwatm.management_modules.globals.Flags = {'calib': False, 'check': False, 'gui': False, 'loud': False, 'maskmap': False, 'printtime': False, 'quiet': False, 'test': False, 'use': False, 'veryquiet': False, 'warm': False, 'warranty': False}

Global execution flags controlling CWatM behavior. Controls output verbosity, execution modes, and special features throughout the model.

Type

dict

cwatm.management_modules.globals.calibclear()

Clear global variables specifically for calibration mode.

This function performs a selective clearing of global variables that need to be reset between calibration runs, while preserving spatial and model structure information that remains constant across calibration iterations.

Notes

This partial clearing approach optimizes calibration performance by: - Resetting all command-line flags to False - Clearing input data counters and meteorological file tracking - Resetting initial condition variables and date variables - Clearing time series output but preserving map output structure - Maintaining spatial domain information (maskinfo, geotrans, domain) - Preserving model structure (modelSteps, xmlstring) for efficiency

cwatm.management_modules.globals.globalFlags(setting, arg, settingsfile, Flags)

Parse command-line flags and configure CWatM execution behavior.

This function processes command-line arguments to set various execution flags that control CWatM’s output verbosity, checking modes, timing, and special execution modes like calibration or GUI operation.

Parameters

• setting (str) – Path to the settings file for the CWatM run

• arg (list) – List of command-line arguments passed to CWatM

• settingsfile (list) – Global list to store the settings file path

• Flags (dict) – Global dictionary of boolean flags controlling execution behavior

Notes

Supported command-line flags: - -q, –quiet: Minimal output with progress dots - -v, –veryquiet: No progress output - -l, –loud: Verbose output with timestep details - -c, –checkfiles: Input validation mode only - -t, –printtime: Print computation time for modules - -w, –warranty: Show copyright and warranty information - -k, –calib: Enable calibration mode - -0, –warm: Enable warm start/restart mode - -g, –gui: Enable GUI mode - -m, –maskmap: Enable mask map processing

The function also automatically detects pytest execution environment and sets the ‘test’ flag accordingly.

cwatm.management_modules.globals.globalclear()

Clear all global variables and data structures used in CWatM.

This function resets all global dictionaries, lists, and containers to their initial empty state. It is typically called during model initialization or between model runs to ensure clean state.

Notes

This function clears all major global data structures including: - Configuration and settings (settingsfile, binding, option) - Model spatial information (maskinfo, geotrans, domain, indexes) - Time stepping and initialization data (timestepInit, modelSteps) - Input/output management (meteofiles, outDir, outMap, outTss) - Reporting and metadata structures (reportMaps*, metadataNCDF) - Version control and model tracking (versioning)

cwatm.management_modules.globals.outputTypMap = ['daily', 'monthtot', 'monthavg', 'monthend', 'monthmid', 'annualtot', 'annualavg', 'annualend', 'totaltot', 'totalavg', 'totalend', 'once', '12month']

Valid output types for map (NetCDF) outputs. Defines temporal aggregation options for spatial output files including daily, monthly, annual, and total simulation period aggregations.

Type

list

cwatm.management_modules.globals.outputTypTss = ['daily', 'monthtot', 'monthavg', 'monthend', 'annualtot', 'annualavg', 'annualend', 'totaltot', 'totalavg']

Valid output types for time series outputs. Similar to outputTypMap but without spatial-only options like ‘once’ and ‘12month’.

Type

list

cwatm.management_modules.globals.outputTypTss2 = ['tss', 'areasum', 'areaavg']

Valid aggregation methods for time series outputs. Defines whether time series should be point values, area sums, or area averages.

Type

list

cwatm.management_modules.globals.python_bit = 64

Python architecture bit size (32 or 64). Used to ensure CWatM runs on 64-bit Python installations only.

Type

int

dynamicModel module

Framework of initial and dynamic modules

class cwatm.management_modules.dynamicModel.DynamicModel

Bases: object

Base class for dynamic hydrological model components.

Provides the foundation for time-dependent model components in CWatM. This class serves as a template for hydrological modules that require dynamic time-stepping behavior and state evolution over the simulation period.

Variables

i (int) – Simple counter attribute for model indexing.

Notes

This is a minimal base class inspired by PCRaster’s dynamic modeling framework. Concrete hydrological modules inherit from this class and implement specific dynamic behaviors for water cycle processes.

The class provides the structural foundation for CWatM’s modular architecture, where individual hydrological processes are implemented as separate dynamic components that interact through the main model framework.

i = 1

class cwatm.management_modules.dynamicModel.ModelFrame(model, lastTimeStep=1, firstTimestep=1)

Bases: object

Execution framework for dynamic hydrological model time stepping.

This class manages the temporal execution of CWatM, controlling the time-stepping loop and orchestrating the dynamic components of the hydrological model. It provides the main execution framework that advances the model through time, managing state transitions and coordinating hydrological processes.

Variables

• _model (object) – Reference to the main CWatM model instance containing all hydrological components and state variables.

• currentStep (int) – Current time step number during model execution.

Notes

The ModelFrame implements the core time-stepping algorithm: 1. Initialize model state and time counters 2. Execute dynamic processes for each time step 3. Update state variables and advance time 4. Continue until simulation end

This design separates the temporal execution logic from the hydrological process implementations, enabling modular development and testing of individual model components.

The framework supports flexible time stepping configurations and can accommodate various temporal resolutions from sub-daily to multi-year simulations.

initialize_run()

Initialize the model run by setting the starting time step.

Prepares the time-stepping framework for dynamic execution by setting the current time step to the configured starting point. This initialization occurs before the main time-stepping loop begins.

Returns

Sets currentStep to the model’s first time step.

Return type

None

Notes

This method is called once at the beginning of each model run to establish the temporal starting point. The subsequent dynamic execution will iterate from this starting point to the final time step.

The initialization is separate from the constructor to allow for multiple runs with the same ModelFrame instance.

run()

Execute the complete dynamic simulation from start to finish.

Runs the full hydrological simulation by executing the time-stepping loop from the first to the last configured time step. This is the main entry point for model execution, coordinating initialization and the complete temporal sequence of hydrological processes.

Returns

Completes the full simulation run.

Return type

None

Notes

The run sequence: 1. Initialize the run with starting conditions 2. Execute time steps sequentially until simulation end 3. Each time step includes all active hydrological processes 4. State variables are updated and outputs generated as configured

This method orchestrates the complete CWatM simulation, managing the temporal progression of all hydrological components including: - Meteorological forcing data reading - Evapotranspiration calculations - Soil water dynamics - Groundwater processes - Surface water routing - Water demand and allocation - Output generation and reporting

step()

Execute a single time step of the hydrological model.

Performs one iteration of the model’s dynamic processes, including all hydrological computations, state updates, and process interactions for the current time step. This is the core execution unit that advances the model state forward in time.

Returns

Updates model state and advances time step counter.

Return type

None

Notes

The time step execution sequence: 1. Set current time step in the model instance 2. Execute all dynamic hydrological processes 3. Update state variables and fluxes 4. Advance to next time step

This method coordinates the execution of all active hydrological modules including evapotranspiration, soil processes, groundwater, routing, and water management components.

replace_pcr module

Some pcr operation are done in numpy

PCRaster replacement functions using NumPy operations.

This module provides NumPy-based implementations of common PCRaster spatial analysis operations, particularly area-based statistics functions. These functions are used throughout CWatM to perform spatial aggregations and statistics on raster data using efficient NumPy operations instead of PCRaster library calls.

The module focuses on area-based operations where values are aggregated or analyzed within discrete spatial units defined by area class identifiers.

Key Functions

npareatotal : numpy area total calculation npareaaverage : numpy area average calculation npareamaximum : numpy area maximum calculation npareamajority : numpy area majority calculation

Notes

These functions use NumPy’s bincount and advanced indexing operations for efficient spatial aggregation. They handle missing values and edge cases appropriately for hydrological modeling applications.

cwatm.management_modules.replace_pcr.npareaaverage(values, areaclass)

Calculate average values for each area class using NumPy operations.

This function computes the mean of all values within each area class, providing a NumPy equivalent to PCRaster’s areaaverage operation.

Parameters

• values (numpy.ndarray) – Array of values to be averaged within each area class

• areaclass (numpy.ndarray) – Array of area class identifiers, same shape as values

Returns

Array with same shape as input, where each cell contains the average of all values within its area class

Return type

numpy.ndarray

Notes

Uses np.bincount to compute both weighted sums and counts for each class, then divides to get averages. Error state management prevents warnings from division by zero or invalid operations in empty classes.

cwatm.management_modules.replace_pcr.npareamajority(values, areaclass)

Calculate majority values for each area class using NumPy operations.

This function finds the most frequently occurring value within each area class, providing a NumPy equivalent to PCRaster’s areamajority operation.

Parameters

• values (numpy.ndarray) – Array of discrete values to find majority within each area class

• areaclass (numpy.ndarray) – Array of area class identifiers, same shape as values

Returns

Array with same shape as input, where each cell contains the most frequently occurring value within its area class

Return type

numpy.ndarray

Notes

Uses np.unique to identify distinct area classes, then applies bincount to count occurrences of each value within each class. The most frequent value (argmax of bincount) becomes the majority value for that class. Results are mapped back using the inverse indices from unique operation.

cwatm.management_modules.replace_pcr.npareamaximum(values, areaclass)

Calculate maximum values for each area class using NumPy operations.

This function finds the maximum value within each area class, providing a NumPy equivalent to PCRaster’s areamaximum operation.

Parameters

• values (numpy.ndarray) – Array of values to find maximum within each area class

• areaclass (numpy.ndarray) – Array of area class identifiers, same shape as values

Returns

Array with same shape as input, where each cell contains the maximum value found within its area class

Return type

numpy.ndarray

Notes

Creates an array sized to hold all possible class IDs, then uses np.maximum.at to efficiently find the maximum value for each class. The result is mapped back to original positions using np.take.

cwatm.management_modules.replace_pcr.npareatotal(values, areaclass)

Calculate total values for each area class using NumPy operations.

This function computes the sum of all values within each area class, providing a NumPy equivalent to PCRaster’s areatotal operation.

Parameters

• values (numpy.ndarray) – Array of values to be summed within each area class

• areaclass (numpy.ndarray) – Array of area class identifiers, same shape as values

Returns

Array with same shape as input, where each cell contains the total sum of all values within its area class

Return type

numpy.ndarray

Notes

Uses np.bincount with weights to efficiently compute class totals, then maps results back to original array positions using np.take. This approach is much faster than iterative summation methods.

CWatM Management Modules Package.

This package contains the core management and infrastructure modules for the Community Water Model (CWatM). These modules provide essential functionality for model configuration, data handling, execution control, and output generation.

Modules

configurationmodule

Configuration parsing, settings validation, and global state management

data_handlingmodule

NetCDF I/O, spatial data processing, and file handling operations

dynamicModelmodule

Model execution framework and time stepping control

timestepmodule

Time management, temporal calculations, and date handling

outputmodule

Output system, NetCDF writing, and data export functionality

globalsmodule

Global variables, constants, and shared state management

replace_pcrmodule

PCRaster replacement functions using NumPy operations

messagesmodule

Error handling, warning systems, and user communication

checksmodule

Input validation, data verification, and quality control

Notes

These modules form the infrastructure backbone of CWatM, handling all aspects of model execution that are not directly related to hydrological processes. They provide platform-independent functionality for data processing, file I/O, temporal management, and model control.