Code Generation
As a separately licensed feature, PLECS can generate C code from a simulation model to facilitate real-time simulations. Code generation is subject to certain limitations, which are described in the first section of this chapter. The next two sections describe how the code generation capabilities are used within PLECS Standalone and the PLECS Blockset, respectively.
Code Generation for Physical Systems
As described earlier in this manual, PLECS models physical systems using piecewise linear state-space equations that can be described using multiple sets of state-space matrices. For details see Physical Model Equations.
During normal simulations, PLECS calculates new sets of state-space matrices on the fly as the individual switching components change their states. This is not possible in the generated C code because the algorithms for calculating the matrices are proprietary and because the calculation would simply be too time consuming under real-time constraints.
When generating code for a physical model, PLECS therefore embeds the
matrices for all combinations of switch states that it expects to encounter during the
execution of a simulation run. In general this means that for a system with switch
elements
sets of state-space matrices are calculated and embedded into the
generated C code. The actual number can be reduced by eliminating impossible
combinations. For instance, the Triple Switch blocks internally consists of 3 switch
elements but it still only accounts for 3 instead of
combinations because
one and only one switch will conduct at any time. Even so, systems with
many switches will lead to large source and executable files and long compile
times.
Limiting the Code Size
You can reduce the size of the generated code and the required compile time
by specifying the combinations for which code should be generated. The
combinations are specified separately for the electrical and mechanical domain. You
must specify the combinations of switch states for a domain explicitly if
PLECS finds that there are over 1024 () possible combinations in this
domain.
The combinations are specified in the circuit resp. subsystem parameters CodeGenTopologies in PLECS Standalone or the circuit parameter RTWTopologies in the PLECS Blockset. Currently, these parameters are only accessible via the command line interface.
The combinations are provided as a struct variable with two fields, electrical and mechanical. The field values must be matrices where the individual columns represent the switch elements of the physical model and each row represents one combination of switch states (zero for an open switch and non-zero for a closed switch). The column order of the matrices can be determined from the command line by querying the model parameter StateSpaceOrder (see Extraction of State-Space Matrices). An empty matrix defaults to all possible combination. For backward compatibility reasons, if instead of a struct only a matrix is provided, it is assumed to apply to the electrical domain.
If at run-time a combination is encountered, for which no code has been generated, the execution is aborted with an error message.
Maximum Number of Switches
The number of switch elements is limited to 16 or 32 per physical domain depending on the integer word size. This is due to the fact that the switch states of a physical domain are stored internally in a single unsigned integer variable. Note that some components, such as the Triple Switch, internally consist of more than one switch element.
Naturally Commutated Devices
Switched physical models are difficult to handle in real-time simulations if the natural switching instants can occur between two time steps. This is the case for naturally commutated components where switching events are triggered by internal quantities of the physical model. Examples of such components are the diode (which turns on when the voltage becomes positive and turns off then the current becomes negative) or the mechanical friction components (which start slipping when the torque resp. force exceeds a certain level and become stuck when the speed becomes zero).
During normal simulations, PLECS handles such non-sampled switching events using an interpolation scheme (see Interpolation of Non-Sampled Switching Events). This is not practical under real-time constraints because the computation time required for the interpolation is several times larger than that of an ordinary simulation step. In real-time simulations, PLECS will therefore defer the switching to the immediately following time step. Note that this reduces the accuracy compared to a normal simulation.
Unsupported Components
PLECS currently does not support code generation for the following components:
- Variable Inductor
- Variable Resistor with Variable Series Inductor
- Variable Resistor with Constant Series Inductor
- Variable Capacitor
- Variable Resistor with Variable Parallel Capacitor
- Variable Resistor with Constant Parallel Capacitor
- Brushless DC Machine
- Switched Reluctance Machine
Code Generation with PLECS Standalone
PLECS Standalone produces C code in an embedded format, generating entry point functions that must be called from a main application. The following functions are generated:
- void model_initialize(double time)
- This function should be called once at the beginning of a simulation to initialize the internal data structures and the start value of the global clock for components that depend on the absolute time.
- void model_step()
- This function should be called at every simulation step to advance the model by one step.
- void model_terminate()
- This function should be called at the end of a simulation to release resources that were acquired at the beginning of or during a simulation.
where the prefix model is replaced by a model-specific string.
Generating Code for a Model
To generate code for a complete model, choose Simulation parameters... from the Simulation menu and select the Code Generation pane. This pane only appears if you have a license for the PLECS Standalone Coder.
For a description of the code generation options see Code Generation Options.
To generate code, click on the button Generate Code. Note that you need to choose the fixed-step Discrete solver on the Solver page. It is not possible to generate code for a model that uses a variable-step solver.
Code generation can also be initiated via the XML-RPC interface using the command
plecs.codegen('model')
plecs.codegen('model', 'outputDir')
If outputDir is provided, the generated files will be placed in this folder instead of the folder that is specified in the model.
Generating Code for a Subsystem
To enable code generation for an individual subsystem in a model, select the subsystem, then choose Execution settings... from the Subsystem submenu of the Edit menu or the context menu. In the Subsystem Settings dialog check the option Enable code generation. This option is only shown if you have a license for the PLECS Standalone Coder. Checking this option implicitly also checks the option Treat as atomic unit and unchecks the option Minimize occurrence of algebraic loops. For more information on these options see Virtual and Atomic Subsystems.
Note It is not possible to generate code for subsystems that have physical terminals.
Checking the option Enable code generation also enables the Code Generation pane. On this pane you can configure and start the code generation.
For a description of the code generation options see Code Generation Options.
To generate code, click on the button Generate Code. Code generation can also be initiated via the XML-RPC interface using the command
plecs.codegen('subsystemPath')
plecs.codegen('subsystemPath', 'outputDir')
If outputDir is provided, the generated files will be placed in this folder instead of the folder that is specified in the subsystem settings.
Simulating a Subsystem in CodeGen Mode
Checking the option Enable code generation also enables the Simulation Mode parameter on the General pane. When this parameter is set to Normal, which is the default, the subsystem is simulated like a normal subsystem. When the parameter is set to CodeGen, the generated code is compiled and linked to PLECS to be executed instead of the subsystem during a simulation.
In connection with the "Traces" feature of the scopes (see Adding Traces), this allows you to easily verify the fidelity of the generated code against a normal simulation.
Code Generation Options
General
Discretization step size This parameter specifies the sample time used to discretize the physical model equations (see Physical Model Discretization). For the code generation of a complete model, the fixed step-size specified in the solver settings is used.
Input/output order These fields allow you to specify the order, in which the input and output signals appear in the generated code. To reorder the items, drag them with the mouse. For the code generation of a complete model, the input and output order is determined by the Port number parameter of the individual Input and Output blocks.
Diagnostics
Integer word size This setting allows you to specify the size of the signed and unsigned integer types (in bits) that are used in the generated code. Integer types are used e.g. to implement tick counters for discrete sample times or to store the conduction states of physical switches. PLECS will issue an error if a required value exceeds the range of a given integer type.
Usage of absolute time This setting allows you to specify the diagnostic action to be taken if PLECS generates code for a component that depends on the absolute time. In order to avoid round-off errors, PLECS generates code to calculate the absolute time using an integer tick counter that is implemented using two integers of the specified word size. If an executable runs for an infinite time, this tick counter will eventually overflow, which may lead to unexpected and often undesired results.
Depending on this setting, PLECS will either ignore this condition of it will issue a warning or error message that indicates the components that use the absolute time.
Parameter Inlining
These two settings specify how PLECS handles tunable parameters in the generated code.
Default behavior This setting specifies whether PLECS inlines the parameter values as numeric constants directly into the code (Inline parameter values) or generates a date structure, from which the values are read (Keep parameters tunable).
Inlining parameter values reduces the code size and increases the execution speed. However, changing an inlined parameter value requires regenerating and recompiling the code. On the other hand, the values of tunable parameters can be changed at execution time without recompiling the code.
Exceptions For the components listed here, the opposite of the default behavior applies. If the default behavior is to inline all parameter values, the components listed here will keep their parameters tunable and vice versa. To add components to this list, simply drag them from the schematic into the list. Use the Remove button to remove components from the list.
Note Physical component parameters that affect the physical model equations, such as resistances or inductances, cannot be kept tunable, because changing such parameters in general requires a recalculation of the complete equation system. You can, however, keep the parameters of source blocks tunable.
Output options
Base name This parameter allows you to specify a custom prefix used to name the generated files and the exported symbols such as the interface functions or the input, output and parameter structs. By default, i.e. if you clear this field, the base name is derived from the model or subsystem name.
Output directory This parameter allows you to specify, where the generated files are stored. This can be an absolute path or a relative path with respect to the location of the model file. The default path is a directory model_codegen next to the model file.
Code Generation with the PLECS Blockset
The PLECS Blockset fully integrates with Simulink Coder (formerly Real-Time Workshop) to generate C code for your simulation model. Whenever you start the build process from within Simulink, PLECS automatically generates the code for a circuit block and inserts it at the appropriate places into the code generated by Simulink Coder.
Note Scopes which are placed in PLECS schematics are not updated during a simulation using code generation. To view the simulation results all scopes must be placed in the Simulink model.
Code Generation Targets
PLECS can generate code for two different targets: the Rapid Simulation target (or RSim target) and the Real-Time target. These two targets are described in detail in the following two sections. The table below highlights the differences between the targets.
RSim Target | Real-Time Target | |
Purpose | Rapid, non-real-time simulations. | Real-time simulations. |
Technique | A compressed description of the circuit schematic is embedded in the code and interpreted at run time. | Signal and state-space equations are inlined as ANSI C code. |
Limitations | none | Limited support for naturally commutated devices and non-linear components. |
Inlining | Parameters may be declared tunable, so that they are evaluated at run time. | All parameters are inlined, i.e. evaluated at compile time and embedded into the generated code. |
Deployment | Requires distribution of the PLECS RSim module. | Generated code does not have external dependencies. |
Licensing | Requires a PLECS license at run time. | Requires a PLECS Blockset Coder license at build time. |
Real-Time Target
The Real-Time Target is selected by default when you generate code using any of the real-time targets of Simulink Coder. Code generation for the Real-Time target requires a separate license for the PLECS Coder for PLECS Blockset.
For a detailed description of the code generation process for physical systems and its current limitations see Code Generation for Physical Systems.
Rapid Simulation Target
The RSim target is selected by default when you run a simulation using Simulink's Rapid Accelerator mode or when you generate an executable using the RSim target or the S-Function target of Simulink Coder. The resulting code links against the RSim module of PLECS, a shared library which part of the standard installation.
Deploying Rapid Simulation Executables
To deploy the generated executable you need to copy the appropriate shared library file onto the target computer. The following table lists the library files for the supported platforms.
Parameter | Description |
Windows 32-bit | plecs/bin/win32/plecsrsim.dll |
Windows 64-bit | plecs/bin/win64/plecsrsim.dll |
Mac Intel 32-bit | plecs/bin/maci/libplecsrsim.dylib |
Mac Intel 64-bit | plecs/bin/maci64/libplecsrsim.dylib |
Linux 32-bit | plecs/bin/glnx86/libplecsrsim.so |
Linux 64-bit | plecs/bin/glnxa64/libplecsrsim.so |
Licensing Protocols for the PLECS RSim Module
The RSim module checks out a PLECS license for the duration of execution. It uses the environment variable PLEXIM_LICENSE_FILE to locate the license file. If the module is unable to check out a PLECS license, it issues an error message and stops the simulation.
Note The PLECS RSim module does not link against MATLAB. Therefore, it cannot accept license files that use MATLAB-based host IDs.
Tunable Circuit Parameters in Rapid Simulations
By default, PLECS evaluates the parameters of all circuit components at compile time and inlines them into the circuit description. However, for certain applications - such as rapid simulations on different parameter sets or parameterized S-Functions - it is desirable that the parameters be evaluated at simulation start instead. This can be achieved by declaring the circuit parameters tunable.
To declare circuit parameters tunable,
- Mask the PLECS Circuit block and define all parameters that you wish to keep tunable as mask variables. Mask variables can either be mask parameters (that appear in the parameter dialog) or variables defined in the mask initialization commands. For more information see Customizing the Circuit Block.
- On the Advanced pane of the PLECS simulation parameters, uncheck the option Inline circuit parameters for RSim target.
- Include the variable names in the list of tunable model parameters. Please see the Simulink Coder User's Guide for details.
Limitations on Tunable Circuit Parameters If you declare circuit parameters tunable, the RSim module uses its own parser to evaluate parameter expressions at simulation start; it currently cannot handle mask initialization commands. You will receive runtime errors if your circuit contains masked subsystems using mask initialization commands, or if a parameter expression contains a MATLAB function call.
Other limitations apply due to the way the Simulink Coder handles tunable parameters:
- Circuit parameters must be double-precision, 2-dimensional, non-sparse arrays.
- The first four characters of the parameter names must be unique.
Code Generation Options
The code generation options are configured on the Advanced pane of the PLECS simulation parameters.
Target This parameter specifies the code generation target (see Code Generation Targets). The default, auto, means that PLECS selects the target depending on the Simulink Coder target.
Inline circuit parameters for RSim target Specifies for the RSim target whether component parameters should be evaluated at compile time and inlined into the code (on) or evaluated at run time (off). See also Tunable Circuit Parameters in Rapid Simulations.