tmm_cache_create()
Note: Requires Terrain Modeling Module functionality
Abstract
Creates a data structure to store path loss values for future lookup and possible reuse.
Syntax
tmm_cache_create (symmetry, position_tolerence_m, height_tolerance_m)
| Argument | Type | Description |
|---|---|---|
symmetry |
TmmT_Cache_Symmetry |
specifies whether the path loss calculations in the cache are valid in both directions (TMMC_CACHE_SYMMETRIC) or in only one direction (TMMC_CACHE_ASYMMETRIC). See Table 86 “TMM Cache Symmetry Symbolic Constants“ on page 27 for details. |
position_tolerence_m |
float |
horizontal cell size (in meters) This argument defines the maximum variation in horizontal position for reusing a path loss calculation. |
height_tolerance_m |
float |
vertical cell size (in meters) This argument defines the maximum variation in vertical position for reusing a path loss calculation. |
Return Value
TmmT_Cache
Data structure that contains a list of the previous position pairs, as well as the path loss value for those points.
Header
tmm.h
Example
/* Search our list of loss caches for a match on this frequency */
cache_ptr = my_find_cache (&cache_list, center_freq);
if (cache_ptr == NULL)
{
/* We have never performed a calculation for this frequency. */
/* Create a cache for the values for this frequency. */
/* Our signal calculations are symmetric with regard to transmitter */
/* receiver (propagation between a to b is equal to b to a). */
new_cache_ptr = tmm_cache_create (TMMC_CACHE_SYMMETRIC,
100 /* 100 meters tolerance */,
5 /* 5 meters vertical tolerance */);
/* Add the new cache data structure to our list of all caches. */
...
}
Details
Because path loss calculations involving terrain can take a long time, TMM provides a means to reuse previously calculated path losses whenever possible. It does so by creating a data structure to hold the following information about every path loss calculation that is made:
Table 19: Path Loss Calculations
| Value | Type | Description |
|---|---|---|
p1_latitude |
float |
the latitude of the first position, in degrees. |
p1_longitude |
float |
the longitude of the first position, in degrees. |
p1_height |
float |
the height of the first position, in meters above sea level. |
p2_latitude |
float |
the latitude of the second position, in degrees. |
p2_longitude |
float |
the longitude of the second position, in degrees. |
p2_height |
float |
the height of the second position, in meters above sea level. |
loss_value |
double |
the actual value of the calculated propagation loss for the corresponding set of latitude/longitude/height coordinates. |
value_status |
TmmT_Loss_Status |
the status of the path loss calculation. See Table 87 “TMM Path Loss Status Symbolic Constants“ on page 27 for details. |
TMM can reuse a path loss calculation if the endpoints of the new path fall in the same cells as the end points of a previously calculated position. The cell size is determined by the position_tolerance_m and height_tolerance_m arguments.
The cache data structure does not include frequency information. If you are making path loss calculations for different frequencies, you should create a different cache for each frequency or band used.
Purpose
Allocates a data structure to hold information about the path loss calculated for a pair of positions, such as the location of a transmitter/receiver pair. This information can then be reused for other similar position pairs, so that the path loss does not have to be recalculated. (Cache operation is described in "Reusing Path Loss Calculations" on page 24.)
Errors
- First argument (
symmetry) totmm_cache_create()is invalid. - Second argument (
position_tolerance_m) totmm_cache_create()must be non-negative. - Third argument (
height_tolerance_m) totmm_cache_create()must be non-negative.
Reference
- Use the function tmm_cache_destroy() to destroy a specified cache.
- Use the function tmm_cache_entry_add() to add path loss information for a specific position pair to the TmmT_cache data structure.
- Use the function tmm_cache_entry_find() to search the TmmT_cache data structure and return a path loss for the specified position pair, if one exists.