Under Sea Modeling Library (USML) Release Notes

Release 1.0.0 - May 2015

• Bugs
• Re-work the implementation of seq_vector and it sub-classes to allow better in ublas expressions. Fixes issues #95 and #66.
  • Restructured seq_vector to follow the design pattern of a typical ublas vector but still preserves the read-only nature of the original implementation.
  • Removed deprecated function data( size_type i ) const as it is not used or needed.
  • Removed dependency of ublas vector from seq_vector.
• Fix implementation of (v / t) [i] = v [i] / t in config/vector_expressions.h so that it uses scalar_divides instead of scalar_multiplies.
• Update the logic in netcdf_profile::fill_missing to extend all profiles to the maximum depth, even if the dataset does not have any data at the deepest depths. The updated fill_missing logic removes all NaN values from the profile.
• Enhancements
• Improve the way offsets are computed to fix accuracy issues pointed out by ARL/UT IV&V report. Fixes issue #106.
  • Use folds in the wavefront to determine on_edge instead of path type. This keeps the wavefront from becoming all "edges" in long range surface ducts.
  • Modifed compute offsets revert to 2x2 inverse if unstable.
  • Changed assumption on the sign of the Hessian inverse's offset when unstable.
  • Extrapolate the location of the wavefront points using time offset and compare differences in depth.
  • Pull evaluation of instability from build_eigenrays into compute_offsets. No longer a need to share unstable flag outside of compute_offsets.

Release 1.0.0rc2 - Jan 2015

• Bugs
• Use differences in surface, bottom, and caustic counts to find ray family edges instead of trying to deduce from changes in direction. Fixes accuracy errors in Lloyd's depth test and Pedersen tests.
• Remove explicit use of std::isnan() in netcdf_profile.cc to fix compile error in Visual C++.
• Enhancements
• Added profile_lock and boundary_lock classes to allow multiple threads to access boundary_model(s) and profile_model(s) via boost mutexs.
• Add checkEigenray() method to eigenrayListener interface to support support returning of eigenray as quickly as possible.
• Added macros to usml_config.h to prevent Eclipse from finding semantic errors on macro that are not specfied until the compile line "-D".
• Guard against starting wavefront below bottom or above surface. Automatically adjusts source location if it is within 0.1 meters of being above the ocean surface or below the ocean bottom.
• Add copysign functions specializations for double in math_traits.h
• Modified Matlab implementation of raytrace plots to re-use logic from demo_gui.
• Undo the splitting of wave_queue.cc code based on _az_boundary. Minor slow down in execution speed, but simplifies maintenance.

Release 1.0.0rc1 - Dec 2014

• Bugs
• Fix error in the way that proploss class was summing both coherent and incoherent propagation losses.
• Fixed logic for computing offsets in spreading_hybrid_gaussian to fix errors in eignenrays.
• Fixed an error in reflection_model so that TOO_SHALLOW logic works correctly. Rays were not turning around in very shallow water.
• Corrected the way in which propagation loss intensity was being written to netCDF files. Frequency dimension was not handled correctly.
• Change the way in which transmission loss is clipped to 300 dB in wave_queue class. Previously, only the first frequency value was checked. Now we check all of them.
• Use of fill_missing() and interp_type() in netcdf_woa are no longer dependent on the presence of shallow data source. Had been causing NaN values to appear in gridded data.
• Added destructors in data_grid_svp and data_grid_bathy to fix memory leaks, required making data_grid's destructor virtual.
• Changed seq_data so that it works properly with size of 1.
• Eliminate typo in vector_expression.hpp so that operator/() uses scalar_divides() instead of scalar_multiplies().
• Fixed a Gaussian normalization error in theory paper, was correct in code.
• Change minimum optimization level from -00 to -01 to avoid errors in uBLAS.
• Fixed a memory leak in proploss class by removing cloned versions of _frequencies, source_de, and _source_az in the destructor.
• Removed FE_INVALID as one of the conditions that we test for in trapfe.cc to prevent exceptions for perfectly legit calculations.
• Enhancements
• Added surface loss reflection for Eckart and Beckmann-Spizzichino.
• Added Pierson and Moskowitz model for computing wave height from wind speed.
• Add detect_vertices() function to wave_queue class to count the number of upper and lower verticies encountered by each ray path. Not used by our model, but needed by other simulation systems. Added upper and lower members to wave_front class to track these values.
• Add check_eigenray() callback to eigenrayListener(). Used by the listeners to limit the time window in which they listen for eigenrays, relative to the first eigenray for that target.
• Add scattering strength and volume scattering models to ocean module in anticipation of future reverberation work.
• Added run_id to each wave_queue object. Used by eigenrayListener to keep track of cases where multiple wavefronts are active at the same time.
• Add write_netcdf() method to data_grid class so that any grid can written to netCDF file.
• Change the default earth radius from 6378101.30201019 (the WGS-84 value at 45 degrees) to 6371000 meters (the FAI standard). This is the same value used to compute that 1 degree of latitude equals 60 nautical miles.
• Change the datatypes for netCDF outputs from proploss.cc so that indices use ncLong instead of ncShort. Allows creations of larger outputs files.
• Make deletion of incoming grids by data_grid_mackenzie optional.
• Replace #include guards with #prama once statements. The new style is less prone to error.
• Added non-const version of seq_vector* axis in data_grid.
• Changed the name of the proplossListener class to eigenrayListener.
• Added ability to compile USML without compiling Tests or Studies. Broke the *.cmake files for Tests or Studies out of CMakeList.txt and into their own files.
• Greatly simplified the installation on Windows systems by relying on pre-built binaries.

Release 0.4.1 - Apr 2014

• Update reflect_loss_netcdf to use better variable names in the netcdf file.
• Limit reflect_loss_rayleigh sediment types to those in the reference, remove MUD as a type.
• Fix the use of grazing angle in reflect_loss_rayleigh, was using normal angle by accident.
• Changed the way that we compute Zb in reflect_loss_rayleigh to avoid a divide by zero.

Release 0.4 - Feb 2014

• Added specialized data_grids for sound speed profiling and bathymetry, optimized for speed, data_grid_svp and data_grid_bathy. Regression tests for both of these new data_grids can be found in datagrid_tests.
• In order to use the above specialized data_grids, it required new implementations of boundary_grid and profile_grid. These new boundary_grid_fast and profile_grid_fast, now allow for data_grids of type bathy and svp, respectively, to be passed into and used as the ocean's boundary and profile models.
• Added new logic to correctly produce only one eigenray when the azimuthal angles overlap, ie 0.0 and 360.0 are the same. Included new regression tests for this implementation in eigenray_test.
• Added new logic to correctly produce appropriate number of eigenrays when a target is almost directly above the source. Also included new regression test for this implementation in eigenray_test.
• Corrected gaussian intensity calculations to appropriately take into account the offset from the CPA, when choosing where to start looking for contributions.
• Many changes to how the Hybrid Gaussian beam calculations are done when close to the rayfan edges. When close to boundaries we previously had an inherent left-handed, all axis values prioritized to the left index, nature when doing calculations. This however, created issues when close to the boundary, breaking previously conceived notions that symmetry would still hold. Added new logic to correct, rebalance, and restore symmetry to the calculations at the rayfan edges.
• Modified wave_queue and proploss class to use the new class prolossListener. The proplossListener implements the Observer/Subject pattern which will allow multiple classes to "listen" for updated proploss eigenrays.
• Added method setIntensityThreshold to wave_queue class to ignore transimission loss eigenrays weaker than the threshold. Default value of the threshold is -300 dB.
• Repurposed profile_mackenzie to now produce a data_grid instead of a profile_grid. This change allows us to use the new data_grid_svp for speed optimization.
• Added std::invalid_argument exception for netcdf_bathy and netcdf_profile. Exception thrown when filename argument conatins wrong path or filename.

Release 0.3 - May 2013

• Introduced the ability to accumulate energy across ray families by adding virutal rays to the end of each ray family and allows the needed support at the edge of ray families. This first exhibited during the lloyds_depth_proploss test. As the TL was calculated closer and closer to the surface, the TL got further and further from the theoretical values and introducing these virtual rays rectified this issue.
• Made a significant change to the way that wavefronts are collected into families. The on_edge logic no longer uses the number of surface and bottom bounces to determine the location of a fold in the wavefront. This logic fails in ducts because the bounces do not always result in a fold. As a consequence of this change, the on_fold logic was removed and significantly simplified the way that caustics are detected.
• The reflect_loss_rayleigh mogdel had a bug where speed_shear was not being scaled correctly. Now the results of the plot_rayleigh_sediments match Fig 1.24 in Jensen, Kuperman, et al. Simplified the conversion from dB/wavelength to loss tanget by defining ATT_CONVERT constant.
• Created the ascii_arc_bathy model to extract Coastal Relief Model (CRM) bathymetry data. This data is produced by the NGDC web site as ASCII files with an ARC header.
• Created reflect_loss_netcdf model to read provinced bottom loss data from netCDF file. Assumes that each of the provinces and be modelled using the reflect_loss_rayleigh model, and that the provinces define the province number as a function of latitude and logitude. Each province number corresponds to a specific comination of geophysical properties (aka reflect_loss_rayleigh arguments).
• The "too shallow" calculation in the reflection_model was not normalizing the theta and phi components of the normal correctly. And this allowed them to be much greater than 1, which lead to crazy jumps.
• The boundary_grid model has a sqrt() in the calculation of the rho component of the normal. If the gradients were very large, the sum of the squares of the theta and phi componenets were slightly greater than 1. This leads to a rho value of NaN, and then everything turns bad.
• Enabled floating point exception traps when USML_DEBUG is set. Uses the GCC constructor attributes (a C language extension) to invoke the feenableexcept() function whent he shared library is loaded. Only supported by GCC compilers and shared libraries at this time.
• Discovered math overflow using "float" for bathymetry. Replaced all "float" with "double".
• Added the ability to limit interpolation locations to values inside of the lat/long boundaries of the bathymetry and profile grids.
• Corrected an error in pchip algorithm in data_grid (y3=y2 and not y2=y2).
• Added great circle range/bearing calculations to wposition1. Frequently used during testing.
• Developed a cmp_speed study to compare WaveQ3D speeds with CASS/GRAB scenario based on STD14. Built CASS runstreams to compute transmission loss for 1, 10, 20, 30, ..., 100 targets. Implemented as a ring of receivers at 100 km from source.
• Changed profile_mackenzie to set edge_limit in the depth direction to true. Eliminated cases where extrapolation outside of the water column was leading to NaN in ray trace of ray_speed. This, in turn, was causing ray_speed to run very slow.
• Prevent the first longitude point in the extraction from netCDF files from using lng_first index values that were smaller than zero. Effects netcdf_profile and netcdf_bathymetry models.
• Updated CMake process to support: install targets, included the libraries for zlib, hdf5, and curl that were required for NetCDF 4.
• Added reflect_loss_rayleigh parameters for MUD bottoms.
• In netccdf_profile, changed NcError to silent_nonfatal instead of verbose to prevent the extra line print out.
• Updated documentation to include BSD 2-Clauses License.
• Migrate test platform to Ubuntu 12.04 LTS from 10.04.

Release 0.2 - Feb 2012

• Convert to CMake build system to support multiple operating systems.
• Port the library to Windows using Visual C++ 2010 Express.
• Eliminate the need for USML_ROOT environment variable.
• Define symbols for test data files in CMakeLists file.
• Quitely fail some tests w/o errors if current platform does not include the ncks utility.
• Fix vector/matrix operations with scalars.
• Requires upgrade of Boost library to version 1.48.0 or better.
• Use enable_if<> template like 1.48.0 version of ublas.
• Before this fix, scalar addition with vector/matrix just resulted in the original vector/matrix on Windows.
• This fix fixed the errors in dot_test and distance_test.
• Use operator*() and operator/() as aliases for element_prod() and element_div().
• Requires a bug fix in ublas itself.
• file: boost/numeric/ublas/vector_expression.hpp lines 1409 through 1417 Should be using the enable_if<> macros just like the operator*() in lines 1397 through 1407 (just above it). Doing so allows further overloading of operator/() for other types.
• Fixed a bug in wave_front::find_edges(). First loop on line 201 said max_az when it should have said max_de.
• Fixed memory leaks in the way that tests were using NetCDF. Calls to get_att() and values() require the user to free the memory when they are down with it.
• Change the name of wave_q3d to waveq3d.
• Move eigenray_llyods to studies directory because it runs slow.

Release 0.1 - Jan 2012

• First version delivered to ONR.