Compiling, installing, and running Delft3D on Ubuntu Linux

Here are my notes on compiling Delft3D on a fresh Ubuntu install. Lines beginning with "$" indicate commands entered on command line. Of course, don't enter the $ part.

1. Installed ubuntu 12.04.1 LTS 64-bit release on a 2007-era Dell OptiPlex 745, with a Core2 2.16 GHz processor and 2GB RAM. This process is straightforward and involves downloading an ISO file, burning it to a CD (or DVD) and following the steps on the installation. I went with an LTS release because I don't enjoy re-installing operating systems every 18 months. Note also that I got the 64-bit release, not 32-bit, and that I haven't yet gotten Delft3D to take advantage of both cores.
2. Once Ubuntu was installed, I installed an SSH server so that I could access my machine from my primary workstation.
   $ sudo apt-get install openssh-server
3. Then I restarted the machine and performed updates:
   $ sudo apt-get update; sudo apt-get upgrade
4. Now it's time to beging the Delft3D install. I mainly followed the official installation instructions found here. You should use those as your primary resource; my notes here are the extra things I had to do that weren't explicitly noted in the installation isntructions.
5. On a freshly installed systems, many packages need to be added. I had to install the following 11 packages. You can install them with several sudo apt-get install commands, or you can combine all the packages into a single command as shown below.
   $ sudo apt-get install subversion autotools-dev autoconf libtool g++ expat gfortran mpich2 flex bison libreadline6-dev
6. Next, you need to get the Delft3D source code. At the time of this writing, the most recent tag is 4440.
   $ svn checkout https://svn.oss.deltares.nl/repos/delft3d/tags/4440 d3d
   This checks out the source code to your local machine. I had to enter my username as nowacki@X when prompted, since that seems to be how usernames on Deltares's SVN system are set up. Note: this is a several-hundred MB download.
7. After checkout, enter the d3d/src directory and run
   $ ./build.sh -gnu -64bit
   This produced an error: 20130205.152505 :: Configure fails!
   OK. look in logs/configure.log. Says it can't find expat.h. Google and find that I need to install libexpat1-dev:
   $ sudo apt-get install libexpat1-dev
8. Now try building again:
   $ ./build.sh -gnu -64bit
   This again produced an error: 20130205.153044 :: Make fails!
   I look in logs/make.log and note that make can't find mpif90, which needs to be installed:
   $ sudo apt-get install libopenmpi-dev
9. Let's try building one more time: $ ./build.sh -gnu -64bit
   Another complaint about mpich. Here, I backed up build.sh and changed the location for the mpich2 stuff, which was hard coded into build.sh, but editing the relevant lines in the file to be the following:
   export MPI_INCLUDE=/usr/include/mpich2
   export MPILIBS_ADDITIONAL="-L/usr/lib/mpich2 -lfmpich -lmpich -lmpl"
   export MPIFC=/usr/bin/mpif90
   This changes the lines to look in the right locations for the default installation on an Ubuntu system. Doing this resulted in a very pleasing 20130205.155421 :: Build finished.
   
10. OK! Now we are getting somewhere. Run one of the test cases by executing ./run_flow2d3d.sh in, say, the 01_standard directory of the examples directory.

Looking at test case output

To look at your newly modeled testcase data, I suggest using quickplot. It took me a while to figure out how to access it. I copied the quickplot directory from src/tools_lgpl/matlab in the Delft3D repo checked out in the steps above from the Linux modeling machine to my Windows workstation, which has Matlab installed (R2012A at the time of writing). In Matlab, I changed to the relevant directory and ran make_d3dmatlab on a whim, and to my amazement it created a new delft3d_matlab directory. I then ran d3d_qp and got a nice GUI that popped up and allowed me to open and examine output files from the 01_standard testcase.

Quickplot is also available in the Delft3D GUI, described below.

Generating input files and running models other than testcases

For a first attempt, I used Delft Dashboard, which is part of OpenEarthTools, for generating input files. I followed these instructions, because the packaged files available on the Delft3D website didn't work for me (they require an older version of Matlab Compiler Runtime, and I already have full-fledged Matlab on my workstation anyway). I did the svn checkout on my Linux box and copied the files over to my Windows workstation so I didn't have to mess with installing TortoiseSVN on Windows. Note: if you checkout the entire openearthtools directory structure, which is recommended, it's a 1.3 GB download.

$ svn checkout https://svn.oss.deltares.nl/repos/openearthtools/trunk/ oet

Then copy the oet directory to the computer you have Matlab installed on. Start Matlab, change to that directory, and run oetsettings. Then, within Matlab, go in to applications/DelftDashBoard, and type ddb at the command line to start Delft Dashboard. From here, follow this tutorial to get started with making your own model.

Using the Delft3D GUI

I found Delft Dashboard to be pretty limiting and wanted to be able to create my own bathymetry, grids, and input files. For this, you want to use the Delft3D GUI, which is available only in binary form from the Deltares website.

Note: I have switched to using the GUI on Windows as described below.

You'll have to request the GUI binaries from Deltares by sending an email following the instructions here, under "temporary extra service." You will get access to the RPMs via an FTP site. Because this is Ubuntu, not Red Hat, and also because I wanted control over where the files were placed, I extracted the RPM to the local directory. I originally was going to convert the RPM to a .deb using the alien package, but that produced errors regarding 32-bit/64-bit incompatibility, so I did the following:

This will produce the appropriate directory structure in the current directory. I moved opt/delft3d into /opt/delft3d in case any directories were hard-coded. Because this is a 64-bit system, you must install 32-bit libraries with

sudo apt-get install ia32-libs

You will also need to install the 32-bit libjpeg libraries:

Now follow the instructions on the Deltares website to change the 5.0 directory structure to 4.0 directory structure and move the binaries as directed into /opt/delft3d (scroll down to "Using the GUI menu").

Finally, go into etc/profile.d (from the RPM you extracted) and edit delft3d.sh to point to the correct Delft3D locations. As in the official instructions, dot the profile so your environment variables are set up correctly.

Now change to delft3d/intel and run ./delft3d-menu. If all has gone well, you should be looking at the GUI screen! I had to set up a local X server on my Windows workstation and run the GUI on the Ubuntu modeling machine, tunneling X over SSH. If you are working locally on the Ubuntu machine, you won't have to do this.

Getting RGFGRID and other modules to run requires some editing of config files as described in this forum post.

You will also need to execute sudo apt-get install tcl8.4:i386 tk8.4:i386 for some of the menus to work properly in the GUI.

Using the Delft3D GUI under Windows

After a day or so of using the GUI to run the tutorials under Linux, I decided it was too buggy and gave the Windows GUI a try. This was a sanity-saving move. The Linux GUI kept crashing without warning when performing simple tasks in, for example, QUICKIN. Luckily, you can download the Windows binaries using the same username and password you got for the Linux GUI download, and use the same license file to run it. So far, I've found the Windows GUI to be much more stable. In practice, I generate all the input files (grid, bathymetry, MDF, etc) using the Windows GUI, and then I actually run the model on my Linux machine. I set up Samba on my Linux machine and mount the shared directory as a network drive on my Windows workstation. In this way I can access, modify, and save all the input files in the shared directory from the Windows GUI and then start the model from an SSH session on my Linux box. Then, I can analyze the output from within Windows (again, via Samba) where I have the latest Matlab and other tools installed.

This gives me the best of both worlds--relative ease of model compilation on Linux (no dealing with the horrors of compiling Windows executables) and relative ease of use and stability with the Windows GUI. If you have access to both operating systems, this would be my (admittedly beginner's) suggestion.

Queueing jobs and running in "parallel"

I haven't gotten any of the mpd/mpich parallelizing features of Delft3D to work. I have, however, implemented a kind of parallelizing queue to take advantage of the two cores on my modeling machine. I can run up to two simultaneous model runs at a time, and also have several runs waiting in the queue to run as soon as a core is freed up.

The system is very simple and is based off the supremely handy Task Spooler. The main thing to do is first run ts -S <num> with the number of cores/processors you have. Then you can add model runs (I keep input files for each run in separate directories) with ts -L <runid> ./run_flow2d3d_xml.sh. The -L <runid> is optional but helps with identifying the runs in the queue, which can be displayed with ts.

Alternatively, you could use make's -j option to specify the number of jobs to run simultaneously (inspired by this post). This is simpler in that it doesn't require installing any additional packages like ts above, but more limiting in that you must specify all the runs at the beginning, and can't add jobs at will.

Dan Nowacki nowacki@uw.edu. Last updated January 2015.