ControlBlock Class Reference
[Data Processing]

#include <ControlBlock.h>

Inheritance diagram for ControlBlock:

List of all members.

Detailed Description

Base class from which all control block classes are derived.

A control block is intended to model a discrete transfer function of the following kind

      x(k+1) = h( x(k) , u(k), p )
      y(k) = g( x(k), u(k), p )

where:

k is a temporal index
x is a vector of state variables that are updated at every sampling time k
u is a vector of input variables that are updated at every sampling time k
y is a vector of output variables that are updated at every sampling time k
p is a vector of nominally constant parameters
h(.) is a state propagation function
g(.) is an output update function

This class offers the following types of services:

services to set and get the number of the inputs, outputs, states, and parameters
services to set and get the values of the state variables and of the parameters
services to propagate the state and update the outputs
reset service to reset the state propagation and output update algorithms and bring the state back to the value it had at the time the control block was initialized

No services are defined to set and get the output and input values because there can be several ways in which a control block is linked to the source of its inputs and to the destination for its outputs. Example of typical input/output linking mechanisms are:

Copy Link: at every sampling time, the inputs are copied from the external input source into an internal buffer maintained by the control block. After state and output propagation, the updated values of the outputs are copied to the external output destination location.
Pointer Link: during the configuration phase, the control block is loaded with pointers to the input sources and to the output destinations. The control block then accesses its inputs and outputs through these pointers.
Data Item Link: during the configuration phase, the control block is loaded with data items (instances of class DC_DataItem) that encapsulate the input sources and output destinations. The control block then accesses its inputs and outputs through their data items.
Data Pool Link: the input sources and output destinations are assumed to be located in the data pool. During the configuration phase, the control block is loaded with the identifiers of the data pool locations that hold the inputs and outputs. The control block then accesses its inputs and outputs directloy from the data pool.

The diversity of the above mechansims makes it impossible to define the services to access the inputs and outputs at the level of this base class. The definition of these services is therefore left to subclasses of ControlBlock.

This is an abstract class because it defines neither the state propagation and output update functions nor the input and output allocation, setter and getter functions. However it internally defines variables that are intended to make it easy for developers to create concrete classes that implement specific state propagation and output update algorithms. More specifically, this class defines the following items:

The number of inputs (nInputs)
The number of outputs (nOutputs)
The number of state variables (nStates)
The number of parameters (nParameters)
An array x to hold the state variables
An array p to hold the parameter variables

These variables are declared protected so as to give subclasses ready and easy access to them. It should be stressed however that there is no obligation on the part of subclasses to use these data structures. If they are subject to special requirements, they are free to implement the state propagation and output update services using class-specific structures.

The internal data structures must be configured by the user. Thus, the configuration process for an instance of this class is as follows:

set the number of inputs
set the number of outputs
set the number of states
set the number of parameters

Access to specific parameter and state values is performed through an integer index i that designates the location of the desired input, output, parameter or state value within the corresponding array. Run-time checks on the legality of the index are only performed where errors might corrupt internal data structures (i.e. during write accesses). In other cases, responsibility for ensuring the legality of the index is left to the caller.

Author:: Alessandro Pasetti, Roberto Totaro

Version:: 1.0

Definition at line 105 of file ControlBlock.h.

Public Member Functions

ControlBlock (void)

Instantiate a control block.

int getNumberOfOutputs (void) const

Return the number of outputs of the control block.

int getNumberOfStates (void) const

Return the number of states of the control block.

int getNumberOfInputs (void) const

Return the number of inputs of the control block.

int getNumberOfParameters (void) const

Return the number of parameters of the control block.

TD_Float getState (unsigned int i) const

Return the value of the i-th state.

TD_Float getParameter (unsigned int i) const

Return the value of the i-th parameter.

void setState (unsigned int i, TD_Float newValue)

Set the value of the i-th state.

void setParameter (unsigned int i, TD_Float newValue)

Set the value of the i-th parameter.

virtual void propagate (void)

Propagate the input values updating the state variables and the outputs.

virtual void reset (void)

Reset the control block bringing its state back to the value they had when the configuration process of the control block was terminated.

virtual bool isObjectConfigured (void)

Perform a class-specific configuration check on a control block.

Protected Member Functions

virtual void setNumberOfInputs (unsigned int n)=0

Set the number of inputs and, if required, allocate the necessary storage.

virtual void setNumberOfOutputs (unsigned int n)=0

Set the number of outputs and, if required, allocate the necessary storage.

void setNumberOfStates (unsigned int n)

Set the number of states.

void setNumberOfParameters (unsigned int n)

Set the number of parameters.

virtual void propagateState (void)=0

Implement the state propagation function.

virtual void updateOutput (void)=0

Implement the output update function.

Protected Attributes

int nInputs

Number of inputs.

int nOutputs

Number of outputs.

int nStates

Number of state variables.

int nParameters

Number of parameters.

TD_Float * x

Array to hold the state variables.

TD_Float * p

Array to hold the parameter variables.

Constructor & Destructor Documentation

ControlBlock::ControlBlock ( void )

Instantiate a control block.
The number of inputs, outputs, states and parameters is initialized with illegal values to signify that the component is not yet configured.
Definition at line 17 of file ControlBlock.cpp.

Member Function Documentation

int ControlBlock::getNumberOfInputs ( void ) const [inline]

Return the number of inputs of the control block.

Returns:
the number of inputs

Definition at line 36 of file ControlBlock_inl.h.

int ControlBlock::getNumberOfOutputs ( void ) const [inline]

Return the number of outputs of the control block.

Returns:
the number of outputs

Definition at line 30 of file ControlBlock_inl.h.

int ControlBlock::getNumberOfParameters ( void ) const [inline]

Return the number of parameters of the control block.

Returns:
the number of parameters

Definition at line 48 of file ControlBlock_inl.h.

int ControlBlock::getNumberOfStates ( void ) const [inline]

Return the number of states of the control block.

Returns:
the number of states

Definition at line 42 of file ControlBlock_inl.h.

TD_Float ControlBlock::getParameter ( unsigned int i ) const [inline]

Return the value of the i-th parameter.
The argument i must lie in the interval [0,n-1] where n is the number of parameters. No check is performed on the legality of the index i.
Returns:
the value of the i-th parameter variable

Parameters:

i the index of the parameter variable

Definition at line 24 of file ControlBlock_inl.h.

TD_Float ControlBlock::getState ( unsigned int i ) const [inline]

Return the value of the i-th state.
The argument i must lie in the interval [0,n-1] where n is the number of states. No check is performed on the legality of the index i.
Returns:
the value of the i-th state variable

Parameters:

i the index of the state variable

Definition at line 18 of file ControlBlock_inl.h.

bool ControlBlock::isObjectConfigured ( void ) [virtual]

Perform a class-specific configuration check on a control block.
It is checked that the number of inputs, outputs, states and parameters have been set to legal values.
Reimplemented from CC_RootObject.
Reimplemented in DataItemControlBlock, DataPoolControlBlock, and PointerControlBlock.
Definition at line 76 of file ControlBlock.cpp.

void ControlBlock::propagate ( void ) [virtual]

Propagate the input values updating the state variables and the outputs.
This method implements the transfer function encapsulated by the control block. It causes the state variables to be updated to take account of the latest input values and it then uses the new state values to compute a new set of ouptuts. A pseudo-code implementation for this method is as follows:
propagateState(); updateOutput();
Note that methods propagateState and updateOutput are pure virtual methods. Together, they define the transfer function encapsulated by the control block.
This class defines the structure of the propagation cycle. It is defined to be virtual to allow subclasses to implement different propagation cycles.
Definition at line 62 of file ControlBlock.cpp.

virtual void ControlBlock::propagateState ( void ) [protected, pure virtual]

Implement the state propagation function.
The result of calling this method should be a new set of values for the state variables computed as a function of the current input values, the old state values, and the parameter values. Note that the state and parameter values are directly accessible as protected variables. This should facilitate the implementation of this method in concrete subclasses.
See also:
propagate

Implemented in DC_DummyCopyControlBlock, DC_DummyDataItemControlBlock, DC_DummyDataPoolControlBlock, DC_DummyPointerControlBlock, DC_MatlabCopyPID, DC_MatlabDataItemPID, DC_MatlabDataPoolPID, DC_MatlabPointerPID, DC_SampleControlBlock_1, DC_SampleControlBlock_2, DC_SampleControlBlock_3, and DC_SampleControlBlock_4.

void ControlBlock::reset ( void ) [virtual]

Reset the control block bringing its state back to the value they had when the configuration process of the control block was terminated.
The default implementation provided by this class resets the state values to zero.
Reimplemented in CopyControlBlock, DC_DummyCopyControlBlock, DC_DummyDataItemControlBlock, DC_DummyDataPoolControlBlock, DC_DummyPointerControlBlock, DC_MatlabCopyPID, DC_MatlabDataItemPID, DC_MatlabDataPoolPID, DC_MatlabPointerPID, DC_SampleControlBlock_1, DC_SampleControlBlock_2, DC_SampleControlBlock_3, and DC_SampleControlBlock_4.
Definition at line 69 of file ControlBlock.cpp.

virtual void ControlBlock::setNumberOfInputs ( unsigned int n ) [protected, pure virtual]

Set the number of inputs and, if required, allocate the necessary storage.
The number of inputs must be non-negative.
Parameters:

n the number of inputs

Implemented in CopyControlBlock, DataItemControlBlock, DataPoolControlBlock, and PointerControlBlock.

virtual void ControlBlock::setNumberOfOutputs ( unsigned int n ) [protected, pure virtual]

Set the number of outputs and, if required, allocate the necessary storage.
The number of inputs must be non-negative.
Parameters:

n the number of outputs

Implemented in CopyControlBlock, DataItemControlBlock, DataPoolControlBlock, and PointerControlBlock.

void ControlBlock::setNumberOfParameters ( unsigned int n ) [protected]

Set the number of parameters.
This method causes the memory for the parameter array to be allocated. The number of parameters must be non-negative. The parameter values are initialized to zero. This is an initialization method: it shall be called only once.
Parameters:

n the number of parameters

Definition at line 35 of file ControlBlock.cpp.

void ControlBlock::setNumberOfStates ( unsigned int n ) [protected]

Set the number of states.
This method causes the memory for the state array to be allocated. The number of states must be non-negative. The state values are initialized to zero. This is an initialization method: it shall be called only once.
Parameters:

n the number of states

Definition at line 26 of file ControlBlock.cpp.

void ControlBlock::setParameter ( unsigned int i,

TD_Float newValue

)

Set the value of the i-th parameter.
The argument i must lie in the interval [0,n-1] where n is the number of parameters. Illegal argument values trigger the generation of an event report EVT_ILLEGAL_CB.
Parameters:

newValue the new value of the i-th parameter variable

i the index of the parameter variable

Definition at line 53 of file ControlBlock.cpp.

void ControlBlock::setState ( unsigned int i,

TD_Float newValue

)

Set the value of the i-th state.
The argument i must lie in the interval [0,n-1] where n is the number of states. Illegal argument values trigger the generation of an event report EVT_ILLEGAL_CB. This method should not normally be used since the state values are internally computed by propagating the input and the previous state values. It is provided for the (non-nominal) case where there is a need to overwrite the internally computed state.
Parameters:

newValue the new value of the i-th state variable

i the index of the state variable

Definition at line 44 of file ControlBlock.cpp.

virtual void ControlBlock::updateOutput ( void ) [protected, pure virtual]

Implement the output update function.
This method uses the current values of the inputs and state variables to compute and apply new values for the outputs. Note that the input, state and parameter values are directly accessible as protected variables. This should facilitate the implementation of this method in concrete subclasses.
See also:
propagate

Implemented in DC_DummyCopyControlBlock, DC_DummyDataItemControlBlock, DC_DummyDataPoolControlBlock, DC_DummyPointerControlBlock, DC_MatlabCopyPID, DC_MatlabDataItemPID, DC_MatlabDataPoolPID, DC_MatlabPointerPID, DC_SampleControlBlock_1, DC_SampleControlBlock_2, DC_SampleControlBlock_3, and DC_SampleControlBlock_4.

Member Data Documentation

TD_Float* ControlBlock::p [protected]

Array to hold the parameter variables.
p[i] holds the i-th state variable with i in the interval [0,N-1] where N is the number of parameters.
See also:
nParameters

Definition at line 141 of file ControlBlock.h.

TD_Float* ControlBlock::x [protected]

Array to hold the state variables.
x[i] holds the i-th state variable with i in the interval [0,N] where N is the number of states.
See also:
nStates

Definition at line 133 of file ControlBlock.h.

The documentation for this class was generated from the following files:


Public Member Functions
	ControlBlock (void)
	Instantiate a control block.
int	getNumberOfOutputs (void) const
	Return the number of outputs of the control block.
int	getNumberOfStates (void) const
	Return the number of states of the control block.
int	getNumberOfInputs (void) const
	Return the number of inputs of the control block.
int	getNumberOfParameters (void) const
	Return the number of parameters of the control block.
TD_Float	getState (unsigned int i) const
	Return the value of the i-th state.
TD_Float	getParameter (unsigned int i) const
	Return the value of the i-th parameter.
void	setState (unsigned int i, TD_Float newValue)
	Set the value of the i-th state.
void	setParameter (unsigned int i, TD_Float newValue)
	Set the value of the i-th parameter.
virtual void	propagate (void)
	Propagate the input values updating the state variables and the outputs.
virtual void	reset (void)
	Reset the control block bringing its state back to the value they had when the configuration process of the control block was terminated.
virtual bool	isObjectConfigured (void)
	Perform a class-specific configuration check on a control block.
Protected Member Functions
virtual void	setNumberOfInputs (unsigned int n)=0
	Set the number of inputs and, if required, allocate the necessary storage.
virtual void	setNumberOfOutputs (unsigned int n)=0
	Set the number of outputs and, if required, allocate the necessary storage.
void	setNumberOfStates (unsigned int n)
	Set the number of states.
void	setNumberOfParameters (unsigned int n)
	Set the number of parameters.
virtual void	propagateState (void)=0
	Implement the state propagation function.
virtual void	updateOutput (void)=0
	Implement the output update function.
Protected Attributes
int	nInputs
	Number of inputs.
int	nOutputs
	Number of outputs.
int	nStates
	Number of state variables.
int	nParameters
	Number of parameters.
TD_Float *	x
	Array to hold the state variables.
TD_Float *	p
	Array to hold the parameter variables.

ControlBlock Class Reference [Data Processing]

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

ControlBlock Class Reference
[Data Processing]