The XBeach structure

The XBeach structure is a common MATLAB structure having at least one field: data. Other fields are often available too and provide meta data of the XBeach structure. The data field contains a structure array containing at least two fields: name and value. Other fields, again provide meta data on the name/value pairs. The structure array in data has an item for each parameter stored in the structure. The name of each parameter is stored in name and it's value in value. Hence, an XBeach structure looks like this:

% create empty xbeach structure
xb = xb_empty

xb = 

        date: '30-Dec-2010 17:47:25'
    function: 'xb_empty'
        type: ''
        file: ''
        data: [0x0 struct]

The meta information consists of the modification date, the name of the last modifying function, the type of structure and the file(s) from which the data is obtained. The latter two being empty in this case. The XBeach structure contains no data since data is empty. Many functions output XBeach structures, at least all xb_generate_* functions do so. Two examples:

xbm = xb_generate_model

xbm = 

        date: '30-Dec-2010 17:47:25'
    function: 'xb_generate_model'
        type: 'input'
        file: ''
        data: [1x21 struct]

fpath = fullfile(strrep(abspath(fileparts(which(mfilename))), [filesep 'trunk' filesep], [filesep 'test' filesep]), 'datoutput', '2D');

xbo = xb_read_output(fpath)

Error using ==> xb_read_output at 79
File does not exist [e:\Temp\tpd74361c1_bdec_4ee9_a597_3ec30e27a41f\datoutput\2D]

Error in ==> xb_structure_tutorial at 37
xbo = xb_read_output(fpath)

Error in ==> evalinemptyworkspace>eval_fun at 8
eval(getappdata(0,'emptyworkspaceevaluation'));

Error in ==> evalinemptyworkspace at 3
eval_fun();

In these examples the structures contain data. The data field of the latter structure looks like this:

xbo.data

The data field apparently contains 5 variables of which the first two look like this:

xbo.data(1)

xbo.data(2)

We can see that the first parameter is a structure again. Displaying the contents of this variable reveals that this is a nested XBeach structure generated by the xb_read_dat function and containing 22 variables being dimensions.

xbo.data(1).value

% check if this really is a XBeach structure
xb_check(xbo.data(1).value)

Also the XBeach structure obtained from the xb_generate_model function contains nested XBeach structures, for example:

xbm.data(12).value

{xbm.data(12).value.data.name}
{xbm.data(12).value.data.value}

The structure of the XBeach structure as explained in the previous section is extremely felxible, but it's a tedious job to find and read data in that structure. Not to speak of altering data. In order to make XBeach structures better accessible, a variety of functions is developed. We start off with xb_show. This function does, what we manually did in the previous section: it reveals the contents of an XBeach structure and works like the whos function in MATLAB.

xb_show(xbo);

We see the meta data of the XBeach structure on top and a list of variables in the XBeach structure below. The list also displays the dimensions, size and type of the variables and, if possible, the contents. We can access nested XBeach structures, be requesting their specific name:

xb_show(xbo, 'DIMS');

It is also possible to filter the list of variables in a similar manner as can be done with the xb_read_output function (see the 3. Reading your model results).

% this list is too long
xb_show(xbm);

% only display the variables starting with a _z_
xb_show(xbm, 'z*');

% or having exactly four characters
xb_show(xbm, '/^.{4}$');

Now we can easily examine the contents of an XBeach structure, we also need to be able to access these contents. For this purpose, the xb_get function is available.

% retrieve bathymetry from XBeach output structure
zb = xb_get(xbo, 'zb');

% retrieve multiple variables at once
[zb zs u v] = xb_get(xbo, 'zb', 'zs', 'u', 'v');

% retrieve a nested structure
dims = xb_get(xbo, 'DIMS');

Accessing variables in a nested structure can be done directly using the dot symbol:

[nx ny] = xb_get(xbo, 'DIMS.globalx', 'DIMS.globaly');

If a requested variable does not exist, an empty vector is returned. The existance of a variable can be checked using xb_exist which returns the number of variables that exist from the given selection.

xb_exist(xbo, 'zb');
xb_exist(xbo, 'zb', 'zs');
xb_exist(xbo, 'zb', 'xb');
xb_exist(xbo, 'xb');

Modifying variables in an XBeach structure is possible using the xb_set function. This function works similar to the xb_get function. If a variable does not exist, it is created.

xbm = xb_set(xbm, 'dtheta', 10);
xbm = xb_set(xbm, 'thetamin', -45, 'thetamax', 45, 'dtheta', 10);
xbm = xb_set(xbm, 'bcfile.Hm0', 9);

Variables can be deleted and renamed:

xbm2 = xb_del(xbm, 'dtheta');
xbm2 = xb_rename(xbm2, 'instat', 'instat_old');

Multiple XBeach structures can be joined and splitted. The meta data from the left-most structure is used and it's variables are overwritten in order from left to right.

xbm3 = xb_join(xbm, xbm2);
[xbm4 xbm5] = xb_split(xbm3, {'thetamin', 'thetamax'}, {'instat', 'instat_old'});

xb_show(xbm5);

Setting meta data in your XBeach structure and consolidating the data goes like this:

% create XBeach structure
xb = xb_meta(xb_empty, mfilename, 'dummy', 'some_file_name');

% put some data in it
xb = xb_set(xb, 'a', [1 2 3 4 5], 'b', [2 2 2 2 2], 'c', [5 5 5 5 6]);

% show it
xb_show(xb);

% consolidate it
xb = xb_consolidate(xb);

% show it again
xb_show(xb);