FAQ - XBeach
Where do I start? ▶
You'll need a free OSS account to become part of the XBeach community. With this account you can access the Subversion repository to download the XBeach source code and the Matlab toolbox, participate in the forums and access all other features of the XBeach community.
If you already have a OSS account, you are all set. If you do not have an account yet, please click on "Sign In" in the upper-right corner of this page to start registration. If you are already logged in, the link is not present and you are already registered.
If you want to start developing XBeach, you will need to upgrade your account to have write access to the Subversion repository. You can request such an update by contacting the development team.
It is also possible to start using XBeach without registration by just downloading a pre-compiled version of the source code and start modelling. However, in order to monitor the different fields of application of the model and thereby anticipate on the users of XBeach, registration is greatly appreciated.
How do I download XBeach? ▶
To start modelling using XBeach, you will need to download it first. In principle, there are two options:
- Download the XBeach source code and compile the executable yourself
- Download a pre-compiled executable suitable for you operating system and needs
Download source code
In order to download the XBeach source code, again two options are available:
- Subversion (https://svn.oss.deltares.nl/repos/xbeach/trunk)
- ZIP file
Subversion is a well-known version management system that allows you to always have the most recent source code at hand. It also allows developers to commit changes to the source code, without interferring with other developers. In order to use Subversion, you will need a Subversion client. A well-known client for Windows is Tortoise. If you have registered, you can download the source code via the following URL: https://svn.oss.deltares.nl/repos/xbeach/trunk.
If you do not want to use Subversion, you can download prepared ZIP files with the entire source code from our Source code page. Please be aware that different versions of XBeach can be downloaded and that the most recent ZIP file does not necessarily contain the most recent XBeach version.
Download pre-compiled executable
You can download pre-compiled executables for Windows systems. XBeach is tested for 32-bit Windows versions and on a CentOS Linux system, that is closely related to the Red Hat Linux system. The available downloads are listed on Source code page. Please be aware that different versions of XBeach can be downloaded and that the most recent executables are not necessarily the most recent XBeach version.
As you will see on the download page, XBeach comes in different flavours. Next to the regular XBeach executable, you will find the following executables:
- MPI
- netCDF
- MPI + netCDF
The MPI executable enables you to use a parallel programming application like MPICH2 to run XBeach over multiple processors and/or computers. The netCDF executable enables you to write XBeach output to a netCDF formatted file, which is particulary interesting for large models and publication of data. The last type of executable enables you to use both.
If you choose to download pre-compiled executables, you can skip the next step in the current menu .
How do I compile the source code ▶
If you downloaded the XBeach source code, you have to compile it in order to use the XBeach model. If you downloaded a pre-compiled version of XBeach, you can skip this entire step.
XBeach is written in Fortran and can be compiled on either a 32-bit Windows system or a UNIX system. XBeach is tested with two compilers on the following platforms:
- Windows XP 32-bit with the Intel Fortran compiler
- CentOS Linux (similar to Red Hat Linux) with the Intel Fortran or GFortran compiler
Other Windows and Linux platforms may not pose any problems, but it hasn't been tested officially yet. If you experience any problems on other Windows of Linux platforms, please describe the problem in the Compiling XBeach forum in the Forum page and we will try to help you out. Other compilers may pose problems and are not supported for now.
Use the Intel Fortran compiler
If you use the Intel Fortran compiler, the easiest way is to use this compiler from either the Visual Fortran or the Visual Studio 2008 (see figure) software development suites. You can open the corresponding project files in the trunk or the trunk/VS2008 directory and compile the entire project after selecting the right build (MPI, netCDF, debug, etc.)
How to use the GFortran compiler ▶
Use the GFortran compiler
From the UNIX command line, go to the trunk directory of the XBeach source code location.
You can now compile XBeach by issuing the following commands:
>> ./configure
>> make
This command can be preceded by on of the following commands, to clear previously compiled parts of XBeach:
>> make clean
>> make distclean
Compiling XBeach using a specific compiler version is done by altering the first command a bit:
>> FC=gfortran44 ./configure
In order to compile XBeach with MPI support, the this command can again be altered slightly:
>> FC=gfortran44 ./configure --with-mpi
>> FC=gfortran44 MPIFC=/opt/mpich2-1.0.8-gcc44-x86_64/bin/mpif90 ./configure --with-mpi
The same can be done for done for netCDF support:
>> FC=gfortran44 ./configure --with-netcdf >> FC=gfortran44 PKG_CONFIG_PATH=/opt/netcdf-4.1.1/gfortran/lib/pkgconfig ./configure --with-netcdf
Or both:
>> FC=gfortran44 ./configure --with-mpi --with-netcdf
>> FC=gfortran44 MPIFC=/opt/mpich2-1.0.8-gcc44-x86_64/bin/mpif90 PKG_CONFIG_PATH=/opt/netcdf-4.1.1/gfortran/lib/pkgconfig ./configure --with-mpi --with-netcdf
If you use the Intel Fortran compiler on a UNIX system, you might need to initialize the compiler by the following command:
>> . /opt/intel/Compiler/11.0/081/bin/ifortvars.sh ia32
If you use MPI support, please make sure that the MPI software is added to your path:
>> export PATH="/opt/mpich2/bin:${PATH}"How to compile XBeach as a Library ▶
The GFortran compiler and the XBeach library
Nowadays, XBeach can be compiled as library. In fact, XBeach is always compiled as library, possibly with a wrapper binary calling this library. See the following examples on how to deal with this new program structure and the GFortran compiler.
If this doesn't work you might need to specify a MPI compiler specifically by adding the MPIFC environment option (of course, the path may be different):
# this will put xbeach in the /home/user/xbeach-r1234/bin directory ./configure --prefix=/home/user/xbeach-r1234 && make install # this will put xbeach shell script + .libs directory in the current directory ./configure & make # this will create an xbeach wrapper script and .libs directory for multiple versions mkdir r1234 mkdir r1235 svn up -r1234 cd r1234 ../configure make cd ../r1235 ../configure make # this will make xbeach versions in multiple directories mkdir ~/xbeachr1234 mkdir ~/xbeachr1235 svn up -r1234 ./configure --prefix=$(cd;pwd)/xbeachr1234 make install make clean svn up -r1235 ./configure --prefix=$(cd;pwd)/xbeachr1235 make install # this debugs xbeach ./libtool --mode=execute gdb ./xbeach # this shows what xbeach is linked against ./libtool --mode=execute ldd ./xbeach # otool -L in OSX # this debugs xbeach in mpi in 2 different terminals mpirun -np 2 xterm -e ./libtool --mode=execute gdb ./xbeach
All paths in the examples above might need to be altered to fit the local environment.
How do I set up the XBeach model? ▶
XBeach is configured using a collection of files that hold information on the bathymertry, boundary conditions, model settings, etcetera. All files are plain text files that should be in a single directory, the model run directory. Running the XBeach executable in this directory, will make XBeach use those files and save the model output in the very same directory.
Setting up a model implies creating these files in any way of your preference. Common tools that are used to setup an XBeach model are:
RFGrid and QuickIn
Matlab and the OpenEarth Matlab toolbox for XBeach
Python
How these files should look like is described on the XBeach documentation website at:
This website also provides some basic tutorials and example model schematizations.
How do I run the XBeach model? ▶
You can run your model by simply executing the XBeach executable in the directory where you wrote your models settings to. This is the directory where the params.txt file is located. The model output will be a netCDF file (extension: NC).
Where can I find more examples, deeper information? ▶
Hopefully you have a general idea about what XBeach modelling is like. Of course, the examples are not very elaborated and the XBeach model has many features you still have to explore. However, in the previous pages we tried to supply you with and introduce you to the tools necessary for this exploration.
So, what's next? We suggest you do anything (or all) of the following:
- Have a look at the example models
- Read the manual.
- Start modelling and join and initiate the discussions on the forum