Summary of climate.c in SWMM5

 Below is a step‐by‐step overview of how climate.c manages climate‐related data in SWMM5—specifically, temperature, evaporation, wind speed, and monthly adjustment factors. This file handles:

1. Reading climate input parameters (temperature sources, evaporation sources, monthly pattern adjustments).
2. Opening and interpreting external climate data files (various formats).
3. Updating daily/hourly climate states (temperature, evaporation, wind) each simulation day/time step.
4. Applying monthly adjustments (e.g., temperature offset, rainfall multiplier, hydraulic conductivity factor, etc.).

---

1. Main Responsibilities

1. Temperature

   • Allows temperature to come from:
     • A time series in the SWMM input file, or
     • An external climate file, or
     • No temperature data (some default or not used).
   • For min/max daily temperature (from climate file), it models hourly temperature via a sinusoidal interpolation.

2. Evaporation

   • Supports various methods:
     • Constant daily evaporation.
     • Monthly average evaporation for each month of the year.
     • A time series of evaporation rates.
     • File with daily evaporation data.
     • Temperature-based evaporation (Hargreaves method) derived from daily temperature extremes.

3. Wind Speed

   • Can be:
     • Monthly fixed average speeds, or
     • Daily data from the climate file.

4. Adjustments

   • Monthly adjustments for:
     • Temperature, Evaporation, Rainfall, Hyd. conductivity.
   • Patterns for subcatchment infiltration parameters, roughness, etc.

5. File Format Handling

   • Recognizes several climate file formats:
     • User‐prepared (simple ASCII with year, month, day, TMAX, TMIN, EVAP, WIND),
     • NCDC GHCN Daily (GHCND),
     • NCDC TD3200,
     • Canadian DLY02 or DLY04.

---

2. Key Global Variables

Within climate.c, these are prominent:

1. Temp

   • Stores temperature data source, user file date range, current day’s temperature, average daily temp, etc.

2. Evap

   • Type of evaporation method (constant, monthly, timeseries, etc.).
   • Current evaporation rate Evap.rate.

3. Wind

   • Type of wind speed data (monthly or file).
   • Current wind speed Wind.ws.

4. Adjust

   • Holds arrays of 12 monthly adjustments for temp[i], evap[i], rain[i], hydcon[i].
   • Also stores subcatchment adjustment patterns (like Subcatch[i].nPervPattern).

5. File‐specific (like Fclimate)

   • Fclimate.name = external climate file name, Fclimate.file = file pointer.
   • FileYear, FileMonth, FileDay = track which day’s data we are currently on.
   • FileData[var][day] = a month’s worth of daily data for each climate variable.

---

3. Important Functions

3.1 Reading Input Lines

• climate_readParams(...)

  • Reads lines in the [TEMPERATURE] section.
  • Possible tokens:
    • TIMESERIES name
    • FILE name [startDate] [tempUnits]
    • WINDSPEED MONTHLY ...
    • WINDSPEED FILE
    • SNOWMELT v1 ... v6
    • ADC IMPERV/PERV ... (areal depletion curve data)
  • Configures the data source for temperature and wind speeds, plus any snowmelt parameters.

• climate_readEvapParams(...)

  • Reads lines in the [EVAPORATION] section.
  • Possible tokens:
    • CONSTANT value
    • MONTHLY v1 ... v12
    • TIMESERIES name
    • FILE (monthly pan coefficients)
    • TEMPERATURE
    • RECOVERY patternName
    • DRY_ONLY YES/NO

• climate_readAdjustments(...)

  • Reads lines in the [ADJUSTMENTS] section.
  • Could be:
    • TEMPERATURE 12vals
    • EVAPORATION 12vals
    • RAINFALL 12vals
    • CONDUCTIVITY 12vals
    • N-PERV subcatchID patternID
    • DSTORE subcatchID patternID
    • INFIL subcatchID patternID

---

3.2 Validation & Initialization

• climate_validate()

  • Ensures a valid climate file is provided if needed.
  • Opens it (climate_openFile()) if Wind.type==FILE_WIND, Evap.type==FILE_EVAP or Temp.dataSource==FILE_TEMP.
  • Checks snowmelt parameters, latitude bounds, adjusts monthly temperature/evap arrays if UnitSystem == SI.

• climate_openFile()

  • Actually fopen() the climate file and determines file format via getFileFormat().
  • Positions the file at the correct starting date (either the simulation start or Temp.fileStartDate).

• climate_initState()

  • Called at start of simulation.
  • Resets last day, sets up time series evaporation (if used) to track next date & next rate, etc.
  • For temperature-based evaporation, sets up a 7-day moving average structure Tma.

---

3.3 Setting Climate State Each Day/Time

• climate_setState(theDate)
  • Called at each new routing time step to update:
    1. Temperature,
    2. Evaporation,
    3. Wind Speed,
    4. Monthly rainfall/hyd. conductivity multipliers,
    5. NextEvapDate (the next day/time evap changes).
  • Internally calls:
    • updateFileValues(theDate) if using external climate file.
    • setTemp(theDate), setEvap(theDate), setWind(theDate).

---

3.4 Temperature Routines

1. setTemp(theDate)

   • If using a file for TMIN/TMAX, it checks if a new day has started, updates daily TMIN/TMAX, times of sunrise/sunset, etc.
   • For hourly temperature, does sinusoidal interpolation:
     • min temp at sunrise, max at early afternoon, then decreasing.
   • If using a temperature time series, just looks up the temperature in the time series.

2. updateTempTimes(day)

   • Calculates approximate sunrise/sunset hour angles, sets Hrsr, Hrss, etc. to determine when TMIN/TMAX occur.

3. updateTempMoveAve(tmin, tmax)

   • Maintains a 7-day moving average of average daily temperature (tAve) and daily range (tRng).
   • Used by Hargreaves evaporation approach (when Evap.type == TEMPERATURE_EVAP).

---

3.5 Evaporation Routines

1. setEvap(theDate)

   • Chooses evaporation rate based on method:
     • CONSTANT_EVAP: a single value.
     • MONTHLY_EVAP: uses the monthly value for mon-1.
     • TIMESERIES_EVAP: if current date >= NextEvapDate, loads NextEvapRate.
     • FILE_EVAP: uses FileValue[EVAP], possibly scaled by pan coefficients.
     • TEMPERATURE_EVAP: uses the Hargreaves formula with the 7‐day average T.
   • Applies monthly climate adjustments from Adjust.evap[mon-1].

2. getTempEvap(day, tAve, tRng)

   • Implements Hargreaves daily evap formula from 7‐day average T and daily range.
   • Converts from mm/day to in/day if in US units.

3. climate_getNextEvapDate()

   • Returns the current NextEvapDate (the next day/time we might update evaporation rate if from a time series or climate file).

---

3.6 Wind Speed Routines

• setWind(theDate)
  • If monthly, picks the monthly average from Wind.aws[mon-1].
  • If file-based, uses FileValue[WIND].

---

3.7 Climate File Reading Internals

1. climate_openFile() + getFileFormat()

   • Reads the first line.
   • Checks if format is:
     • TD3200 (first 3 chars = "DLY", line[23..26] = "9999"),
     • DLY0204 (Canadian format, line length >= 233, some coded fields),
     • USER_PREPARED (attempts to parse year, month, day),
     • GHCND (checks for "DATE" + possible TMIN/TMAX/Evap lines).
   • Positions the file at the right year/month.

2. readFileValues()

   • Reads a month’s worth of data into FileData[var][day] arrays.
   • For each line in that month, calls specialized parse functions (like parseUserFileLine(), parseTD3200FileLine(), etc.) to fill daily values.

3. updateFileValues(theDate)

   • Each day, we advance the day counters. If we moved to a new month, read a fresh chunk of data from the file.

---

4. Typical Flow (No pun intended)

1. User specifies climate sections in the SWMM input:
   • [TEMPERATURE] lines, [EVAPORATION] lines, [ADJUSTMENTS], etc.
2. During Setup:
   1. climate_validate() ensures it’s consistent, maybe opens the climate file if needed.
   2. climate_initState() initializes internal variables.
3. At Each Simulation Day/Time:
   1. climate_setState(theDate) is called from the runoff or routing engine.
   2. Possibly reads new file data if a new day or new month has begun.
   3. Updates daily TMIN/TMAX or hour interpolation for temperature, sets evaporation, wind speed, etc.
   4. Applies monthly adjustments.

---

5. Key Takeaways

• climate.c is the central hub for SWMM’s climate data. It orchestrates:
  • Reading external climate data in multiple formats,
  • Maintaining internal arrays of daily min/max temperature, evaporation, wind,
  • Interpolating hourly temperature from daily extremes (for rainfall/runoff processes),
  • Calculating Hargreaves evaporation if required,
  • Applying monthly adjustments across temperature, evaporation, rainfall, and infiltration parameters.
• The flexibility (user time series, external file, monthly/constant) allows SWMM to handle many real-world climate scenarios.