Introduction

The XBeach Toolbox in the OpenEarthTools repository tries to provide a generic and easy-to-use Matlab interface to the XBeach model.

How can I obtain the XBeach toolbox?

Download it from the OpenEarthTools subversion repository: https://repos.deltares.nl/repos/OpenEarthTools/trunk/matlab/applications/xbeach/

What will I download?

Unknown macro: {table-plus}

Toolbox	Collection	Subcollection	Description
XBeach	xb_io		Low-level I/O functions. Return XBeach structures containing the contents of any XBeach file.
		xb_dat	Low-level function for XBeach DAT files. Return contents of an XBeach DAT file or information about an XBeach DAT file, mainly type and dimensions.
	xb_human		Mid-level functions to interact with XBeach structures as supplied by the xb_io and xb_modelsetup toolboxes. Displays, adds, modifies, deletes, checks, merges, splits, renames contents of XBeach structures in a way understandable for human beings.
	xb_modelsetup		Mid-level functions for model setup. In fact, a collection of xb_generate_* functions that all supply a part of an XBeach settings structure, which can be written to disk as a fully functional XBeach model by the xb_io toolbox.
		xb_grid	Mid-level functions for grid generation. Generates XBeach settings structures containing grids based on bathymetries, waves, etcetera.
		xb_bc	Mid-level functions for boundary conditions generation. Generates XBeach settings structures containing waves and tide data.
	xb_run		High-level functions to run XBeach settings structures as an actual model. Functions to write XBeach settings structures to disk, obtain the latest XBeach binaries applicable in the current situation from the TeamCity build server and start the model.
	xb_visualise		High-level functions to visualise XBeach structure contents. Basic functions to visualise XBeach input and output stored in a XBeach structure.
		xb_output_gui / xb_result_viewer	High-level functions to build advances visualisations of XBeach structure contents.
	xb_analysis		High-level functions to analyse XBeach output structures.
	xb_nesting		High-level nesting functions to nest XBeach models in other models like Delft3D.
		xb_swan	Helper functions for SWAN input/output.
		xb_delft3d	Helper functions for Delft3D input/output.
	xb_lib		Low-level miscellaneous functions.
	xb_gui		Graphical User Interface for the toolbox (under construction).

How do I use it?

See the tutorials in the OpenEarthTools wiki space: [OET:Matlab Tutorials]

How do I contribute?

Script and commit!

Please not the following conventions, next to the general OpenEarthTools coding conventions (like documentations, test functions, etc):

All function names are prefixed by "xb_"
(Parts of) XBeach model configurations or output are structured in a generic Matlab structure (see XBeach structure)
Functions are minimal. All functions have their own tiny task. Only combined they will show their strength!
Functions do not output to the screen. If all minimal functions output to the screen, it will be a mess!. So, no output unless explicitly requested (e.g. xb_plot_*, xb_show, etc)

">XBeach structure

A few very specific functions in the XBeach Toolbox just return the desired result. If any flexibility of the returned value is needed, the XBeach structure is used. For example, the result of the xb_read_input function, which reads an entire model input, returns such a structure. Several XBeach structures can be nested into each other. The xb_human collection of functions provides low-level interaction functions for the XBeach structure.

Format

An example of a full-formatted XBeach structure is given below. The "data" field contains the actual data. All other fields contain meta-information added by the several toolbox functions.

xb = struct(
    'date',     '01-Dec-2010 00:00:00'
    'function', 'xb_read_input',
    'type',     'input',
    'file',     'C:\path_to_model\params.txt',
    'data',     [1x7 struct]
);

The field "data" contains a structure array, which contains the actual data. An example of such structure array is:

data = struct(
    'name',  {'nx', 'ny', 'xfile',      'yfile',      'depfile',    'xori', 'yori' },
    'value', {200,  3,    [1x1 struct], [1x1 struct], [1x1 struct], 12345,  67890  },
    'units', {[],   [],   [],           [],           [],           'm',    'm'    }
);

The fields "xfile", "yfile" and "depfile" are nested XBeach structures, which can look like this:

bathy = struct(
    'date',     '01-Dec-2010 00:00:00'
    'function', 'xb_read_bathy',
    'type',     'bathymetry',
    'file',     {'C:\path_to_model\x.grd', 'C:\path_to_model\y.grd', 'C:\path_to_model\bed.dep'},
    'data',     [1x3 struct]
);

Again, all fields contain meta-information except the "data" field. The "data" field contains a structure array which can look like this:

data = struct(
    'name',  {'xfile',        'yfile',        'depfile'      },
    'value', {[200x3 double], [200x3 double], [200x3 double] },
    'units', {'m',            'm',            'm'            }
);

Usage

The xb_human function collection provides low-level functions to interact with the XBeach structure. The most important functions are described in the following table:

Function	Description
xb_empty	Returns an empty XBeach structure
xb_set	Sets one or more specific fields in a XBeach structure or nested structure
xb_get	Returns one or more specific field values from a XBeach structure or nested structure
xb_meta	Sets meta-information in XBeach structure (date, function, type and filenames)
xb_check	Returns a boolean indicating if the supplied variable is a valid XBeach structure
xb_show	WHOS-like display of XBeach structure or nested structures with regexp-based filtering

Space shortcuts

Child pages