2. Running your model

To run an XBeach model setup, you can supply the XBeach structure containing the model to the xb_run function. This function writes the model to disk, downloads the latest XBeach executable for your operating system and needs from TeamCity and forks a process that runs the model. The function returns another XBeach structure containing information on the model run like process id and location.

% setup dummy model
xbm = xb_generate_model;

% run dummy model
xbr = xb_run(xbm);

In the way described above, the model is ran in the current directory with the latest executable from TeamCity on a single node with DAT output only. These options can be changed as follows:

% running the model in a different location
xbr = xb_run(xbm, 'path', 'path_to_model/');

% running the model with a different executable
xbr = xb_run(xbm, 'binary', 'xbeach.exe');

% running the model on multiple cores (not yet implemented)
xbr = xb_run(xbm, 'nodes', 4);

% running the model with netcdf output
xbr = xb_run(xbm, 'netcdf', true);

The xbr variable containing information on the model run can be used to read the model output once the model has finished running. The variable can also be used to monitor whether the model has finished already or not.

% check if model is still running
if xb_check_run(xbr)
    finished = false;
else
    finished = true;
end

% display a message once the model is finished
xb_check_run(xbr, 'repeat', true);

Large XBeach models may be too time consuming to run locally on your own desktop. Cluster computing is a solution to this problem. Via SSH XBeach model runs can be started on a remote cluster on multiple nodes. To accomodate this procedure, the xb_run_remote function is developed. It works similar to the xb_run function except it needs a username and password to log on to the cluster.

% run a dummy model remotely
xbr = xb_run_remote(xbm, 'ssh_user', 'user', 'ssh_pass', 'pass');

% you can also ask the function to prompt for a username and password
xbr = xb_run_remote(xbm, 'ssh_prompt', true);

The same options as for the xb_run function are available for the xb_run_remote function, except for the path option, which is called path_local to distinguish from the option path_remote. The former contains the path to the model on disk seen from the local computer, while the latter contains the same path seen from the cluster computer. By default, the models are ran on the cluster computer called h4 via the home directory of the current user:

% default settings for xb_run_remote
xbr = xb_run_remote(xbm, 'ssh_host', 'h4', 'path_local', 'u:\', 'path_remote', '~/');

The status of the remote run can be monitored in the same way as a local run:

xb_check_run(xbr, 'repeat', true);