1 Getting Started - MapleSim Connector Help

1 Getting Started

1.1 Setting Up the MapleSim Connector

To generate an S-function block and have Maple communicate with MATLAB® you have to establish a connection with MATLAB®.

To set up the MapleSim Connector

 1 Start Maple.
 2 Enter the following command to establish a connection with MATLAB®.

 3 A MATLAB® command window opens and the connection is established. If the window does not open, follow the instructions in the Matlab/setup help page in the Maple help system to configure the connection.

 4 Next, set up the MATLAB® mex compiler. Go to the MATLAB® command window and enter the following setup command:

 5 Follow the instructions to choose a local C compiler that supports ANSI (American National Standards Institute) C code. See the MapleSimConnector,setup help page for more information.

 1.2 Getting Help In Maple, enter ?MapleSimConnector at a prompt in a worksheet.

1.3 Using the Simulink® Component Block Generation Template

The MapleSim Connector provides a Simulink® Component Block Generation template in the form of a Maple worksheet for manipulating and exporting MapleSim subsystems. This template contains pre-built embedded components that allow you to generate S-function or C code from a MapleSim subsystem, export the subsystem as a Simulink® block, and save the source code.

Using this template, you can define inputs and outputs for the system, set the level of code optimization, choose the format of the resulting S-function, and generate the source code, library code, block script, or Simulink® block. You can use any Maple commands to perform task analysis, assign model equations to a variable, group inputs and outputs to a single vector and define additional input and output ports for variables.

Note:  Code generation now handles all systems modeled in MapleSim, including hybrid systems with defined signal input (RealInput) and signal output (RealOutput) ports.

The S-Function Block Generation consists of the following steps:

 • Subsystem Preparation
 • Subsystem Selection
 • Port and Parameter Management
 • S-Function Options
 • Generate S-Function
 • View S-Function
 Subsystem Preparation Convert your model or part of your model into a subsystem.  This identifies the set of modeling components that you want to export as a block component.  Since Simulink® only supports data signals, properties on acausal connectors such as mechanical flanges and electrical pins, must be converted to signals using the appropriate ports.   To connect a subsystem to modeling components outside of its boundary, you add subsystem ports.  A subsystem port is an extension of a component port in your subsystem.  The resulting signals can then be directed as inputs and outputs for MapleSim™ Connector Template.   Note:  For connectors you must use signal components, since acausal connectors can not be converted to a signal.   By creating a subsystem you not only improve the visual layout of a system in Model Workspace but also prepare the model for export.  The following examples in this section show you how to group all of the components into a subsystem.
 Subsystem Selection You can select which subsystems from your model you want to export to a Simulink® block.  After a subsystem is selected, click Load Selected Subsystem.  All defined input and output ports are loaded.

S-Function Options

These settings specify the advanced options for the code generation process.

 Table Handling Options Select Export lookup tables as external .CSV files to generate a comma-separated values (CSV) file with the values for your lookup tables. You can then change the values in your lookup table without having to recompile your code. The updated values are read at run-time.
 Optimization Options Set the level of code optimization to specify whether equations are left in their implicit form or converted to an ordinary differential equation (ODE) system during the code generation process.  This option specifies the degree of simplification applied to the model equations during the code generation process and eliminates redundant variables and equations in the system. Select one of the following options: None (0): no optimization is performed; the default equations will be used in the generated code. Partial (1, 2): removes redundant equations from the system. Full  (3): performs index reduction to reduce the system to an ODE system or a differential algebraic equation (DAE) system of index 1, and removes redundant equations.
 Constraint Handling Options The Constraint Handling Options area specifies whether the constraints are satisfied in a DAE system by using constraint projection in the generated Simulink® block. Use this option to improve the accuracy of a DAE system that has constraints. If the constraint is not satisfied, the system result may deviate from the actual solution and could lead to an increase in error at an exponential rate. Set the Maximum number of projection iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution. Set the Error tolerance to specify the desirable error tolerance to achieve after the projection. Select Apply projection during event iterations to interpolate iterations to obtain a more accurate solution. Constraint projection is performed using the constraint projection routine in the External Model Interface as described on The MathWorks™ web site to control the drift in the result of the DAE system.
 Event Handling Options The Event Handling Options area specifies whether the events are satisfied in a DAE system by using event projection in the generated Simulink® block.  Use this option to improve the accuracy of a DAE system with events. If the constraint is not satisfied, the system result may deviate from the actual solution and could lead to an increase in error at an exponential rate. Set the Maximum number of event iterations to specify the maximum number of times that a projection is permitted to iterate to obtain a more accurate solution. Set the Width of event hysterias band to specify the desirable error tolerance to achieve after the projection. Select Optimize for use with fixed-step integrators to optimize the event iterations as a function of hysteresis bandwidth.
 Baumgarte Constraint Stabilization The Baumgarte constraint stabilization method stabilizes the position constraint equations, by combining the position, velocity, and acceleration constraints into a single expression. By integrating the linear equation in terms of the acceleration, the Baumgarte parameters, alpha and beta, act to stabilize the constraints at the position level. Apply Baumgarte constraint stabilization: Apply the Baumgarte constraint stabilization. Export Baumgarte parameters: Add Alpha and Beta as parameters in the generated code. Alpha: Set the derivative gain for Baumgarte constraint stabilization. Beta: Set the proportional gain for Baumgarte constraint stabilization.

Fixed-Step Integrator Options

Select Optimize for use with fixed-step integrators to optimize events handling and relax the inconsistencies detection tolerance.
Select Add Failure Handling to reinitialize the model on failure, and then select one of the following re-initialization options:

 • Re-initialize to initial point: Reinitialize the model to the initial values when a failure happens.
 • Hold to previous successful step: Reinitialize the model to the values at the end of the last successful step.

Note: Failure handling is only available for Simulink® fixed-step integration.

Discretization

Select Export as a discrete model (no continuous states) to apply discretization to your model. When selected, you can select a solver type from one of the following options:

 • Euler: forward Euler method
 • RK2: second-order Runge-Kutta method
 • RK3: third-order Runge-Kutta method
 • RK4: fourth-order Runge-Kutta method
 • Implicit Euler: implicit Euler method

In this section, you can also set the Discrete Timestep (in seconds) for the discretization.

Select Allow intermediate steps between fixed steps if you want to trigger events inside a fixed step (instead of at the end of the fixed step). Your solver must be either Euler or Implicit Euler. After selecting this option, enter the following settings:

 • Number of intermediate steps: The maximum number of intermediate steps you want to take inside the fixed step.
 • Tolerance: The proportion of the current step size that the solver is allowed to overshoot so as to catch more than one close-firing event. Generally, enter a smaller tolerance for models that are fairly linear between steps and a larger tolerance for solutions that are far from linear.

 Diagnostic Options Select Add outputs for log(stepsize), event and constraint iterations, and constraint residual to provide run-time diagnostics in the generated Simulink® block. This adds four outputs to the bottom of the Simulink® block: LogStepSize(t), EventIterations(t), ConstraintIterations(t), and ConstraintResidual(t).
 Generate S-Function Provide a name and specify the location for the generated file. To generate an S-Function block without a Simulink® connection, click Generate S-Function (no Compile). To generate an S-Function block, click Generate and Compile S-Function. Note: If your model contains an external library, then you must add the directory that contains the external library to your search path. See Adding External Libraries to Your Search Path for instructions on how to do this.

View S-Function

After you generate the S-Function code and create the block a MATLAB® command window opens and the block with any of the following specified parameters is generated in Simulink®:

 • Block Generation Script
 • C Code
 • Parameter Script

Toolbox examples are available in the MapleSim Connector Examples palette in MapleSim.

To view an example:

 • Expand the MapleSim Connector Examples palette on the left side of the MapleSim window, and click the entry for the model that you want to view.

Some models include additional documents, such as templates that display model equations or define custom components.  If present, you can find the attachments under the Project tab by expanding the Attachments palette and then expanding Documents. To open a document, right-click its entry and select View.

1.5 Example: RLC Circuit Model

In this example, you will generate a Simulink® block from an RLC circuit model that was created in MapleSim.

Note:  Before starting this tutorial, you must set up MATLAB® and the mex compiler in order to have the template appear in the list.  For more information, see the MapleSimConnector,setup help page for more information.

To generate an S-function block

 1 In the MapleSim Connector Examples palette, select the RLC Parallel Circuit example.
 2 Click Templates ( ) in the Main Toolbar.
 3 From the list, select Simulink® Component Block Generation.
 4 In the Attachment field, enter RLC Circuit as the worksheet name and click Create Attachment. Your MapleSim model opens in the Simulink® Component Block Generation template in Maple.
 5 Using the navigation controls above the model, select Main > RLC.  The RLC subsystem appears in the workspace.
 6 Click Load Selected Subsystem.  All of the template fields are populated with information specific to the RLC subsystem.

Note:  By default, all parameters in the model are kept as configurable parameters.

 7 In the S-Function Options section, set the Level of code optimization option to Full (3).
 8 In the Generate C Code section, specify the location of generated files.
 9 Click Generate and Compile S-Function to generate the S-function code and create the block.

Note: Generating a block may require a few minutes.

A MATLAB® command window opens and the block with the specified parameters is generated in Simulink®.

Double-clicking the block opens the mask that contains the symbolic parameters from the original model. This block can now be connected with any compatible Simulink® blocks.

1.6 Preparing a Model for Export

In this example, you will perform the steps required to prepare a slider-crank mechanism model and export it as an S-function block:

1. Convert the slider-crank mechanism model to a subsystem.

2. Define subsystem inputs and outputs.

3. Define and assign subsystem parameters.

4. Export the model using the Simulink® Component Block Generation template.

5. Implement the S-function block in Simulink®.

Note:  The following tutorial will take you through these steps in detail. Before starting this tutorial, you must set up MATLAB® and the mex compiler. For more information, see the MapleSimConnector,setup help page for more information.

To open the slider-crank mechanism example

 1 In MapleSim, under the Libraries tab, browse to the Examples > User's Guide Examples menu.
 2 Open the  Planar Slider-Crank Mechanism example in Chapter 6. The example appears in the Model Workspace.

 Converting the Model to a Subsystem By converting your entire model or part of your model into a subsystem, you identify which parts of the model that you want to export. In this example, you will prepare the system for export by grouping all of the components into a subsystem. To convert the model to a subsystem 1. Using the selection tool ( ) located above the Model Workspace, draw a box around all of the components in the model. 2. From the Edit menu, select Create Subsystem.  The Create Subsystem dialog box appears. 3. Enter SliderCrank as the subsystem name. 4. Click OK. A SliderCrank subsystem block appears in the Model Workspace.

Defining Subsystem Inputs and Outputs

MapleSim uses a topological representation to connect interrelated components without having to consider how signals flow between them, whereas traditional signal-flow modeling tools require explicitly defined system inputs and outputs.  Since Simulink® only supports data signals, properties on acausal ports, such as mechanical flanges and electrical pins, must be converted to signals using the appropriate components. The resulting signals are directed as inputs and outputs for the subsystem in MapleSim and for the S-function block.

Note: Currently, code generation is limited to subsystems with defined signal input (RealInput) and signal output (RealOutput) ports.

In this example, you will convert the displacements of the slider and the joint between the crank and connecting rod to output signals. The input signal needs to be converted to a torque that is applied to the revolute joint that represents the crank shaft.

To convert the system signals

 1 Double-click the subsystem block to view its contents. The broken line surrounding the components indicates the subsystem boundary, which can be resized by clicking and dragging its sizing handles.
 2 Delete the probes that are attached to the model.
 3 On the left side of the MapleSim window, expand the Multibody palette and then expand the Sensors submenu.
 4 Drag the Absolute Translation component to the Model Workspace and place it below the Prismatic Joint component.

 5 Right-click (Control-click for Macintosh®) the Absolute Translation component and select Rotate Counterclockwise.
 6 From the Signal Blocks > Routing > Demultiplexers menu, drag a Real Demultiplexer component to the Model Workspace and place it to the right of the Absolute Translation component.

 7 To connect the Absolute Translation component to the model, click the frame_b connector. The frame is highlighted in green when you hover your pointer over it.

 8 Draw a vertical line and click the connection line directly above the component. The sensor is connected to the rest of the diagram.

 9 In the same way, connect the r output port ($\mathrm{TMOutputP}$) of the Absolute Translation component to the demultiplexer Real input signal (u) port. This is the displacement signal from the sensor in x, y, and z coordinates. Since the slider only moves along the x axis, the first coordinate needs to be an output signal.

 10 Hover your pointer over the first demultiplexer port and click your mouse button once.

 11 Drag your pointer to the subsystem boundary and then click the boundary once. A real output port is added to your subsystem.

 12 Add another Absolute Translation component above the Connecting Rod subsystem.
 13 Right-click (Control-click for Macintosh) the Absolute Translation component and select Flip Vertical. Right-click the Absolute Translation component again and select Rotate Clockwise.
 14 Add a Real Demultiplexer component to the right of the sensor and connect the components as shown below.

Note: Since the crank is moving in the x-y plane, you only need to output the first two signals.

You will now add a real input port to your subsystem to control the torque on the crank shaft.

 15 From the 1-D Mechanical > Rotational > Torque Drivers menu, add a Torque component to the Model Workspace and place it above the Fixed Frame component.
 16 Connect the white flange of the Torque component to the white flange of the leftmost Revolute Joint.

 17 Click the input port of the Torque component, then drag your pointer to the subsystem boundary and click the boundary once. A real input port is added to your subsystem.

The complete subsystem appears below.

 18 Click Main above the Model Workspace to browse to the top level of the model.
 19 From the Signal Blocks > Sources > Real menu, drag a Constant source into the Model Workspace and connect its output port to the input port of the SliderCrank subsystem as shown below.

 20 Click Attach probe ( ) above the Model Workspace and then click the top output port of the SliderCrank subsystem.
 21 Drag the probe to an empty location on the Model Workspace, and then click the workspace to position the probe.
 22 In the same way, add probes to the other SliderCrank output ports as shown below.

Define and Assign Subsystem Parameters

You can define custom parameters that can be used in expressions in your model to edit values more easily. To do so, you define a parameter with a numeric value in the parameter editor. You can then assign that parameter as a variable to the parameters of other components; those individual components will then inherit the numeric value of the parameter defined in the parameter editor. By using this approach, you only need to change the value in the parameter editor to change the parameter values for multiple components.

To edit parameters

 1 Double-click on the SliderCrank subsystem, and then click Parameters ( ) above the Model Workspace. The parameter editor appears.
 2 In the first Name field, enter CrankL and press Enter.
 3 Enter 1 in the Default Value field of CrankL, and then enter  Length of the crank in the Description field.
 4 In the second row of the table, enter ConRodL in the Name field and press Enter.
 5 Enter 2 in the Default Value field of ConRodL, and then enter Length of the connecting rod  in the Description field.

 6 Click Diagram ( ) to switch to the diagram view. The parameters are defined in the Parameters pane.

 7 In the Model Workspace, select the Crank subsystem.
 8 In the Parameters pane, change the length value (L) to CrankL. The Crank subsystem now inherits the numeric value of CrankL that you defined.

 9 Select the ConnectingRod subsystem and change its length value to ConRodL.
 10 Click Main in the Navigation Toolbar above the workspace to navigate to the top level of the model.

You will include these parameter values in the model that you export. You are now ready to convert your model to an S-function block.

After preparing the model, you can use the Simulink® Component Block Generation template to set export options and convert the model to an S-function block.

 1 Click Templates ( ) in the Main Toolbar.
 2 From the list, select Simulink® Component Block Generation.
 3 In the Attachments field, enter Slider Crank S-Function as the worksheet name and click Create Attachment. The slider-crank subsystem opens in the Simulink® Component Block Generation template in Maple.
 4 From the drop-down menu above the model, select SliderCrank.
 5 In the Step 1: Subsystem Selection section of the template, click Load Selected Subsystem.  All of the template fields are populated with information specific to the subsystem.
 6 In the Step 2: Inputs/Outputs and Parameter Management section, browse to the Parameters table, and then select the ConRodL parameter that you defined in the previous section.

Note: The Export option for this parameter is selected by default ("X"). Also, by default, all input ports, output ports, and parameters in the model are kept as configurable parameters.

 7 Click Generate and Compile S-Function to generate the S-function code and create the block.  A MATLAB® command window opens and the block with the specified parameters is generated in Simulink®.

Note: Generating a block may require a few minutes.

Implement the S-Function Block in Simulink®

In Simulink®, you can connect your block to other compatible blocks, specify initial conditions, and edit the component parameter values.

To implement the S-Function block

 1 In Simulink®, double-click the block. The Parameter Mask dialog box appears.  This dialog box displays the ConRodL and CrankL parameters that you defined in MapleSim as a vector. The text in the dialog describes each parameter in the order they appear in the vector. Initial conditions can also be changed in this dialog box.

 2 Click Help. This window provides a model description and information about the inputs, outputs, parameters, and initial conditions.
 3 All inputs and outputs are implemented as vector signals. To access individual signals in Simulink®, use a Mux block for inputs and a Demux block for outputs.