Nom
C_struct — C Block structure of a computational function
Description
The C structure of a xcos block defines all the fields to handle data provided by the simulator such inputs/outputs, parameters, states, ...
That structure of type is defined in the file , and user must include that header in each computational functions in the form :
#include <varargs.h>
void computational_function( |
scicos_block *block, int flags); |
|
scicos_block *block, int flags; |
The fields, that can be either C pointers or directly data, are then
accessible via the scicos_block structure :
block->field
This access is a approach and most of users should prefer the approach for facilities purpose.
In the current version of xcos, the structure is defined :
/* scicos_block structure definition */
typedef struct {
int nevprt;
voidg funpt ;
int type;
int scsptr;
int nz;
double *z;
int noz;
int *ozsz;
int *oztyp;
void **ozptr;
int nx;
double *x;
double *xd;
double *res;
int nin;
int *insz;
void **inptr;
int nout;
int *outsz;
void **outptr;
int nevout;
double *evout;
int nrpar;
double *rpar;
int nipar;
int *ipar;
int nopar;
int *oparsz;
int *opartyp;
void **oparptr;
int ng;
double *g;
int ztyp;
int *jroot;
char *label;
void **work;
int nmode;
int *mode;
} scicos_block;
Inputs/outputs
block->nin : Integer that gives the number of regular input ports of the block.
One can't override the index when reading sizes of input ports in the array and the index when reading data in the array with a C computational function.
The number of regular input ports can also be got by the use of the C macros .
block->insz : An array of integers of size that respectively gives the first dimensions, the second dimensions and the type of data driven by regular input ports.
Note that this array of size differs from the array and to provide full compatibilty with blocks that only use a single dimension.
Suppose that you have a block with three inputs : the first is an int32 matrix of size 3,2, the second a single complex number (matrix of size 1,1) and the last a real matrix of size 4,1.
In thescicos_model of such a block, the inputs will be defined : and the corresponding field at C computational function level will be coded as : Do the difference here in the type numbers defined at the (2,1,3) and the type numbers defined at the (84,11,10). The following table gives the correspondance for all xcos type:
block->inptr : An array of pointers of size nin,1 that allow to directly access to the data contained in the regular input matrices.
Suppose the previous example (block with three inputs : an int32 matrix of size [3,2], a complex scalar and a real matrix of size [4,1]).
contains three pointers, and should be viewed as arrays contained the data for the int32, the real and the complex matrices : For i.e., to directly access to the data, the user can use theses instructions : One can also use the set of C macros :
, ,
, ,
, ,
, ,
to have the appropiate pointer of the data to handle and
, ,
, ,
,
to handle number, dimensions and type of regular input ports. ().
For the previous example that gives : Finally note that the regular input port registers are only accessible for reading.
block->nout : Integer that gives the number of regular output ports of the block.
One can't override the index when reading sizes of output ports in the array and the index when reading data in the array with a C computational function.
The number of regular output ports can also be got by the use of the C macros .
block->outsz : An array of integers of size that respectively gives the first dimensions, the second dimensions and the type of data driven by regular output ports.
Note that this array of size differs from the array and to provide full compatibilty with blocks that only use a single dimension.
Suppose that you have a block with two outputs : the first is an int32 matrix of size 3,2, the second a single complex number (matrix of size 1,1) and the last a real matrix of size 4,1.
In thescicos_model of such a block, the outputs will be defined : and the corresponding field at C computational function level will be coded as : Do the difference here in the type numbers defined at the (2,1,3) and the type numbers defined at the (84,11,10) and please report to the previous table to have the correspondence for all xcos type.
block->outptr : An array of pointers of size nout,1 that allow to directly acces to the data contained in the regular output matrices.
Suppose the previous example (block with three outputs : an int32 matrix of size [3,2], a complex scalar and a real matrix of size [4,1]).
contains three pointers, and should be viewed as arrays contained the data for the int32, the real and the complex matrices : For i.e., to directly access to the data, the user can use theses instructions : One can also use the set of C macros :
, ,
, ,
, ,
, ,
to have the appropiate pointer of the data to handle and
, ,
, ,
,
to handle number, dimensions and type of regular output ports. (). For the previous example that gives : Finally note that the regular output port registers must be only written for =1.
Events
block->nevprt : Integer that gives the event input port number by which the block has been activated. This number is a binary coding. For i.e, if block have two event inputs ports, can take the value 1 if the block has been called by its first event input port, the value 2 if it has been called by the second event input port and 3 if it is called by the same event on both input port 1 and 2.
Note that can be -1 if the block is internally called.
One can also retrieve this number by using the C macros .
block->nevout : Integer that gives the number of event output ports of the block (also called the length of the output event register).
One can't override the index when setting value of events in the output event register .
The number of event output ports can also be got by the use of the C macro .
block->evout : Array of double of size nevout,1 corresponding to the output event register. That register is used to program date of events during the simulation.
When setting values in that array, you must understand that you give a delay relative to the current time of simulator :
where
is the date of the programmed event,
is the current time in the simulator and
the value that must be informed in the output
event register. For i.e, suppose that you want generate an event with
the first event output port, 1ms after each calls of the block, then
you'll use :Note that every events generated from output event register will be asynchronous with event coming from event input port (even if you set ).
The event output register must be only written for =3.
Parameters
block->nrpar : Integer that gives the length of the real parameter register.
One can't override the index when reading value of real parameters in the register .
The total number of real parameters can also be got by the use of the C macro .
block->rpar : Array of double of size nrpar,1 corresponding to the real parameter register. That register is used to pass real parameters coming from the scilab/xcos environment to your block model.
The C type of that array is (or C xcos type ).
Suppose that you have defined the following real parameters in thescicos_model of a block : you can retrieve the previous data in the C computational function with : You can also use the C macro to get the pointer of the real parameter register. For i.e., if we define the following in an interfacing function of a xcos block : in the corresponding C computational function of that block, we'll use : Note that real parameters register is only accessible for reading.
block->nipar : Integer that gives the length of the integer parameter register.
One can't override the index when reading value of integer parameters in the register .
The total number of integer parameters can also be got by the use of the C macro .
block->ipar : Array of int of size nipar,1 corresponding to the integer parameter register. That register is used to pass integer parameters coming from the scilab/xcos environment to your block model.
The C type of that array is (or C xcos type ).
Suppose that you have defined the following integer parameters in thescicos_model of a block : you can retrieve the previous data in the C computational function with : You can also use the C macro to get the pointer of the real parameter register.
Most of time in the xcos C block libraries, the integer register is used to parametrize the length of real parameters. For i.e. if you define the following in a block : the array of real parameters (parametrized by ipar) can be retrieved in the correspondig C computational function with : Note that integer parameters register is only accessible for reading.
block->nopar : Integer that gives the number of the object parameters.
One can't override the index when accessing data in the arrays , and in a C computational function.
This value is also accessible via the C macro .
block->oparsz : An array of integer of size nopar,2 that contains the dimensions of matrices of object parameters.
The first column is for the first dimension and the second for the second dimension. For i.e. if we want the dimensions of the last object parameters, we'll use the instructions : The dimensions of object parameters can be get with the following C macro : with an integer that gives the index of the object parameter, .
block->opartyp : An array of integer of size nopar,1 that contains the type of matrices of object parameters.
The following table gives the correspondence for xcos type expressed in Scilab number, in C number and also corresponding C pointers and C macros used for : The type of object parameter can also be got by the use of the C macro . For i.e, if we want the C number type of the first object parameter, we'll use the following C instructions:
block->oparptr : An array of pointers of size nopar,1 that allow to directly acces to the data contained in the object parameter.
Suppose that you have defined in the editor a block with the followingopar field inscicos_model : Then we have two object parameters, one is an 32-bit integer matrix with two rows and two columns and the second is a vector of complex numbers that can be understand as a matrix of size 1,3.
At the C computational function level, the instructions , , , will respectively return the values 2,1,2,3 and the instructions , the values 11 and 84.
will contain then two pointers, and should be viewed as arrays contained data of object parameter as shown in the following figure : For i.e., to directly access to the data, the user can use theses instructions : One can also use the set of C macros :
, ,
, ,
, ,
,
to have the appropiate pointer of the data to handle ().
For the previous example that gives : Note that object parameters register is only accessible for reading.
States and work
block->nx : Integer that gives the length of the continus state register.
One can't override the index when reading or writing data in the array , or with a C computational function.
block->x : Array of double of size nx,1 corresponding to the continuous state register.
That gives the result of the computation of the state derivative.
A value of a continuous state is readable (for i.e the first state) with the C instructions : Note that on =4, user can write some initial conditions in that register.
The pointer of that array can also be retrieve via the C macro .
block->xd : Array of double of size nx,1 corresponding to the derivative of the continuous state register.
When systems are explicitly given in terms of Ordinary Differential Equations (ODE), it can be explicitly expressed or implicitly used in the residual vector when systems are expressed in terms of Differantial Algebraic Equations (DAE).
Both systems must be programmed with .
For i.e the Lorentz attractor written as an ODE system with three state variables, of the form :
will be defined :
block->res : Array of double of size nx,1 corresponding to Differential Algebraic Equation (DAE) residual.
It is used to write the vector of systems that have the following form :
For i.e the Lorentz attractor written as a DAE system with three state variables, will be defined :
block->nz : Integer that gives the length of the discrete state register.
One can't override the index when reading data in the array with a C computational function.
This value is also accessible via the C macros .
block->z : Array of double of size nz,1 corresponding to the discrete state register.
A value of a discrete state is directly readable (for i.e the second state) with the C instructions : Note that the state register should be only written for =4 and =2.
The pointer of that array can also be retrieve via the C macro .
block->noz : Integer that gives the number of the discrete object states.
One can't override the index when accessing data in the arrays , and in a C computational function.
This value is also accessible via the C macro .
block->ozsz : An array of integer of size noz,2 that contains the dimensions of matrices of discrete object states.
The first column is for the first dimension and the second for the second dimension. For i.e. if we want the dimensions of the last object state, we'll use the instructions : The dimensions of object discrete states can be get with the following C macro : with an integer that gives the index of the discrete object state, .
block->oztyp : An array of integer of size noz,1 that contains the type of matrices of discrete object states.
The following table gives the correspondence table for xcos type expressed in Scilab number, in C number and also corresponding C pointers and C macros used for : The type of discrete object state can also be got by the use of the C macro . For i.e, if we want the C number type of the first discrete object state, we'll use the following C instructions:
block->ozptr : An array of pointers of size noz,1 that allow to directly acces to the data contained in the discrete object state.
Suppose that you have defined in the editor a block with the followingodstate field inscicos_model : Then we have two discrete object states, one is an 32-bit integer matrix with two rows and two columns and the second is a vector of complex numbers that can be understand as a matrix of size 1,3.
At the C computational function level, the instructions , , , will respectively return the values 2,1,2,3 and the instructions , the values 11 and 84.
will contain then two pointers, and should be viewed as arrays contained data of discrete object state as shown in the following figure : For i.e., to directly access to the data, the user can use theses instructions : One can also use the set of C macros :
, ,
, ,
, ,
,
to have the appropiate pointer of the data to handle ().
For the previous example that gives : Finally note that the discrete objects state should be only written for =4 and =2.
block->work : A free pointer to set a working array for the block.
The work pointer must be firstly allocated when = 4 and finally be free in the = 5.
Then a basic life cyle of that pointer in a C computational function should be : Note that if a block use a pointer, it will be called with =2 even if the block don't use discrete states.
The pointer of that array can also be retrieve via the C macro .
Zero crossing surfaces and modes
block->ng : Integer that gives the number of zero crossing surface of the block.
One can't override the index when reading/writing data in the array with a C computational function.
The number of zero crossing surface can also be got by the use of the C macro .
block->g : Array of double of size ng,1 corresponding to the zero crossing surface register.
That register is used to detect zero crossing of state variable during time domain integration.
Note that it is accessible for writting for = 9.
The pointer of that array can also be retrieve via the C macro .
block->nmode : Integer that gives the number of mode of the block.
One can't override the index when reading/writing data in the array with a C computational function.
The number of mode can also be got by the use of the C macro .
block->mode : Array of integer of size nmode,1 corresponding to the mode register.
That register is used to set the mode of state variable during time domain integration.
It is typically accessible for writting for = 9.
The pointer of that array can also be retrieve via the C macro .