agi.foundation.communications

(agi.foundation.communications-2024r2.jar)

Class Polarization

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.communications.Polarization

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

EllipticalPolarization, LeftHandCircularPolarization, LinearPolarization, RightHandCircularPolarization

public abstract class Polarization
extends DefinitionalObject

Base class for all types of signal polarization. Provides the polarization tilt angle, reference axis, and axial ratio.

Field Summary

Fields

Modifier and Type	Field and Description
static double	MaximumAxialRatio The maximum possible polarization axial ratio.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Polarization(Polarization existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
protected	Polarization(PolarizationReferenceAxis referenceAxis, double tiltAngle, double axialRatio) Constructs a new instance with the provided reference axis, tilt angle, and axial ratio.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(Polarization other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
static double	computeEfficiency(Polarization source, Polarization sink, UnitQuaternion sourceToSinkRotation, UnitCartesian sinkToSourceDirection, double crossPolarizationLeakage) Computes the polarization efficiency.
static double	computeRotation(Polarization source, Polarization sink, UnitQuaternion sourceToSinkRotation, UnitCartesian sinkToSourceDirection) Computes the rotation angle between the source and sink polarizations.
static double	computeRotation(PolarizationReferenceAxis sourcePolarizationReferenceAxis, double sourcePolarizationTiltAngle, PolarizationReferenceAxis sinkPolarizationReferenceAxis, UnitQuaternion sourceToSinkRotation, UnitCartesian sinkToSourceDirection) Computes the rotation angle between the source and sink polarizations.
static Polarization	constructOrthogonalPolarization(Polarization sourcePolarization) Constructs an instance of polarization which is orthogonal to the supplied source polarization.
double	getAxialRatio() Gets the polarization axial ratio.
PolarizationReferenceAxis	getReferenceAxis() Gets the polarization reference axis.
static UnitCartesian	getRotatedReferenceAxis(PolarizationReferenceAxis referenceAxis, double tiltAngle) Gets the polarization reference axis rotated by the specified tilt angle.
double	getTiltAngle() Gets the polarization tilt angle.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, enumerateDependencies, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MaximumAxialRatio

public static final double MaximumAxialRatio

The maximum possible polarization axial ratio.

See Also:

Constant Field Values

Constructor Detail

Polarization

protected Polarization(@Nonnull
                       PolarizationReferenceAxis referenceAxis,
                       double tiltAngle,
                       double axialRatio)

Constructs a new instance with the provided reference axis, tilt angle, and axial ratio.

Parameters:

referenceAxis - The polarization reference axis. The reference axis from which the tilt angle is measured.

tiltAngle - The polarization tilt angle.

axialRatio - The polarization axial ratio.

Polarization

protected Polarization(@Nonnull
                       Polarization existingInstance,
                       @Nonnull
                       CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

checkForSameDefinition

protected final boolean checkForSameDefinition(DefinitionalObject other)

Checks to determine if another instance has the same definition as this instance and returns 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).

Specified by:

checkForSameDefinition in class DefinitionalObject

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(Polarization other)

Checks to determine if another instance has the same definition as this instance and returns 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).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the Polarization.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

getReferenceAxis

@Nonnull
public final PolarizationReferenceAxis getReferenceAxis()

Gets the polarization reference axis. The reference axis from which the tilt angle is measured.

getTiltAngle

public final double getTiltAngle()

Gets the polarization tilt angle.

getAxialRatio

public final double getAxialRatio()

Gets the polarization axial ratio.

computeEfficiency

public static double computeEfficiency(@Nonnull
                                       Polarization source,
                                       @Nonnull
                                       Polarization sink,
                                       @Nonnull
                                       UnitQuaternion sourceToSinkRotation,
                                       @Nonnull
                                       UnitCartesian sinkToSourceDirection,
                                       double crossPolarizationLeakage)

Computes the polarization efficiency.

The maximum value of 1.0 returned from this function corresponds to no mismatch between the source and sink polarization. The minimum value returned will be governed by the crossPolarizationLeakage value and corresponds to complete mismatch between the source and sink polarization.

Parameters:

source - The polarization associated with the source or the transmission.

sink - The polarization associated with the sink or receiver of the transmission.

sourceToSinkRotation - The unit quaternion which represents the rotation from the source axes to the sink axes.

sinkToSourceDirection - The direction from the sink to the source.

crossPolarizationLeakage - The cross polarization leakage. The value which corresponds to complete mismatch between the source and sink polarizations.

Returns:

The polarization efficiency.

getRotatedReferenceAxis

@Nonnull
public static UnitCartesian getRotatedReferenceAxis(@Nonnull
                                                              PolarizationReferenceAxis referenceAxis,
                                                              double tiltAngle)

Gets the polarization reference axis rotated by the specified tilt angle.

Parameters:

referenceAxis - The polarization reference axis from which the title angle is measured.

tiltAngle - The desired polarization tilt angle.

Returns:

The polarization reference axis rotated by the tilt angle.

computeRotation

public static double computeRotation(Polarization source,
                                     Polarization sink,
                                     @Nonnull
                                     UnitQuaternion sourceToSinkRotation,
                                     @Nonnull
                                     UnitCartesian sinkToSourceDirection)

Computes the rotation angle between the source and sink polarizations.

Parameters:

source - The polarization associated with the signal source.

sink - The polarization associated with the signal sink.

sourceToSinkRotation - The unit quaternion which represents the rotation from the source axes to the sink axes.

sinkToSourceDirection - The direction from the sink position to the source position.

Returns:

The rotation angle in radians.

computeRotation

public static double computeRotation(@Nonnull
                                     PolarizationReferenceAxis sourcePolarizationReferenceAxis,
                                     double sourcePolarizationTiltAngle,
                                     @Nonnull
                                     PolarizationReferenceAxis sinkPolarizationReferenceAxis,
                                     @Nonnull
                                     UnitQuaternion sourceToSinkRotation,
                                     @Nonnull
                                     UnitCartesian sinkToSourceDirection)

Computes the rotation angle between the source and sink polarizations.

Parameters:

sourcePolarizationReferenceAxis - The polarization reference axis of the source polarization.

sourcePolarizationTiltAngle - The tilt angle of the source polarization.

sinkPolarizationReferenceAxis - The polarization reference axis of the sink polarization.>

sourceToSinkRotation - The unit quaternion which represents the rotation from the source axes to the sink axes.

sinkToSourceDirection - The direction from the sink position to the source position.

Returns:

The rotation angle in radians.

constructOrthogonalPolarization

public static Polarization constructOrthogonalPolarization(Polarization sourcePolarization)

Constructs an instance of polarization which is orthogonal to the supplied source polarization.

Parameters:

sourcePolarization - The source polarization used to compute the orthogonal instance of polarization.

Returns:

The orthogonal polarization instance.