Using World Ocean Simulation System (WOSS) library with ns-3

World Ocean Simulation System (WOSS)

“WOSS is a multi-threaded C++ framework that permits the integration of any existing underwater channel simulator that expects environmental data as input and provides as output a channel realization.

Currently, WOSS integrates the Bellhop ray-tracing program.

The user only has to specify the location in the world and the time where the simulation should take place. This is done by setting the simulated date and the wanted latitude and longitude of every node involved. The simulator automatically handles the rest (The image shown here is taken from[4]).

WOSS can be integrated in any network simulator or simulation tool that supports C++.[1][3]”.

WOSS depends on

Acoustic Toolbox (ATB)
NetCDF (Network Common Data Form)
HDF5 (Hierarchical Data Format version 5) and
GEBCO NetCDF Grid Database (GEBCO_NetCDF_DB)

NetCDF (Network Common Data Form)

NetCDF is a file format for storing multi-dimensional scientific data such as temperature, humidity, pressure, wind speed, etc. It was developed by the Unidata program at the University Corporation for Atmospheric Research (UCAR).

NetCDF4 is a particular version of the NetCDF format that uses the HDF5 data model, which provides improved performance and enhanced functionality, including support for larger datasets, faster data access, and the ability to store metadata and attributes along with the data.

The HDF5 data model allows for the creation of hierarchical structures within a NetCDF file, making it easier to organize and access data. The NetCDF4 format is backward-compatible with previous versions of the NetCDF format and provides improved data compression options.

HDF5 (Hierarchical Data Format version 5)

HDF5 is a data model and file format used for storing and managing large, complex scientific data sets. It is designed to handle data that is too large to fit into the memory of a single computer, and provides a flexible, high-level interface for working with that data.

In the HDF5 data model, data is organized into a hierarchy of objects, similar to a file system, with objects stored in a container called a “file”. Each object in the hierarchy can contain data, attributes, or other objects, making it easy to structure complex data sets in a way that is both organized and intuitive.

One of the key features of the HDF5 data model is its ability to store data in a way that allows for efficient data access and manipulation. For example, it provides advanced indexing and caching mechanisms that allow users to access specific parts of a data set without reading the entire file into memory.

It also provides a rich set of data types, including both primitive and compound data types, allowing users to store a wide range of data types and structures, from simple numbers and text to complex arrays and matrices.

The HDF5 data model is widely used in scientific and engineering fields, including earth and space science, high-performance computing, and multimedia. It provides a flexible, scalable, and efficient solution for managing large and complex data sets, making it an essential tool for many applications.

Acoustic Toolbox (AT)

Acoustic Toolbox is a software suite that provides tools for processing, analyzing, and visualizing acoustic signals, such as speech and music. It is designed for researchers, engineers, and students in the fields of audio and speech processing, music information retrieval, and computational audio.

The Acoustic Toolbox provides a range of functions for tasks such as speech analysis, sound visualization, and audio feature extraction. For example, it can be used to extract spectral features, such as Mel-frequency cepstral coefficients (MFCCs), to represent speech signals, or to compute spectral and temporal features of music signals, such as spectral flux and rhythmic features.

The software also includes tools for visualizing signals, such as spectrograms and waveforms, as well as for comparing different signals in terms of their similarity or difference.

Generally, AT is used in combination with other software packages, to perform more advanced analysis and processing tasks. It is a widely used tool in the audio and speech processing community, due to its versatility, ease of use, and the quality of the results it produces.

GEBCO NetCDF Grid Database (GEBCO_NetCDF_DB)

GEBCO_NetCDF_DB is a comprehensive bathymetric data set that provides a global representation of the seafloor and is maintained by the General Bathymetric Chart of the Oceans (GEBCO) organization. The data is stored in the NetCDF file format, which is a widely used standard for storing and sharing scientific data.

The GEBCO NetCDF Grid Database provides a high-resolution representation of the seafloor, with data covering the entire ocean, including coastal areas, and the deep ocean floor. The data includes information on the depth and shape of the seafloor, and is used for a variety of applications, including oceanography, marine biology, geology, and navigation.

The GEBCO_NetCDF_DB is designed to be a flexible and accessible data source for a wide range of users and applications. It is available for download, and can be easily accessed and used with a variety of software packages, including MATLAB, Python, and other programming languages and tools.

The database is regularly updated to ensure that it is up-to-date and accurate, and provides a valuable resource for those working in the field of oceanography and related fields.

WOSS and WOSS-NS3[1]

WOSS and WOSS-NS3 are available as git repositories
Users of “WOSS-NS3 Integration Framework” MUST update to version 1.9.0 or greater
WOSS version 1.9.0 or greater is matching the output syntax of the Acoustic Toolbox version cited in the “Recommended libraries” section.
It is strongly advised to upgrade Bellhop library to this version.
Old AT library and syntax can be still used with WOSS, however the syntax configuration must be changed accordingly.
WOSS 1.9.0 introduces support for the GEBCO 2019 and onward datasets, which require the NetCDF4 + HDF5 libraries.
From WOSS 1.10.0 support for the WOA 2013 and 2018 SSP datasets has been introduced, which has an increased resolution of 0.25 degrees.

WOSS now supports the installation as a stand alone library (e.g. with no NS2 and NS-Miracle support). This installation method is useful if you require the library to work in any project that doesn’t need NS2/NS-Miracle libraries and related source code[2].

Installing woss-ns3[3]

Step 1: First Install WOOS

The following steps from[2] explains the compilation and installation procesure of WOSS library. In fact, if you want to compile the library for the old version of network simulator 2 (NS2) and NSMIRACLE, it is also possible with the configuration script.

extract the compressed file in a directory of your choice and cd into that directory;
run ./autogen.sh
run ./configure with the following options:
- –with-ns-allinone=<ns2-allinone_path> optional, needed if you want to compile the library for NS2 and NSMIRACLE.
- –with-nsmiracle=<ns-miracle_path> optional, needed if you want to compile the library for NS2 and NSMIRACLE.
- –with-netcdf4=<NetCDF4_install_path> optional, needed if you want to use NetCDF4 + HDF5 databases. (The path is the same mentioned in the Requirements section, if NetCDF4 was installed with no –prefix, the default path SHOULD be /usr/local)
- –with-pthread optional but recommended
- –prefix=<path_where_libraries_will_be_installed>
  this path is optional and should be the same one used with NS-Miracle installation. If used, this path should be added to the environmental variable LD_LIBRARY_PATH. Please refer to NS-Miracle documentation for more info
run make
run make check to optionally perform any framework test
should any test fail, please enable its debug, rerun the test, collect the debug output file written woss/tests/ directory and send a mail to [email protected]
run make install

Step 2: Install ns-3

WOSS-ns3 is a WOSS ns3 Integration Framework module that can be installed on ns-3. So, install suitable version of ns-3 as per your need. You may select a suitable version as per your choice.
For example, if you are going to implement AI/ML related features in your simulaiton, then you may need to use a suitable lower version of ns-3 in which that AI/ML related components will work without any problem. In that case, first you may do a installation like the following and then proceed with the installation of woo-ns3.

Installing ns3-ai Model under ns-3.35

Step 3: Finally, Install woss-ns3

For installing ‘woss-ns3’, one may follow the procedure explained in [2] or [3] as given below.

Latest WOSS source code, installation instructions and related libraries can be found at http://telecom.dei.unipd.it/ns/woss/

‘woss-ns3’ module will be automatically installed by the ns3 app installer, but this feature is not yet complete.

It can also be manually installed as presented in[3] as follows:

by downloading and installing the recommended Acoustic Toolbox library
with optional NetCDF support, by downloading and installing the recommended HDF5, NetCDF libraries, with NetCDF4 format support
by downloading and installing the latest WOSS library with optional NetCDF4 and HDF5 support
by cloning this repository in the /src path and then running one of the following:
- NetCDF4 and HDF5 support, pay attention to the CXXFLAGS inline redefinition due to a unresolved NetCDF-C++4 API warning ./waf configure --with-woss-source= --with-woss-library= --with-netcdf4-install= CXXFLAGS="-Wall -Werror -Wno-unused-variable"
- with no NetCDF support ./waf configure --with-woss-source= --with-woss-library=
for info on how to install all the required libraries with the suggested paths, please check http://telecom.dei.unipd.it/ns/woss/doxygen/installation.html