Michael Thomas Flanagan's Java Scientific Library

ComplexErrorProp Class:     Error Propagation in Complex Arithmetic

      

Last update: 28 May 2007

This class defines an object consisting of a real part with a value and its associated error and an imaginary part with a value and its associated error. The class includes the methods for propagating the error in a limited number of standard complex arithmetic operations. The error should be the standard deviation, or an estimate of the standard deviation, of the variable.

This class does not include propagation methods where the errors of the two complex numbers are correlated but the methods in this class do allow for correlation between the real and imaginary parts of the same complex number, where relevant, e.g. in the determination of the modulus of a complex number.


The propagation error on complex division is estimated by a Monte Carlo simulation.

import directive: import flanagan.complex.ComplexErrorProp; Related classes

SUMMARY OF CONSTRUCTORS AND METHODS
Constructors public ComplexErrorProp()
  
public ComplexErrorProp(ErrorProp real, ErrorProp imag)
  
public ComplexErrorProp(ErrorProp real, ErrorProp imag, double corrCoeff)
  
public ComplexErrorProp(double realValue, double realError, double imagValue, double imagError)
  
public ComplexErrorProp(double realValue, double realError, double imagValue, double imagError, double corrCoeff)
  
Set Values public void reset(ErrorProp real, ErrorProp imag)
  
public void reset(ErrorProp real, ErrorProp imag, double corrCoeff)
  
public void reset(double realValue, double realError, double imagValue, double imagError)
  
public void reset(double realValue, double realError, double imagValue, double imagError, double corrCoeff)
  
public void polar(ErrorProp magn, ErrorProp phase)
  
public void polar(ErrorProp magn, ErrorProp phase, double corrCoeff)
  
public void polar(double magnValue, double magnError, double phaseValue, double phaseError)
  
public void polar(double magnValue, double magnError, double phaseValue, double phaseError, double corrCoeff)
  
public void setReal(ErrorProp real)
  
public void setReal(double realValue, double realError)
  
public void setImag(ErrorProp imag)
  
public void setImag(double imagValue, double imagError)
  
public void setDouble(double constant)
  
public void setCorrCoeff(double corrCoeff)
  
Get Values public ErrorProp getReal()
  
public double getRealValue()
  
public double getRealError()
  
public ErrorProp getImag()
  
public double getImagValue()
  
public double getImagError()
  
public double getCorrCoeff()
  
Copy public ComplexErrorProp copy()
 public static ComplexErrorProp copy(ComplexErrorProp x)
public Object clone()
  
Truncate mantissae to n places public ComplexErrorProp truncate(int n) public static ComplexErrorProp truncate(ComplexErrorProp x, int n)
Print public void print(String message)
  
public void print()
  
public void println(String message)
  
public void println()
  
Conversions public String toString()
 public static String toString(ComplexErrorProp aa)
Addition public ComplexErrorProp plus(ComplexErrorProp a) public static ComplexErrorProp plus(ComplexErrorProp a, ComplexErrorProp b)
Subtraction public ComplexErrorProp minus(ComplexErrorProp a) public static ComplexErrorProp minus(ComplexErrorProp a, ComplexErrorProp b)
Multiplication public ComplexErrorProp times(ComplexErrorProp a) public static ComplexErrorProp times(ComplexErrorProp a, ComplexErrorProp b)
Division public ComplexErrorProp over(ComplexErrorProp a) public static ComplexErrorProp over(ComplexErrorProp a, ComplexErrorProp b)
Modulus (absolute value) public ErrorProp abs() public static ErrorProp abs(ComplexErrorProp aa)
Argument public ErrorProp arg() public static ErrorProp arg(ComplexErrorProp aa)
Exponential public ComplexErrorProp exp() public static ComplexErrorProp exp(ComplexErrorProp aa)
Some Useful
Numbers 		  public static ComplexErrorProp zero()
  public static ComplexErrorProp plusOne()
  public static ComplexErrorProp minusOne()
  public static ComplexErrorProp plusJay()
  public static ComplexErrorProp minusJay()
Monte Carlo Simulation   public static void setMonteCarloLength(int length)
  public static int getMonteCarloLength()


CONSTRUCTORS

public ComplexErrorProp()
public ComplexErrorProp(ErrorProp real, ErrorProp imag)
public ComplexErrorProp(ErrorProp real, ErrorProp imag, double corrCoeff)
public ComplexErrorProp(double realValue, double realError, double imagValue, double imagError)
public ComplexErrorProp(double realValue, double realError, double imagValue, double imagError, double corrCoeff)

Usage:                      ComplexErrorProp aa = new ComplexErrorProp();
This creates a new instance of ComplexErrorProp, aa, and initialises the value of real part of this complex number, the error of real part, the value of the imaginary part, the error of the imaginary part and the correlation coefficient of the real and imaginary parts all to zero.

Usage:                      ComplexErrorProp aa = new ComplexErrorProp(real, imag);
This creates a new instance of ComplexErrorProp, aa, and initialises the value of real part of this complex number and its error to the values held in the ErrorProp argument, real, It initialises the value of the imaginary part and its error to the values held in the ErrorProp argument imag. The correlation coefficient of the real and imaginary parts is set to zero.

Usage:                      ComplexErrorProp aa = new ComplexErrorProp(real, imag, rho);
This creates a new instance of ComplexErrorProp, aa, and initialises the value of real part of this complex number and its error to the values held in the ErrorProp argument, real, It initialises the value of the imaginary part and its error to the values held in the ErrorProp argument imag. The correlation coefficient of the real and imaginary parts is set to the value held in the double argument rho.

Usage:                      ComplexErrorProp aa = new ComplexErrorProp(realValue, realError, imagValue, imagError);
This creates a new instance of ComplexErrorProp, aa, and initialises the value of real part of this complex number to the double argument, realValue, the error of the real part to the double argument, realError, the value of the imaginary part to the double argument, imagValue,and the error of the imaginary part to the double argument, imagError. The correlation coefficient of the real and imaginary parts is set to zero.

Usage:                      ComplexErrorProp aa = new ComplexErrorProp(realValue, realError, imagValue, imagError, rho);
This creates a new instance of ComplexErrorProp, aa, and initialises the value of real part of this complex number to the double argument, realValue, the error of the real part to the double argument, realError, the value of the imaginary part to the double argument, imagValue,and the error of the imaginary part to the double argument, imagError. The correlation coefficient of the real and imaginary parts is set to the value held in the double argument rho.


METHODS

SET VALUES
public void reset(ErrorProp real, ErrorProp imag)
Usage:                      aa.reset(real, imag);
This method sets the value of real part of the complex number held in aa and its error to the values held in the ErrorProp argument, real. It sets the value of the imaginary part and its error to the values held in the ErrorProp argument, imag.

public void reset(ErrorProp real, ErrorProp imag, double corrCoeff)
Usage:                      aa.reset(real, imag, rho);
This method sets the value of real part of the complex number held in aa and its error to the values held in the ErrorProp argument, real. It sets the value of the imaginary part and its error to the values held in the ErrorProp argument, imag. The value of the correlation coefficient of the real and imaginary parts is set to the value of the double rho.

public void reset(double realValue, double realError, double imagValue, double imagError)
Usage:                      aa.reset(realValue, realError, imagValue, imagError);
This method sets the value of real part of the complex number held in aa to the value of realValue. Its error to the value of realError. It sets the value of the imaginary part to the value of imagValue and its error to the value of imagError.

public void reset(double realValue, double realError, double imagValue, double imagError, double corrCoeff)
Usage:                      aa.reset(realValue, realError, imagValue, imagError, rho);
This method sets the value of real part of the complex number held in aa to the value of realValue. Its error to the value of realError. It sets the value of the imaginary part to the value of imagValue and its error to the value of imagError. It sets the value of the imaginary part to the value of imagValue and its error to the value of imagError. The value of the correlation coefficient of the real and imaginary parts is set to the value of the double rho.

public void polar(ErrorProp magn, ErrorProp phase)
Usage:                      aa.polar(magn, phase);
This method allows the complex number to be entered as a magnitude and a phase. It converts this form to the standard a+jb form, propagates the errors of the real and imaginary parts and calculates the correlation coefficient of the real and imaginary parts. The value of magnitude and its error are entered as the ErrorProp argument, magn. The value of phase (in radians) and its error are entered as the ErrorProp argument, phase.
NB The correlation coefficient of the magnitude and the phase is used in this calculation. Use the set method immediately below if this correlation coefficient is not zero.

public void polar(ErrorProp magn, ErrorProp phase, double corrCoeff)
Usage:                      aa.polar(magn, phase, rho);
This method allows the complex number to be entered as a magnitude and a phase. It converts this form to the standard a+jb formform, propagates the errors of the real and imaginary parts and calculates the correlation coefficient of the real and imaginary parts. The value of magnitude and its error are entered as the ErrorProp argument, magn. The value of phase (in radians) and its error are entered as the ErrorProp argument, phase. The value of the correlation coefficient of the magnitude and the phase is set to the value of the double rho.
NB The correlation coefficient of the magnitude and the phase is used in this calculation.

public void polar(double magnValue, double magnError, double phaseValue, double phaseError)
Usage:                      aa.polar(magnValue, magnError, phaseValue, phaseError);
This method allows the complex number to be entered as a magnitude and a phase. It converts this form to the standard a+jb formform, propagates the errors of the real and imaginary parts and calculates the correlation coefficient of the real and imaginary parts. The value of the magnitude is entered as the double, magnValue. The error of the magnitude is entered as the double, magnError. The value of the phase (in radians) is entered as the double, phaseValue. The error of the phase (in radians) is entered as the double, phaseError.
NB The correlation coefficient of the magnitude and the phase is used in this calculation. Use the set method immediately below if this correlation coefficient is not zero.

public void polar(double magnValue, double magnError, double phaseValue, double phaseError, double corrCoeff)
Usage:                      aa.polar(magnValue, magnError, phaseValue, phaseError, rho);
This method allows the complex number to be entered as a magnitude and a phase. It converts this form to the standard a+jb formform, propagates the errors of the real and imaginary parts and calculates the correlation coefficient of the real and imaginary parts. The value of the magnitude is entered as the double, magnValue. The error of the magnitude is entered as the double, magnError. The value of the phase (in radians) is entered as the double, phaseValue. The error of the phase (in radians) is entered as the double, phaseError. The value of the correlation coefficient of the the magnitude and the phase is set to the value of the double rho.
NB The correlation coefficient of the magnitude and the phase is used in this calculation.

public void setReal(ErrorProp real)
Usage:                      aa.setReal(real);
This method sets the value of the real part of the complex number held in aa and its error to the values held in the ErrorProp argument, real.

public void setReal(double realValue, double realError)
Usage:                      aa.setReal(realValue, realError);
This method sets the value of the real part of the complex number held in aa to the value of the double, realValue, and its error to the value held in the double, realError.

public void setImag(ErrorProp imag)
Usage:                      aa.setImag(imag);
This method sets the value of the imaginary part of the complex number held in aa and its error to the values held in the ErrorProp argument, imag.

public void setImag(double imagValue, double imagError)
Usage:                      aa.setImag(imagValue, imagError);
This method sets the value of the imaginary part of the complex number held in aa to the value of the double, imagValue, and its error to the value held in the double, imagError.

public void setDouble(double constant)
Usage:                      aa.setDouble(constant);
This method sets the value of the real part of the complex number held in aa to the value of the double, constant. The imaginary part and both the error of the real and of the imaginary part are all set to zero.

public void setCorrCoeff(double corrCoeff)
Usage:                      aa.setCorrCoeff(rho);
This method sets the value of the correlation coefficient of the real and imaginary parts of the complex number held in aa to the value of the double, rho.


GET VALUES
public ErrorProp getReal()
Usage:                      x = aa.getReal();
The value and the error of the real part are returned as an ErrorProp number.

public double getRealValue()
Usage:                      x = aa.getRealValue();
The value of the real part is returned as a double.

public double getRealError()
Usage:                      x = aa.getRealError();
The error of the real part is returned as a double.

public ErrorProp getImag()
Usage:                      x = aa.getImag();
The value and the error of the imaginary part are returned as an ErrorProp number.

public double getImagValue()
Usage:                      x = aa.getImagValue();
The value of the imaginary part is returned as a double.

public double getImagError()
Usage:                      x = aa.getImagError();
The error of the imaginary part is returned as a double.

public double getCorrCoeff()
Usage:                      rho = aa.getCorrCoeff();
The value set for the correlation coefficient of the real and the imaginary parts is returned as a double.


ADDITION
public ComplexErrorProp plus(ComplexErrorProp a)
public static ComplexErrorProp plus(ComplexErrorProp a, ComplexErrorProp b)
Usage:                      z = x.plus(y);
Usage:                      z = ComplexErrorProp.plus(x, y);
Performs the operation z = x + y and propagates the addition errors, where x, y and z are all ComplexErrorProp.


SUBTRACTION
public ComplexErrorProp minus(ComplexErrorProp a)
public static ComplexErrorProp minus(ComplexErrorProp a, ComplexErrorProp b)
Usage:                      z = x.minus(y);
Usage:                      z = ComplexErrorProp.minus(x, y);
Performs the operation z = x - y and propagates the subtraction errors, where x, y and z are all ComplexErrorProp.


MULTIPLICATION
public ComplexErrorProp times(ComplexErrorProp a)
public static ComplexErrorProp times(ComplexErrorProp a, ComplexErrorProp b)
Usage:                      z = x.times(y);
Usage:                      z = ComplexErrorProp.times(x, y);
Performs the operation z = x*y and propagates the multiplication errors, where x, y and z are all ComplexErrorProp.


DIVISION
public ComplexErrorProp over(ComplexErrorProp a)
public static ComplexErrorProp over(ComplexErrorProp a, ComplexErrorProp b)
Usage:                      z = x.over(y);
Usage:                      z = ComplexErrorProp.over(x, y);
Performs the operation z = x/y and propagates the division errors, where x, y and z are all ComplexErrorProp.


MODULUS
Returns the modulus (absolute value) of a complex number and propagates the error.
public ComplexErrorProp abs()
public static ComplexErrorProp abs(ComplexErrorProp aa)
Usage:                      x = y.abs();
Usage:                      x = ComplexErrorProp.abs(y);
where x and y are ComplexErrorProp.
NB The correlation coefficient of the real and imaginary parts of y is used in this calculation.


ARGUMENT
Returns the argument of a complex number and propagates the error.
public ComplexErrorProp arg()
public static ComplexErrorProp arg(ComplexErrorProp aa)
Usage:                      x = y.arg();
Usage:                      x = ComplexErrorProp.arg(y);
where x and y are ComplexErrorProp.
NB The correlation coefficient of the real and imaginary parts of y is used in this calculation.


EXPONENTIAL
Returns the exponential of a complex number and propagates the error.
public ComplexErrorProp exp()
public static ComplexErrorProp exp(ComplexErrorProp aa)
Usage:                      x = y.exp();
Usage:                      x = ComplexErrorProp.exp(y);
where x and y are ComplexErrorProp.
NB The correlation coefficient of the real and imaginary parts of y is used in this calculation.


TRUNCATE MANTISSAE TO N PLACES
Instance method
public ComplexErrorProp truncate(int n)
Usage:                      xt=x.truncate(n);
Returns a copy of x with the mantissae of the values and of the errors of both the real and imaginary parts rounded to n decimal places. If the argument indicating the number of places before truncation, i.e. n in the above example, is any negative integer, the variable to be truncated, i.e. x in the above example, is returned without truncation. This method can be useful in outputting data.

Static method
public static ComplexErrorProp truncate(ComplexErrorProp x, int n)
Usage:                      xt = ComplexErrorProp.truncate(x, n);
Returns a copy of x with the mantissae of the values and of the errors of both the real and imaginary parts rounded to n decimal places. If the argument indicating the number of places before truncation, i.e. n in the above example, is any negative integer, the variable to be truncated, i.e. x in the above example, is returned without truncation. This method can be useful in outputting data.


Write an ComplexErrorProp Instance

Write an ComplexErrorProp Instance to Screen public void print(String message)
public void print()
Example of Usage:                     aa.print("The value of the ComplexErrorProp number aa is");
Writes to the screen, e.g. the workstation terminal window, the MSDOS window, the message followed by the value of the ComplexErrorProp number (in aa in the above example) in the form:
Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part.
Usage:                     aa.print();
Writes to the screen, e.g. the workstation terminal window, the MSDOS window, the value of a ComplexErrorProp number (in aa in the above example) in the form:
Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part.

public void println(String message)
public void println()
Example of Usage:                     aa.println("The value of the ComplexErrorProp number aa is");
Writes to the screen, e.g. the workstation terminal window, the MSDOS window, the message followed by the value of the ComplexErrorProp number (in aa in the above example) in the form:
Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part.
followed by a line return
Usage:                     aa.println();
Writes to the screen, e.g. the workstation terminal window, the MSDOS window, the value of a ComplexErrorProp number (in aa in the above example) in the form:
Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part
followed by a line return.


TYPE CONVERSIONS
ComplexErrorProp to String
public String toString()
public static String toString(ComplexErrorProp a)
Usage:                      ss = aa.toString();
Usage:                      ss = ComplexErrorProp.toString(aa);
Converts the ComplexErrorProp number in aa to a string (ss in the above example) of the form:
Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part
This method overides java.lang.String.toString(). Consequently you may add an ComplexErrorProp number to the string in the standard output methods, e.g. System.out.print(), System.out.println(), g.drawString, and it will automatically be converted to the Real part: value of real part , error = error of real part ; Imaginary part: value of imaginary part , error = error of the imaginary part format on output.


COPY
REMEMBER: aa = bb; does not copy bb into aa when aa and bb are objects, instead aa becomes a reference to bb.
public ComplexErrorProp copy()
public Object clone()
public static ComplexErrorProp copy(ComplexErrorProp a)

Copy a single ComplexErrorProp number
Usage:                      aa = bb.copy();
Usage:                      aa = ComplexErrorProp.copy(bb);
The ComplexErrorProp number, bb, is copied and returned to aa.

Clone a single ComplexErrorProp number
Usage:                      aa = (ComplexErrorProp) bb.clone();
The ComplexErrorProp number, bb, is copied and returned to aa. This method overrides java.lang.Object.clone()


SOME USEFUL NUMBERS
Return the number zero (0) as a ComplexErrorProp number with value = 0.0 + j0.0 and both errors = 0.0.
public static ComplexErrorProp zero()
Usage:                      x = ComplexErrorProp.zero();

Return the number one (+1) as a ComplexErrorProp number with value = 1.0 + j0.0and both errors = 0.0.
public static ComplexErrorProp plusOne()
Usage:                      x = ComplexErrorProp.plusOne();

Return the number minus one (-1) as a ComplexErrorProp number with value = -1.0 + j0.0and both errors = 0.0.
public static ComplexErrorProp minusOne()
Usage:                      x = ComplexErrorProp.minusOne();

Return the square root of minus one (+j) as a ComplexErrorProp number with value = 0.0 + j1.0and both errors = 0.0.
public static ComplexErrorProp plusJay()
Usage:                      x = ComplexErrorProp.plusJay();

Return the square root of minus one (-j) as a ComplexErrorProp number with value = 0.0 - j1.0and both errors = 0.0.
public static ComplexErrorProp minusJay()
Usage:                      x = ComplexErrorProp.minusJay();


MONTE CARLO SIMULATIONS
When the use of the standard propagation of error formulae become inappropriate due to not readily calculated correlation coefficients, e.g. in complex division, a Monte Carlo simulation has been used in which arrays of the real and imaginary parts are generated as random Gaussian deviates from a population of mean value equal to the real or imaginary part values, and of a standard deviation equal to the error of the real or imaginary parts. The appropriate calculation is performed on all array values and the resultant errors calculated as standard deviations. The values of the real and imaginary parts are calculated by the standard arithmetic formulae.
public static void setMonteCarloLength( int length)
Usage:                      ComplexErrorProp.setMonteCarloLength();
Resets for the length of the arrays used in the Monte Carlo simulations. The default value is 10000.
public static int getMonteCarloLength()
Usage:                      length = ComlexErrorProp.getMonteCarloLength();
The value set for the length of the arrays used in the Monte Carlo simulations is returned as an integer.


OTHER CLASSES USED BY THIS CLASS

 This class uses the following classes in this library:

This page was prepared by Dr Michael Thomas Flanagan