cTraceo

Introduction

The cTraceo Acoustic Raytracing Model is a 2D propagation model based on Gaussian beams for use in underwater acoustics and was developed at the Signal Processing Laboratory of the University of the Algarve.
Technically, cTraceo was written in C and is based on Orlando Rodríguez' TRACEO model written in Fortran 77. The cTraceo model is a completely re-engineered version of it's Fortran predecessor and features 3-4x higher performance, reduced memory usage of up to 3 orders of magnitude as well as better usability and portability.
Should you have any questions, suggestions or feedback, please don't hesitate in contacting us. You may also want to visit our wiki.

Downloads

See the features section below and take a look at our Getting Started guide before downloading.

The current stable version is cTraceo 1.3, released 30.Jan.2013. The list of changes between this and previous versions is maintained in the changelog.txt.
Download packages include the source code, 40+ examples and compiled binaries (executables) for Windows and Linux, both in 32 and 64 bit flavors. Compiled binaries of previous cTraceo versions are also included; this is usefull when it is necessary to EXACTLY reproduce previously modeled results.

Version 1.4 is currently in development and current changes are documented in the development history.

If you find any bugs, please make sure to report them in our issue tracker or contacting us.

Features

• Support for range dependent altimetry and bathymetry interfaces, including range dependent elastic properties;

• Reflections on elastic media interfaces take into account their densities as well as compressional and shear wave speeds and attenuations;

• Range-independent sound speed profiles, and range-dependent sound speed fields;

• Support for user-defined smooth objects within waveguide (like rocks, marine mammals, submarines);

• Full suppport for backscattering (from altimetry, bathymetry and objects);

• Allows free positioning of acoustic source and receivers (altimetry, bathymetry, objects and receivers can easily beo be positioned on either side of the source for modeling complex waveguides);

• Support for horizontal, vertical, rectangular and arbitrarily shaped receiver arrays (allows modelling unusual array shapes, multiple hydrophone arrays as well as array distortions);

• Output options: ray trajectories and amplitudes, eigenray search (with user-definable proximity threshhold), arrival patterns, acoustic pressure, coherent transmission loss, as well as particle velocity components (for modeling vector sensors).

• Modeled results are written to legacy .mat files for easy importing into Matlab, Octave, Scilab, Python or others. Note that cTraceo does not rely on Matlab libraries to write these files, so there is no need to install or use Matlab. Instead we have developed a drop-in replacement for the Matlab C API for writing .mat files to handle this.

• Cross Platform: runs on both Windows and Linux, and has been tested successfully on an ARM embedded system.

Software Requirements

Compiled binaries of cTraceo for Windows and Linux are available in the downloads section. Alternatively you can download the source code and compile it yourself.

Compiler Support

cTraceo requires a C Compiler compatible with the ISO C99 Standard. This is mostly due to the need for complex Math, which is not officially supported in older C standards.

Some notes on well known compilers:

• The GNU C Compiler
  GCC fully supports the ISO C99 standard as of version 4.5. The 4.3.x and 4.4.x versions partially implement the C99 standard and although warnings related to imaginary math may be generated, the code is compiled successfully.
  Successfully tested with versions 4.4.4 and 4.4.5 on Linux as well as with version 4.5.3 on Windows (using Cygwin)

• Clang - LLVM C Language Frontend
  The Clang compiler is the compiler used for development of the cTraceo Model.
  Successfully tested with versions 2.8 and 2.9 on Linux.

• MS Visual Studio
  No version of Microsoft's Visual Studio C Compiler supports the ISO C99 Standard, so compilation should not be possible.
  Not tested.

Matfile output

This software generates Matlab .mat-files as output, and provides 2 methods for writing these files:

1. Linking with Matlab(R) libraries during compilation.
   
2. Using a set of internal functions.
   

Option 2 is now the recommended method and is enabled by default. Although it is still possible to fall back to option 1 this requires some extra configuration, is only supported on Linux and requires a Matlab(R) License to be available.

Compilation and Installation

The easiest way to get started is by using one of the compiled binaries suplied with the download package (See the downloads section above). This section provides some hints if for some reason you need to compile cTraceo your self:

Linux

Just run:

$> make

This will compile the model and place a binary named "ctraceo" in the "bin/" subdirectory.

Windows

To compile cTraceo on windows, several steps are required:

1. Download and install Cygwin from www.cygwin.com. Cygwin provides basic linux build tools (like 'make') for windows.
   When installing Cygwin packages, select the following packages:
   "devel > gcc4"
   "devel > make"
   Several other packages will be installed for dependencies.

2. Add "c:/cygwin/bin" to your system's PATH environment variable.

3. Open Cygwin. A command line will appear. This command line provides an interface similar to Linux, and allows for easy compilation of the model.
   In Cygwin, navigate to location which contains cTraceo's source code; this will look similar to:
   $> cd /cygdrive/c/Users/username/Documents/models/cTraceo

4. Run:
   $> make

If all goes well, this will produce an executable called "ctraceo.exe" in the "bin/" subdirectory which can now be used like any other windows executable.

Matlab Configuration & Example Cases

Several example cases are contained in the "examples/" subdirectory. These examples depend on matlab functions contained in the "M-Files/" subdirectory and as such this folder should be added to the matlab path.

Within the provided example files the model is invoked by calling the command "ctraceo", and thus the "bin/" folder containing the compiled cTraceo binary should be on the system's PATH.

License Notes

The cTraceo Raytracing Model is released under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0).
http://creativecommons.org/licenses/by-nc-sa/3.0/

Contact

The cTraceo model was written at the Signal Processing Laboratory of the University of the Algarve for project SENSOCEAN by:

• Emanuel Ey (emanuel.ey at gmail.com)
  Copyright (C) 2011 - 2013

This software is derived from the FORTRAN 77 TRACEO code, written by:

• Orlando Camargo Rodriguez (orodrig at ualg.pt)
  Copyright (C) 2010

NOTE: cTraceo is research code under active development The code may contain bugs and updates are possible in the future.