Skip to content

Outputs

This page describes the different parameters that affect the way outputs are generated by BG_Flood.

Default behaviour

If you do not specify any output parameters BG_Flood will still produce outputs for variables zb, zs, u, v, h in a file called Output.nc at the start and end of the model run. Default behaviour is fine but most user will want to change these to their needs.

Snapshot output file

outfile = controls the output file name. It can be anything you like but we recommend avoiding spaces and keeping the extension .nc.

BG_Flood will never overwrite an existing output file. Instead it will try to add _1 at the end of the name and iterate that number until a free number is find.

CF-compliant NetCDF files

BG_Flood netcdf output files are CF compliant. They include a lot of metadata that is useful for the user and for using the files elsewhere (e.g. QGIS, ncview...): * Includes CRS info if available in the input * Self describing variables * Compliant time variable

Outputting variable resolution grids

Variables in the output file may be connfusing at first. You will typically see things like u_P0 and zs_N1. the first part is the variable true symbol (here u and zs) but anything after the _ is about the level of refinement. Thjis allow variables to be stored at their true resolution in the model and still form a grid for each level of refinement/resolution. N1 stand for level -1, P2 stands for level 2, and P0 stands for level 0 (default reference level).

Example

If you setup a model with 6 level of resolution going from -3 to 2, output variables will come with _N3,_N2,_N1,_P0,_P1,_P2 attached to their names, each representing a grid with its own resolution.

If you want to load the water level output in say QGIS. You will need to load 6 grids in QGIS : zs_N3,zs_N2,zs_N1,zs_P0,zs_P1,zs_P2 and make sure that NaN values are treated as transparent.

output parameters

See manual section for output parameters. All computed parameters can be outputted. However beware in trying to output variables from a module that is not used in the model. this will make the model crash.

Some parameters are averaged or maximum (e.g. zsmean, hmax) For maximums you can reset the maximum to be the maximum values since last output step using

resetmax = true

Averaged variable are always reset at every output.

output times

BG_Flood will always output model's initial condition and last step. In between you can output every time interval: e.g. outputtimestep = 36.0; to get every 36s since the start of the simulation till the end.

or specify desired times: e.g. Toutput=5.5,0|2.2|4,3.0 will output at 0.0, 2.2s, 3.0, 4.0, 5.5s, after the reference time. The first and last number are seen as second after after the reference time and the 3 numbers separated by | are understood as a range.

outputtimestep = is generally sufficient for most usage but Toutput= is powerful for specifying flexible and precise time. It can also use DateTime format as long as reftime or starttime are specified in the param file. e.g.

Toutput=2020-01-01T00:00:00|1h|2020-01-01T12:00:00,2020-01-01T00:00:03

means output from 2020-01-01T00:00:00 every 1 hour till 2020-01-01T12:00:00 and also 2020-01-01T00:00:03.

output zones

When simulating very large domain it is useful to output only area of interest. This can be done with output zones:

outzone=MyZoneNameb.nc,x1b,x2b,y1b,y2b;

alternatively you can specify what timeyou want to save for that zone:

outzone=zoomed.nc,5.3,5.4,0.5,0.8, 3600:360:7200;

where x1b,x2b,y1b,y2b are the bounding box coordinate of the output area.

Note that The output will not cut a modelling block so the output area may be larger than specified in the outzone.

Additional parameters

  • smallnc when true (default is false) the variable in the netcdf file are shifted and scaled to short integers making the output very small. scalefactor and addoffset parameters controls the scaling to short integer.

  • outishift and outjshift Will allow you to shift the output by 1 cell to see the values in the ghost cells (default is 0 but values can only be -1, 1 or 0)

  • savebyblk makes the model write a single block at a time. this is normally the best way to save to the disk. On some computers the overhead cost of the netcdf write function is way higher. in those case it is way faster to save an entire level at once in some configuration this will require a huge amount of memory. In that ccase consider using a outzone.

  • crs_ref BG_Flood automatically copies

Timeseries Output

BG_Flood allow users to extract timeseries out of the model:

TSnodesout=OutputTSfile.txt,xloc,yloc;

where OutputTSfile.txt is the file where the data will be saved, xloc,yloc are the coordinates off the location for the output.

The user cannot specify when/how often to output. instead you get all the time steps for that location. Intermnally the model copies the data to a GPU buffer that is flushed to the CPU and later to the file either at the same time as saving a map output or when the buffer is full.

Timeseries output are only available for evolving parameters of the hydrodynamic part of the model: zs, h, u and v.