Michael Thomas Flanagan's Java Scientific Library: Control theory black box

Michael Thomas Flanagan's Java Scientific Library

BlackBox class: Control Theory Black Box

Last update: 27 April 2012 Main Page of Michael Thomas Flanagan's Java Scientific Library

This class contains the constructor to create an instance of a generalised BlackBox with a single input, single output and a gain, G, that in the s-domain may be representede by a ratio of two complex polynomials:

It contains the methods, amongst others, for:

setting the s-domain transfer function;
setting the dead time (transportation time);
obtaining the s-domain poles and zeros;
setting, or mapping from the s-domain, the z-domain transfer function;
obtaining the z-domain poles and zeros;
plotting the poles and zeros;
plotting the transient response for impulse, step and ramp inputs;
plotting the Bode plots;
setting the variables needed for handling sampled data.

This class is the superclass for several sub-classes:

OpenLoop - Open loop path	ClosedLoop - Closed loop	Compensator - Compensator	FirstOrder - First Order Process
SecondOrder - Second Order Process	LowPassPassive - Simple low pass filter	HighPassPassive - Simple high pass filter	Transducer - Simple transducer
PropIntDeriv - PID controller	PropInt - PI controller	PropDeriv - PD controller	Prop - Proportional gain controller
ZeroOrderHold - Zero Order Hold	AtoD - Analogue to Digital converter	DtoA - Digital to Analogue converter	DelayLine - Delay Line

import directive: import flanagan.control.BlackBox;

See ClosedLoop and OpenLoop for example programs using subclasses of BlackBox.
Summary table of constructor and methods
Details of constructors and methods
Java source file (Last update: 27 April 2012)
Other Control Engineering Java classes
Other classes, in this library, used by this class
Main Page of Michael Thomas Flanagan's Java Scientific Library

SUMMARY OF CONSTRUCTOR AND METHODS

Constructors		public BlackBox()
s-domain transfer function	Set transfer function numerator	public void setSnumer(double[ ] coeff)
		public void setSnumer(Complex[ ] coeff)
		public void setSnumer(ComplexPoly coeff)
	Get the numerator degree	public int getSnumerDeg()
	Get the numerator degree	public int getSnumerPadeDeg()
	Get the numerator polynomial	public ComplexPoly getSnumer()
	Get the numerator polynomial	public ComplexPoly getSnumerPade()
	Get the numerator scale factor	public ComplexPoly getSnumerScaleFactor()
	Set transfer function denominator	public void setSdenom(double[ ] coeff)
		public void setSdenom(Complex[ ] coeff)
		public void setSdenom(ComplexPoly coeff)
	Get the denominator degree	public Complex getSdenomDeg()
	Get the denominator degree	public Complex getSdenomPadeDeg()
	Get the denominator polynomial	public ComplexPoly getSdenom()
	Get the denominator polynomial	public ComplexPoly getSdenomPade()
	Get the denominator scale factor	public ComplexPoly getSdenomScaleFactor()
	Get the s-values of the poles	publicComplex[ ] getPolesS()
	Get the s-values of the poles	publicComplex[ ] getPolesPadeS()
	Get the s-values of the zeros	publicComplex[ ] getZerosS()
	Get the s-values of the zeros	publicComplex[ ] getZerosPadeS()
	Plot poles and zeros	public void plotPoleZeroS()
	Plot poles and zeros	public void plotPoleZeroPadeS()
	Set the value of the Laplace s variable	public void setS(Complex sValue)
		public void setS(double sReal, double sImag)
		public void setS(double sImag)
	Get the Laplace s value	public Complex getS()
	Evaluate transfer function	public Complex evalTransFunctS()
		public Complex evalTransFunctS(Complex sValue)
		public Complex evalTransFunctS(double freq)
	Evaluate transfer function steady state	public double getSteadyStateValue()
	Evaluate transfer function steady state	public double getSteadyStateValue(double mag)
	Evaluate transfer function magnitude	public double evalMagTransFunctS()
		public double evalMagTransFunctS(Complex sValue)
		public double evalMagTransFunctS(double freq)
	Evaluate transfer function phase	public double evalPhaseTransFunctS()
		public double evalPhaseTransFunctS(Complex sValue)
		public double evalPhaseTransFunctS(double freq)
	Bode plots (magnitude and phase)	public void plotBode(double lowFreq, double highFreq,)
	Inverse Laplace Transform	public static Complex[ ] [ ] inverseTransform(ComplexPoly numer, ComplexPoly denom)
		public static double[ ] [ ] inverseTransformToReal(ComplexPoly numer, ComplexPoly denom)
		public static Complex timeTerm(double time, Complex coeff, Complex constant, Complex power)
		public static double timeTerm(double time, double coeff, double constant, double power)
		public static double timeTerm(double time, double coeff, double constant, int power)
	Set the input in the s-domain	public void setInputS(Complex input)
	Get the input in the s-domain	public Complex getInputS()
	Get the output in the s-domain	public Complex getOutputS()
	Get the output in the s-domain	public Complex getOutputS(Complex svalue, Complex input)
Dead Time (transportation time)	Set the dead time	public void setDeadtime(double deadTime)
	Set the dead time	public void setDeadtime(double deadTime, double padeOrder)
	Get the dead time	public double getDeadtime()
	Set the Pade order	public void setPadeOrder(double padeorder)
	Get the Pade order	public void setPadeOrder(double padeorder)
Continuous time domain (uses the s-domain transfer function)	Plot impulse input transient	public void impulseInput(double finaltime)
	Plot impulse input transient	public void impulseInput(double mag, double finaltime)
	Plot step input transient	public void stepInput(double finaltime)
	Plot step input transient	public void stepInput(double mag, double finaltime)
	Plot ramp input transient	public void rampInput(double finaltime)
		public void rampInput(double mag, double finaltime)
		public void rampInput(int order, double finaltime)
		public void rampInput(double mag, int order, double finaltime)
	Plot generalised transient response	public static void transientResponse(double finaltime, ComplexPoly numer, ComplexPoly denom, String graphtitle1, String graphtitle2)
z-domain transfer function	Map s-domain or time domain transfer function into the z-domain	public void zTransform()
		public void zTransform(double deltaT)
		public void mapstozAdHoc()
		public void mapstozAdHoc(double deltaT)
		public void setMaptozero(boolean maptozero)
		public boolean getMaptozero( )
		public void setZtransformMethod(int ztransMethod)
		public int getZtransformMethod( )
	Set transfer function numerator	public void setZnumer(double[ ] coeff)
		public void setZnumer(Complex[ ] coeff)
		public void setZnumer(ComplexPoly coeff)
	Get the numerator degree	public int getZnumerDeg()
	Get the numerator polynomial	public ComplexPoly getZnumer()
	Set transfer function denominator	public void setZdenom(double[ ] coeff)
		public void setZdenom(Complex[ ] coeff)
		public void setZdenom(ComplexPoly coeff)
	Get the denominator degree	public int getZdenomDeg()
	Get the denominator polynomial	public ComplexPoly getZdenom()
	Calculate poles and zeros	public void calcPoleZeroZ()
	Get the z-values of the poles	publicComplex[ ] getPolesZ()
	Get the z-values of the zeros	publicComplex[ ] getZerosZ()
	Plot poles and zeros	public void plotPoleZeroZ()
	Set the value of the z variable	public void setZ(Complex zValue)
	Set the value of the z variable	public void setZ(double zReal, double zImag)
	Get the z value	public Complex getZ()
	Evaluate transfer function	public Complex evalTransFunctZ()
	Evaluate transfer function	public Complex evalTransFunctZ(Complex zValue)
	Evaluate transfer function magnitude	public double evalMagTransFunctZ()
	Evaluate transfer function magnitude	public double evalMagTransFunctZ(Complex zValue)
	Evaluate transfer function phase	public double evalPhaseTransFunctZ()
	Evaluate transfer function phase	public double evalPhaseTransFunctZ(Complex zValue)
Sampled signal	Set the sampling length	public void setSampleLdength(int samplelength)
	Get the sampling length	public int getSampleLength()
	Set the sampling period	public void setDeltaT(double deltaT)
	Get the sampling period	public double getDeltaT()
	Set the sampling frequency	public void setSampFreq(double sfreq)
	Get the sampling frequency	public double getSampFreq()
	Set the sampled input and time	public void setInputT(double time, double input)
	Get the current value of the time	public double getCurrentTime()
	Get the array of times	public double[] getTime()
	Get the current value of the input	public double getCurrentInputT()
	Get the array of the inputs	public double[] getInputT()
	Calculate the current value of the output	public double calcOutputT()
	Calculate the current value of the output	public double calcOutputT(double time, double input)
	Get the current value of the output	public double getCurrentOutputT()
	Get the array of the outputs	public double getOutputT()
	Set numerical integration method	public void setIntegrateMethod(int integMethod)
	Set numerical integration method	public void setIntegrateMethod(String integMethodOpt)
	Get numerical integration method	public int getIntegrateMethod()
	Set the exponential forgetting factor	public void setForgetFactor(double forgetfactor)
	Set the exponential forgetting factor	public void setForgetFactor(double forgetfactor, int samplength )
	Get the forgetting factor	public double getForgetFactor()
Deep Copy		public BlackBox copy()
Deep Copy		public Object clone()
General methods	Reset all inputs, outputs and times to zero	public void resetZero()
	Set the name of the black box	public void setName(String name)
	Get the name of the black box	public String getName()

CONSTRUCTOR

public BlackBox()
Usage: BlackBox box = new BlackBox();
This creates a new instance of BlackBox.

TRANSFER FUNCTION IN THE s-DOMAIN

SET THE s-DOMAIN TRANSFER FUNCTION NUMERATOR
public void setSnumer(double[ ] coeff)
public void setSnumer(Complex[ ] coeff)
public void setSnumer(ComplexPoly coeff)
Sets the coefficients a[i] in the numerator polynomial of the transfer function:

Usage:                      box.setSnumer(coeff);
The values of a[i], i.e. coeff in above example, may be supplied as an array of type double (all coefficients real), of type Complex (coefficients are complex) or as an instance of ComplexPoly. If the roots of the numerator polynomial are all that is known, they may be converted to an instance of ComplexPoly using ComplexPoly.rootsToPoly(roots). The coefficients are stored in the BlackBox instant in a ComplexPoly variable, sNumer.
This method also calculates and stores, as a Complex array, the zeros in the s-domain.
If a dead time (transportation time) has been set the s-domain numerator including the terms arising from the Pade approximation and the s-domain zeros are also calculated and stored.

GET THE DEGREE OF THE s-DOMAIN NUMERATOR
public int getSnumerDeg()
public int getSnumerPadeDeg()
Usage:                      ndeg = box.getSnumerDeg();
Returns the degree of the s-domain numerator polynomial before the addition of any Pade approximations.

Usage:                      ndeg = box.getSnumerPadeDeg();
Returns the degree of the s-domain numerator polynomial after the addition of any Pade approximations.

GET THE s-DOMAIN NUMERATOR
public ComplexPoly getSnumer()
public ComplexPoly getSnumerPade()
Usage:                      numers = box.getSnumer();
Returns the s-domain numerator polynomial, before the addition of any Pade approximations, as an instance of a ComplexPoly.
Usage:                      numers = box.getSnumerPade();
Returns the s-domain numerator polynomial, after the addition of any Pade approximations, as an instance of a ComplexPoly.

GET THE s-DOMAIN NUMERATOR SCALE FACTOR
public Complex getSnumerScaleFactor()
Usage: sf = box.getSnumerScaleFactor();
Returns the s-domain numerator scale factor as an instance of a Complex, i.e. returns the factor needed to multiply the product of all the (s - roots [zeros]) to obtain the same values as that on evaluating the numerator polynomial for the same value of s.

SET THE s-DOMAIN TRANSFER FUNCTION DENOMINATOR
public void setSdenom(double[ ] coeff)
public void setSdnom(Complex[ ] coeff)
public void setSdenom(ComplexPoly coeff)
Sets the coefficients b[i] in the denominator polynomial of the transfer function:

Usage:                      box.setSdenom(coeff);
The values of b[i], i.e. coeff in above example, may be supplied as an array of type double (all coefficients real), of type Complex (coefficients are complex) or as an instance of ComplexPoly. If the roots of the denominator polynomial are all that is known, they may be converted to an instance of ComplexPoly using ComplexPoly.rootsToPoly(roots). The coefficients are stored in the BlackBox instant in a ComplexPoly variable, sdenom.
This method also calculates and stores, as a Complex array, the poles in the s-domain.
If a dead time (transportation time) has been set the s-domain denominator including the terms arising from the Pade approximation and the s-domain poles are also calculated and stored.

GET THE DEGREE OF THE s-DOMAIN DENOMINATOR
public int getSdenomDeg()
public int getSdenomPadeDeg()
Usage:                      ddeg = box.getSdenomDeg();
Returns the degree of the s-domain denominator polynomial before any Pade approximation additions.

Usage:                      ddeg = box.getSdenomPadeDeg();
Returns the degree of the s-domain denominator polynomial after any Pade approximation additions.

GET THE s-DOMAIN DENOMINATOR
public ComplexPoly getSdenom()
public ComplexPoly getSdenomPade()
Usage:                      denoms = box.getSdenom();
Returns the s-domain denominator polynomial, before any Pade approximation additions, as an instance of a ComplexPoly.

Usage:                      denoms = box.getSdenomPade();
Returns the s-domain denominator polynomial, after any Pade approximation additions, as an instance of a ComplexPoly.

GET THE s-DOMAIN DENOMINATOR SCALE FACTOR
public Complex getSdenomScaleFactor()
Usage: sf = box.getSdenomScaleFactor();
Returns the s-domain denominator scale factor as an instance of a Complex, i.e. returns the factor needed to multiply the product of all the (s - roots [poles]) to obtain the same values as that on evaluating the denominator polynomial for the same value of s.

GET THE VALUES OF THE s-DOMAIN POLES
publicComplex[ ] getPolesS()
publicComplex[ ] getPolesPadeS()
Usage: poles = box.getPolesS();
Returns, to a Complex array, the poles of the s-domain transfer function denominator represented by the BlackBox variable sDenom [Set Denominator above]. The poles arising from any Pade approximation are not included in this output [see below].

Usage: poles = box.getPolesPadeS();
As in getPolesS() above with the exception that the poles arising from any Pade approximations are also included.

GET THE VALUES OF THE s-DOMAIN ZEROS
publicComplex[ ] getZerosS()
publicComplex[ ] getZerosPadeS()
Usage: zeros = box.getZeroS();
Returns, to a Complex array, the zeros of the s-domain transfer function numerator represented by the BlackBox variable sNumer [see Set Numerator above]. The zeros arising from any Pade approximation are not included in this output [see below].

Usage: zeros = box.getZeroPadeS();
As in getZeroS() above with the exception that the zeros arising from any Pade approximations are also included.

PLOT THE s-DOMAIN POLES AND ZEROS
public void plotPolesZeroS()
public void plotPolesZeroPadeS()
Usage: box.plotPolesZeroS();
Plots, in a new window, the poles and zeros of the s-domain transfer function represented by the BlackBox variables sNumer and sDenom [see Set Numerator and Set Denominator above] before any Pade approximations have been included. It also creates a textfile, named PoleZeroOutput.txt, and writes to this file:

File header
Time and date the output file was created.
Coefficients of the numerator polynomial.
Coefficients of the denominator polynomial.
Roots of the numerator polynomial (zeros).
Roots of the denominator polynomial (poles).
Check for system stability.

Usage: box.plotPolesZeroPadeS();
As in plotPolesZeroS() above with the exception that the zeros and poles arising from any Pade approximations are also included.

SET THE VALUE OF THE LAPLACE s VARIABLE
public void setS(Complex sValue)
public void setS(double sReal, double sImag)
public void setS(double sImag)
Usage: box.setS(arg);
Sets the value of the Laplace s variable. The method argument (arg in the above usage) may be a single complex number [type Complex], two real [type double] numbers; the real and imaginary parts of s or a single real [type double] number. The latter sets the imaginary part of s to arg and the real part to zero. The latter facilitates the calculation of outputs for a sinusoidal input.

GET THE VALUE OF THE LAPLACE s VARIABLE
public Complex getS()
Usage: box.setS(arg);
Gets the value of the Laplace s variable as an instance of Complex.

EVALUATE THE s DOMAIN TRANSFER FUNCTION
If a dead time (transportation time) has been set it is evaluated, in this method, as exp(-s.deadtime) and not as the Pade approximation, unless the subclass calling this method is ControlLoop.
public Complex evalTransFunctS()
public Complex evalTransFunctS(Complex sValue)
public Complex evalTransFunctS(double freq)
Usage:                      val = box.evalTransFunctS();
Returns the value, as a complex number, of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the Lapace s variable.
br> Usage:                      val = box.evalTransFunctS(svalue);
Returns the value, as a complex number, of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of the Lapace s variable, passed to the function as the Complex instance, svalue, in the above usage.
Usage:                      val = box.evalTransFunctS(freq);
Returns the value, as a complex number, of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given sinusoidal input frequency [in Hz], passed to the function as the double, freq, in the above usage. This facilitates the calculation of the output for a sinusoidal input.

EVALUATE THE TRANSFER FUNCTION STEADY STATE VALUE
public double getSteadyStateValue()
public double getSteadyStateValue(double mag)
Usage:                      ss = box.getSteadyStateValue();
Returns the value of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the steady state reached after a unit step input excitation.
Usage:                      ss = box.getSteadyStateValue(mag);
Returns the value of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the steady state reached after a step input excitation of magnitude, mag.

EVALUATE THE MAGNITUDE OF THE s DOMAIN TRANSFER FUNCTION
If a dead time (transportation time) has been set it is evaluated, in this method, as exp(-s.deadtime) and not as the Pade approximation, unless the subclass calling this method is ControlLoop.
public double evalMagTransFunctS()
public double evalMagTransFunctS(Complex sValue)
public double evalMagTransFunctS(double freq)
Usage:                      mag = box.evalMagTransFunctS();
Returns the value, as a double, of the magnitude of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the Lapace s variable.
Usage:                      mag = box.evalTransFunctS(svalue);
Returns the value, as a double, of the magnitude of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of the Lapace s variable, passed to the function as the Complex instance, svalue, in the above usage.
Usage:                      mag = box.evalMagTransFunctS(freq);
Returns the value, as a double, of the magnitude of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given sinusoidal input frequency [in Hz], passed to the function as the double, freq, in the above usage. This facilitates the calculation of the output for a sinusoidal input.

EVALUATE THE PHASE OF THE s DOMAIN TRANSFER FUNCTION
If a dead time (transportation time) has been set it is evaluated, in this method, as exp(-s.deadtime) and not as the Pade approximation, unless the subclass calling this method is ControlLoop.
public double evalPhaseTransFunctS()
public double evalPhaseTransFunctS(Complex sValue)
public double evalPhaseTransFunctS(double freq)
Usage:                      phase = box.evalPhaseTransFunctS();
Returns the value, in radians, as a double, of the phase of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the Lapace s variable.
Usage:                      phase = box.evalPhaseTransFunctS(svalue);
Returns the value, in radians, as a double, of the phase of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of the Lapace s variable, passed to the function as the Complex instance, svalue, in the above usage.
Usage:                      phase = box.evalPhaseTransFunctS(freq);
Returns the value, in radians, as a double, of the phase of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given sinusoidal input frequency [in Hz], passed to the function as the double, freq, in the above usage. This facilitates the calculation of the output for a sinusoidal input.

BODE PLOTS (MAGNITUDE AND PHASE)
If a dead time (transportation time) has been set it is evaluated, in this method, as exp(-s.deadtime) and not as the Pade approximation, unless the subclass calling this method is ControlLoop.
public void plotBode(double lowFreq, double highFreq,)
Usage: box.plotBode(lowFreq, highFreq);
Plots, to two separate new windows, Bode plots for the magnitude and for the phase of the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], between two given frequencies [Hz] (lowFreq and highFreq in the above usage).

INVERSE LAPLACE TRANSFORM
public static Complex[ ] [ ] inverseTransform(ComplexPoly numer, ComplexPoly denom)
public static double[ ] [ ] inverseTransformToReal(ComplexPoly numer, ComplexPoly denom)
Usage: coeff = box.inverseTransform(numer, denom);
Expands the transfer function, represented by sNumer over sDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], as a sum of partial fractions, and returns the values of A[i], a[i] and n[i] for the recurring root terms:

and the values of A[i] and a[i] with n[i] set to unity for the non-recurring root terms:

The values of A[i], a[i] and n[i] are returned to a 3 x m dimensional Complex array, where m is the number of partial fraction terms in the sum. The m values of A[i] are returned, e.g. in the above usage, in coeff[0][0] to coeff[0][m-1], the m values of a[i] are returned in coeff[1][0] to coeff[1][m-1] and the m values of n[i] are returned in coeff[2][0] to coeff[2][m-1].

Usage: coeff = box.inverseTransformToReal(numer, denom);
As with inverseTransform above with the exception that the parameters, A[i] and a[i] and n[i], are returned as double.

public static Complex timeTerm(double time, Complex coeff, Complex constant, Complex power)
public static double timeTerm(double time, double coeff, double constant, double power)
public static double timeTerm(double time, double coeff, double constant, int power)
Usage: tTerm = BlackBox.timeTerm(time, coeffA, coeffa, coeffn);
Returns the value of

at time t (time in the above usage) where A[i] (coeffA in the above usage), a[i] (coeffa in the above usage) and n[i] (coeffn in the above usage) are the coefficients obtained from the inverseTransform method [See above].

SET THE INPUT IN THE s-DOMAIN
public void setInputS(Complex input)
Usage: box.setInputS(input);
Sets the input in the s-domain to the Complex variable, input (in the above usage).

GET THE INPUT IN THE s-DOMAIN
public void getInputS(Complex input)
Usage: input = box.getInputS();
Returns the input in the s-domain to a Complex variable, input (in the above usage).

GET THE OUTPUT IN THE s-DOMAIN
If a dead time (transportation time) has been set it is evaluated, in this method, as exp(-s.deadtime) and not as the Pade approximation, unless the subclass calling this method is ControlLoop.
public void getOutputS()
public void getOutputS(Complex svalue, Complex input)
Usage: output = box.outInputS();
Returns the output in the s-domain to a Complex variable, output (in the above usage) for the stored values of the s value and the input.
Usage: output = box.outInputS(svalue, input);
Returns the output in the s-domain to a Complex variable, output (in the above usage) for given values of the s value and the input.

DEAD TIME (TRANSPORTATION TIME)

SET THE DEAD TIME (TRANSPORTATION TIME)
public void setDeadTime(double deadTime)
public void setDeadTime(double deadTime, double padeOrder)
Usage:                      box.setDeadTime(deadTime);
Sets the dead time (transportation time), i.e. the lag time between an input and the corresponding output. The default value is zero.
Usage:                      box.setDeadTime(deadTime, padeorder);
Sets the dead time (transportation time), i.e. the lag time between an input and the corresponding output and the order of the Pade approximation to the Laplace transform of the dead time. The default value of the dead time is zero and of the Pade approximation order is 2.

GET THE DEAD TIME (TRANSPORTATION TIME)
public double getDeadTime(double deadTime)
Usage:                      deadTime = box.getDeadTime();
Returns the dead time (transportation time), i.e. the lag time between an input and the corresponding output.

SET THE PADE APPROXIMATION ORDER
public void setPadeOrder(double padeOrder)
Usage:                      box.setPadeOrder(padeOrder);
The Laplace transform of a dead time, T, is exp(-sT). The Pade approximation, of order, n, is the is given by:

The argument of this method, padeOrder, in the above usage, is the order, n. This method supports orders between 1 and 4. If a value below 1 is enterted a order of 1 is used. If a value above 4 is entered a order of 4 is used. The default value, i.e. the order used if this method is not invoked, is 2.
The approximations are:
First order

Second order (default approximation)

Third order

Fourth order

The methods, in this class BlackBox, evaluate the Laplace transform of the dead time as exp(-sT) where ever convenient and only use the Pade approximation when the explicit evaluation presents problems, e.g. in a s-domain to z-domain mapping. See documentation on method for details on the choice of method of the evaluation of exp(-sT).

GET THE PADE APPROXIMATION ORDER
public void getPadeOrder()
Usage: padeOrder = box.setPadeOrder();
Returns the order of the Pade approximation of the the Laplace transform of a dead time, T, is exp(-sT). See above for details of the Pade approximation.

CONTINUOUS TIME DOMAIN

PLOT TRANSIENT RESPONSE TO AN IMPULSE INPUT
public void impulseInput(double finaltime)
public void impulseInput(double mag, double finaltime)
Usage: box.impulseInput(finaltime);
Plots, in a new window, the transient response, to an input of a unit impulse, from zero time to a given time (finaltime in the above usage).
Usage: box.impulseInput(mag, finaltime);
Plots, in a new window, the transient response, to an input of an impulse of a given magnitude (mag in the above usage), from zero time to a given time (finaltime in the above usage).

PLOT TRANSIENT RESPONSE TO A STEP FUNCTION INPUT
public void stepInput(double finaltime)
public void stepInput(double mag, double finaltime)
Usage: box.stepInput(finaltime);
Plots, in a new window, the transient response, to an input of a unit step function, from zero time to a given time (finaltime in the above usage).
Usage: box.stepInput(mag, finaltime);
Plots, in a new window, the transient response, to an input of a step function of a given magnitude (mag in the above usage), from zero time to a given time (finaltime in the above usage).

PLOT TRANSIENT RESPONSE TO A RAMP FUNCTION INPUT
public void rampInput(double finaltime)
public void rampInput(double mag, double finaltime)
public void rampInput(int order, double finaltime)
public void rampInput(double mag, int order, double finaltime)
Usage:                      box.rampInput(finaltime);
Plots, in a new window, the transient response, to an input of a first order, unit ramp function, t, from zero time to a given time (finaltime in the above usage).
Usage:                      box.rampInput(mag, finaltime);
Plots, in a new window, the transient response, to an input of a first order, ramp function of gradient a (mag in the above usage), at, from zero time to a given time (finaltime in the above usage).
Usage:                      box.rampInput(order, finaltime);
Plots, in a new window, the transient response, to an input of a nth order (order in the above usage), unit ramp function,

from zero time to a given time (finaltime in the above usage).
Usage: box.rampInput(mag, order, finaltime);
Plots, in a new window, the transient response, to an input of a nth order (order in the above usage), ramp function,

(where a is mag in the above usage) from zero time to a given time (finaltime in the above usage).

PLOT THE TRANSIENT RESPONSE OF A GENERAL FUNCTION
public static void transientResponse(double finaltime, ComplexPoly numer, ComplexPoly denom, String graphtitle1, String graphtitle2)
Usage: BlackBox.transientResponse(finaltime, numer, denom, graphtitle1, graphtitle2);
Plots, in a new window, the transient response, of the generalised function, numer/denom, from zero time to a given time (finaltime in the above usage). The ComplexPoly numer and denom are the complex polynomials forming the numerator and denominator of the function. The Strings graphtitle1 and graphtitle2 are the title and subtitle of the graph.

TRANSFER FUNCTION IN THE z-DOMAIN

MAP THE s-DOMAIN OR TIME -DOMAIN TRANSFER FUNCTION INTO THE z-DOMAIN
public void zTransform()
public void zTransform(double deltaT)
Usage:                      box.zTransform();
This method calculates and stores the numerator and the denominator of the transfer function in the z-domain and the values of the zeros and poles in the z-domain. The superclass method maps s-domain zeros and poles of the s-domain transfer function onto the z-domain using the ad-hoc method [see below] for an already set sampling period. May be overridden, in subclasses, by a more specific transform.
Usage:                      box.ztransform(deltaT);
Maps s-domain zeros and poles of the transfer function onto the z-domain using the ad-hoc method [see below].
IT IS PREFERABLE THAT THIS METHOD BE OVERRIDDEN, IN ANY SUBCLASS, UTILISING A LESS GENERAL z-TRANSFORM, ESPECIALLY, IF A DIFFERENTIATION AND/OR INTEGRATION IS INVOLVED, e.g. See PropIntDeriv.
See, also, the method setZtransformMethod (below) for method of choosing z-transform method option.

AD HOC METHOD
References: John Dorsey, Continuous and Discrete Control Systems, pp 490-491, McGraw Hill (2002)
J R Leigh, Applied Digital Control, pp 78-80, Prentice-Hall (1985)
public void mapstozAdHoc()
public void mapstozAdHoc(double deltaT)
Usage:                      box.mapsstozAdHoc();
Maps s-domain zeros and poles of the transfer function onto the z-domain using the ad-hoc method for an already set sampling period. Derives the z-domain transfer function numerator and denominator. Zeros derived from infinite poles may be mapped to z=0 or to z=1. The default option is the former. To change this option use setMaptozero(opt) [see below].
Usage:                      box.mapsstozAdHoc(deltaT);
Maps s-domain zeros and poles of the transfer function onto the z-domain using the ad-hoc method for a given sampling period (deltaT in the above usage). Derives the z-domain transfer function numerator and denominator. Zeros derived from infinite poles may be mapped to z=0 or to z=1. The default option is the former. To change this option use setMaptozero(opt) [see below]

RESET THE INFINITY DERIVED ZEROS MAPPING OPTION
public void setMaptozero(boolean maptozero)
Usage:                      box.setMapsstozero(option);
Resets the mapping option for zeros derived from infinite poles. They may be:

mapped to z=0 [set the method argument (option in the above usage) to true]
mapped to z=1 [set the method argument (option in the above usage) to false]

The default option is true.

GET THE INFINITY DERIVED ZEROS MAPPING OPTION
public boolean getMaptozero( )
Usage: option = box.getMapsstozero();
Returns the mapping option for zeros derived from infinite poles. This may be:

true - mapped to z = 0
false - mapped to z = 1

The default option is true.

RESET THE z-TRANSFORM METHOD OPTION
public void setZtransformMethod(int ztransMethod)
Usage: box.setZtransformMethod(option);
If the method argument (option in the above usage) is set to 0 the z-transform is performed using the ad hoc method of s-domain to z-domain mapping described under the method mapstozAdHoc() above.
If the method argument (option in the above usage) is set to 1 the z-transform is performed using a more specific z-transform procedure, e.g. of a numerical difference equation.
The default option, in BlackBox, is the former, i.e. 0. The option is automatically reset to 1 in the subclasses PropIntDeriv, PropInt, PropDeriv and FirstOrder where the method ztransform is overridden using a difference equation procedure. It may be reset to 0 within these subclasses, using this method (setZtransformMethod).

GET THE z-TRANSFORM METHOD OPTION
public int getZtransformMethod( )
Usage: option = box.getZtransformMethod();
Returns the z-transform method. This may be

0 s-domain to z-domain pole and zero mapping
1 specific transform, e.g. using difference equation.

See above (setZtransformMethod) for details and default options.

SET THE z-DOMAIN TRANSFER FUNCTION NUMERATOR
public void setZnumer(double[ ] coeff)
public void setZnumer(Complex[ ] coeff)
public void setZnumer(ComplexPoly coeff)
Sets the coefficients a[i] in the numerator polynomial of the transfer function:

Usage:                      box.setZnumer(coeff);
The values of a[i], i.e. coeff in above example, may be supplied as an array of type double (all coefficients real), of type Complex (coefficients are complex) or as an instance of ComplexPoly. If the roots of the numerator polynomial are all that is known, they may be converted to an instance of ComplexPoly using ComplexPoly.rootsToPoly(roots). The coefficients are stored in the BlackBox instant in a ComplexPoly variable, zNumer. This method also calculates the values of the zeros in the z-domain and stores them as a Complex array.

GET THE DEGREE OF THE z-DOMAIN NUMERATOR
public int getZnumerDeg()
Usage:                      ndeg = box.getZnumerDeg();
Returns the degree of the z-domain numerator polynomial. Returns -1 if the polynomial has not been set.

GET THE z-DOMAIN NUMERATOR
public ComplexPoly getZnumer()
Usage:                      numers = box.getZnumer();
Returns the z-domain numerator polynomial as an instance of a ComplexPoly.

SET THE z-DOMAIN TRANSFER FUNCTION DENOMINATOR
public void setZdenom(double[ ] coeff)
public void setZdnom(Complex[ ] coeff)
public void setZdenom(ComplexPoly coeff)
Sets the coefficients b[i] in the denominator polynomial of the transfer function:

Usage:                      box.setZdenom(coeff);
The values of b[i], i.e. coeff in above example, may be supplied as an array of type double (all coefficients real), of type Complex (coefficients are complex) or as an instance of ComplexPoly. If the roots of the denominator polynomial are all that is known, they may be converted to an instance of ComplexPoly using ComplexPoly.rootsToPoly(roots). The coefficients are stored in the BlackBox instant in a ComplexPoly variable, zDenom. This method also calculates the values of the poles in the z-domain and stores them as a Complex array.

GET THE DEGREE OF THE z-DOMAIN DENOMINATOR
public int getZdenomDeg()
Usage:                      ddeg = box.getZdenomDeg();
Returns the degree of the z-domain denominator polynomial. Returns -1 if the polynomial has not been set.

GET THE z-DOMAIN DENOMINATOR
public ComplexPoly getZdenom()
Usage:                      denomz = box.getZdenom();
Returns the z-domain denominator polynomial as an instance of a ComplexPoly.

GET THE VALUES OF THE z-DOMAIN POLES
publicComplex[ ] getPolesZ()
Usage:                      poles = box.getPolesZ();
Returns, to a Complex array, the poles of the z-domain transfer function represented by the BlackBox variables zNumer and zDenom [see Set Numerator and Set Denominator above] after ztransform method has been called.

GET THE VALUES OF THE z-DOMAIN ZEROS
publicComplex[ ] getZerosZ()
Usage:                      zeros = box.getZeroZ();
Returns, to a Complex array, the zeros of the z-domain transfer function represented by the BlackBox variables zNumer and zDenom [see Set Numerator and Set Denominator above], after ztransform method [see above] has been called.

PLOT THE z-DOMAIN POLES AND ZEROS
public void plotPolesZeroZ()
Usage:                      box.plotPolesZeroZ();
Plots, in a new window, the poles and zeros of the z-domain transfer function represented by the BlackBox variables zNumer and zDenom [see Set Numerator and Set Denominator above], after calcPoleZeroZ() [see above] has been called. It also creates a textfile, named PoleZeroOutput.txt, and writes to this file:

File header
Time and date the output file was created.
Coefficients of the numerator polynomial.
Coefficients of the denominator polynomial.
Roots of the numerator polynomial (zeros).
Roots of the denominator polynomial (poles).
Radial distances (root moduli).
Check for system stability.

SET THE VALUE OF THE z VARIABLE
public void setZ(Complex sValue)
public void setZ(double sReal, double sImag)
Usage: box.setZ(arg);
Sets the value of the Laplace s variable. The method argument (arg in the above usage) may be a single complex number [type Complex] or two real [type double] numbers; the real and imaginary parts of s.

GET THE VALUE OF THE z VARIABLE
public Complex getZ()
Usage: box.setZ(arg);
Gets the value of the Laplace s variable as an instance of Complex.

EVALUATE THE z DOMAIN TRANSFER FUNCTION
public Complex evalTransFunctZ()
public Complex evalTransFunctZ(Complex zValue)
Usage:                      val = box.evalTransFunctZ();
Returns the value, as a complex number, of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the z variable.
Usage:                      val = box.evalTransFunctZ(zvalue);
Returns the value, as a complex number, of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of z variable, passed to the function as the Complex instance, zvalue, in the above usage.

EVALUATE THE MAGNITUDE OF THE z DOMAIN TRANSFER FUNCTION
public double evalMagTransFunctZ()
public double evalMagTransFunctZ(Complex sValue)
Usage:                      mag = box.evalMagTransFunctZ();
Returns the value, as a double, of the magnitude of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the z variable.
Usage:                      mag = box.evalTransFunctZ(zvalue);
Returns the value, as a double, of the magnitude of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of the z variable, passed to the function as the Complex instance, zvalue, in the above usage.

EVALUATE THE PHASE OF THE z DOMAIN TRANSFER FUNCTION
public double evalPhaseTransFunctZ()
public double evalPhaseTransFunctX(Complex zValue)
Usage:                      phase = box.evalPhaseTransFunctZ();
Returns the value, in radians, as a double, of the phase of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for the currently stored value of the z variable.
Usage:                      phase = box.evalPhaseTransFunctZ(zvalue);
Returns the value, in radians, as a double, of the phase of the transfer function, represented by zNumer over zDenom stored in the instance of BlackBox [See Set Numerator and Set Denominator above], for a given value of the z variable, passed to the function as the Complex instance, zvalue, in the above usage.

SAMPLED SIGNAL

SET THE SAMPLING LENGTH
public void setSampleLength(int samplelength)
Usage: box.setSampleLength(samplelength);
Sets the length, e.g. samplelength in the above usage, of the arrays in which the times, inputs in the time domain and outputs in the time domain are stored. The default value is 3 which accomodates difference equations needed by first and second order systems. The sample length should be reset to higher values in subclasses in which, e.g.:

higher order processes are modelled in which numerical solutions of the differential equations are included
methods are included in which a forgetting method, e.g. exponential forgetting, is included. It is automatically set to 1000 in the PI controller class (PropInt) and the PID controller class (PropIntDeriv).

GET THE SAMPLING LENGTH
public int getSampleLength()
Usage: samplen = box.getSampleLength();
Gets the length of the arrays in which the times, inputs in the time domain and outputs in the time domain are stored. See immediately above for details.

SET THE SAMPLING PERIOD
public void setDeltaT(double deltaT)
Usage: box.setDeltaT(deltaT);
Sets the sampling period to e.g. deltaT in the above usage.

GET THE SAMPLING PERIOD
public double getDeltaT()
Usage: deltaT = box.getDeltaT();
Returns the sampling period as a double.

SET THE SAMPLING FREQUENCY
public void setSampFreq(double sFreq)
Usage: box.setSampFreq(sFreq);
Sets the sampling frequency [in Hz] to e.g. sFreq in the above usage.

GET THE SAMPLING FREQUENCY
public double getDeltaT()
Usage: sFreq = box.getSampFreq();
Returns the sampling frequency [as Hz] as a double.

SET THE SAMPLED INPUT AND TIME
public void setInputT(double time, double input)
Usage: box.setInputT(time, input);
Sets the sampled input to e.g. input in the above usage, at a given time, e.g. time in the above usage. The time must be greater than that set at the previous call to this method.

GET THE CURRENT VALUE OF THE TIME
public double getCurrentTime()
Usage: time = box.getCurrentTime();
Returns the current value of the time as a double.

GET THE ARRAY OF THE TIMES
public double[] getTime()
Usage: time = box.getTime();
Returns the value of the times, at all the previous sampling times up to the sampling length.

GET THE CURRENT VALUE OF THE SAMPLED INPUT
public double getCurrentInputT()
Usage: input = box.getCurrentInputT();
Returns the current value of the sampled input as a double.

GET THE ARRAY OF THE SAMPLED INPUT VALUES
public double[] getInputTdouble time)
Usage: input = box.getInputT();
Returns the array of value of the sampled input, at the all sampling times up to the sampling length.

CALCULATE THE CURRENT VALUE OF THE OUTPUT FOR A SAMPLED INPUT
public void getCurrentOutputT()
public void getCurrentOutputT(double time, double input)
Usage: box.calcOutputT();
Calculates and stores the current value of the output for the current stored value of the time and sampled input. This method uses the inverse Laplace transform of the transfer function formed by the ratio of the s-domain numerator and denominator polynomials.
Usage: box.calcOutputT(time, input);
Calculates and stores the current value of the output for a given value of the time and a given value of the sampled input. The time must be greater than the value set by the previous call to any method that sets the time, e.g. this method or the method setInputT.

This method uses the inverse Laplace transform of the transfer function formed by the ratio of the s-domain numerator and denominator polynomials.
IT IS PREFERABLE THAT THIS METHOD BE OVERRIDDEN, IN ANY SUBCLASS, WITH A SPECIFIC CALCULATION OF THE OUTPUT, ESPECIALLY, IF A DIFFERENTIATION AND/OR INTEGRATION IS INVOLVED, e.g. See PropIntDeriv.

GET THE CURRENT VALUE OF THE OUTPUT FOR A SAMPLED INPUT
public double getCurrentOutputT()
Usage: output = box.getCurrentOutputT();
Returns the current value of the output for sampled input.

GET THE ARRAY OF OUTPUTS FOR SAMPLED INPUTS
public double[] getOutputT()
Usage: input = box.getInputT();
Returns the values of the outputs for all sampled inputs up to the sampling length.

SET THE NUMERICAL INTEGRATION METHOD OPTION
public void setIntegrateMethod(int methodInt)
public void setIntegrateMethod(String methodInt)
Usage: box.setIntegrateMethod(methodInt);
Sets the numerical integration method option. This may be:

The Trapezium Rule: set methodInt to the integer 0 or to the String "trapezium";
The Backward Rectangular Rule: set methodInt to the integer 1 or to the String "backward";
The Foreward Rectangular Rule: set methodInt to the integer 2 or to the String "foreward";

GET THE NUMERICAL INTEGRATION METHOD OPTION
public int getIntegrateMethod()
Usage: methodInt = box.getIntegrateMethod();
Gets the numerical integration method option. This may be:

The Trapezium Rule: returns 0;
The Backward Rectangular Rule: returns 1;
The Foreward Rectangular Rule: returns 2;

SET THE FORGETTING FACTOR
public void setForgetFactor(double factor)
Usage: box.setForgetFactor(factor);
Sets the forgetting factor. This is the factor used in exponential forgetting in the numerical integration. In the absence of exponential forgetting the integral is evaluated, in a discrete implementation, by summing the discrete inputs following the trapezium, backward rectangular or foreward rectangular rules. If exponential forgetting is included the inputs are first multiplied by the forgetting factor (factor in the above usage) raised to the power (sampling length - current time array element index) i.e.

Typical exponential forgetting factors lie between 0.95 and 1.0 (1.0 = no forgetting). This method also resets the sampling length, i.e. the length of the arrays of times, inputs and outputs in the time domain, so that falls to at least 1/10000. If this length is greater than 5000 the array length is set at 5000. If it is less than 100 it is set at 100.

Usage: box.setForgetFactor(factor, samplength);
Sets the exponential forgetting factor and resets the length of the arrays storing the times, inputs and outputs in the time domain. See immediately above for a description of the exponential forgetting factor.

GET THE FORGETTING FACTOR
public double getForgetFactor()
Usage: factor = box.getForgetFactor();
Gets the forgetting factor. See immediately above for details of this factor.

DEEP COPY

public BlackBox copy()
public Object clone()

Copy a BlackBox
Usage: aa = bb.copy();
A deep copy of BlackBox, bb, is returned as aa.
This method is overridden in each subclass to ensure a true deep copy of the subclass.

Clone a BlackBox
Usage: aa = bb.clone();
A deep copy of BlackBox, bb, is returned as aa cast as Object.
This method overrides java.lang.Object.clone() and is overridden in each subclass to ensure a true deep copy of the subclass

GENERAL METHODS

RESET ALL INPUTS, OUTPUTS AND TIMES
public void resetZero()
Usage: box.resetZero();
Resets the time, time at previous sampling, sampled input, sampled input at previous sampling, output for sampled input, output for sampled input at previous sampling, s-domain input and s-domain output to zero.

SET THE NAME OF THE BLACK BOX
public void setName(String name)
Usage: box.setName(name);
Sets the name of the BlackBox instance to the String, e.g.name in the above usage. The default option is "BlackBox". Subclasses may reset this variable, e.g. PropIntDeriv() resets it to "PID"

GET THE NAME OF THE BLACK BOX
public String getName()
Usage: name = box.getName();
Returns the name of the BlackBox instance to a String, e.g. name in the above usage.

OTHER CLASSES USED BY THIS CLASS

This class uses the following classes in this library:

This page was prepared by Dr Michael Thomas Flanagan