agi.foundation.communications

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

Class Signal

java.lang.Object

agi.foundation.communications.Signal

All Implemented Interfaces:

IEquatable<Signal>

public class Signal
extends Object
implements IEquatable<Signal>

An immutable data structure which represents the properties of a single signal consisting of a power, center frequency, bandwidth range, noise temperature, noise bandwidth range, and a set of additional objects representing additional data. The additional data is identified by type and is used to represent things like message data encoded on the signal, DigitalModulation, SignalDataRate, etc.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Signal(Signal existingInstance) Create a new instance by copying an existing instance.

Method Summary

Modifier and Type	Method and Description
<T> Signal	addAndRemoveExistingData(TypeLiteral<T> typeLiteralT, T additionalData) Creates a new signal by adding data in addition to the data existing on this signal.
Signal	addData(Object additionalData) Creates a new signal by adding data in addition to the data existing on this signal.
Signal	addNoiseTemperature(double noiseTemperature) Creates a new signal by adding noise temperature (such as thermal noise), in kelvin.
Signal	applyGain(double gain) Create a new signal by applying a gain to this signal.
boolean	containsDataByType(Class<?> type) Gets a value indicating whether this signal contains data of the specified type.
<T> boolean	containsDataByType(TypeLiteral<T> typeLiteralT) Gets a value indicating whether this signal contains data of the specified type.
static Signal	createSignal(double power, double frequency, double lowerBandwidthLimit, double upperBandwidthLimit) Create a new noiseless signal based on the given properties.
static Signal	createSignal(double power, double frequency, double lowerBandwidthLimit, double upperBandwidthLimit, double noiseTemperature, double lowerNoiseBandwidthLimit, double upperNoiseBandwidthLimit) Create a new signal based on the given properties.
static Signal	createSignal(double power, double frequency, double lowerBandwidthLimit, double upperBandwidthLimit, double noiseTemperature, double lowerNoiseBandwidthLimit, double upperNoiseBandwidthLimit, Iterable<? extends Object> signalData) Create a new signal based on the given properties.
static Signal	createSignal(double power, double frequency, double lowerBandwidthLimit, double upperBandwidthLimit, Iterable<? extends Object> signalData) Create a new noiseless signal based on the given properties.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
boolean	equalsType(Signal other) Indicates whether another instance of this type is exactly equal to this instance.
double	getBandwidth() Gets the signal bandwidth, in hertz.
static Signal	getBaseSignal() Gets an instance of a signal with zero power, zero frequency, and infinite bandwidth.
Object	getDataByType(Class<?> type) Gets signal data based on the type of data requested.
<T> T	getDataByType(TypeLiteral<T> typeLiteralT) Gets signal data based on the type of data requested.
ArrayList<Object>	getDataList() Create a copy of the signal data.
double	getFrequency() Gets the center frequency of the signal, in hertz.
double	getLowerBandwidthFrequency() Gets the lower bandwidth frequency, in hertz.
double	getLowerBandwidthLimit() Gets the offset from the center Frequency (get) to the lower bandwidth limit, in hertz.
double	getLowerNoiseBandwidthFrequency() Gets the frequency of the lower boundary of the noise bandwidth, in hertz.
double	getLowerNoiseBandwidthLimit() Gets the offset from the center Frequency (get) to the lower limit of the noise bandwidth, in hertz.
double	getNoiseBandwidth() Gets the bandwidth of the signal noise, in hertz.
double	getNoisePower() Gets the power of the noise, in watts, as computed from the NoiseTemperature (get) based on the NoiseBandwidth (get).
double	getNoiseTemperature() Gets the equivalent noise temperature, in kelvin.
double	getPower() Gets the total signal power, in watts.
double	getUpperBandwidthFrequency() Gets the upper bandwidth frequency, in hertz.
double	getUpperBandwidthLimit() Gets the offset from the center Frequency (get) to the upper bandwidth limit, in hertz.
double	getUpperNoiseBandwidthFrequency() Gets the frequency of the upper boundary of the noise bandwidth, in hertz.
double	getUpperNoiseBandwidthLimit() Gets the offset from the center Frequency (get) to the upper limit of the noise bandwidth, in hertz.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
Signal	modifyBandwidth(double lowerBandwidthLimit, double upperBandwidthLimit) Create a new signal by modifying the bandwidth limits of this signal.
Signal	modifyFrequency(double frequency) Create a new signal by modifying the frequency of this signal.
Signal	modifyNoiseTemperature(double noiseTemperature) Create a new signal by modifying the NoiseTemperature (get) of this signal.
Signal	modifyNoiseTemperature(double noiseTemperature, double lowerNoiseBandwidthLimit, double upperNoiseBandwidthLimit) Create a new signal by modifying the NoiseTemperature (get) of this signal.
Signal	modifyPower(double power) Create a new signal by modifying the power of this signal.
Signal	modifySignalProperties(double power, double frequency, double lowerBandwidthLimit, double upperBandwidthLimit, double noiseTemperature, double lowerNoiseBandwidthLimit, double upperNoiseBandwidthLimit) Create a new signal by modifying the properties of this signal.
<T> Signal	removeData(TypeLiteral<T> typeLiteralT) Creates a new signal by removing all data of the given type existing on this signal.

Methods inherited from class java.lang.Object

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

Constructor Detail

Signal

protected Signal(@Nonnull
                 Signal existingInstance)

Create a new instance by copying an existing instance.

Parameters:

existingInstance - An existing signal.

Method Detail

createSignal

@Nonnull
public static Signal createSignal(double power,
                                            double frequency,
                                            double lowerBandwidthLimit,
                                            double upperBandwidthLimit)

Create a new noiseless signal based on the given properties. To modify a preexisting signal, use Signal.modifySignalProperties(double, double, double, double, double, double, double) or similar methods on the preexisting signal instance.

Parameters:

power - Signal power, in watts.

frequency - Signal frequency, in hertz.

lowerBandwidthLimit - A value specifying the (negative) offset, in hertz, from the central frequency, to the lower limit of the signal's bandwidth.

upperBandwidthLimit - A value specifying the (positive) offset, in hertz, from the central frequency, to the upper limit of the signals' bandwidth.

Returns:

The newly created signal.

Throws:

ArgumentOutOfRangeException -

Thrown when:

• frequency or power is negative
• the computed LowerBandwidthFrequency (get) (frequency + lowerBandwidthLimit) is negative
• the frequency Bandwidth (get) (upperBandwidthLimit - lowerBandwidthLimit) is zero

createSignal

@Nonnull
public static Signal createSignal(double power,
                                            double frequency,
                                            double lowerBandwidthLimit,
                                            double upperBandwidthLimit,
                                            @Nullable
                                            Iterable<? extends Object> signalData)

Create a new noiseless signal based on the given properties. To modify a preexisting signal, use Signal.modifySignalProperties(double, double, double, double, double, double, double) or similar methods on the preexisting signal instance.

Parameters:

power - Signal power, in watts.

frequency - Signal frequency, in hertz.

lowerBandwidthLimit - A value specifying the (negative) offset, in hertz, from the central frequency, to the lower limit of the signal's bandwidth.

upperBandwidthLimit - A value specifying the (positive) offset, in hertz, from the central frequency, to the upper limit of the signals' bandwidth.

signalData - A set of data which describe optional properties of this signal (e.g. modulation, encoding, polarization, command information, etc). If null, will be ignored.

Returns:

The newly created signal.

Throws:

ArgumentOutOfRangeException -

Thrown when:

• frequency or power is negative
• the computed LowerBandwidthFrequency (get) (frequency + lowerBandwidthLimit) is negative
• the frequency Bandwidth (get) (upperBandwidthLimit - lowerBandwidthLimit) is zero

createSignal

@Nonnull
public static Signal createSignal(double power,
                                            double frequency,
                                            double lowerBandwidthLimit,
                                            double upperBandwidthLimit,
                                            double noiseTemperature,
                                            double lowerNoiseBandwidthLimit,
                                            double upperNoiseBandwidthLimit)

Create a new signal based on the given properties. To modify a preexisting signal, use Signal.modifySignalProperties(double, double, double, double, double, double, double) or similar methods on the preexisting signal instance.

Parameters:

power - Signal power, in watts.

frequency - Signal frequency, in hertz.

lowerBandwidthLimit - A value specifying the (negative) offset, in hertz, from the central frequency, to the lower limit of the signal's bandwidth.

upperBandwidthLimit - A value specifying the (positive) offset, in hertz, from the central frequency, to the upper limit of the signals' bandwidth.

noiseTemperature - The equivalent noise temperature, in kelvin, spread out over the noise bandwidth.

lowerNoiseBandwidthLimit - The offset to the lower limit of the noise bandwidth, in hertz.

upperNoiseBandwidthLimit - The offset to the upper limit of the noise bandwidth, in hertz.

Returns:

The newly created signal.

Throws:

ArgumentOutOfRangeException -

Thrown when:

• frequency, power, or noiseTemperature is negative
• the computed LowerBandwidthFrequency (get) (frequency + lowerBandwidthLimit) is negative
• the frequency Bandwidth (get) (upperBandwidthLimit - lowerBandwidthLimit) is zero
• lowerNoiseBandwidthLimit causes the lowest frequency of the noise to be negative (frequency + lowerNoiseBandwidthLimit must be positive)
• lowerNoiseBandwidthLimit is greater than upperNoiseBandwidthLimit (note that lowerNoiseBandwidthLimit is usually negative)

createSignal

@Nonnull
public static Signal createSignal(double power,
                                            double frequency,
                                            double lowerBandwidthLimit,
                                            double upperBandwidthLimit,
                                            double noiseTemperature,
                                            double lowerNoiseBandwidthLimit,
                                            double upperNoiseBandwidthLimit,
                                            @Nullable
                                            Iterable<? extends Object> signalData)

Create a new signal based on the given properties. To modify a preexisting signal, use Signal.modifySignalProperties(double, double, double, double, double, double, double) or similar methods on the preexisting signal instance.

Parameters:

power - Signal power, in watts.

frequency - Signal frequency, in hertz.

lowerBandwidthLimit - A value specifying the (negative) offset, in hertz, from the central frequency, to the lower limit of the signal's bandwidth.

upperBandwidthLimit - A value specifying the (positive) offset, in hertz, from the central frequency, to the upper limit of the signals' bandwidth.

noiseTemperature - The equivalent noise temperature, in kelvin, spread out over the noise bandwidth.

lowerNoiseBandwidthLimit - The offset to the lower limit of the noise bandwidth, in hertz.

upperNoiseBandwidthLimit - The offset to the upper limit of the noise bandwidth, in hertz.

signalData - A set of metadata which describe additional properties of this signal. If null, will be ignored.

Returns:

The newly created signal.

Throws:

ArgumentOutOfRangeException -

Thrown when:

• frequency, power, or noiseTemperature is negative
• the computed LowerBandwidthFrequency (get) (frequency + lowerBandwidthLimit) is negative
• the frequency Bandwidth (get) (upperBandwidthLimit - lowerBandwidthLimit) is zero
• lowerNoiseBandwidthLimit causes the lowest frequency of the noise to be negative (frequency + lowerNoiseBandwidthLimit must be positive)
• lowerNoiseBandwidthLimit is greater than upperNoiseBandwidthLimit (note that lowerNoiseBandwidthLimit is usually negative)

getPower

public final double getPower()

Gets the total signal power, in watts. This specifies the total power spread out over the Bandwidth (get).

getFrequency

public final double getFrequency()

Gets the center frequency of the signal, in hertz. This is usually the frequency which has the greatest power density.

getUpperBandwidthLimit

public final double getUpperBandwidthLimit()

Gets the offset from the center Frequency (get) to the upper bandwidth limit, in hertz.

getLowerBandwidthLimit

public final double getLowerBandwidthLimit()

Gets the offset from the center Frequency (get) to the lower bandwidth limit, in hertz. (Usually, this value is negative).

getUpperBandwidthFrequency

public final double getUpperBandwidthFrequency()

Gets the upper bandwidth frequency, in hertz. This specifies the signal's highest frequency.

getLowerBandwidthFrequency

public final double getLowerBandwidthFrequency()

Gets the lower bandwidth frequency, in hertz. This specifies the signal's lowest frequency.

getBandwidth

public final double getBandwidth()

Gets the signal bandwidth, in hertz. This specifies the range of frequencies over which the majority of signal Power (get) is distributed.

getNoisePower

public final double getNoisePower()

Gets the power of the noise, in watts, as computed from the NoiseTemperature (get) based on the NoiseBandwidth (get).

getNoiseTemperature

public final double getNoiseTemperature()

Gets the equivalent noise temperature, in kelvin. This represents the contribution of thermal noise and other stochastic processes on the signal.

getLowerNoiseBandwidthLimit

public final double getLowerNoiseBandwidthLimit()

Gets the offset from the center Frequency (get) to the lower limit of the noise bandwidth, in hertz. (Usually, this value is negative).

getUpperNoiseBandwidthLimit

public final double getUpperNoiseBandwidthLimit()

Gets the offset from the center Frequency (get) to the upper limit of the noise bandwidth, in hertz.

getLowerNoiseBandwidthFrequency

public final double getLowerNoiseBandwidthFrequency()

Gets the frequency of the lower boundary of the noise bandwidth, in hertz. This specifies the lowest frequency at which there is significant noise.

getUpperNoiseBandwidthFrequency

public final double getUpperNoiseBandwidthFrequency()

Gets the frequency of the upper boundary of the noise bandwidth, in hertz. This specifies the highest frequency at which there is significant noise.

getNoiseBandwidth

public final double getNoiseBandwidth()

Gets the bandwidth of the signal noise, in hertz. This specifies the range of frequencies over which there is significant noise.

applyGain

@Nonnull
public final Signal applyGain(double gain)

Create a new signal by applying a gain to this signal. The gain is applied to both the signal Power (get) and NoisePower (get).

Parameters:

gain - The multiplicative gain to apply.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException - Thrown when gain is negative.

modifyPower

@Nonnull
public final Signal modifyPower(double power)

Create a new signal by modifying the power of this signal.

Parameters:

power - The new power, in Watts.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException - Thrown when power is negative.

modifyFrequency

@Nonnull
public final Signal modifyFrequency(double frequency)

Create a new signal by modifying the frequency of this signal.

Parameters:

frequency - The new frequency, in hertz.

Returns:

The modified signal.

Throws:

IllegalStateException - Thrown when frequency combined with the old bandwidth causes part of the frequency range to be negative (frequency + LowerBandwidthLimit (get) must be positive).

modifyBandwidth

@Nonnull
public final Signal modifyBandwidth(double lowerBandwidthLimit,
                                              double upperBandwidthLimit)

Create a new signal by modifying the bandwidth limits of this signal.

Parameters:

lowerBandwidthLimit - The new offset to the lowest frequency from the center frequency, in hertz. (Usually negative)

upperBandwidthLimit - The new offset to the highest frequency from the center frequency, in hertz.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException - Thrown when lowerBandwidthLimit causes the lowest frequency to be negative (Frequency (get) + lowerBandwidthLimit must be positive).

modifyNoiseTemperature

@Nonnull
public final Signal modifyNoiseTemperature(double noiseTemperature)

Create a new signal by modifying the NoiseTemperature (get) of this signal.

Parameters:

noiseTemperature - The new noise temperature, in kelvin.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException - Thrown when noiseTemperature is negative.

modifyNoiseTemperature

@Nonnull
public final Signal modifyNoiseTemperature(double noiseTemperature,
                                                     double lowerNoiseBandwidthLimit,
                                                     double upperNoiseBandwidthLimit)

Create a new signal by modifying the NoiseTemperature (get) of this signal.

Parameters:

noiseTemperature - The new noise temperature, in kelvin.

lowerNoiseBandwidthLimit - The new offset to the lower limit of the NoiseBandwidth (get), in hertz.

upperNoiseBandwidthLimit - The new offset to the upper limit of the NoiseBandwidth (get), in hertz.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException - Thrown when noiseTemperature is negative, or when lowerNoiseBandwidthLimit is greater than upperNoiseBandwidthLimit.

addNoiseTemperature

@Nonnull
public final Signal addNoiseTemperature(double noiseTemperature)

Creates a new signal by adding noise temperature (such as thermal noise), in kelvin.

Parameters:

noiseTemperature - The temperature to add, in kelvin.

Returns:

A new signal with a new value for NoiseTemperature (get).

Throws:

ArgumentOutOfRangeException - Thrown when the computed NoiseTemperature (get) is negative.

modifySignalProperties

@Nonnull
public final Signal modifySignalProperties(double power,
                                                     double frequency,
                                                     double lowerBandwidthLimit,
                                                     double upperBandwidthLimit,
                                                     double noiseTemperature,
                                                     double lowerNoiseBandwidthLimit,
                                                     double upperNoiseBandwidthLimit)

Create a new signal by modifying the properties of this signal.

The modified Signal retains any additional Data on the original signal.

Parameters:

power - The new total power, in watts.

frequency - The new center frequency, in hertz.

lowerBandwidthLimit - The new offset from the center frequency to the lowest frequency, in hertz. (usually negative)

upperBandwidthLimit - The new offset from the center frequency to the highest frequency, in hertz.

noiseTemperature - The new noise temperature, in kelvin.

lowerNoiseBandwidthLimit - The new offset from the center frequency to the lowest frequency at which there is significant noise, in hertz.

upperNoiseBandwidthLimit - The new offset from the center frequency to the highest frequency at which there is significant noise, in hertz.

Returns:

The modified signal.

Throws:

ArgumentOutOfRangeException -

Thrown when:

• frequency, power, or noiseTemperature is negative
• the computed LowerBandwidthFrequency (get) (frequency + lowerBandwidthLimit) is negative
• the frequency Bandwidth (get) (upperBandwidthLimit - lowerBandwidthLimit) is zero
• lowerNoiseBandwidthLimit causes the lowest frequency of the noise to be negative (frequency + lowerNoiseBandwidthLimit must be positive)
• lowerNoiseBandwidthLimit is greater than upperNoiseBandwidthLimit (note that lowerNoiseBandwidthLimit is usually negative)

addData

@Nonnull
public final Signal addData(@Nullable
                                      Object additionalData)

Creates a new signal by adding data in addition to the data existing on this signal.

If additionalData is null, the original Signal is returned.

Parameters:

additionalData - New data to add to this signal's data.

Returns:

The modified signal with the additional data added.

addAndRemoveExistingData

@Nonnull
public final <T> Signal addAndRemoveExistingData(TypeLiteral<T> typeLiteralT,
                                                           @Nullable
                                                           T additionalData)

Creates a new signal by adding data in addition to the data existing on this signal. Existing instances of the supplied data type will be removed.

If additionalData is null, the original Signal is returned.

Type Parameters:

T - The type of data.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

additionalData - New data to add to this signal's data.

Returns:

The modified signal with the additional data added.

removeData

@Nonnull
public final <T> Signal removeData(TypeLiteral<T> typeLiteralT)

Creates a new signal by removing all data of the given type existing on this signal.

Type Parameters:

T - The type of data to remove.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

Returns:

The modified signal with data removed.

getDataByType

@Nullable
public final <T> T getDataByType(TypeLiteral<T> typeLiteralT)

Gets signal data based on the type of data requested. This data represents optional properties on the signal.

There should be only one instance of a given type in a given signal. If there are more, this method will return the first occurrence.

Type Parameters:

T - The type of data to retrieve.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

Returns:

The data, or null if there is no data of the given type.

containsDataByType

public final <T> boolean containsDataByType(TypeLiteral<T> typeLiteralT)

Gets a value indicating whether this signal contains data of the specified type.

Type Parameters:

T - The type of data to check for.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

Returns:

true if this signal contains data of the specified type; otherwise false.

getDataByType

@Nullable
public final Object getDataByType(@Nonnull
                                             Class<?> type)

Gets signal data based on the type of data requested. This data represents optional properties on the signal.

There should be only one instance of a given type in a given signal. If there are more, this method will return the first occurrence.

Parameters:

type - The type of data to retrieve.

Returns:

The data, or null if there is no data of the given type.

Throws:

ArgumentNullException - Thrown when type is null.

containsDataByType

public final boolean containsDataByType(@Nonnull
                                        Class<?> type)

Gets a value indicating whether this signal contains data of the specified type.

Parameters:

type - The type of data to check for.

Returns:

true if this signal contains data of the specified type; otherwise false.

getDataList

@Nonnull
public final ArrayList<Object> getDataList()

Create a copy of the signal data. The Signal will not reflect changes to the list. This data represents optional properties on the signal.

Returns:

The list of signal data.

equals

public boolean equals(Object obj)

Indicates whether another object is exactly equal to this instance.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this instance.

Returns:

true if obj is an instance of this type and represents the same value as this instance; otherwise false.

See Also:

Object.hashCode(), HashMap

equalsType

public final boolean equalsType(Signal other)

Indicates whether another instance of this type is exactly equal to this instance.

Specified by:

equalsType in interface IEquatable<Signal>

Parameters:

other - The instance to compare to this instance.

Returns:

true if other represents the same value as this instance; otherwise false.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

getBaseSignal

@Nonnull
public static Signal getBaseSignal()

Gets an instance of a signal with zero power, zero frequency, and infinite bandwidth.