public class TiremPropagationModel extends SignalPropagationModel implements IFreeSpacePathLossModel
TIREM calculates the propagation loss between antennas on or up to 30 km above the surface of the Earth for frequencies from 1 to 40000 MHz.
TiremPropagationData will be added as data to the Signal as it is propagated.
To use the TIREM Signal Propagation Model, you must have a TIREM Library license and an additional JAR file, which customers can request from AGI Support by emailing support@agi.com.
Note that this implementation uses native libraries to perform the calculation. As a result, this implementation
only supports 64-bit Windows and Linux platforms. An older implementation, TiremPropagationModel3_18,
is also available without these limitations.
TIREM contains its own versions of signal free-space path loss and atmospheric attenuation.
DME Component Libraries also has versions of these loss models, and FreeSpacePathLossModel
is added by default by WirelessLinkExtension, and CommunicationSystem.
Note that WirelessLinkExtension will check to ensure that only one model
computes free-space path loss, and throw an exception, to avoid incorrect results.
When using TIREM, decide which free-space path loss model you want to use, and either
disable the TIREM calculation by setting UseFreeSpaceLossModel (get / set),
or remove the FreeSpacePathLossModel.
TIREM (Terrain Integrated Rough Earth Model) examines the terrain profile between the antennas, using the effective Earth
radius geometry to determine whether the antennas are within line of sight (LOS) or beyond Line of Sight (BLS) and to find
the number, location and extent of sea water bodies along the path. Note that you must ensure you have set the
MeanSeaLevel (get / set) property of the EarthCentralBody for TIREM to work properly.
If it is not set, an exception will be thrown.
If LOS, the loss above free space is estimated as the smaller of the reflection region loss due to terrain intrusion into the first Fresnel zone or the spherical Earth loss for an assumed all land path. If there is sea water along the profile, the spherical Earth loss is calculated for an assumed all-sea path using sea water constants. The LOS loss above free space is then taken to be a combination of the all-land loss and all-sea loss weighted by the proportion of land and sea segments along the profile. The total path loss is found as the sum of the LOS loss, the loss due to atmospheric absorption, and the free space loss.
If BLS, the knife edge diffraction losses are found using the Epstein-Peterson method. If these average less than 7 dB, the terrain is regarded as smooth and the diffraction loss above free space is calculated using the spherical Earth model with ground constants for land. If there are bodies of sea water along the profile, the spherical Earth model is used again with sea water constants and the diffraction loss above free space is weighted by the proportion of land and sea segments along the profile. If the average knife edge diffraction loss exceeds 7 dB, the terrain is regarded as rough and the diffraction loss above free space is the sum of the knife edge losses, the reflection region losses that occur between the transmitter and its horizon and the receiver and its horizon (using a method similar to LOS), and (if diffraction occurs on sea water) spherical Earth losses for the sea water segments of the profile. In any case, the loss due to atmospheric absorption and the free space loss are added. Next, the tropospheric-scatter loss is calculated and combined with the atmospheric absorption for the troposcatter geometry. The total path loss is found by comparing the diffraction loss and troposcatter loss and selecting the dominant (noted by the smaller loss) mode.
| Modifier and Type | Class and Description |
|---|---|
static class |
TiremPropagationModel.PropagationData
Contains the values returned from the TIREM propagation for this version of TIREM.
|
| Modifier | Constructor and Description |
|---|---|
|
TiremPropagationModel()
Initializes a new instance.
|
|
TiremPropagationModel(TerrainProvider terrainProvider)
Initializes a new instance from the given terrain provider.
|
|
TiremPropagationModel(TerrainProvider terrainProvider,
double terrainSamplingStep,
double surfaceRefractivity,
double surfaceConductivity,
double surfaceRelativePermittivity,
double surfaceHumidity,
boolean useHorizontalPolarization,
boolean useFreeSpaceLossModel,
boolean useAtmosphericAbsorption)
Initializes a new instance from the given terrain provider, and sampling step.
|
protected |
TiremPropagationModel(TiremPropagationModel existingInstance,
CopyContext context)
Initializes a new instance as a copy of an existing instance.
|
| Modifier and Type | Method and Description |
|---|---|
protected boolean |
checkForSameDefinition(SignalPropagationModel other)
Checks to determine if another instance has the same definition as this instance and
returns
true if it does. |
protected boolean |
checkForSameDefinition(TiremPropagationModel other)
Checks to determine if another instance has the same definition as this instance and
returns
true if it does. |
Object |
clone(CopyContext context)
Clones this object using the specified context.
|
protected int |
computeCurrentDefinitionHashCode()
Computes a hash code based on the current properties of this object.
|
void |
enumerateDependencies(DependencyEnumerator enumerator)
Enumerates the dependencies of this object by calling
DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. |
double |
getMaximumAltitude()
Gets the model's maximum altitude.
|
SignalPropagator |
getSignalPropagator(EvaluatorGroup group,
IServiceProvider link)
Get a propagator which can propagate communication signals over the given link.
|
ScalarDependentOnServiceProvider |
getSurfaceConductivity()
Gets the conductivity of the earth's surface.
|
ScalarDependentOnServiceProvider |
getSurfaceHumidity()
Gets the humidity of the earth's surface in grams per cubic meter at the transmitter.
|
ScalarDependentOnServiceProvider |
getSurfaceRefractivity()
Gets the refractivity of the earth's surface.
|
ScalarDependentOnServiceProvider |
getSurfaceRelativePermittivity()
Gets the relative permittivity of the earth's surface.
|
TiremTerrainProfileComputation |
getTerrainProfileComputation()
Gets the terrain profile computation.
|
TerrainProvider |
getTerrainProvider()
Gets the terrain provider used in computing loss with the TIREM model.
|
Double |
getTerrainSamplingStep()
Gets the terrain sampling step, in radians.
|
boolean |
getUseAtmosphericAbsorptionModel()
Gets a value indicating whether TIREM Atmospheric Absorption loss is included in the results.
|
boolean |
getUseFreeSpaceLossModel()
Gets a value indicating whether the TIREM Free Space loss is included in the results.
|
boolean |
getUseHorizontalPolarization()
Gets a value indicating whether to use horizontal polarization instead of the default vertical polarization setting.
|
static void |
setNativeLibraryPath(String path)
Sets the path of the directory containing the native libraries used by this propagation model.
|
void |
setSurfaceConductivity(ScalarDependentOnServiceProvider value)
Sets the conductivity of the earth's surface.
|
void |
setSurfaceHumidity(ScalarDependentOnServiceProvider value)
Sets the humidity of the earth's surface in grams per cubic meter at the transmitter.
|
void |
setSurfaceRefractivity(ScalarDependentOnServiceProvider value)
Sets the refractivity of the earth's surface.
|
void |
setSurfaceRelativePermittivity(ScalarDependentOnServiceProvider value)
Sets the relative permittivity of the earth's surface.
|
void |
setTerrainProfileComputation(TiremTerrainProfileComputation value)
Sets the terrain profile computation.
|
void |
setTerrainProvider(TerrainProvider value)
Sets the terrain provider used in computing loss with the TIREM model.
|
void |
setTerrainSamplingStep(Double value)
Sets the terrain sampling step, in radians.
|
void |
setUseAtmosphericAbsorptionModel(boolean value)
Sets a value indicating whether TIREM Atmospheric Absorption loss is included in the results.
|
void |
setUseFreeSpaceLossModel(boolean value)
Sets a value indicating whether the TIREM Free Space loss is included in the results.
|
void |
setUseHorizontalPolarization(boolean value)
Sets a value indicating whether to use horizontal polarization instead of the default vertical polarization setting.
|
checkForSameDefinitionareSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozenpublic TiremPropagationModel()
public TiremPropagationModel(TerrainProvider terrainProvider)
terrainProvider - The terrain provider used to compute the terrain profile.public TiremPropagationModel(TerrainProvider terrainProvider, double terrainSamplingStep, double surfaceRefractivity, double surfaceConductivity, double surfaceRelativePermittivity, double surfaceHumidity, boolean useHorizontalPolarization, boolean useFreeSpaceLossModel, boolean useAtmosphericAbsorption)
terrainProvider - The terrain provider used to compute the terrain profile.terrainSamplingStep - The step at which to sample the terrain.surfaceRefractivity - The refractivity of the Earth's surface.surfaceConductivity - The conductivity of the Earth's surface.surfaceRelativePermittivity - The relative permittivity of the Earth's surface.surfaceHumidity - The surface humidity at the transmitter site.useHorizontalPolarization - The horizontal polarization indicator. If set to true horizontal polarization will be used instead of the default
vertical polarization setting.useFreeSpaceLossModel - Whether TIREM Free Space loss is include in the results.useAtmosphericAbsorption - Whether TIREM Atmospheric Absorption loss is included in the results.protected TiremPropagationModel(@Nonnull TiremPropagationModel existingInstance, @Nonnull CopyContext context)
See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor
in a derived class.
existingInstance - The existing instance to copy.context - A CopyContext that controls the depth of the copy.ArgumentNullException - Thrown when existingInstance or context is null.public Object clone(CopyContext context)
This method should be implemented to call a copy constructor on the class of the
object being cloned. The copy constructor should take the CopyContext as a parameter
in addition to the existing instance to copy. The copy constructor should first call
CopyContext.addObjectMapping(T, T) to identify the newly constructed instance
as a copy of the existing instance. It should then copy all fields, using
CopyContext.updateReference(T) to copy any reference fields.
A typical implementation of ICloneWithContext:
public static class MyClass implements ICloneWithContext {
public MyClass(MyClass existingInstance, CopyContext context) {
context.addObjectMapping(existingInstance, this);
someReference = context.updateReference(existingInstance.someReference);
}
@Override
public final Object clone(CopyContext context) {
return new MyClass(this, context);
}
private Object someReference;
}
In general, all fields that are reference types should be copied with a call to
CopyContext.updateReference(T). There are a couple of exceptions:
If one of these exceptions applies, the CopyContext should be given an opportunity
to update the reference before the reference is copied explicitly. Use
CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns
the original object, indicating that the context does not have a replacement registered,
then copy the object manually by invoking a Clone method, a copy constructor, or by manually
constructing a new instance and copying the values.
alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}
If you are implementing an evaluator (a class that implements IEvaluator), the
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the
copy context constructor. Code duplication can be avoided by doing the following:
CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to
non-evaluators.
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the
same CopyContext passed to the constructor.
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.
public MyClass(MyClass existingInstance, CopyContext context) {
super(existingInstance, context);
someReference = context.updateReference(existingInstance.someReference);
evaluatorReference = existingInstance.evaluatorReference;
updateEvaluatorReferences(context);
}
@Override
public void updateEvaluatorReferences(CopyContext context) {
evaluatorReference = context.updateReference(evaluatorReference);
}
@Override
public Object clone(CopyContext context) {
return new MyClass(this, context);
}
private Object someReference;
private IEvaluator evaluatorReference;clone in interface ICloneWithContextclone in class DefinitionalObjectcontext - The context to use to perform the copy.protected final boolean checkForSameDefinition(SignalPropagationModel other)
true if it does. Derived classes MUST override this method and check
all new fields introduced by the derived class for definitional equivalence. It is NOT necessary
to check base class fields because the base class will already have done that. When overriding this method,
you should NOT call the base implementation because it will return false for all derived-class instances.
Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).checkForSameDefinition in class SignalPropagationModelother - The other instance to compare to this one.true if the two objects are defined equivalently; otherwise false.protected boolean checkForSameDefinition(TiremPropagationModel other)
true if it does. Derived classes MUST override this method and check
all new fields introduced by the derived class for definitional equivalence. It is NOT necessary
to check base class fields because the base class will already have done that. When overriding this method,
you should NOT call the base implementation because it will return false for all derived-class instances.
Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).other - The other instance to compare to this one.true if the two objects are defined equivalently; otherwise false.protected int computeCurrentDefinitionHashCode()
TiremPropagationModel.checkForSameDefinition(agi.foundation.communications.signalpropagation.SignalPropagationModel) method.computeCurrentDefinitionHashCode in class SignalPropagationModelpublic void enumerateDependencies(DependencyEnumerator enumerator)
DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
Derived classes which contain additional dependencies MUST override this method, call the base
implementation, and enumerate dependencies introduced by the derived class.enumerateDependencies in interface IEnumerateDependenciesenumerateDependencies in class DefinitionalObjectenumerator - The enumerator that is informed of the dependencies of this object.public final ScalarDependentOnServiceProvider getSurfaceRefractivity()
ILinkService.public final void setSurfaceRefractivity(ScalarDependentOnServiceProvider value)
ILinkService.public final ScalarDependentOnServiceProvider getSurfaceConductivity()
ILinkService.public final void setSurfaceConductivity(ScalarDependentOnServiceProvider value)
ILinkService.public final ScalarDependentOnServiceProvider getSurfaceRelativePermittivity()
ILinkService.public final void setSurfaceRelativePermittivity(ScalarDependentOnServiceProvider value)
ILinkService.public final ScalarDependentOnServiceProvider getSurfaceHumidity()
ILinkService.public final void setSurfaceHumidity(ScalarDependentOnServiceProvider value)
ILinkService.public final boolean getUseHorizontalPolarization()
public final void setUseHorizontalPolarization(boolean value)
public final TerrainProvider getTerrainProvider()
public final void setTerrainProvider(TerrainProvider value)
public final double getMaximumAltitude()
The TIREM model is only valid up to 30 Kilometers. If any portion of the signal is above the maximum value, the TIREM
model is not used. This SignalPropagator will only calculate TIREM loss for those portions of the signal that are
below the maximum altitude.
@Nullable public final Double getTerrainSamplingStep()
null, and the sampling step will be half of the
MinimumSampleSpacing (get) of the configured TerrainProvider (get / set).
Setting this value will override the sampling step, which will affect the number of samples taken.
Note that this value is the angle in radians, measured from the center of the central body, between successive terrain evaluation points.
public final void setTerrainSamplingStep(@Nullable Double value)
null, and the sampling step will be half of the
MinimumSampleSpacing (get) of the configured TerrainProvider (get / set).
Setting this value will override the sampling step, which will affect the number of samples taken.
Note that this value is the angle in radians, measured from the center of the central body, between successive terrain evaluation points.
public final boolean getUseFreeSpaceLossModel()
getUseFreeSpaceLossModel in interface IFreeSpacePathLossModelpublic final void setUseFreeSpaceLossModel(boolean value)
public final boolean getUseAtmosphericAbsorptionModel()
public final void setUseAtmosphericAbsorptionModel(boolean value)
@Nullable public final TiremTerrainProfileComputation getTerrainProfileComputation()
null, and the terrain profile will be computed automatically.
In unusual situations, this delegate can be provided to have full control over the terrain profile information
which will be provided to the TIREM calculation.public final void setTerrainProfileComputation(@Nullable TiremTerrainProfileComputation value)
null, and the terrain profile will be computed automatically.
In unusual situations, this delegate can be provided to have full control over the terrain profile information
which will be provided to the TIREM calculation.public SignalPropagator getSignalPropagator(EvaluatorGroup group, IServiceProvider link)
getSignalPropagator in class SignalPropagationModelgroup - The evaluator group in which to create the evaluator.link - The link over which to propagate the signals.ArgumentNullException - Thrown when group, or link is null.PropertyInvalidException - Thrown if TerrainProvider (get / set), SurfaceRefractivity (get / set),
SurfaceConductivity (get / set), SurfaceRelativePermittivity (get / set), or
SurfaceHumidity (get / set) is null,
or if the MeanSeaLevel (get / set) property of
EarthCentralBody is null,
or if TerrainSamplingStep (get / set) is not greater than zero.public static void setNativeLibraryPath(@Nonnull String path)
Sets the path of the directory containing the native libraries used by this propagation model.
By default, the native libraries will be automatically unpacked to the temporary directory and loaded from there. If that is not desirable for a particular application, this method can be used to bypass the automatic unpacking process. This method must be called before any other calculations are performed using this propagation model.
path - The full path of the directory containing the required native libraries.ArgumentNullException - Thrown when path is null.