PLECS 3.0 Online Help

C-Script

Purpose

Execute custom C code.

Library

Control / Functions & Tables

Description

pict

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.

Block Setup

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 n × 2   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.

Code Sections

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.


Note  It is not safe to make any assumptions about the progression of time between calls to the output function. The output function may be called multiple times during the same major time step, and the time may jump back and forth between function calls during minor time steps. Code that should execute exactly once per major time step should be placed in the update function.

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.).

C-Script Macros

The following table lists the macros that can be used in the function bodies.

MacroTypeAccessDescription
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.



Note  The values of the input and output signals are not stored in contiguous memory. Therefore, signal values may only be accessed by using the macros, not by pointer arithmetic. For example, trying to access the second output using the following code will fail:
   double *output = &Output(0); // not recommended  
   output[1] = 1;     // fails  
   *(output + 1) = 1; // fails  
   Output(1) = 1;     // ok