Under Sea Modeling Library (USML)
The Under Sea Modeling Library (USML) is a collection of C++ software
development modules for sonar modeling and simulation.
The Wavefront Queue 3D (WaveQ3D) model is the component of USML
that computes acoustic transmission loss in the ocean using
Hybrid Gaussian Beams in Spherical/Time Coordinates.
At this time, most of the other modules provide support to WaveQ3D.
USML depends on the NetCDF package, for access to test data,
and the Boost package, for fast computations (uBLAS) and unit test utilities.
Correctly configuring these packages is the #1 problem reported by USML users.
Before you attempt to build and test USML, please read this section carefully.
External Dependencies
This current version of this package has been tested in
the following environments:
- Ubuntu Linux 12.04 LTS 32bit (this is USML's primary environment)
- Red Hat Enterprise Linux 6.3 x86-64
-
Windows 7
Problems with Boost package
- There is a bug in the Boost uBLAS library that prevents us from overloading
operator/(). To see the corrected version of this code, please search for the
symbol BOOST_UBLAS_CHECK_DIVISION_TYPE in the
vector_expression.hpp
and matrix_expression.hpp files in the usml/config directory.
In each case, the operator/() should be using the enable_if<> macros just like the operator*()
just above it. Those using Boost 1.41.0 and later versions can just replace the original files with the
ones from the usml/config directory.
Problems with NetCDF package
- At this time, USML does not support the use of HDF5 or cURL. So in order to use USML and NetCDF
versions 4.0.1 and higher there are two options that you will need to do in order to run USML.
- The first option is to download the source code for netcdf at
http://www.unidata.ucar.edu/downloads/netcdf
and configure the install to disable netcdf-4 and dap.
- The second option is if you wish to keep these features on for netcdf. In order to get USML
to run properly, you will need to alter the CMakeLists.txt to include HDF5/zLib/cURL packages.
If you need to do this, there is a CMakeLists.txt file in the
usml/config directory
that is specifically setup to do this for you. NOTE: you will need to download the HDF5/zLib/cURL
packages from source and compile them appropriately. There is also a README.txt provided in the
usml/config directory that assists with this.
- Unidata's recent refactoring of the NetCDF library (Summer of 2010) hopelessly broke
the existing port to Microsoft Visual Studio (see
http://www.unidata.ucar.edu/software/netcdf/docs/faq.html#windows_netcdf4_1).
Until this is fixed by the open source community, Windows developers are expected
to create their own NetCDF libraries from source code. A copy of the
CMake-based build that system that we used for testing is freely available on GitHub at
https://github.com/campreilly/netcdf-4.1.3-with-cmake.
- By default, CMake does not include a module to find NetCDF libraries. Please copy the
FindNetCDF.cmake file from the usml/config directory
into CMake's shared modules directory. For Linux it's the /usr/share/cmake-2.8/Modules directory.
Building and Testing USML
For the sake of the example, let's assume that you are installing on a Linux
system into the "~/Projects/usml" directory. Assuming that this is the current
directory, and that all of the tarballs are here as well, the Linux commands
to execute would be:
tar -xzf usml-src-#.##.tar.gz
tar -xzf usml-doc-#.##.tar.gz
tar -xzf usml-data-#.##.tar.gz
where #.## is the version number to be installed.
This library is built using the CMake cross-platform, open-source build system.
Users are strongly encouraged to configure their builds using the cmake-gui
tool. CMake makes it much easier to support cross-platform builds, but it
requires a few more steps than a direct Makefile interface.
For example, a simple Unix build includes the following steps.
-
In the cmake-gui tool, set the source directory to the place where you
installed the USML source code. As suggested above source code could go in
"~/Projects/usml".
-
Setup for an "out of source" build by setting the binaries directory to
something like the
"~/Projects/usml-build" directory. Using a binary
directory that is not outside of the source tree is strictly optional,
except for the Eclipse CMake generator.
-
Use the "Configure" button to process the CMakeList file.
Select the "Unix Makefile" generator from the pop-up menu.
-
Change any options that you'd like. Note that the USML_PEDANTIC option
is only used to search for questionable programming during our development.
- Note: Boost_FORCE_SHAREDLIB should be used if the Boost static test suite libraries are not installed.
-
Hit the "Configure" button a second time, even if you have not changed any
options. Hit the "Generate" button to create makefiles for your system.
At this point, you can close the cmake-gui tool.
-
Run the "make" utility from
"~/Projects/usml-build" directory to compile both
the usml shared libraries and the usml_test regression tests.
-
You can optionally use "sudo make install" to install the compiled programs into
the include, lib, and src directories in /usr/local.
-
Running the "usml_test" regression test should run without errors if the
compilation and install were successful. Prints "*** No errors detected".
Additional Resources
- Mustafa Abbasi, a PhD Student at the University of Texas, has posted the step-by-step process
that he used to compile USML. He posted this procedure in the form of a video on his blog
(http://loudflames.wordpress.com/).
This may help you, especially if you have having trouble setting up the external
dependencies. Note that there is no sound in this video.