Adding a model setup to the skillbed

To add your XBeach model to the skillbed one has to take the following actions:

  • Create a checkout of the skillbed repository: https://svn.oss.deltares.nl/repos/xbeach/skillbed/
  • Create a test directory with the name of the test in the input directory
  • Create a working model in the test directory. It is possible to group related tests in a single directory. Simply use subdirectories for this purpose. In the test configuration file, the subdirectories should be mentioned (see further down).
  • Create a Matlab script that analyses the model output in the test directory (to include images in the skillbed report)

The Matlab script takes two arguments: info and dirs. Both arguments are structs that have the following contents:

 info = struct( ...
    'revision', 1234, ...                                                       // revision number of current binary
    'binary',   'trunk', ...                                                    // name of current binary
    'type',     'custom',                                                       // mode of current run
    'test',     'CarrierGreenspan',                                             // name of current test
    'run',      'default' ...                                                   // name of current run
);

dirs = struct( ...
    'output',  'C:\TESTBED\analysis\trunk\custom\CarrierGreenspan\default', ... // Path where output should be stored
    'data',    '', ...                                                          // Path where static data can be found
    'network', 'P:\STORAGE\DATA\CarrierGreenspan' ...                           // Network storage that can be used
);
  • Create a configuration file called .config in the test directory

The configuration file has the following or similar contents:

 [general]                               // SECTION: General information
enable          = 1                     // Enable test in testbed
runs            = default, stationary   // Definition of test runs
responsible     = Bas Hoonhout          // Name and e-mail of maintainer

[run_default]                           // SECTION: Configuration of test run "default"
enable          = 1                     // Enable run in testbed
params          = params_original.txt   // Parameter file to use in run
binaries        = all                   // Binaries that should use this run
types           = all                   // Modes in which this run should be used (custom/default/all)
platforms       = all                   // Platforms on which this run should be used (win32/unix/all)
nodes           = 1                     // Number of nodes that should be used during this run (> 1 for MPI)
analysis        = analyze_this          // Matlab function to be used for the postprocessing of the results

[run_stationary]                        // SECTION: Configuration of test run "stationary", see above
enable          = 1
params          = params_stationary.txt
binaries        = trunk, speedup
types           = custom
platforms       = win32
nodes           = 1
analysis        = analyze_this

[categories]                            // SECTION: Category definitions used for classification of test
configuration   = 1D                    // Grid configuration (1D/2D)
waves           = stationary            // Wave configuration (stationary/non-stationary)
waterlevels     = constant              // Water level configuration (constant/varying)
morphology      = no                    // Morphology configuration (yes/no)
fractions       = 1                     // Number of sediment fractions
hardlayers      = no                    // Hard layer configuration (yes/no)
groundwaterflow = no                    // Ground water flow configuration (yes/no)

 

If you use subdirectories to group related model setups, the configuration file(s) can be stored in the root directory or in any subdirectory. The location of the configuration file determines where the model setup definition end and the run definition starts. In case the configuration file is located in one or more subdirectories, the names of the subdirectories are concatenated to the name of the model setup, separated by an underscore (_). Any other subdirectories should be mentioned in the run definition of the configuration file itself. In the path of directories to a configuration file, no other configuration files may be found, otherwise this configuration file is used instead.

A simple script to generate a default configuration file can be found in the root of the input directory. It searches for subdirectories to be interpreted as runs or otherwise generates a single run for the root directory. Please at least alter responsibilities and characteristics of the model setup manually.

  • Create a TEX file in the latex/_tests directory with a descriptive text for the added model setup and references to the postprocessing output

Images are referenced to as shown below. The first argument is the path containing the model setup and run name of the output. The second argument is the file name to be referenced. The third argument is an optional caption of the image.

${tools.image('CarrierGreenspan/default/', 'fig1.eps', 'Model output')}

Tables are referenced in a similar manner:

${tools.table('Assateague_Island/profA/', 'conditions.tex', 'Hydrodynamic boundary conditions XBeach simulations')}

  • Create one or more references to the model setup description TEX file in one or more documents

References to descriptive texts are made as follows:

<%include file="carriergreenspan.tex"/>

  • Commit the additions to the Subversion repository

Troubleshoot

Sometimes the resulting report is not what you expected. The following information might be relevant to get the report just as you want.

  • References turn into question marks (??)

The reference is not valid. Please make sure you use the full reference identifier: <name of model setup>_<run name>_<filename> without extension for generated files. For static files that are not generated by the analysis scripts, you simply use the filename without extension.

  • My formulas are not aligned as they should

Often formulas are aligned using table-like alignment commands. These end in line endings (two back-slashes). This line ending is also the command for Python to concatenate lines to a single line. In order to use the former functionality only, simply add a space after the line ending command.

 

Coding guidelines

The Matlab XBeach Toolbox is available within the skillbedbed environment. The following commands from this toolbox are preferred to use, including the names of the variables. Please see the corresponding documentation for the exact syntax:

 % Read model dimensions
d = xb_read_dims;

% Read model input
xbi = xb_read_input;

% Read model output
xbo = xb_read_output(pwd, 'vars', { ... }, ...);

xbo = xb_peel(xb_read_output(pwd, 'vars', { ... }, ...));

% Generate grid information
s = xb_stagger(d.x,d.y);

% Analyze output
xbh = xb_get_hydro(xbo, ...);

xbm = xb_get_morpho(xbo, ...);

xbt = xb_get_sedtrans(xbo, ...);

xbs = xb_get_spectrum(xbo, ...);

% Create figures and tables
xb_plot_profiles(xbo, ...);
xb_plot_profiles(xbo, 'measured', [x y], 'durosta', [x y], ...);

xb_plot_hydro(xbh, ...);
xb_plot_hydro(xbh, 'Hrms_lf', zs, 'Hrms_hf', H);

xb_plot_morpho(xbm, ...);

xb_plot_sedtrans(xbt, ...);

xb_plot_spectrum(xbs, ...);

xb_write_skilltable(xbo, [x y]);

% Miscellaneous functions
path = fullfile( ... );
k = disper(w,h);
S = xb_spectrum(zs);
[r2 sci relbias bss] = xb_skill( ... );