Model configuration

Model inputs are specified in a main configuration (config) file, which may include links to additional data files for example shapefiles specifying positional input data in real world coordinate systems or CSV files of boundary condition timeseries data. Below the input parameters and options available in the configuration file are explained along with details of required additional data files.

The model config file is a ASCII formatted text file with extension .cnf. The file is broken into several sections, each of which contains several keyword identified inputs. Comments are optional and preceded by a #, blank lines can be included as desired. The order of sections and keywords is not important, but keywords must be in the correct section. Input values are either numeric or strings, depending on the keyword. If string inputs include spaces they must be encapsulated in quotes. For example:

[Section1Name]
KeywordName = 7.3
# Comment here
AnotherKeyword = StringInputWithNoSpaces 

[Section2Name]
# Another comment, for example describing where input data has been 
# derived or what a keyword means
AKeywordInSection2 = 'A long string input with spaces encapsulated in quotes'
[[Sub-section1]]
# This subsection is part of Section 2.
AnotherKeyword = 42
# This keywrod is under sub-section 1 in section 2.

The various sections and keywords are listed below:

[BoundaryConditions]

Keyword	Description
RiverFlow	River flow timeseries input. Either: filename/path of input csv file, e.g. RiverFlow = LagoonInflow.csv, or keyword shotnoise to use a synthetic shotnoise flow hydrograph (requires the additional section [[ShotnoiseHydrographParameters]]), i.e. RiverFlow = shotnoise.
WaveConditions	Wave conditions timeseries (filename/path of input csv file), e.g. WaveConditions = WaveData.csv
SeaLevel	Sea level timeseries input. Either: filename/path of input csv file, e.g. SeaLevel = SeaLevel.csv, or keyword harmonic to use a harmonic tidal boundary (requires the additional section [[HarmonicTideParameters]], i.e. SeaLevel = harmonic
[[ShotnoiseHydrographParameters]]	Input parameters to the shot-noise hydrograph generator. This sub-section to [BoundaryConditions] is only required/used if RiverFlow = shotnoise
MeanDaysBetweenEvents	Mean time between flow increase events [days] e.g. MeanDaysBetweenEvents = 15
MeanEventIncrease	Mean flow increase associated with each 'event' [m3/s] e.g. MeanEventIncrease = 100
FastDecayRate	Fast flow (runoff) decay rate between events [/day] e.g. FastDecayRate = 0.3
SlowDecayRate	Slow flow (baseflow) decay rate between events [/day] e.g. SlowDecayRate = 0.015
FastFlowProp	Proportion of event flow which is classified as fast flow e.g. FastFlowProp = 0.9
RisingLimbTime	Time for flow to rise prior to event peak [days] e.g. RisingLimbTime = 1.0
HydrographDt	Discretisation interval for generated flow timeseries [mins] (optional, default=60) e.g. HydrographDt = 60
RandomSeed	Optional seed value to initialise random number generator [integer] e.g RandomSeed = 1
HydrographStart	Optional start time to generate hydrograph from (default = model start time). This functionality should be used with RandomSeed to allow hotstarting part finished simulations with synthetic hrdrographs. Specified as a string in the format d mmm yyyy e.g. HydrographStart = 1 Jul 2015
[[HarmonicTideParameters]]	Input parameters to the harmonic tide generator. Only required if SeaLevel = harmonic.
MeanSeaLevel	Mean sea level for generated harmonic tidal boundary [m]. Optional parameter, default = 0. E.g. MeanSeaLevel = 0
TidalRange	Tidal range for generated harmonic tidal boundary [m] e.g. TidalRange = 1.44
SeaLevelDt	Discretisation interval for generated tidal timeseries [mins] (optional, default=60) E.g. SeaLevelDt = 30

[HotStart]

Optional section which can be used to 'hotstart' a model from the outputs of a previous run. Note that if this section is provided then SpatialInputs and InitialConditions are ignored.

Keyword	Description
InitialConditionsNetCDF	NetCDF file from previous model run to use for initial conditions e.g. InitialConditionsNetCDF = ..\ModelOutputs.nc
HotStartTime	Date and time from specified hotstart file to use as initial conditions for new simulation (specified as a string in the format d mmm yyyy) e.g. HotStartTime = '19 Aug 2015 00:00'
ContinueSimulation	Flag to reset start time to be the same as the timestep which is being used for hotstarting. Note that the original StartTime specified in [TimeInputs] will still be used for generating random flow timeseries etc. (True/False, default = False) e.g. ContinueSimulation = True.

[SpatialInputs]

Parameters specifying the spatial arrangement of the lagoon at the start of the simulation. Only required if [Hotstart] is not provided. These can either be provided by specifying:

• shapefiles for Shoreline, RiverLocation, BarrierBackshore and CliffToe - typically these would have been created for a specific real world location; or
• parameters ShorelineLengthLeft, ShorelineLengthRight and BeachWidth to set up a simplified initial conditoin with no lagoon.

Keyword	Description
Shoreline	Filename of a polyline shapefile specifying shoreline initial position e.g. Shoreline = HurunuiShoreline.shp
RiverLocation	Filename of a point shapefile specifying the location the river flows into lagoon e.g. RiverLocation = RiverInflow.shp
BarrierBackshore	Filename of a polyline shapefile specifying the location of the barrier backshore (seaward edge of lagoon) e.g. BarrierBackshore = LagoonPolyline.shp
CliffToe	Cliff toe line (polyline extending over full model domain, even river!) e.g. CliffToe = CliffPolyline.shp
OutletLocation	Initial outlet position (polyline shapefile of outlet centerline) e.g. OutletLocation = InitialOutlet.shp
ShorelineLengthLeft	Model domain extent to left of river centerline when looking to sea [m] e.g. ShorelineLengthLeft = 1000
ShorelineLengthRight	Model domain extent to right of river centerline when looking to sea [m] e.g. ShorelineLengthRight = 1000
BeachWidth	Beach width in initial condition (uniform across whole model domain, no lagoon) [m] e.g. BeachWidth = 50

[InitialConditions]

Some physical parameters relating to the model initial condition. Only required if [Hotstart] is not provided.

Keyword	Description
OutletWidth	Initial outlet width [m] e.g. OutletWidth = 35
OutletBed	Initial bed level of the seaward end of the outlet channel e.g. OutletBed = -1.0
LagoonBed	Lagoon bed elevation [m] e.g. LagoonBed = -1.0
BarrierElev	Barrier crest height [m] e.g. BarrierElev = 3.0

[Time]

Keyword	Description
StartTime	Simulation start date (specified as a string in the format d mmm yyyy) e.g. StartTime = '1 Jul 2015'
EndTime	Simulation end date e.g. EndTime = '30 Jun 2016'
HydDt	Hydraulic Timestep [s] e.g. HydDt = 5
MorDtMin	Minimum morphology Timestep [s] e.g. MorDtMin = 60. This should ideally be an exact multiple of the hydraulic timestep.
MorDtMax	Maximum morphology Timestep [s] e.g. MorDtMax = 1920. During simulation the morphology timestep adaptively changes in the range from MorDtMin to MorDtMax inclusive. It changes by doubling/halving so ideally MorDtMax should equal MorDtMin * 2<sup>N</sup> where N is an integer.

[PhysicalParameters]

Keyword	Description
Kcoef	K coefficient for longshore transport calculation (non-dimensional) e.g. Kcoef = 0.03
RhoSed	Sediment density [kg/m3] (optional, default = 2650) e.g. RhoSed = 2650
RhoSea	Seawater density [kg/m3] (optional, default = 1025) e.g. RhoSea = 1025
RhoRiv	River water density [kg/m3] (optional, default = 1000) e.g. RhoRiv = 1000
VoidRatio	Sediment void ratio (optional, default = 0.3) e.g. VoidRatio = 0.3
Gravity	Gravity [m/s2] (optional, default = 9.81) e.g. Gravity = 9.81
GammaRatio	Ratio of water depth at breakpoint to breaking wave height (WaveHeightAtBreaking = GammaRatio x WaterDepthAtBreakPoint) (optional, default = 0.5) e.g. GammaRatio = 0.5
WaveDataDepth	Depth of output point for wave model data given in WaveConditions file [m] e.g. WaveDataDepth = 10.0
ClosureDepth	Closure depth for single line shoreline model [m] e.g. ClosureDepth = 5.0
BeachSlope	Beach shoreface slope for runup calculation [m/m] e.g. BeachSlope = 0.13
RiverSlope	Initial condition river bed slope upstream of lagoon [m/m] e.g. RiverSlope = 0.003
GrainSize	Median grain size for fluvial sediment transport (D50) [m] e.g. GrainSize = 0.032
CritShieldsStress	Critical shields stress for initiation of bedload transport. See wiki regarding bedload transport for more details (optional, default = 0.0495) e.g. CritShieldsStress = 0.0495
MPM_coef	Coefficient for generalised Meyer-Peter-Muller style bedload transport formula. See wiki regarding bedload transport for more details (optional, default = 3.97) e.g. MPM_coef = 3.97
MPM_exp	Exponent for generalised Meyer-Peter-Muller style bedload transport formula. See wiki regarding bedload transport for more details (optional, default = 1.5) e.g. MPM_exp = 1.5
UpstreamLength	Upstream river length to simulate [m] e.g. UpstreamLength = 1000
RiverWidth	River width upstream of hapua [m] e.g. RiverWidth = 100
RoughnessManning	Fluvial hydraulic roughness (Manning's n) [m(-1/3).s] e.g. RoughnessManning = 0.03
WidthDepthRatio	Width-Depth ratio of eroding channel [dimensionless] e.g. WidthDepthRatio = 30
BackshoreElev	Elevation of top of lagoon backshore [m] e.g. BackshoreElev = 30
MaxOutletElev	Maximum elevation of the downstream end of the outlet channel [m] This elevation is applied downstream of the last real outlet channel cross-section and should be below the minimum sea level. e.g. MaxOutletElev = -2.0
OT_coef	Overtopping coefficient - controls magnitude of overtopping sediment flux [s-1] e.g. OT_coef = 0.0002
OT_exp	Overtopping exponent (recommended value = 2) e.g. OT_exp = 2
OwProp_coef	Overwash proportion coefficient e.g. OwProp_coef = 10
MinOpForOw	Minimum overtopping potential for overwash to initiate e.g. MinOpForOw = 0.0
BeachTopElev	Crest height of 'new' barrier created by longshore transport across river mouth [m] e.g. BeachTopElev = 2
SpitWidth	Crest width of 'new' barrier created by longshore transport across river mouth [m] e.g. SpitWidth = 10.0
MinOutletWidth	Threshold width for setting outlet channel to closed [m] e.g. MinOutletWidth = 1.0
OutletSedSpreadDist	Assumed maximum alongshore distance for spreading gravel discharged from the river onto the shoreline (see inter-model-connectivity). Note that while it is possible to specify any value greater than or equal to AlongShoreDx it is recommended that OutletSedSpreadDist should be an exact multiple of AlongShoreDx (otherwise this will introduce small mass-balance errors due to the way it is implemented) [m] e.g. OutletSedSpreadDist = 100.0
OutletBankEroFac	Proportion of bank erosion occuring on outside bend of the downstream end of the outlet channel. OutletBankEroFac = 0 means there is no preferential erosion of the outside bank (i.e. even split of erosion between banks), OutletBankEroFac = 1 means all erosion occurs on outside bank, and 0 < OutletBankEroFac < 1 weights erosion towards outside bank.
BarrierPermeability	Barrier permeability in m3/s, per m barrier length, per m head difference from lagoon to ocean [m/s] e.g. BarrierPermeability = 0.001 i.e. 1m3/s per km of barrier if there is a 1m level difference between lagoon and sea.
ShorelineErosionRate	Erosion rate of shoreline at edges of model domain [m/yr]. See wiki regarding shoreline erosion rate boundary condition for more details (optional, default = 0.0) e.g. ShorelineErosionRate = 0.5 i.e. 0.5m per year coastal erosion rate would be forced at the edges of the domain.

[NumericalParameters]

Keyword	Description
AlongShoreDx	Alongshore discretisation resolution (transect spacing) [m] e.g. AlongShoreDx = 20
Beta	Momentum (Boussinesq) coefficient (generally in the range 1 to 1.05). Opgional, default = 1.05. Can be set to zero to ignore the convective acceleration term of the momentum equation if desired (for increased stability but reduced accuracy)! e.g. Beta = 0
Theta	Temporal weighting factor for implicit Preissmann scheme (0.5 <= Theta <= 1). Optional, default = 0.7.
Psi	Spatial weighting coefficient for bedload transport (0.5=central, 0-0.5=partial upwinding). Optional, default = 0.4.
ErrTol	Error tolerance for implicit solution to unsteady river hydraulics [m and m/s]. Optional, default = 0.001.
MaxIt	Maximum iterations for implicit solution to unsteady river hydraulics. Optional, default = 30.
WarnTol	Warning tolerance for change in water level/velocity within a single iteration of the hydrodynamic solution [m and m/s]. Optional, default = 0.1.
MaxMorChange	Maximum morphological change per timestep (used for adaptive timestepping) [m]. Optional, default = 0.05.

[OutputOptions]

Keyword	Description
OutFile	Filename of the netCDF file which outputs will be written to (optional, default = filename of the cnf file with the suffix "_outputs.nc") e.g. OutFile = 'ModelOutputs.nc'
TsOutFile	Filename of the netCDF file which high frequency timeseries outputs will be written to (optional, default = filename of the cnf file with the suffix "_TSoutputs.nc") e.g. TsOutFile = 'TsModelOutputs.nc'
OutInt	Interval to save complete output data to netCDF file [s] e.g. OutInt = 3600
TsOutInt	Interval to save high frequency timeseries data to netCDF file [s] e.g. TsOutInt = 900
LogInt	Interval at which progress will be logged to console/logfile during simulation [s] e.g. LogInt = 3600
PlotInt	Interval to update plots (zero means no plotting will occur) [s] e.g. PlotInt = 7200