User model

HTZ allows the user to create a user-defined model. The user-defined model may be created by using
Visual C++. It consists in (programming) a dynamic link library (.dll) file that can be called by HTZ
either for PTP, profile or coverage calculations. The model is called by HTZ at any new point of the
DTM where the field strength computation is needed. When one creates a new model in C++, one
must open a new project including 2 mandatory elements: a header file that must not be modified:
usrdll.h and a locally “main” file whose name can be defined by the user but its input/output cannot
be changed. Additional files for functions can naturally be included in the project. We present here a
simple example with files used to create a DLL that performs computations with the above mentioned
Millington/Bullington diffraction method.

1 Header file : usrdll.h

//------------------------------------------------
#ifdef __cplusplus
extern "C" {
#endif
#pragma pack(push,8) // structures are aligned 8 bytes
//------------------------------------------------

typedef struct {
float altitude; // corrected by earth curvature in meter
char veget; // clutter code 0 to 20
unsigned char alt_veget; // clutter altitude
short x,y; // DTM point (coordinates)
float distance; // distance ray Tx/Rx in meter
}ALT2;

typedef struct {
long count; // number of path values
long TxX, TxY; // Tx position (point dtm)
float TxAntennaHeight, RxAntennaHeight; // meter
float RadiatedPower; // WATT
float Frequency; //MHz
short dx,dy; // DTM step meter
double EarthRadius; // meter
unsigned char Seen; // 0 = not seen - 1 = seen
float h_eff1; // effective height 1 --> 15km
float h_eff3; // effective height 3 --> 15km
unsigned char iso; // 0: ½ wave dipole convention, 1: iso
} InModel;

// the second argument is a pointer to an OutModel structure that is filled by the DLL:

typedef struct {
double LossFreeSpace; //dB
double LossDiffraction; //dB
double LossFresnel; //dB
double LossUser; // information field
double LossClutter; //dB
 double FieldFreeSpace; //dBµV/m
double FieldReceived; //dBµV/m
unsigned char LineOfSight; // 0=not seen, 1 = seen
char Obstacle; // -1=no computation, 0=0 obsta 1=1 obs...
} OutModel;

#ifdef USERMOD_DLL_COMPILING // this expression has to be defined in DLL

#define DLLENTRY _declspec(dllexport)
#else
#define DLLENTRY _declspec(dllimport)
#endif

DLLENTRY void UserModel(ALT2 *profil,InModel inparam,OutModel *outparam);

//------------------------------------------------
#pragma pack( pop ) // restore previous alignment
#ifdef __cplusplus
}
#endif
//------------------------------------------------

The first input structure ALT2 depends on the point where a field has to be computed while the
second structure InModel provides global parameters. The first input is actually a pointer on a ALT2
structure (*profil). The number of elements is in the second structure InModel (inparam.count). If the
index i is defined from 0 to inparam.count, profil[i].* provides parameters from the first point of the
profile (Tx) to the last point (Rx). When a field strength is computed along a path of n points, HTZ
successively calls the DLL, providing it first with a 2 elements pointer on a ALT2 structure, then a 3
elements pointer on a ALT2 structure (the third element is new), ..., until a n element pointer is
provided. Thus, the DLL is called n-1 times for a profile of length n. The name of structure
component is explicit. Let us precise that inparam.Seen is a boolean value that states whether there is
a direct visibility between Tx and Rx and that, if inparam.h_eff1=-9999 or inparam.h_eff3=-9999, the
calling program require that the DLL file performs the computation of the effective antenna height (if
needed in the model). Indeed, not only HTZ can call the DLL but also HerTZ Mapper that does not
itself pre compute effective antenna heights.

Differences between HTZ and HerTZ Mapper also appear in the output structure. For HerTZ
mapper, only outparam->FieldReceived (yielding the field strength value at the current point) is
mandatory. For HTZ, this field is not mandatory but the behavior is more complicated, with a
subdivision defined w.r.t. standard geometrical model components.
• outparam->LossFresnel: this field is for the attenuation when there is visibility
(inparam.Seen=1);
• outparam->LossDiffraction: this field is for the attenuation when there is no visibility
(inparam.Seen=0);
• outparam->LossClutter: this field receives the clutter attenuation term;
• outparam->FieldFreeSpace: this field receives the freespace field strength term.
All the previous terms are mandatory and contribute additively or (if they start with the prefix “Loss”)
negatively to the global field strength. Thus, if not used, they must be set to zero. Regarding the 4
remaining terms:
• outparam->LossFreeSpace: this field is aimed at receiving the free space attenuation term but
has not been used so far by HTZ;
• outparam->FieldReceived: this term is not taken into account by HTZ but is mandatory for
HerTZ Mapper;
 • outparam->LossUser: this term does not contribute to the global field strength but is
displayed in an “info” field when a field strength profile is drawn (it may contain an
attenuation component);
• outparam->Obstacle: used to display the number of obstacles encountered by the model
(when geometrical);
• outparam->LineOfSight: plays the same role as inparam.Seen, but as output (for example if
the user wishes to recompute this value with a different Earth radius).

As a result, the field strength displayed by HTZ reads:

F=outparam->FieldFreeSpace–outparam->LossFresnel–outparam->LossDiffraction–
outparam->LossClutter- Lgas–Lrain,

where Lgas and Lrain are pre computed by HTZ (Lrain is activated only if the user switches the rain
attenuation term on within the Tools/Propagation model box). The aforementioned example is now
presented with 3 additional files to include in the project:
• mill.h;
• mill.c;
• milloss.c.

2 Additional header file: mill.h

#define USERMOD_DLL_COMPILING 1
#include "usrdll.h"
#include <math.h>
#include <stdio.h>

double milloss(ALT2 *profil,InModel inparam,OutModel *outparam);

3 DLL “main” file: mill.c

#include "mill.h"

void UserModel(ALT2 *profil,InModel inparam,OutModel *outparam)

{
double FSR;

//Free space
FSR=76.99+10.0*log10(inparam.RadiatedPower)
-20.0*log10(profil[inparam.count].distance/1000.0);
if (inparam.iso)
FSR-=2.15;
outparam->FieldFreeSpace=FSR;
outparam->LossDiffraction=0.0;
outparam->LossFresnel=0.0;
outparam->LineOfSight=0;
outparam->LossUser=0.0;
outparam->LossClutter=0;
 if(!inparam.Seen)
{
outparam->LossDiffraction=milloss(profil,inparam,outparam);
outparam->Obstacle=1;
}
else
{
outparam->LossFresnel=milloss(profil,inparam,outparam);
outparam->Obstacle=0;
}
outparam->FieldReceived=outparam->FieldFreeSpace
-outparam->LossDiffraction-outparam->LossFresnel-outparam->LossUser
-outparam->LossClutter;
}

4 Diffraction function: milloss.c

#include "mill.h"

double milloss(ALT2 *profil,InModel inparam,OutModel *outparam)

{
double nu,KnifeEdgeLoss,distsol,hsol,r1;
double slope,txalt,txtalt,rxalt,rxtalt,rxd,interm;
double disti,alti,TxTan,RxTan,TxClTan,RxClTan;
int i,iTx;

// Useful variables
iTx=0; // Tx position
rxd=(double)profil[inparam.count].distance;
txalt=(double)profil[iTx].altitude;
rxalt=(double)profil[inparam.count].altitude;
txtalt=txalt+inparam.TxAntennaHeight;
rxtalt=rxalt+inparam.RxAntennaHeight;

// distance Tx-Rx and slope

slope=(double)(rxalt+inparam.RxAntennaHeight-txtalt)/rxd;

// Pass n°1:
// Research for Tx clearance and Rx clearance points
TxClTan=-1e10;
RxClTan=-1e10;
interm=547.7*547.7/(2.0e3*(double)inparam.Frequency);

for (i=iTx+1;i<inparam.count;i++)
{
disti=(double)profil[i].distance;
alti=(double)profil[i].altitude;
TxTan=(alti-txtalt)/disti;
RxTan=(alti-rxtalt)/(rxd-disti);
if (TxClTan<TxTan)
TxClTan=TxTan;
if (RxClTan<RxTan)
RxClTan=RxTan;
}

// Special case where TxClTan+RxClTan==0.0, LOS tangent obstacle

 if (TxClTan+RxClTan==0.0)
{
KnifeEdgeLoss=6.4;
return(KnifeEdgeLoss);
}
else
{
// Distance of the hypothetical obstacle
distsol=((rxtalt-txtalt)+RxClTan*rxd)/(TxClTan+RxClTan);
// height above the LOS
hsol=(rxd*rxd*RxClTan*TxClTan+rxd*(TxClTan-RxClTan)*(rxtalt-txtalt)-
(rxtalt-txtalt)*(rxtalt-txtalt))/(rxd*(TxClTan+RxClTan));
r1=sqrt(300.0/inparam.Frequency*distsol*(rxd-distsol)/rxd);
// Clearance ratio
nu=sqrt(2)*hsol/r1;
KnifeEdgeLoss=6.4+20.0*log10(sqrt(nu*nu+1.0)+nu);
if (KnifeEdgeLoss<0.0)
KnifeEdgeLoss=0.0;
return(KnifeEdgeLoss);
}
}