PLECS 3.0 Online Help |
Execute custom C code.
Control / Functions & Tables
The C-Script block allows custom functionality to be implemented in the C programming language. At simulation start, the C-code that you enter is compiled on-the-fly to native machine code and linked dynamically into PLECS.
The C-Script block provides very fine-grained interaction with the solver, allowing you to model virtually any behavior. In order to fully tap this potential it is advantageous that you familiarize yourself with the working principle of a solver (see Model Execution).
The C-Script dialog consists of two tabbed panes that are described in detail below.
In the Setup pane you define the number of elements in the input and output signal, the number of continuous and discrete state variables, and the number of zero-crossing signals that the block provides.
The Sample time parameter lets you specify one or more sample times with
which the block shall be executed. Multiple sample times are specified as an matrix. For details on sample times see section Sample Times.
The Parameters entry is used to pass the values of workspace variables or expressions into the C-code in order to parameterize the behavior of the C-Script block. Parameters are entered as comma-separated expressions. Each expression must evaluate to a double array.
The Input has direct feedthrough box must be checked if you need to access the current input signal values in order to calculate the current output signal values. This has an influence on the block sorting order and the occurrence of algebraic loops (see Block Sorting).
If the Enable runtime checks box is checked, protective code is added to guard you against access violations when working with block data (i.e. signal values, states, zero-crossing signals etc.). The C-Script function calls are also wrapped with protective code to prevent you from violating solver policies such as accessing input signals in the output function without enabling direct feedthrough.
The Code pane consists of a combobox for selecting a particular code section and a text editor that lets you edit the currently selected code section.
The Code declarations section contains global declarations and definitions (that is, global in the scope of the C-Script block). This is the place to include standard library headers (e.g. math.h or stdio.h) and to define macros, static variables and helper functions that you want to use in the C-Script functions.
The Function code sections contain the function bodies of the individual block methods that are described below. Within these sections, block data such as input/output values, state variables etc. can be accessed by means of special C-Script macros (see further below).
Start function The start function is called at the beginning of a simulation. If the C-Script has continuous or discrete state variables they should be initialized here. If the block has registered a Discrete-Variable sample time, the time of the first sample hit must be specified here using the NextSampleHit macro.
Output function The output function is called during major and minor time steps in order to update the output signals of the block. In general, output signals should be continuous during minor time steps; discontinuities should only occur during major time steps. Whether or not the call is made for a major time step can be inquired with the IsMajorStep macro. If the block has registered zero-crossing signals, they should also be updated here.
Update function If the block has discrete state variables, the update function is called once during a major time step after the output signals of all blocks have been updated. During this call, the discrete state variables should be updated using the DiscState macro.
Derivative function If the block has continuous state variables, the derivative function is called during the integration loop of the solver. During this call, the continuous state derivatives should be updated using the ContDeriv macro. Derivatives should be continuous during minor time steps; discontinuities should only occur during major time steps.
Terminate function The terminate function is called at the end of a simulation - regardless of whether the simulation stop time has been reached, the simulation has been stopped interactively, or an error has occurred. Use this function to free any resources that you may have allocated during the start function (e.g. files handles, memory etc.).
The following table lists the macros that can be used in the function bodies.
Macro | Type | Access | Description |
NumInputs | int | R | Returns the number of input signals. |
NumOutputs | int | R | Returns the number of output signals. |
NumContStates | int | R | Returns the number of continuous states. |
NumDiscStates | int | R | Returns the number of discrete states. |
NumZCSignals | int | R | Returns the number of zero-crossing signals. |
NumParameters | int | R | Returns the number of user parameters. |
CurrentTime | double | R | Returns the current simulation time. |
IsMajorStep | int | R | Returns 1 during major time steps, else 0. |
IsSampleHit(int i) | int | R | Returns 1 if the i sample time currently has a hit, else 0. |
NextSampleHit | double | R/W | Specifies the next simulation time when the block should be executed. This is relevant only for blocks that have registered a variable sample time. |
Input(int i) | double | R | Returns the value of the ith input signal. |
Output(int i) | double | R/W | Provides access to the value of the ith output signal. Output signals may only be changed during the output function call. |
ContState(int i) | double | R/W | Provides access to the value of the ith continuous state. Continuous state variables may not be changed during minor time steps. |
ContDeriv(int i) | double | R/W | Provides access to the derivative of the ith continuous state. |
DiscState(int i) | double | R/W | Provides access to the value of the ith discrete state. Discrete state variables may not be changed during minor time steps. |
ZCSignal(int i) | double | R/W | Provides access to the ith zero-crossing signal. |
ParamNumDims(int i) | int | R | Returns the number of dimensions of the ith user parameter. |
ParamDim(int i, j) | int | R | Returns the jth dimension of the ith user parameter. |
ParamRealData(int i, j) | double | R | Returns the value of the jth element of the ith user parameter. The index j is a linear index into the parameter elements. Indices into multi-dimensional arrays must be calculated using the information provided by the ParamNumDims and ParamDim macros. |
SetErrorMessage(char *msg) | void | W | Use this macro to report errors that occur in your code. The simulation will be terminated as soon as the current C-Script function returns. In general, this macro should be followed by a return statement. The pointer msg must point to static memory. |