World Ocean Simulation System (WOSS) library
woss::BellhopWoss Class Reference

Implempentation of ACToolboxWoss for Bellhop raytracing program. More...

#include <bellhop-woss.h>

Inheritance diagram for woss::BellhopWoss:
Inheritance graph
Collaboration diagram for woss::BellhopWoss:
Collaboration graph

Public Member Functions

 BellhopWoss ()
 
 BellhopWoss (const CoordZ &tx, const CoordZ &rx, const Time &start_t, const Time &end_t, double start_freq, double end_freq, double freq_step)
 
virtual bool initialize ()
 
virtual bool initPressResReader (double curr_frequency)
 
virtual bool initTimeArrResReader (double curr_frequency)
 
virtual bool run ()
 
virtual bool timeEvolve (const Time &time_value)
 
virtual bool isValid () const
 
virtual PressuregetAvgPressure (double frequency, double tx_depth, double start_rx_depth=WOSS_MIN_DEPTH, double start_rx_range=WOSS_MIN_RANGE, double end_rx_depth=WOSS_MAX_DEPTH, double end_rx_range=WOSS_MAX_RANGE) const
 
virtual PressuregetPressure (double frequency, double tx_depth, double rx_depth, double rx_range) const
 
virtual TimeArrgetTimeArr (double frequency, double tx_depth, double rx_depth, double rx_range) const
 
BellhopWosssetThorpeAttFlag (bool flag)
 
BellhopWosssetTxMinDepthOffset (double offset)
 
BellhopWosssetTxMaxDepthOffset (double offset)
 
BellhopWosssetTotalTransmitters (int sources)
 
BellhopWosssetRxMinDepthOffset (double offset)
 
BellhopWosssetRxMaxDepthOffset (double offset)
 
BellhopWosssetRxMinRangeOffset (double offset)
 
BellhopWosssetRxMaxRangeOffset (double offset)
 
BellhopWosssetRxTotalDepths (int number)
 
BellhopWosssetRxTotalRanges (int number)
 
BellhopWosssetRaysNumber (int number)
 
BellhopWosssetMinAngle (double angle)
 
BellhopWosssetMaxAngle (double angle)
 
BellhopWosssetBoxDepth (double depth)
 
BellhopWosssetBoxRange (double range)
 
BellhopWosssetBellhopPath (const ::std::string &path)
 
BellhopWosssetBellhopArrSyntax (BellhopArrSyntax syntax)
 
BellhopWosssetBellhopShdSyntax (BellhopShdSyntax syntax)
 
BellhopWosssetBeamOptions (const ::std::string &options)
 
BellhopWosssetBhMode (const ::std::string &mode)
 
BellhopWosssetBathymetryType (const ::std::string &type)
 
BellhopWosssetBathymetryMethod (const ::std::string &type)
 
BellhopWosssetAltimetryType (const ::std::string &type)
 
BellhopWosssetTransducer (const Transducer *const ptr)
 
BellhopWosssetTransformSSPDepthSteps (int depth_steps)
 
BellhopWosssetBeamPatternParam (double init_bearing, double vert_rot=0.0, double horiz_rot=0.0, double mult=1.0, double add=0.0)
 
bool getThorpeAttFlag () const
 
double getTxMinDepthOffset () const
 
double getTxMaxDepthOffset () const
 
int getTotalTransmitters () const
 
double getRxMinDepthOffset () const
 
double getRxMaxDepthOffset () const
 
double getRxMinRangeOffset () const
 
double getRxMaxRangeOffset () const
 
int getRxTotalDepths () const
 
int getRxTotalRanges () const
 
int getRaysNumber () const
 
double getMinAngle () const
 
double getMaxAngle () const
 
double getBoxDepth () const
 
double getBoxRange () const
 
int getTransformSSPDepthSteps () const
 
::std::string getBellhopPath () const
 
BellhopArrSyntax getBellhopArrSyntax () const
 
BellhopShdSyntax getBellhopShdSyntax () const
 
::std::string getBeamOptions () const
 
::std::string getBathymetryType () const
 
::std::string getBathymetryMethod () const
 
::std::string getAltimetryType () const
 
const Transducer *const getTransducer () const
 
bool isValidBhMode (const ::std::string &) const
 
bool usingPressMode () const
 
bool usingTimeArrMode () const
 
bool usingSSPFile () const
 
- Public Member Functions inherited from woss::ACToolboxWoss
 ACToolboxWoss ()
 
 ACToolboxWoss (const CoordZ &tx, const CoordZ &rx, const Time &start_t, const Time &end_t, double start_freq, double end_freq, double freq_step)
 
virtual ~ACToolboxWoss ()
 
virtual bool initialize ()
 
virtual bool isValid () const
 
ACToolboxWosssetRangeSteps (int steps)
 
ACToolboxWosssetSSPDepthPrecision (long double precision)
 
int getRangeSteps () const
 
long double getSSPDepthPrecision () const
 
int getMinSSPDepthSteps () const
 
int getMaxSSPDepthSteps () const
 
double getMinSSPDepth () const
 
double getMaxSSPDepth () const
 
double getMinBathymteryDepth () const
 
double getMaxBathymetryDepth () const
 
- Public Member Functions inherited from woss::WossResReader
 WossResReader ()
 
 WossResReader (const CoordZ &tx, const CoordZ &rx, const Time &start_t, const Time &end_t, double start_freq, double end_freq, double freq_step)
 
virtual bool initResReader (double curr_frequency)=0
 
- Public Member Functions inherited from woss::Woss
 Woss ()
 
 Woss (const CoordZ &tx, const CoordZ &rx, const Time &start_t, const Time &end_t, double start_freq, double end_freq, double freq_step)
 
virtual bool initialize ()=0
 
virtual bool run ()=0
 
virtual bool timeEvolve (const Time &time_value)=0
 
virtual bool isValid () const =0
 
virtual PressuregetAvgPressure (double frequency, double tx_depth, double start_rx_depth=WOSS_MIN_DEPTH, double start_rx_range=WOSS_MIN_RANGE, double end_rx_depth=WOSS_MAX_DEPTH, double end_rx_range=WOSS_MAX_RANGE) const =0
 
virtual PressuregetPressure (double frequency, double tx_depth, double rx_depth, double rx_range) const =0
 
virtual TimeArrgetTimeArr (double frequency, double tx_depth, double rx_depth, double rx_range) const =0
 
WosssetDebug (bool flag)
 
WosssetCleanWorkDir (bool flag)
 
WosssetWorkDirPath (const ::std::string &path)
 
WosssetWossDbManager (const WossDbManager *const ptr)
 
WossinsertFrequency (double freq)
 
WossinsertFrequencies (double freq_start, double freq_end, double freq_step)
 
WosssetFrequencies (const FreqSet &freq_set)
 
WosseraseFrequency (double freq)
 
WossclearFrequencies ()
 
WosssetTotalRuns (int runs)
 
WosssetTxCoordZ (const CoordZ &coordz)
 
WosssetRxCoordZ (const CoordZ &coordz)
 
WosssetStartTime (const Time &start_t)
 
WosssetEndTime (const Time &end_t)
 
WosssetEvolutionTimeQuantum (double value)
 
int getWossId () const
 
::std::string getWorkDirPath () const
 
const FreqSetgetFrequencies () const
 
double getMinFrequency () const
 
double getMaxFrequency () const
 
FreqSCIt freq_begin () const
 
FreqSCIt freq_end () const
 
FreqSCRIt freq_rbegin () const
 
FreqSCRIt freq_rend () const
 
FreqSCIt freq_lower_bound (double frequency) const
 
FreqSCIt freq_upper_bound (double frequency) const
 
int getTotalRuns () const
 
CoordZ getTxCoordZ () const
 
CoordZ getRxCoordZ () const
 
Time getStartTime () const
 
Time getCurrentTime () const
 
Time getEndTime () const
 
double getEvolutionTimeQuantum () const
 
double getGreatCircleDistance () const
 
double getDistance () const
 
double getBearing () const
 
bool usingDebug () const
 
virtual bool isRunning () const
 

Protected Member Functions

virtual void normalizeDbSSP ()
 
virtual void resetNormalizedDbSSP ()
 
bool initResReader (double curr_frequency)
 
void initBox (double depth, double range)
 
void initCfgFiles (double curr_frequency, int curr_run)
 
void writeCfgFiles (double curr_frequency, int curr_run)
 
void writeAllCfgFiles ()
 
void writeNormalizedSSP (int curr_run)
 
void writeSediment ()
 
void writeHeader (double curr_frequency, int curr_run)
 
void writeTransmitter ()
 
void writeReceiver ()
 
void writeRayOptions ()
 
void writeBox ()
 
void writeBeamBlock ()
 
void writeBathymetryFile ()
 
void writeBeamPatternFile ()
 
void writeAltimetryFile (int curr_run)
 
void removeAllCfgFiles ()
 
void removeCfgFiles (double curr_frequency, int curr_run)
 
void checkBoundaries (double &frequency, double &tx_depth, double &rx_start_depth, double &rx_start_range, double &rx_end_depth, double &rx_end_range) const
 
void checkDepthOffsets ()
 
void checkDepthOffsets (const CoordZ &coords, double &min_offset, double &max_offset, double min_depth_value, double max_depth_value)
 
void checkAngles ()
 
void checkRangeOffsets ()
 
- Protected Member Functions inherited from woss::ACToolboxWoss
virtual bool checkSSPUnicity (SSP *&ptr)
 
virtual bool initRangeVector ()
 
virtual bool initCoordZVector ()
 
virtual bool initSediment ()
 
virtual bool initAltimetry ()
 
virtual bool initSSPVector ()
 
virtual void resetSSPVector ()
 
- Protected Member Functions inherited from woss::WossResReader
void clearResReaderMap ()
 
- Protected Member Functions inherited from woss::Woss
virtual bool mkWorkDir (double curr_frequency, int curr_run=0)
 
virtual bool rmWorkDir (double curr_frequency, int curr_run=0)
 
virtual bool rmWorkDir ()
 

Protected Attributes

bool use_thorpe_att
 
::std::string beam_options
 
::std::string bathymetry_type
 
::std::string bathymetry_method
 
::std::string altimetry_type
 
::std::string bellhop_op_mode
 
::std::string bellhop_env_file
 
::std::string bathymetry_file
 
::std::string altimetry_file
 
::std::string beam_pattern_file
 
::std::string ssp_file
 
::std::string shd_file
 
::std::string arr_file
 
::std::string bellhop_path
 
BellhopArrSyntax bellhop_arr_syntax
 
BellhopShdSyntax bellhop_shd_syntax
 
::std::string curr_path
 
::std::string transducer_type
 
double tx_min_depth_offset
 
double tx_max_depth_offset
 
int total_transmitters
 
int total_rx_depths
 
double rx_min_depth_offset
 
double rx_max_depth_offset
 
int total_rx_ranges
 
double rx_min_range_offset
 
double rx_max_range_offset
 
int total_rays
 
double min_angle
 
double max_angle
 
double min_normalized_ssp_depth
 
double max_normalized_ssp_depth
 
int curr_norm_ssp_depth_steps
 
int transform_ssp_depth_steps
 
const Transducertransducer
 
double bp_initial_bearing
 
double bp_vertical_rotation
 
double bp_horizontal_rotation
 
double bp_mult_costant
 
double bp_add_costant
 
bool using_ssp_file
 
bool using_press_mode
 
bool using_time_arrival_mode
 
NormSSPMap normalized_ssp_map
 
NormSSPMap randomized_ssp_map
 
double box_depth
 
double box_range
 
::std::ofstream f_out
 
- Protected Attributes inherited from woss::ACToolboxWoss
long double ssp_depth_precision
 
double min_bathymetry_depth
 
double max_bathymetry_depth
 
double min_altimetry_depth
 
double max_altimetry_depth
 
::std::set< double > min_ssp_depth_set
 
::std::set< double > max_ssp_depth_set
 
int min_ssp_depth_steps
 
int max_ssp_depth_steps
 
int total_range_steps
 
CoordZVector coordz_vector
 
RangeVector range_vector
 
SSPVector ssp_vector
 
::std::set< int > ssp_unique_indexes
 
Sedimentsediment_value
 
Altimetryaltimetry_value
 
bool is_ssp_vector_transformable
 
- Protected Attributes inherited from woss::WossResReader
ResReaderMap res_reader_map
 
- Protected Attributes inherited from woss::Woss
int woss_id
 
::std::string work_dir_path
 
const WossDbManagerdb_manager
 
Time start_time
 
Time current_time
 
Time end_time
 
double evolution_time_quantum
 
CoordZ tx_coordz
 
CoordZ rx_coordz
 
FreqSet frequencies
 
double bearing
 
double total_great_circle_distance
 
double total_distance
 
int total_runs
 
bool debug
 
bool has_run_once
 
volatile bool is_running
 
bool clean_workdir
 

Additional Inherited Members

- Static Protected Attributes inherited from woss::Woss
static pthread_spinlock_t woss_mutex = woss::initWossSpinlock( &Woss::woss_mutex , 0 )
 
static int woss_counter = 0
 

Detailed Description

Implempentation of ACToolboxWoss for Bellhop raytracing program.

BellhopWoss class has the task to create enviromental file, run Bellhop and read its results.

Constructor & Destructor Documentation

◆ BellhopWoss() [1/2]

BellhopWoss::BellhopWoss ( )

BellhopWoss default constructor. Default constructed objects are not valid

◆ BellhopWoss() [2/2]

BellhopWoss::BellhopWoss ( const CoordZ tx,
const CoordZ rx,
const Time start_t,
const Time end_t,
double  start_freq,
double  end_freq,
double  freq_step 
)

BellhopWoss constructor

Parameters
txconst reference to a valid CoordZ object ( transmitter )
rxconst reference to a valid CoordZ object ( receiver )
start_tconst reference to a valid Time object for SSP's averaging purposes ( start date time )
end_tconst reference to a valid Time object for SSP's averaging purposes ( end date time )
start_freqstart frequency [Hz]
end_freqend frequency [Hz]
freq_stepfrequency step [Hz]

Member Function Documentation

◆ checkAngles()

void BellhopWoss::checkAngles ( )
protected

Checks the consistency of given launching angle and modifies them if needed

References woss::Woss::debug, max_angle, min_angle, woss::Woss::total_distance, woss::Woss::total_great_circle_distance, and woss::Woss::woss_id.

Referenced by initialize().

◆ checkBoundaries()

void BellhopWoss::checkBoundaries ( double &  frequency,
double &  tx_depth,
double &  rx_start_depth,
double &  rx_start_range,
double &  rx_end_depth,
double &  rx_end_range 
) const
protected

Checks parameters passed by a WossManager request and modifies them in place if they are not consistent with data

Parameters
frequencyfrequency [Hz]
tx_depthtransmitter depth [m]
rx_start_depthreceiver start depth [m]
rx_start_rangereceiver start range [m]
rx_end_depthreceiver end depth [m]
rx_end_rangereceiver end range [m]

References woss::Woss::frequencies, woss::CoordZ::getDepth(), woss::Woss::rx_coordz, rx_max_depth_offset, rx_max_range_offset, rx_min_depth_offset, rx_min_range_offset, woss::Woss::total_great_circle_distance, woss::Woss::tx_coordz, tx_max_depth_offset, and tx_min_depth_offset.

Referenced by getAvgPressure(), getPressure(), and getTimeArr().

Here is the call graph for this function:

◆ checkDepthOffsets() [1/2]

void BellhopWoss::checkDepthOffsets ( )
protected

◆ checkDepthOffsets() [2/2]

void BellhopWoss::checkDepthOffsets ( const CoordZ coords,
double &  min_offset,
double &  max_offset,
double  min_depth_value,
double  max_depth_value 
)
protected

Checks the consistency of input offsets and modifies them if needed

Parameters
coords3-D coordinates of the point to be tested
min_offsetmin offset to be tested [m]
max_offsetmax offset to be tested [m]
min_depth_valuemin depth value of point to be tested [m]
max_depth_valuemax depth value of point to be tested [m]

References woss::Woss::debug, woss::CoordZ::getDepth(), woss::Coord::getLatitude(), woss::Coord::getLongitude(), and woss::Woss::woss_id.

Here is the call graph for this function:

◆ checkRangeOffsets()

void BellhopWoss::checkRangeOffsets ( )
protected

Checks the consistency of rx range offsets and modifies them if needed

References woss::Woss::debug, woss::Coord::getLatitude(), woss::Coord::getLongitude(), woss::Woss::rx_coordz, rx_max_range_offset, rx_min_range_offset, woss::Woss::total_great_circle_distance, woss::Woss::tx_coordz, and woss::Woss::woss_id.

Referenced by initialize().

Here is the call graph for this function:

◆ getAltimetryType()

::std::string woss::BellhopWoss::getAltimetryType ( ) const
inline

Gets altimetry type string

Returns
"C" or "L"

References altimetry_type.

◆ getAvgPressure()

Pressure * BellhopWoss::getAvgPressure ( double  frequency,
double  tx_depth,
double  start_rx_depth = WOSS_MIN_DEPTH,
double  start_rx_range = WOSS_MIN_RANGE,
double  end_rx_depth = WOSS_MAX_DEPTH,
double  end_rx_range = WOSS_MAX_RANGE 
) const
virtual

Gets the average Pressure value in given rx range-depth box

Parameters
frequencyfrequency [Hz]
tx_depthtransmitter depth [m]
start_rx_depthstart receiver depth [m]
start_rx_rangestart receiver range [m]
end_rx_depthend receiver depth [m]
end_rx_rangeend receiver range [m]
Returns
a valid Pressure value

Implements woss::Woss.

References checkBoundaries(), woss::WossResReader::res_reader_map, and woss::Woss::total_runs.

Here is the call graph for this function:

◆ getBathymetryMethod()

::std::string woss::BellhopWoss::getBathymetryMethod ( ) const
inline

Gets bathymetry write method string

Returns
"S" or "D"

References bathymetry_method.

◆ getBathymetryType()

::std::string woss::BellhopWoss::getBathymetryType ( ) const
inline

Gets bathymetry type string

Returns
"C" or "L"

References bathymetry_type.

◆ getBeamOptions()

::std::string woss::BellhopWoss::getBeamOptions ( ) const
inline

Gets the beam option string

Returns
"R" , "B", "C" or "G"

References beam_options.

◆ getBellhopArrSyntax()

BellhopArrSyntax woss::BellhopWoss::getBellhopArrSyntax ( ) const
inline

Gets the .arr file sintax

Returns
arr file syntax

References bellhop_arr_syntax.

Referenced by woss::ArrBinResReader::getArrBinFile(), and woss::ArrBinResReader::getArrBinHeader().

◆ getBellhopPath()

::std::string woss::BellhopWoss::getBellhopPath ( ) const
inline

Gets the path of bellhop program

Returns
path of bellhop program

References bellhop_path.

◆ getBellhopShdSyntax()

BellhopShdSyntax woss::BellhopWoss::getBellhopShdSyntax ( ) const
inline

Gets the .shd file sintax

Returns
shd file syntax

References bellhop_shd_syntax.

Referenced by woss::ShdResReader::getShdFile().

◆ getBoxDepth()

double woss::BellhopWoss::getBoxDepth ( ) const
inline

Gets the maximum ray depth

Returns
maximum ray depth

References box_depth.

◆ getBoxRange()

double woss::BellhopWoss::getBoxRange ( ) const
inline

Gets the maximum ray range

Returns
maximum ray range

References box_range.

◆ getMaxAngle()

double woss::BellhopWoss::getMaxAngle ( ) const
inline

Gets the maximum launch angle

Returns
maximum launch angle

References max_angle.

◆ getMinAngle()

double woss::BellhopWoss::getMinAngle ( ) const
inline

Gets the minimum launch angle

Returns
minimum launch angle

References min_angle.

◆ getPressure()

Pressure * BellhopWoss::getPressure ( double  frequency,
double  tx_depth,
double  rx_depth,
double  rx_range 
) const
virtual

Gets a Pressure value of given range, depths

Parameters
frequencyfrequency [Hz]
tx_depthtransmitter depth [m]
rx_depthreceiver depth [m]
rx_rangereceiver range [m]
Returns
a valid Pressure value

Implements woss::Woss.

References checkBoundaries(), woss::WossResReader::res_reader_map, and woss::Woss::total_runs.

Here is the call graph for this function:

◆ getRaysNumber()

int woss::BellhopWoss::getRaysNumber ( ) const
inline

Gets the total number of launched angles

Returns
number of launched angles

References total_rays.

◆ getRxMaxDepthOffset()

double woss::BellhopWoss::getRxMaxDepthOffset ( ) const
inline

Gets the receiver maximum depth offset [m]

Returns
depth offset [m]

References rx_max_depth_offset.

◆ getRxMaxRangeOffset()

double woss::BellhopWoss::getRxMaxRangeOffset ( ) const
inline

Gets the receiver maximum range offset [m]

Returns
range offset [m]

References rx_max_range_offset.

◆ getRxMinDepthOffset()

double woss::BellhopWoss::getRxMinDepthOffset ( ) const
inline

Gets the receiver mimimum depth offset [m]

Returns
depth offset [m]

References rx_min_depth_offset.

◆ getRxMinRangeOffset()

double woss::BellhopWoss::getRxMinRangeOffset ( ) const
inline

Gets the receiver mimimum range offset [m]

Returns
range offset [m]

References rx_min_range_offset.

◆ getRxTotalDepths()

int woss::BellhopWoss::getRxTotalDepths ( ) const
inline

Gets the total number of receiver depths

Returns
number of receiver depths

References total_rx_depths.

◆ getRxTotalRanges()

int woss::BellhopWoss::getRxTotalRanges ( ) const
inline

Gets the total number of receiver ranges

Returns
number of receiver ranges

References total_rx_ranges.

◆ getThorpeAttFlag()

bool woss::BellhopWoss::getThorpeAttFlag ( ) const
inline

Gets the thorpe attenuation flag

Returns
boolean flag

References use_thorpe_att.

◆ getTimeArr()

TimeArr * BellhopWoss::getTimeArr ( double  frequency,
double  tx_depth,
double  rx_depth,
double  rx_range 
) const
virtual

Gets a TimeArr value of given range, depths

Parameters
frequencyfrequency [Hz]
tx_depthtransmitter depth [m]
rx_depthreceiver depth [m]
rx_rangereceiver range [m]
Returns
a valid Pressure value

Implements woss::Woss.

References checkBoundaries(), woss::Woss::debug, woss::WossResReader::res_reader_map, woss::Woss::total_runs, and woss::Woss::woss_id.

Here is the call graph for this function:

◆ getTotalTransmitters()

int woss::BellhopWoss::getTotalTransmitters ( ) const
inline

Gets the number of transmitters

Returns
number of transmitters

References total_transmitters.

◆ getTransducer()

const Transducer *const woss::BellhopWoss::getTransducer ( ) const
inline

Gets bathymetry type string

Returns
"C" or "L"

References transducer.

◆ getTransformSSPDepthSteps()

int woss::BellhopWoss::getTransformSSPDepthSteps ( ) const
inline

Returns the depth steps (and possibly transform) of all SSP in use

Returns
transformed SSP depth steps

References transform_ssp_depth_steps.

◆ getTxMaxDepthOffset()

double woss::BellhopWoss::getTxMaxDepthOffset ( ) const
inline

Gets the transmitter maximum depth offset [m]

Returns
depth offset [m]

References tx_max_depth_offset.

◆ getTxMinDepthOffset()

double woss::BellhopWoss::getTxMinDepthOffset ( ) const
inline

Gets the transmitter mimimum depth offset [m]

Returns
depth offset [m]

References tx_min_depth_offset.

◆ initBox()

void woss::BellhopWoss::initBox ( double  depth,
double  range 
)
inlineprotected

Initializes the Bellhop box

Parameters
depthbox depth [m]
rangebox range [m]

References box_depth, and box_range.

Referenced by initialize().

◆ initCfgFiles()

void BellhopWoss::initCfgFiles ( double  curr_frequency,
int  curr_run 
)
protected

Initializes the configuration file(s)

Parameters
curr_frequencyfrequency in use [Hz]
curr_runcurrent run number

References bellhop_env_file, curr_path, woss::Woss::current_time, woss::Woss::work_dir_path, and woss::Woss::woss_id.

Referenced by run(), and writeCfgFiles().

◆ initialize()

bool BellhopWoss::initialize ( )
virtual

◆ initPressResReader()

bool BellhopWoss::initPressResReader ( double  curr_frequency)
virtual

Initializes the ShdResReader object for given frequency

Parameters
curr_frequencyfrequency in use [Hz]
Returns
true if method succeeded, false otherwise

References woss::WossResReader::res_reader_map, and shd_file.

Referenced by initResReader().

◆ initResReader()

bool BellhopWoss::initResReader ( double  curr_frequency)
protectedvirtual

Initializes the ResReader object for given frequency

Parameters
curr_frequencyfrequency in use [Hz]
Returns
true if method succeeded, false otherwise

Implements woss::WossResReader.

References initialize(), initPressResReader(), initTimeArrResReader(), and woss::WossResReader::res_reader_map.

Here is the call graph for this function:

◆ initTimeArrResReader()

bool BellhopWoss::initTimeArrResReader ( double  curr_frequency)
virtual

Initializes the ArrAscResReader or ArrBinResReader object for given frequency

Parameters
curr_frequencyfrequency in use [Hz]
Returns
true if method succeeded, false otherwise

References arr_file, bellhop_op_mode, and woss::WossResReader::res_reader_map.

Referenced by initResReader().

◆ isValid()

bool BellhopWoss::isValid ( ) const
virtual

Checks the validity of Woss

Returns
true if it's valid, false otherwise

Reimplemented from woss::ACToolboxWoss.

References bellhop_op_mode, woss::ACToolboxWoss::isValid(), isValidBhMode(), max_angle, min_angle, woss::ACToolboxWoss::total_range_steps, total_rays, total_rx_depths, total_rx_ranges, and total_transmitters.

Referenced by initialize(), and normalizeDbSSP().

Here is the call graph for this function:

◆ isValidBhMode()

bool woss::BellhopWoss::isValidBhMode ( const ::std::string &  mode) const
inline

Checks the validity of Bellhop run mode

Returns
true if it's valid, false otherwise

Referenced by isValid(), and setBhMode().

◆ normalizeDbSSP()

◆ removeAllCfgFiles()

void BellhopWoss::removeAllCfgFiles ( )
protected

Writes all configuration files

References woss::Woss::frequencies, removeCfgFiles(), and woss::Woss::total_runs.

Here is the call graph for this function:

◆ removeCfgFiles()

void BellhopWoss::removeCfgFiles ( double  curr_frequency,
int  curr_run 
)
protected

Removes the configuration file(s)

Parameters
curr_frequencyfrequency in use [Hz]
curr_runcurrent run number

References woss::Woss::rmWorkDir().

Referenced by removeAllCfgFiles().

Here is the call graph for this function:

◆ resetNormalizedDbSSP()

void BellhopWoss::resetNormalizedDbSSP ( )
protectedvirtual

Deletes all normalized SSPs

References normalized_ssp_map.

Referenced by initialize().

◆ run()

bool BellhopWoss::run ( )
virtual

Runs the channel simulator. It is mandatory to set has_run to true before returning from this function

Returns
true if method was successful, false otherwise

Implements woss::Woss.

References bellhop_arr_syntax, woss::BELLHOP_CREATOR_ARR_FILE_INVALID, woss::BELLHOP_CREATOR_SHD_FILE_INVALID, bellhop_path, bellhop_shd_syntax, curr_path, woss::Woss::debug, woss::Woss::frequencies, initCfgFiles(), woss::Woss::is_running, woss::Woss::total_runs, and woss::Woss::woss_id.

Here is the call graph for this function:

◆ setAltimetryType()

BellhopWoss & woss::BellhopWoss::setAltimetryType ( const ::std::string &  type)
inline

Sets the altimetry type ( L, C). See Bellhop documentation for more info

Parameters
typebeam options
Returns
reference to *this

References altimetry_type.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBathymetryMethod()

BellhopWoss & woss::BellhopWoss::setBathymetryMethod ( const ::std::string &  type)
inline

Sets the bathymetry write method (S, D)

Parameters
typebeam options
Returns
reference to *this

References bathymetry_method.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBathymetryType()

BellhopWoss & woss::BellhopWoss::setBathymetryType ( const ::std::string &  type)
inline

Sets the bathymetry type ( L, C). See Bellhop documentation for more info

Parameters
typebeam options
Returns
reference to *this

References bathymetry_type.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBeamOptions()

BellhopWoss & woss::BellhopWoss::setBeamOptions ( const ::std::string &  options)
inline

Sets the beam option string . See Bellhop documentation for more info

Parameters
optionsbeam options ( G, C, R , B)
Returns
reference to *this

References beam_options.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBeamPatternParam()

BellhopWoss & woss::BellhopWoss::setBeamPatternParam ( double  init_bearing,
double  vert_rot = 0.0,
double  horiz_rot = 0.0,
double  mult = 1.0,
double  add = 0.0 
)
inline

Sets the transmitter beam pattern

Parameters
typevalid woss::BeamPattern
Returns
reference to *this

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBellhopArrSyntax()

BellhopWoss & woss::BellhopWoss::setBellhopArrSyntax ( BellhopArrSyntax  syntax)
inline

Sets the bellhop arr file syntax

Parameters
syntaxsyntax to be used
Returns
reference to *this

References bellhop_arr_syntax.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBellhopPath()

BellhopWoss & woss::BellhopWoss::setBellhopPath ( const ::std::string &  path)
inline

Sets the path of bellhop program

Parameters
pathfilesystem path
Returns
reference to *this

References bellhop_path.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBellhopShdSyntax()

BellhopWoss & woss::BellhopWoss::setBellhopShdSyntax ( BellhopShdSyntax  syntax)
inline

Sets the bellhop shd file syntax

Parameters
syntaxsyntax to be used
Returns
reference to *this

References bellhop_shd_syntax.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBhMode()

BellhopWoss & BellhopWoss::setBhMode ( const ::std::string &  mode)

Sets the Bellhop run mode string. See Bellhop documentation for more info

Parameters
modeBellhop run mode ( A, a , C, I , S)
Returns
reference to *this

References bellhop_op_mode, isValidBhMode(), and woss::Woss::woss_id.

Referenced by woss::BellhopCreator::initializeBhWoss().

Here is the call graph for this function:

◆ setBoxDepth()

BellhopWoss & woss::BellhopWoss::setBoxDepth ( double  depth)
inline

Sets the maximum depth for Bellhop rays

Parameters
depthmaximum ray depth [m]
Returns
reference to *this

References box_depth.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setBoxRange()

BellhopWoss & woss::BellhopWoss::setBoxRange ( double  range)
inline

Sets the maximum range for Bellhop rays

Parameters
rangemaximum ray range [m]
Returns
reference to *this

References box_range.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setMaxAngle()

BellhopWoss & woss::BellhopWoss::setMaxAngle ( double  angle)
inline

Sets the maximum launch angle for all BellhopWoss that will be created

Parameters
anglenumber of launched rays (>= 0)
Returns
reference to *this

References max_angle.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setMinAngle()

BellhopWoss & woss::BellhopWoss::setMinAngle ( double  angle)
inline

Sets the mimimum launch angle for all BellhopWoss that will be created

Parameters
anglenumber of launched rays (>= 0)
Returns
reference to *this

References min_angle.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRaysNumber()

BellhopWoss & woss::BellhopWoss::setRaysNumber ( int  number)
inline

Sets the number of launched rays

Parameters
numbernumber of launched rays (>= 0)
Returns
reference to *this

References total_rays.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxMaxDepthOffset()

BellhopWoss & woss::BellhopWoss::setRxMaxDepthOffset ( double  offset)
inline

Sets the receiver maximum depth offset [m]

Parameters
offset0 <= depth offset <= 0 [m]
Returns
reference to *this

References rx_max_depth_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxMaxRangeOffset()

BellhopWoss & woss::BellhopWoss::setRxMaxRangeOffset ( double  offset)
inline

Sets the receiver maximum depth offset [m]

Parameters
offset-total_distance <= range offset <= total_distance [m]
Returns
reference to *this

References rx_max_range_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxMinDepthOffset()

BellhopWoss & woss::BellhopWoss::setRxMinDepthOffset ( double  offset)
inline

Sets the receiver mimimum depth offset [m]

Parameters
offset0 <= depth offset <= 0 [m]
Returns
reference to *this

References rx_min_depth_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxMinRangeOffset()

BellhopWoss & woss::BellhopWoss::setRxMinRangeOffset ( double  offset)
inline

Sets the receiver mimimum range offset [m]

Parameters
offset-total_distance <= range offset <= total_distance [m]
Returns
reference to *this

References rx_min_range_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxTotalDepths()

BellhopWoss & woss::BellhopWoss::setRxTotalDepths ( int  number)
inline

Sets the number of receiver depths

Parameters
numbernumber of receiver depths
Returns
reference to *this

References total_rx_depths.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setRxTotalRanges()

BellhopWoss & woss::BellhopWoss::setRxTotalRanges ( int  number)
inline

Sets the number of receiver ranges

Parameters
numbernumber of receiver ranges
Returns
reference to *this

References total_rx_ranges.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setThorpeAttFlag()

BellhopWoss & woss::BellhopWoss::setThorpeAttFlag ( bool  flag)
inline

Sets the thorpe attenuation flag

Parameters
flagboolean flag
Returns
reference to *this

References use_thorpe_att.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setTotalTransmitters()

BellhopWoss & woss::BellhopWoss::setTotalTransmitters ( int  sources)
inline

Sets the number of transmitters

Parameters
sourcesnumber of transmitters
Returns
reference to *this

References total_transmitters.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setTransducer()

BellhopWoss & woss::BellhopWoss::setTransducer ( const Transducer *const  ptr)
inline

Sets the transducer type. See TransducerDbCreator for more info

Parameters
typetranducer type
Returns
reference to *this

References transducer.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setTransformSSPDepthSteps()

BellhopWoss & woss::BellhopWoss::setTransformSSPDepthSteps ( int  depth_steps)
inline

Sets the depth steps (and possibly transform) of all SSP in use

Parameters
typebeam options
Returns
reference to *this

References transform_ssp_depth_steps.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setTxMaxDepthOffset()

BellhopWoss & woss::BellhopWoss::setTxMaxDepthOffset ( double  offset)
inline

Sets the transmitter maximum depth offset [m]

Parameters
offset0 <= depth offset <= 0 [m]
Returns
reference to *this

References tx_max_depth_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ setTxMinDepthOffset()

BellhopWoss & woss::BellhopWoss::setTxMinDepthOffset ( double  offset)
inline

Sets the transmitter mimimum depth offset [m]

Parameters
offset0 <= depth offset <= 0 [m]
Returns
reference to *this

References tx_min_depth_offset.

Referenced by woss::BellhopCreator::initializeBhWoss().

◆ timeEvolve()

bool BellhopWoss::timeEvolve ( const Time time_value)
virtual

Performs a time evoulion of all time-dependant parameters

Parameters
time_valueconstant reference to a valid Time object (between start_time and end_time)
Returns
true if method was successful, false otherwise

Implements woss::Woss.

References woss::ACToolboxWoss::altimetry_value, woss::Woss::current_time, woss::Woss::debug, woss::Woss::end_time, woss::Woss::evolution_time_quantum, initialize(), woss::Altimetry::isValid(), woss::Time::isValid(), woss::Woss::start_time, woss::Altimetry::timeEvolve(), and woss::Woss::woss_id.

Here is the call graph for this function:

◆ usingPressMode()

bool woss::BellhopWoss::usingPressMode ( ) const
inline

Signals if the instance is using Bellhop in SHD mode ( C, S , I)

Returns
true if it is using it, false otherwise

◆ usingSSPFile()

bool woss::BellhopWoss::usingSSPFile ( ) const
inline

Signals if the instance is using Bellhop with SSP matrix file

Returns
true if it is using it, false otherwise

◆ usingTimeArrMode()

bool woss::BellhopWoss::usingTimeArrMode ( ) const
inline

Signals if the instance is using Bellhop in ARR mode ( A, a)

Returns
true if it is using it, false otherwise

◆ writeAllCfgFiles()

void BellhopWoss::writeAllCfgFiles ( )
protected

Writes all configuration files

References woss::Woss::frequencies, woss::Woss::total_runs, and writeCfgFiles().

Referenced by initialize().

Here is the call graph for this function:

◆ writeAltimetryFile()

void BellhopWoss::writeAltimetryFile ( int  curr_run)
protected

Writes db created altimetry in the configuration file(s)

Parameters
curr_runcurrent run number

References altimetry_file.

◆ writeBathymetryFile()

void BellhopWoss::writeBathymetryFile ( )
protected

Writes db created bathymetry in the configuration file(s)

References bathymetry_file.

◆ writeBeamPatternFile()

void BellhopWoss::writeBeamPatternFile ( )
protected

Writes transmitter beam pattern file(s)

References beam_pattern_file.

◆ writeBox()

void woss::BellhopWoss::writeBox ( )
inlineprotected

Writes the box options in the configuration file(s)

References box_depth, box_range, and f_out.

◆ writeCfgFiles()

void BellhopWoss::writeCfgFiles ( double  curr_frequency,
int  curr_run 
)
protected

Writes the configuration file(s)

Parameters
curr_frequencyfrequency in use [Hz]
curr_runcurrent run number

References bellhop_env_file, f_out, initCfgFiles(), and woss::Woss::mkWorkDir().

Referenced by writeAllCfgFiles().

Here is the call graph for this function:

◆ writeHeader()

void woss::BellhopWoss::writeHeader ( double  curr_frequency,
int  curr_run 
)
inlineprotected

Writes the header in the configuration file(s)

Parameters
curr_frequencyfrequency in use [Hz]
curr_runcurrent run number

References f_out.

◆ writeNormalizedSSP()

void BellhopWoss::writeNormalizedSSP ( int  curr_run)
protected

Writes the normalized SSP matrix in the configuration file(s)

Parameters
curr_runcurrent run number

References woss::ACToolboxWoss::altimetry_value, woss::SSP::begin(), woss::SSP::end(), f_out, woss::Altimetry::isValid(), max_normalized_ssp_depth, min_normalized_ssp_depth, normalized_ssp_map, woss::SSP::randomize(), randomized_ssp_map, ssp_file, and use_thorpe_att.

Here is the call graph for this function:

◆ writeRayOptions()

void woss::BellhopWoss::writeRayOptions ( )
inlineprotected

Writes the ray options in the configuration file(s)

References beam_options, bellhop_op_mode, f_out, woss::Transducer::isValid(), max_angle, min_angle, total_rays, and transducer.

Here is the call graph for this function:

◆ writeReceiver()

void woss::BellhopWoss::writeReceiver ( )
inlineprotected

Writes the receiver info in the configuration file(s)

References f_out, woss::CoordZ::getDepth(), woss::Woss::rx_coordz, rx_max_depth_offset, rx_max_range_offset, rx_min_depth_offset, rx_min_range_offset, woss::Woss::total_great_circle_distance, total_rx_depths, and total_rx_ranges.

Here is the call graph for this function:

◆ writeSediment()

void woss::BellhopWoss::writeSediment ( )
inlineprotected

Writes the db Sediment in the configuration file(s)

References f_out, woss::Sediment::getStringValues(), woss::Sediment::getType(), max_normalized_ssp_depth, and woss::ACToolboxWoss::sediment_value.

Here is the call graph for this function:

◆ writeTransmitter()

void woss::BellhopWoss::writeTransmitter ( )
inlineprotected

Writes the transmitter info in the configuration file(s)

References f_out, woss::CoordZ::getDepth(), total_transmitters, woss::Woss::tx_coordz, tx_max_depth_offset, and tx_min_depth_offset.

Here is the call graph for this function:

Member Data Documentation

◆ altimetry_file

::std::string woss::BellhopWoss::altimetry_file
protected

Pathname of Bellhop altimetry file

Referenced by writeAltimetryFile().

◆ altimetry_type

::std::string woss::BellhopWoss::altimetry_type
protected

Altimetry type ( L, C )

Referenced by getAltimetryType(), and setAltimetryType().

◆ arr_file

::std::string woss::BellhopWoss::arr_file
protected

Pathname of Bellhop ARR file

Referenced by initTimeArrResReader().

◆ bathymetry_file

::std::string woss::BellhopWoss::bathymetry_file
protected

Pathname of Bellhop bathymetry file

Referenced by writeBathymetryFile().

◆ bathymetry_method

::std::string woss::BellhopWoss::bathymetry_method
protected

Bathymetry write method ( S, D )

Referenced by getBathymetryMethod(), and setBathymetryMethod().

◆ bathymetry_type

::std::string woss::BellhopWoss::bathymetry_type
protected

Bathymetry type ( L, C )

Referenced by getBathymetryType(), and setBathymetryType().

◆ beam_options

::std::string woss::BellhopWoss::beam_options
protected

Bellhop beam options ( G, C, R, B )

Referenced by getBeamOptions(), setBeamOptions(), and writeRayOptions().

◆ beam_pattern_file

::std::string woss::BellhopWoss::beam_pattern_file
protected

Pathname of Bellhop beam pattern file

Referenced by writeBeamPatternFile().

◆ bellhop_arr_syntax

BellhopArrSyntax woss::BellhopWoss::bellhop_arr_syntax
protected

.arr file syntax to be used during file parsing

Referenced by getBellhopArrSyntax(), run(), and setBellhopArrSyntax().

◆ bellhop_env_file

::std::string woss::BellhopWoss::bellhop_env_file
protected

Pathname of Bellhop configuration file

Referenced by initCfgFiles(), and writeCfgFiles().

◆ bellhop_op_mode

::std::string woss::BellhopWoss::bellhop_op_mode
protected

Bellhop run mode ( A, a, C, I, S )

Referenced by initTimeArrResReader(), isValid(), setBhMode(), and writeRayOptions().

◆ bellhop_path

::std::string woss::BellhopWoss::bellhop_path
protected

Pathname of Bellhop program

Referenced by getBellhopPath(), run(), and setBellhopPath().

◆ bellhop_shd_syntax

BellhopShdSyntax woss::BellhopWoss::bellhop_shd_syntax
protected

.shd file syntax to be used during file parsing

Referenced by getBellhopShdSyntax(), run(), and setBellhopShdSyntax().

◆ box_depth

double woss::BellhopWoss::box_depth
protected

Bellhop box depth [m]

Referenced by getBoxDepth(), initBox(), setBoxDepth(), and writeBox().

◆ box_range

double woss::BellhopWoss::box_range
protected

Bellhop box range [m]

Referenced by getBoxRange(), initBox(), setBoxRange(), and writeBox().

◆ curr_norm_ssp_depth_steps

int woss::BellhopWoss::curr_norm_ssp_depth_steps
protected

Depth steps of all SSP involved

Referenced by normalizeDbSSP().

◆ curr_path

::std::string woss::BellhopWoss::curr_path
protected

Current working path

Referenced by initCfgFiles(), and run().

◆ f_out

::std::ofstream woss::BellhopWoss::f_out
protected

◆ max_angle

double woss::BellhopWoss::max_angle
protected

Maximum launching angle [decimal degrees]

Referenced by checkAngles(), getMaxAngle(), isValid(), setMaxAngle(), and writeRayOptions().

◆ max_normalized_ssp_depth

double woss::BellhopWoss::max_normalized_ssp_depth
protected

Maximum depth of normalized SSP matrix [m]

Referenced by checkDepthOffsets(), initialize(), normalizeDbSSP(), writeNormalizedSSP(), and writeSediment().

◆ min_angle

double woss::BellhopWoss::min_angle
protected

Minimum launching angle [decimal degrees]

Referenced by checkAngles(), getMinAngle(), isValid(), setMinAngle(), and writeRayOptions().

◆ min_normalized_ssp_depth

double woss::BellhopWoss::min_normalized_ssp_depth
protected

Minimum depth of normalized SSP matrix [m]

Referenced by checkDepthOffsets(), normalizeDbSSP(), and writeNormalizedSSP().

◆ normalized_ssp_map

NormSSPMap woss::BellhopWoss::normalized_ssp_map
protected

SSP matrix normalized for Bellhop requirements (same depths and same depth-steps for all SSP involved)

Referenced by normalizeDbSSP(), resetNormalizedDbSSP(), and writeNormalizedSSP().

◆ randomized_ssp_map

NormSSPMap woss::BellhopWoss::randomized_ssp_map
protected

SSP matrix normalized and randomized for Bellhop requirements (same depths and same depth-steps for all SSP involved)

Referenced by writeNormalizedSSP().

◆ rx_max_depth_offset

double woss::BellhopWoss::rx_max_depth_offset
protected

Receiver maximum depth offset [m]

Referenced by checkBoundaries(), checkDepthOffsets(), getRxMaxDepthOffset(), setRxMaxDepthOffset(), and writeReceiver().

◆ rx_max_range_offset

double woss::BellhopWoss::rx_max_range_offset
protected

◆ rx_min_depth_offset

double woss::BellhopWoss::rx_min_depth_offset
protected

Receiver minimum depth offset [m]

Referenced by checkBoundaries(), checkDepthOffsets(), getRxMinDepthOffset(), setRxMinDepthOffset(), and writeReceiver().

◆ rx_min_range_offset

double woss::BellhopWoss::rx_min_range_offset
protected

Receiver minimum range offset [m]

Referenced by checkBoundaries(), checkRangeOffsets(), getRxMinRangeOffset(), setRxMinRangeOffset(), and writeReceiver().

◆ shd_file

::std::string woss::BellhopWoss::shd_file
protected

Pathname of Bellhop SHD file

Referenced by initPressResReader().

◆ ssp_file

::std::string woss::BellhopWoss::ssp_file
protected

Pathname of Bellhop SSP file

Referenced by writeNormalizedSSP().

◆ total_rays

int woss::BellhopWoss::total_rays
protected

Number of launched rays

Referenced by getRaysNumber(), isValid(), setRaysNumber(), and writeRayOptions().

◆ total_rx_depths

int woss::BellhopWoss::total_rx_depths
protected

Number of receiver depths

Referenced by getRxTotalDepths(), isValid(), setRxTotalDepths(), and writeReceiver().

◆ total_rx_ranges

int woss::BellhopWoss::total_rx_ranges
protected

Number of receiver ranges.

On some configuration (linux distribution / cpu ) bellhop will output an empty file with a value of total_rx_ranges = 1.

Referenced by getRxTotalRanges(), isValid(), setRxTotalRanges(), and writeReceiver().

◆ total_transmitters

int woss::BellhopWoss::total_transmitters
protected

Number of transmitter

Referenced by getTotalTransmitters(), isValid(), setTotalTransmitters(), and writeTransmitter().

◆ transducer

const Transducer* woss::BellhopWoss::transducer
protected

Transmitter beam pattern

Referenced by getTransducer(), setTransducer(), and writeRayOptions().

◆ transform_ssp_depth_steps

int woss::BellhopWoss::transform_ssp_depth_steps
protected

transformed SSP depth steps. Set <= 0 in order to disable the feature.

Referenced by getTransformSSPDepthSteps(), normalizeDbSSP(), and setTransformSSPDepthSteps().

◆ tx_max_depth_offset

double woss::BellhopWoss::tx_max_depth_offset
protected

Transmitter maximum depth offset [m]

Referenced by checkBoundaries(), checkDepthOffsets(), getTxMaxDepthOffset(), setTxMaxDepthOffset(), and writeTransmitter().

◆ tx_min_depth_offset

double woss::BellhopWoss::tx_min_depth_offset
protected

Transmitter minimum depth offset [m]

Referenced by checkBoundaries(), checkDepthOffsets(), getTxMinDepthOffset(), setTxMinDepthOffset(), and writeTransmitter().

◆ use_thorpe_att

bool woss::BellhopWoss::use_thorpe_att
protected

let bellhop calculate thorpe attenuation

Referenced by getThorpeAttFlag(), setThorpeAttFlag(), and writeNormalizedSSP().


The documentation for this class was generated from the following files: