#
# Delft3D: Water quality
#
# This file contains some general information needed for the
# user-interface:
#
# - Typical ranges for the concentration of substances and the values
#   of parameters
# - Units of concentration and the related units of mass and discharge
# - Integration options
# - Quantities required for the proper calculation in the water
#   quality model.
# - Auxiliary programs called from the user-interface
#
# Note: the first two parts can be edited or extended as
#       the need may be.
#
#
# Check on version:
#

version 3 minor 31

#
# Typical ranges for the concentration of substances
# and the values of parameters:
#
# Per line:
# - Substance name (as known to the Delft3D-WAQ processes library)
# - Typical minimum value (often 0.0)
# - Typical maximum value
# - Typical default for open boundaries and initial conditions
#
# Note: the default for waste loads is always zero!
#
quantities
  'Salin'   0.0    35.0     35.0        # Typical for coastal seas
  'OXY'     3.0    12.0      8.0
  'CBODu'   0.0     5.0      0.5
  'Ecoli'   0.0 20000.0      0.0        # Maximum downstream outfalls
  'TColi'   0.0 20000.0      0.0        # Ditto
  'FColi'   0.0  1000.0      0.0        # Ditto
  'IM1'     1.0   100.0      2.0        # Coastal seas
   # ...
end-quantities

#
# Units for discharges (or waste loads)
#
# Per concentration unit:
# - The so-called primary unit of discharge:
#      the result of <unit-of-concentration? * m3/s,
#   this is the unit in which Delft3D-WAQ and Delft3D-PAR expect the
#   waste loads.
# - Any of a number of secondary units.
#   In these cases the conversion factor to the primary unit must be
#   given, so that the program can convert the numbers.
#
discharge-units
   units-related-to 'mg/l'
      primary    'g/s'
      secondary  'kg/day'      0.011574  # 1000 g / 86400 s
      secondary  'kton/day'   31.70979   # 1,000,000,000 g / 86400*365 s
      # ...
   end-units
   # ...
end-discharge-units

#
# Units for mass
#
# Per concentration unit:
# - The so-called primary unit of discharge:
#      the result of <unit-of-concentration? * m3,
#   this is the unit in which Delft3D-PAR expects the
#   masses
# - Any of a number of secondary units.
#   In these cases the conversion factor to the primary unit must be
#   given, so that the program can convert the numbers.
#
mass-units
   units-related-to 'mg/l'
      primary    'g'
      secondary  'kg'     1000.0     # 1000 g
      secondary  'kton'   1.0E9      # 1,000,000,000 g
      # ...
   end-units
   # ...
end-mass-units

#
# Integration options:
# For all useful integration options the following information:
# - the number in the DELFT3D-WAQ input file
# - a concise description of the option (up to about 60 characters)
#
integration-options
    1     '1-Explicit, backward in space and time'
    2     '2-Explicit, 2nd order Runge Kutta'
    3     '3-Explicit, 2nd order Lax Wendroff' allow-forester-filter
    4     '4-Alternate direction Implicit'
    5     '5-Flux-corrected transport, explicit'
    6     '6-RCA/ECOM transport routine, explicit' requires-regular-grid
   10    '10-Implicit, backward in space and time'
   11    '11-Horizontally backward, vertically implicit (central)' allow-forester-filter
   12    '12-Horizontally flux-corrected, vertically implicit (central)' allow-forester-filter
   13    '13-Horizontally backward, vertically implicit (backward)'
   14    '14-Horizontally flux-corrected, vertically implicit (backward)'
#
# Options for fast solvers
#
   15    '15-Iterative solver, backward differences'
   16    '16-Iterative solver, horizontally backward, vertically central' allow-forester-filter
#
# Options for ADI on regular gird (this is essential!)
# Requires the use of an extra keyword to indicate the differences
# in the DELWAQ input file
#
   19 '19-ADI, vertically central'  requires-regular-grid allow-forester-filter allow-anticreep
   20 '20-ADI, vertically backward' requires-regular-grid allow-anticreep
end-integration-options

#
# Computational quantities: general water quality and sediment
#
# This part of the file contains those parameters that
# are always required in a calculation with Delft3D-WAQ.
# So as not to bother the user with these parameters,
# the user-interface fills them in automatically (in most
# cases these provide work arrays only)
#
# The quantities can be:
# - constant:         the name is added to the list of "constants"
# - parameter:        the name is added to the list of "parameters"
# - function:         the name is added to the list of "functions"
# - segment-function: the name is added to the list of "segment-functions"
# - output:           the name is added to the list of "output parameters"
#
# For each quantity, the default must be given, usually zero, as
# the value is calculated. For quantities of the type "parameter" or
# "segment-function" an indication of an auxiliary file can be
# given as well. For instance:
#
#    parameter "SURF" 1.0 from base-surfaces file
#
# Such files must have been generated by the coupling program or be
# otherwise available.
# Valid file indications are:
# - base-surfaces       for the surface area
# - shear-stresses      for the shear stresses
# - vertical-diffusion  for the vertical diffusion
# - salinity            for the salinity
# - temperature         for the temperature
# - chezy-coefficients  for the Chezy coefficients
#
# Be careful to specify the right type of information. Hardly any check is
# made.
#
# Note:
# Unless you know what Delft3D-WAQ expects, do not change this
# section. The calculations may not be correct if you change
# the wrong things.
#
# Note:
# This part of the file may be extended in the near future.
#
computational-quantities-watqual
   parameter         'SURF'        1.0 from base-surfaces file
   output            'SURF'        0.0            # Depth is derived from this parameter
   segment-function  'VertDisper'  0.0 from vertical-diffusion file
   # segment-function  'Tau'         0.0 from shear-stresses file
   constant          'ACTIVE_VERTDISP'  0.0  # Activate this process!
   constant          'ACTIVE_TOTDEPTH'  0.0  # Activate this process!
   constant          'ACTIVE_DYNDEPTH'  0.0  # Activate this process!
   # constant        'VWind'       0.01      # For calculation vertical diffusion
   #                                         # and shear stresses from waves;
   #                                         # Should not be zero!
   constant          'CLOSE_ERR'   1.0       # Closure error correction
   output            'LocalDepth'  1.0       # Must be defined: for postprocessing
   #
   # Parameters that are set directly in the screens
   #
   constant          'ScaleVDisp'  1.0       # Scale factor for vertical diffusion
   #
   # Parameters controlling iterative solvers
   #
   constant          'MaxIter'     100.0     # Maximum number of iterations
   constant          'Tolerance'   1.0E-07   # Tolerance for iteration error
   constant          'Iteration Report'  0.0 # Turn off detailed report
                                             # To turn it on: set to 1.0
   #
   # Parameters controlling the finer details of a z-layers model
   #
   constant          'ACTIVE_TOPLAYER'   0.0  if z-layer # Activate this process!
   constant          'TopLayerThreshold' 0.01 if z-layer

   # ...
end-computational-quantities

computational-quantities-sediment
   parameter         'SURF'        1.0 from base-surfaces file
   output            'SURF'        0.0       # Depth is derived from this parameter
   constant          'ACTIVE_VERTDISP'  0.0  # Activate this process!
   constant          'ACTIVE_TOTDEPTH'  0.0  # Activate this process!
   constant          'ACTIVE_DYNDEPTH'  0.0  # Activate this process!
   output            'dZsand'      0.0       # Always output this
   segment-function  'VertDisper'  0.0 from vertical-diffusion file
   # segment-function  'Tau'         0.0 from shear-stresses file
   # constant          'VWind'       0.01    # For calculation vertical diffusion
   #                                         # and shear stresses from waves;
   #                                         # Should not be zero!
   constant          'CLOSE_ERR'   1.0       # Closure error correction
   output            'LocalDepth'  1.0       # Must be defined: for postprocessing
   # output            'Tau'         1.0       # For postprocessing
   #
   # Parameters controlling iterative solvers
   #
   constant          'MaxIter'     100.0     # Maximum number of iterations
   constant          'Tolerance'   1.0E-07   # Tolerance for iteration error
   constant          'Iteration Report'  0.0 # Turn off detailed report
                                             # To turn it on: set to 1.0
   #
   # Parameters controlling the finer details of a z-layers model
   #
   constant          'ACTIVE_TOPLAYER'   0.0  if z-layer # Activate this process!
   constant          'TopLayerThreshold' 0.01 if z-layer
   # ...
end-computational-quantities

#
# Auxiliary programs
#
# This block contains the names of the scripts to be
# run for starting several external programs. The names of these scripts
# depend on the platform.
#
# Two blocks need to be defined:
# - one or the UNIX versions of these programs
# - one of the NT version of the programs
# As these programs run parallel to the user-interface (except for
# the coupling program), the command is more complicated than it seems
# necessary:
# - use "nohup .. &" for UNIX
# - use "start ..." for Windows NT
#
auxiliary-programs-unix
   coupling-program 'convhyd.sh'
   grid-editor      'dido.sh'
   substance-editor 'nohup sel_subst.sh &'
end-auxiliary-programs-unix

auxiliary-programs-windows-nt
   coupling-program '%D3D_HOME%\%ARCH%\waq\bin\convhyd.bat'
   grid-editor      'start %D3D_HOME%\%ARCH%\waq\bin\dido.exe'
   substance-editor 'start %D3D_HOME%\%ARCH%\waq\bin\sel_subs.bat'
end-auxiliary-programs-windows-nt


#
# Interfacing with HydroQual's RCA program:
#
# The keywords are fixed:
# An @ at the beginning indicates the start of a keyword
# An @ at the end indicates that the newline should be suppressed
# After the @ follows the card group as described in the
# RCA user's guide.
#
# The keywords are referred to within the program, so adding new
# keywords should be done in concert with changes to the source code.
#
# Note:
# Information that can not be defined via these keywords is written
# by the routine WriteRCAInputFile() and is derived as much as possible
# from the scenario data.
#
# Note:
# The format for these lines is determined by RCA's input processor.
# In general fixed formats are used.
#

begin-rca-lines
   @A1_model_listing '    0    1    1    1    1    1    1    1    1     0'
                   #  cycle modl iser irun lst1 lst2 lst3 lst4 lst5 idiag

   @A5_system_bypass ' 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
                   #  1 for bypassing systems in the calculation

   @B3_system_bypass_dump ' 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
                   #  1 for bypassing systems in the detailed dumps

   @B5_integration_corrections '    0    0    0'
                   #            negsln, slcopt, ismolar

  # Note:
  # Use the next two keywords only if slcopt is set to 1.
  #@B6_sigma_time_number  '100000000.    0'
                   #          dtslc  noslc

  #@B6_sigma_levels  '       0.0       0.0       0.0       0.0             0.0       0.0       0.0       0.0'
                   #      slcdpth(i) ...
                   # Use this line if noslc is not zero

   @B7_time_scale_factor@      '       1.0'
                   #                 scalt

   @B7_kinetics_timestep       '       0.0'
                   #                 scalt
   # Note:
   # Only use this if there are such data required
   #@TUNER_user_defined         ' '
                   # Use this keyword for user-defined input for the TUNER routine
end-rca-lines

#
# Statistics:
# Properties of the statistical output routines
# - Three types of parameters, real, time, logical. For the latter we can
#   also use the keywords "calculation-start-time" and "calculation-stop-time"
#
statistical-operations
   operation 'STADSC' 'Average over time'
      period-used
      # No additional parameters
   end-operation

   operation 'STAGEO' 'Geometric mean'
      period-used
      # A single additional parameter
      real-parameter 'Threshold' 'THRESH' 1.0
   end-operation

   operation 'STADPT' 'Depth averaging'
      no-period-used
      # No additional parameters
   end-operation

   operation 'STADAY' 'Periodic averages'
      no-period-used
      time-parameter 'Start time' 'TINIT'  calculation-start-time
      time-parameter 'Period'     'PERIOD' '00000001000000' # One day
   end-operation

   operation 'STAPRC' 'Percentiles (Exceedance time)'
      period-used
      real-parameter 'Critical concentration' 'CCRIT' 0.0
      logical-parameter 'Exceedence' 'ABOVE' yes
   end-operation

   operation 'STAQTL' 'Quantiles'
      period-used
      real-parameter 'Quantile (in %) to be reported' 'CQLEV' 0.0
      real-parameter 'Number of buckets to use' 'NOBUCK' 20.0
      real-parameter 'Lower concentration bound' 'CLOBND' 0.0
      real-parameter 'Upper concentration bound' 'CUPBND' 0.0
   end-operation

end-statistical-operations