CCustomBlock
This is a customizable block that you can define in C language.
Library
Activate/CustomBlocks
Description
The CCustomBlock block provides a generic interface for specifying the block properties and defining the block simulation function. The simulation function is specified in C code and is stored as a block parameter. The code is compiled and used automatically at the start of the simulation.
Compared to creating and using new blocks, Custom blocks have the advantage of not requiring any library management operations. But even though their look and feel may be customized to some extent (in particular by encapsulating them in a masked Super Block) Custom blocks are not always the best solution. With Custom blocks, there is no mechanism for automatically upgrading the code of Custom blocks as there is for library blocks. Custom blocks are often used as a first step to develop and test C simulation codes destined for new blocks.
The CCustomBlock block also provide the option of not including the source code of the simulation function. The simulation function may be provided by a shared library. Instead of the C code, the block parameters include the path to the shared library and the name of the entry point. This option is particularly interesting for preserving intellectual property, but note that the model is no longer self-contained. The shared library file must be distributed along with the model.
Block Simulation Function
Block simulation functions are called by the Twin Activate simulator during simulation to perform different tasks, such as updating the output or the state. Simulation functions have two arguments: block and flag. The task to be realized is specified by the argument flag. The argument block is a the block’s data structure to be passed to the APIs to get and set block data.
Block Parameter GUI
CCustomBlock block's parameter GUIs provide an interactive user interface to define block properties. You can define the number and types of inputs and outputs, the states and simulation parameters and other properties. The interface also gives access to an editor for writing the block’s simulation code.
Developing a simulation code requires a knowledge of the APIs needed to get and set block data, for example for reading block inputs and writing block outputs. The CCustomBlock block provide a utility to generate a skeleton of the simulation code by taking into account the block properties specified by the user. This significantly facilitates the development of the simulation code.
Block inputs, outputs and simulation parameters are named and the code skeleton generator takes into account this information in order to provide a code where the user, in most cases, simply needs to add instructions involving the provided names as program variables. These variables are already declared and initialized when needed.
Alternative
The MathExpression and MatrixExpression blocks should be considered before using Custom blocks since they provide even simpler ways to express the dynamical behavior of a block. They are however limited to expressing stateless dynamics: block outputs depend on block inputs alone, and the expressions support a fixed set of functions that cannot be extended by the user.
Parameters
Name | Label | Description | Data Type | Valid Values |
---|---|---|---|---|
nin | Number of input ports | Number | ||
inports | Input ports parameters | Structure | ||
inports/inrow | Row size | Cell of scalars | ||
inports/incol | Column size | Cell of scalars | ||
inports/it | Type | Cell of strings | 'double' | |
inports/depu | Feedthrough | Cell of scalars | 0 | |
inports/name | Name | Cell of strings | ||
nevin | Number of input event ports | Number | ||
nout | Number of output ports | Number | ||
outports | Output port parameters | Structure | ||
outports/outrow | Row size | Cell of scalars | ||
outports/outcol | Column size | Cell of scalars | ||
outports/ot | Type | Cell of strings | 'double' | |
outports/name | Name | Cell of strings | ||
nevout | Number of output event ports | Number | ||
evoutports | Initial firing values | Structure | ||
evoutports/fir | Firing(<0 for no firing) | Cell of scalars |
Name | Label | Description | Data Type | Valid Values |
---|---|---|---|---|
xx | Initial continuous state | Vector | ||
xd | Initial state derivative | Vector | ||
z | Initial discrete state | Vector | ||
noz | Number of initial object states | Number | ||
ozparams | Initial object states | Structure | ||
ozparams/oztyp | Type | Cell of strings | 'double' | |
ozparams/ozvalue | Value | Cell of matrices | ||
ozparams/name | Name | Cell of strings |
Name | Label | Description | Data Type | Valid Values |
---|---|---|---|---|
rpar | Real parameters vector | Vector | ||
ipar | Integer parameters vector | Vector | ||
nopar | Number of object parameters | Number | ||
oparparams | Object parameters | Structure | ||
oparparams/opartyp | Type | Cell of strings | 'double' | |
oparparams/oparvalue | Value | |||
oparparams/name | Name | Cell of strings |
Name | Label | Description | Data Type | Valid Values |
---|---|---|---|---|
inlined | Inlined C code | Number | 0 | |
code | Function code | String | ||
fcn | Function | Structure | ||
fcn/slib | Shared library path | Cell of strings | ||
fcn/epoint | Entry point | Cell of strings | ||
impl | Implicit block (function) | Number | 0 | |
nincludepath | Number of Include paths | Number | ||
includepath | Include paths | Structure | ||
includepath/path | Include Path | Cell of strings | ||
ndefine | Number of Defines | Number | ||
define | Defines | Structure | ||
define/path | Define | Cell of strings | ||
ncompileflags | Number of compiler flags | Number | ||
compileflags | Compiler Flags | Structure | ||
compileflags/path | Compiler flag | Cell of strings | ||
nlibpath | Number of library paths | Number | ||
libpath | Library paths | Structure | ||
libpath/path | Library path | Cell of strings | ||
nlibs | Number of libraries | Number | ||
libs | Libraries | Structure | ||
libs/path | Library name | Cell of strings |
Name | Label | Description | Data Type | Valid Values |
---|---|---|---|---|
nmode | Number of modes | Scalar | ||
nzcr | Number of zero-crossings | Scalar | ||
dept | Activation mode | String | 'Always |
Ports
Name | Type | Description | IO Type | Number |
---|---|---|---|---|
Port 1 | explicit | output | nout | |
Port 2 | explicit | input | nin | |
Port 3 | activation | input | nevin | |
Port 4 | activation | output | nevout |
Example
Several demo models are available in demo browser in folder Activate/Custom blocks/CCustomBlock.