xal.tools.dsp

Class DigitalFunctionUtility

java.lang.Object

xal.tools.dsp.DigitalFunctionUtility

public class DigitalFunctionUtility
extends java.lang.Object

Utility class for performing common operations on and for digital functions.

Within this package digital functions are taken to be objects of type double[]). Because sub-typing from double[] is illegal in Java, it is necessary to create a utility class to handle the common operations on digital functions.

Constructor Summary

Constructors

Constructor and Description
DigitalFunctionUtility()

Method Summary

Modifier and Type	Method and Description
static double[]	abs(double[] arrFunc) Compute and return the (functional) absolute value of the given function.
static double[]	add(double[] arrFunc1, double[] arrFunc2) Compute and return the function sum of the given functions.
static int	argGreaterThan(double dblVal, double[] arrFunc) Return the index where the function first exceeds the given value.
static int	argMaximum(double[] arrFunc) Return the index at with the function maximum occurs.
static int	argMinimum(double[] arrFunc) Return the index at with the function minimum occurs.
static java.lang.String	buildValueTable(double[]... argFuncs) Build a table of function values for comparison.
static double	compError(double[] arrFunc, double[] arrTarg) Computes and returns the l2 distance between the given vector functions normalized by the norm ||arrTarg||2.
static double[]	generateCosine(int szArray, int intFreq, double dblPhase) Generate a discrete cosine function of the given size, given discrete frequency, and given phase offset.
static double[]	generateSine(int szArray, int intFreq, double dblPhase) Generate a discrete sine function of the given size, given discrete frequency, and given phase offset.
static double	integral(double[] arrFunc) Compute and return the integral (i.e., the summation of all the elements) of the given function.
static double	maximumValue(double[] arrFunc) Return the maximum value of the function.
static double	minimumValue(double[] arrFunc) Return the minimum value of the function.
static void	scaleFunction(double dblVal, double[] arrFunc) Scale the function by the given value.
static double[]	square(double[] arrFunc) Compute and return the (functional) square of the given function.
static double[]	subtract(double[] arrFunc1, double[] arrFunc2) Compute and return the function difference of the given functions.
static void	subtractFrom(double[] arrFunc, double dblVal) In place subtraction of the given value from the function.
static double[]	totalVariation(double[] arrFunc) Compute and return the total variation of the given function.

Methods inherited from class java.lang.Object

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

Constructor Detail

DigitalFunctionUtility

public DigitalFunctionUtility()

Method Detail

compError

public static double compError(double[] arrFunc,
                               double[] arrTarg)

Computes and returns the l₂ distance between the given vector functions normalized by the norm ||arrTarg||₂.

Parameters:

arrFunc - vector function

arrTarg - target vector function

Returns:

||arrFunc1 - arrFunc2||₂/||arrTarg||₂

buildValueTable

public static java.lang.String buildValueTable(double[]... argFuncs)
                                        throws java.lang.ArrayIndexOutOfBoundsException

Build a table of function values for comparison. Each table row consists of the function index, then corresponding function values, all separated by tab characters ("\t").

Parameters:

argFuncs - discrete functions to be tabulated

Returns:

formatted string of tabulated values

Throws:

java.lang.ArrayIndexOutOfBoundsException - arguments are not all the same size

generateSine

public static double[] generateSine(int szArray,
                                    int intFreq,
                                    double dblPhase)

Generate a discrete sine function of the given size, given discrete frequency, and given phase offset. Note that the largest frequency that returns a meaning function is szArray/2. Any frequencies larger than that are unrecognizable due to insufficient resolution.

Parameters:

dblPhase - phase offset (in radians)

szArray - array size of the returned function

intFreq - frequency component of the returned function

Returns:

sin(2πf + φ)

generateCosine

public static double[] generateCosine(int szArray,
                                      int intFreq,
                                      double dblPhase)

Generate a discrete cosine function of the given size, given discrete frequency, and given phase offset. Note that the largest frequency that returns a meaning function is szArray/2. Any frequencies larger than that are unrecognizable due to insufficient resolution.

Parameters:

dblPhase - phase offset (in radians)

szArray - array size of the returned function

intFreq - frequency component of the returned function

Returns:

cos(2πf + φ)

scaleFunction

public static void scaleFunction(double dblVal,
                                 double[] arrFunc)

Scale the function by the given value.

Parameters:

dblVal - scale factor

add

public static double[] add(double[] arrFunc1,
                           double[] arrFunc2)
                    throws java.lang.IllegalArgumentException

Compute and return the function sum of the given functions.

Parameters:

arrFunc1 - addend

arrFunc2 - adder

Returns:

sum of arguments

Throws:

java.lang.IllegalArgumentException - arguments are of different sizes

subtract

public static double[] subtract(double[] arrFunc1,
                                double[] arrFunc2)
                         throws java.lang.IllegalArgumentException

Compute and return the function difference of the given functions.

Parameters:

arrFunc1 - subtractend

arrFunc2 - subtractor

Returns:

difference of arguments

Throws:

java.lang.IllegalArgumentException - argument are of different sizes

subtractFrom

public static void subtractFrom(double[] arrFunc,
                                double dblVal)

In place subtraction of the given value from the function.

Parameters:

arrFunc - subtractend

dblVal - subtractor

Throws:

java.lang.IllegalArgumentException - argument are of different sizes

maximumValue

public static double maximumValue(double[] arrFunc)

Return the maximum value of the function.

Parameters:

arrFunc - digital function

Returns:

function maximum

minimumValue

public static double minimumValue(double[] arrFunc)

Return the minimum value of the function.

Parameters:

arrFunc - digital function

Returns:

function minimum

argMaximum

public static int argMaximum(double[] arrFunc)

Return the index at with the function maximum occurs.

Parameters:

arrFunc - digital function

Returns:

index of maximum value

argMinimum

public static int argMinimum(double[] arrFunc)

Return the index at with the function minimum occurs.

Parameters:

arrFunc - digital function

Returns:

index of minimum value

argGreaterThan

public static int argGreaterThan(double dblVal,
                                 double[] arrFunc)

Return the index where the function first exceeds the given value.

Parameters:

dblVal - inspection value

arrFunc - digital function

Returns:

index where function first exceeds value or arrFunc.length if none

abs

public static double[] abs(double[] arrFunc)

Compute and return the (functional) absolute value of the given function.

Parameters:

arrFunc - function to process

Returns:

functional absolute value of the argument

square

public static double[] square(double[] arrFunc)

Compute and return the (functional) square of the given function.

Parameters:

arrFunc - function to square

Returns:

functional square of the argument

totalVariation

public static double[] totalVariation(double[] arrFunc)

Compute and return the total variation of the given function. The total variation TV(f) of a function f(·) is defined as

TV[f](t) ≡ ∫^t|df(τ)/dt|dτ

Parameters:

arrFunc - target function

Returns:

total variation of given function

integral

public static double integral(double[] arrFunc)

Compute and return the integral (i.e., the summation of all the elements) of the given function.

Parameters:

arrFunc - function to integrate

Returns:

the sum of all array elements