%% The XBeach structure
%
% In order to facilitate easy access to complex models in the XBeach
% Toolbox, the XBeach structure is used. An XBeach structure is a MATLAB
% struct having a certain generic structure. This structure and several
% functions that provides easy access to XBeach structures is explained in
% this tutorial.

%% Structure of 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

%%
% 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

%%

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

xbo = xb_read_output(fpath)

%%
% 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

%%
%  We can check if this really is a XBeach structure as follows:

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}

%% Accessing the XBeach structure
%
% 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
% <xb_readresults_tutorial.html 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 the XBeach structure
%
% 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);

%%
% The links in the _xb_show_ result enable you to interactively modify and
% query the displayed XBeach structure. Access to plotting and run routines
% are also available.
