Basic abstract class for wrapping generic algorithms. More...

#include <Block.h>

Detailed Description

Basic abstract class for wrapping generic algorithms.

Rationale

This class is aimed to wrap generic algorithms and it represents the most basic component of BlockFactory.

The entire execution of a generic algorithm can be split in the following major steps:

Initialization: implemented with core::Block::configureSizeAndPorts, core::Block::initialize
Execution: implemented with core::Block::output
Termination: implemented with core::Block::terminate

Considering that the main aim of this framework at its beginning was the integration with Simulink, it contains other methods for exposing the algorithm as a Simulink block.

Main concept

A generic application is the composition of many algorithms sharing and processing each other data. Every algorithm is represented by a core::Block, and the data shared with other blocks is carried by core::Signal.

The block is generally unaware of the data that it will process, and it is only interested in knowing how many input / output signals are connected, their size and data type. Blocks have the concept of ports, which are the connections between external core::Signal and the block itself.

Remarks: A signal can be plugged to more than one port.

This kind of information is set by a core::BlockInformation object, and it is specific to the framework where the algorithm runs (e.g. standalone C++ code, Simulink, etc).

Beyond this, an algorithm often needs parameters. This class provides functionalities to gather them in a core::Parameters object.

Other information

You can create a new block by deriving from this class and implementing at least all the abstract methods.

Note: This block interface assumes that algorithms are represented as instantaneous systems, there is no default storage capability between different sampling times. However, concrete blocks can have buffers that retain previous data.

Note: Despite some of the methods inside this class look Simulink-dependent, objects of this class are completely generic. In fact, core::Block only provides algorithm callbacks, and the operation to set input / output data is demanded to the core::BlockInformation interface. For what concerns Simulink, a mex::SimulinkBlockInformation implementation is provided.

See also: core::Signal, core::Port, core::BlockInformation

Block Parameters

Type	Index	Rows	Cols	Name
ParameterType::STRING	0	1	1	"className"
ParameterType::STRING	1	1	1	"libName"

Public Member Functions
virtual	~Block ()=default
	Destructor. More...

std::string	getUniqueName (const BlockInformation *blockInfo) const
	Get the unique name of the block instance. More...

virtual unsigned	numberOfParameters ()
	Returns the number of configuration parameters needed by this block. More...

virtual std::vector< std::string >	additionalBlockOptions ()
	Returns the vector of additional block options. More...

virtual unsigned	numberOfDiscreteStates ()
	Returns the number of discrete states of the block. More...

virtual unsigned	numberOfContinuousStates ()
	Returns the number of continuous states of the block. More...

virtual bool	updateDiscreteState (const BlockInformation *blockInfo)
	Update the internal discrete state. More...

virtual bool	stateDerivative (const BlockInformation *blockInfo)
	Update the internal continuous state. More...

virtual bool	parameterAtIndexIsTunable (unsigned index)
	Specify if the parameter at the specified index is tunable. More...

virtual bool	parseParameters (BlockInformation *blockInfo)
	Parse the parameters stored into the core::BlockInformation object. More...

bool	getParameters (blockfactory::core::Parameters &params) const
	Gather all the stored parameters. More...

virtual bool	configureSizeAndPorts (BlockInformation *blockInfo)
	Configure the input and output ports. More...

virtual bool	initialize (BlockInformation *blockInfo)
	Initialize the block. More...

virtual bool	initializeInitialConditions (const BlockInformation *blockInfo)
	Initialize block initial conditions. More...

virtual bool	terminate (const BlockInformation *blockInfo)
	Cleanup block resources. More...

virtual bool	output (const BlockInformation *blockInfo)=0
	Compute the output of the block. More...

Static Public Attributes
static constexpr unsigned	NumberOfParameters = 2
	Number of parameters of core::Block. More...

Protected Attributes
Parameters	m_parameters
	Container for block parameters. You can get this member using Block::getParameters. More...

Constructor & Destructor Documentation

virtual blockfactory::core::Block::~Block ( )

virtualdefault

Destructor.

Member Function Documentation

virtual std::vector<std::string> blockfactory::core::Block::additionalBlockOptions ( )

virtual

Returns the vector of additional block options.

Implement this method if you want to store in the Block additional options that can be parsed later from BlockInformation::optionFromKey.

Returns: A vector containing a list of options.

virtual bool blockfactory::core::Block::configureSizeAndPorts ( BlockInformation * blockInfo )

virtual

Configure the input and output ports.

Implement this method to set information about number and size of input and output ports. The terminology port comes as Simulink inheritage, and it marks the connection of a signal (which resides in some buffer in the program memory) to the block input or output.

These information will be used later (e.g. in the core::Block::initialize and core::Block::output) for preallocating resources and accessing data knowing its size in advance.

Note: If the size is not known (core::Signal::DynamicSize) during this configuring phase, at latest it should be set in the core::Block::initialize method.

Warning: Do not allocate any data in this stage! Object are destroyed afterwards and created again before the core::Block::initialize step. All allocated memory and stored values will be deleted. Only information stored in blockInfo will persist.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True if the block was configured successfully, false otherwise.

See also: core::BlockInformation::setIOPortsData

bool blockfactory::core::Block::getParameters ( blockfactory::core::Parameters & params ) const

Gather all the stored parameters.

After the parameters have been successfully stored and parsed using the core::Block::parseParameter, you can gather them using this method.

Parameters

[out] params A core::Parameters object containing block parameters.

Returns: bool True for success, false otherwise.

std::string blockfactory::core::Block::getUniqueName ( const BlockInformation * blockInfo ) const

Get the unique name of the block instance.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: The unique name of the block instance if it was set, an empty string otherwise.

virtual bool blockfactory::core::Block::initialize ( BlockInformation * blockInfo )

virtual

Initialize the block.

Implement this method to initialize and allocate the resources the algorithm needs during its execution.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

virtual bool blockfactory::core::Block::initializeInitialConditions ( const BlockInformation * blockInfo )

virtual

Initialize block initial conditions.

Implement this method to specify block initial conditions. Its execution will happen after block::Block::initialize and before the first call of core::Block::output. The default is an empty implementation.

Note: This function is also called on a reset event. In Simulink, an example is when the block resides in an enabled subsystem.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

virtual unsigned blockfactory::core::Block::numberOfContinuousStates ( )

virtual

Returns the number of continuous states of the block.

The base implementation returns 0, i.e. no continuous states.

Note: If you return a number > 0, you should implement the Block::stateDerivative function.

Returns: The number of continuous states.

virtual unsigned blockfactory::core::Block::numberOfDiscreteStates ( )

virtual

Returns the number of discrete states of the block.

The base implementation returns 0, i.e. no discrete states.

Note: If you return a number > 0, you should implement the Block::updateDiscreteState function.

Returns: The number of discrete states.

virtual unsigned blockfactory::core::Block::numberOfParameters ( )

virtual

Returns the number of configuration parameters needed by this block.

Returns: The number of parameters.

See also: Block::NumberOfParameters

virtual bool blockfactory::core::Block::output ( const BlockInformation * blockInfo )

pure virtual

Compute the output of the block.

This method is called at every iteration of the model. Implement here a single step of the algorithm.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

virtual bool blockfactory::core::Block::parameterAtIndexIsTunable ( unsigned index )

virtual

Specify if the parameter at the specified index is tunable.

Tunable means that it can be changed during the simulation. Usually parameters are defined before the beginning of the simulation and they stay constant for all its duration.

Note: For the time being tunable parameters are not used in this toolbox.

Parameters

index Index of the parameter.

Returns: True if the parameter is tunable, false otherwise.

virtual bool blockfactory::core::Block::parseParameters ( BlockInformation * blockInfo )

virtual

Parse the parameters stored into the core::BlockInformation object.

Implement this method to create the metadata of the parameters your block needs (using core::ParameterMetadata), store them into the blockInfo object with core::BlockInformation::addParameterMetadata, and parse them using core::BlockInformation::parseParameters.

An example of the implementation is the following:

bool MyBlock::parseParameters(BlockInformation* blockInfo)
{
    ParameterMetadata fooMetadata(PARAM_STRING, PARAM_IDX_FRAME, 1, 1, "foo");
    bool ok = blockInfo->addParameterMetadata(fooMetadata);
    if (!ok) {
        bfError << "Failed to store parameter metadata.";
        return false;
    }
    return blockInfo->parseParameters(m_parameters);
}

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

See also: core::BlockInformation::addParameterMetadata, core::BlockInformation::parseParameters

virtual bool blockfactory::core::Block::stateDerivative ( const BlockInformation * blockInfo )

virtual

Update the internal continuous state.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

virtual bool blockfactory::core::Block::terminate ( const BlockInformation * blockInfo )

virtual

Cleanup block resources.

This method is called during the termination of the execution. Implement this method to deallocate all the memory requested during the previous steps or to perform other terminating operations.

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

virtual bool blockfactory::core::Block::updateDiscreteState ( const BlockInformation * blockInfo )

virtual

Update the internal discrete state.

i.e. x[i+1] = f(x[i])

Parameters

blockInfo The pointer to a BlockInformation object.

Returns: True for success, false otherwise.

Member Data Documentation

Parameters blockfactory::core::Block::m_parameters

protected

Container for block parameters. You can get this member using Block::getParameters.

constexpr unsigned blockfactory::core::Block::NumberOfParameters = 2

static

Number of parameters of core::Block.

Static variable matching Block::numberOfParameters. It might be useful to define parametric constants for parameter indices in child blocks.

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

/home/travis/build/robotology/blockfactory/sources/Core/include/BlockFactory/Core/Block.h

Detailed Description

Rationale

Main concept

Other information

Block Parameters

Public Member Functions

Static Public Attributes

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation