
Calling Sequence


A := MapleSim:LinkModel();
A:GetCompiledProc(options)


Parameters


options



(optional) equation(s) of the form name = value





Returns


•

If ccodeonly = false then

–

Module : an executable Maple module, containing a simulation behavior of linked MapleSim model

•

If ccodeonly = true then

–

string : the filename of the generated C procedure equivalent to the compiled code version



Options


•

ccodeonly: true or false


Specifies whether to only generate C code (no compilation). This option can only be used with a fixedstep solver. The resulting C code can be used to integrate a MapleSim system using a specified solver. Default is false.

•

checklibrary : true or false


Used with the library option. False means that the current conditions (model, compiler setting etc.) are not checked against those used for the stored library archive. Avoiding the check saves reflattening the model. The default is true.

•

library : string; Maple archive


Specifies a Maple library archive to reuse a module. The string must have extension mla.

–

If the library exists and contains a previously stored module created with the same conditions as the current call, that module is returned. Otherwise the module is computed, saved to the library, and returned. If checklibrary is false, a stored library is used without checking whether it matches the current conditions.

–

If the string begins with attach://, the remainder is the library name and the resulting archive is attached to the MapleSim file. This cannot be used when LinkModel attached to a Modelica file.

–

The default is the empty string, which prevents using and creating a library archive.


Parameter and Initialization Options


•

ics : set of equations of the form x(t) = numeric


Specifies the initial conditions for system states, ix1 variables, and inputs. The default value is the linked model A subsystem's initial conditions. Note that any initial conditions in the linked model that are specified as functions of parameters or are set to an initial value based on an initial equation in the linked model (for example, the initial length of a pendulum string being computed from the initial position) cannot be set in this way. In these cases, the initial conditions will instead be computed.


Specifies the system's outputs. The default value is the linked model A subsystem's outputs.

•

params : list of equations


Specifies the system's parameters. The default value is the linked model A subsystem's parameters.


Specifies whether the parameters and initial conditions are entered as the original model names or the substituted names. Default is false.



Simulation Options


The default values for the simulation options below are retrieved from the linked MapleSim model. Note that if the compile option from the linked MapleSim model is false, it is ignored. If the linking is done through a Modelica file, the defaults are as specified by MapleSim[LinkModel][GetSettings].

The tf option specifies the simulation end time in seconds.

•

solver : {"Euler", "RK2", "RK3", "RK4", "ImplicitEuler", "RKF45", "CK45", "Rosenbrock"}


Specifies which solver to include in the compiled procedure. If either "RKF45", "CK45", or "Rosenbrock" is specified, then the variable step compiled procedure is returned. If a variable step solver is specified, the ccodeonly option cannot be used.


The t0 option specifies the simulation start time in seconds. You can specify a value for this option only when a fixedstep method is used. For variablestep solvers, specify the start time in the Advanced Simulation section under the Simulation Settings tab in the MapleSim GUI.


Specifies derivative (alpha) and proportional (beta) gains for Baumgarte constraint stabilization in the form baumgarte=[alpha,beta]. If this parameter is set to the empty list, the Baumgarte constraint stabilization is not carried out.

•

numericjacobian : true or false


Specifies whether the system Jacobian is formulated numerically for implicit integration solver. This option is only used with stiff solvers (Rosenbrock or ImplicitEuler).


Indicates the maximum number of constraint projection iterations. If coniter is set to 0, constraint projections are not carried out.


Indicates the error tolerance at which constraints are satisfied and projection iterations are terminated.

•

evtiter: positive integer


Specifies maximum number of event iterations.

•

scalemethod : one of the following: "none","minimum","maximum","geometric"


Method of variable scaling applied to the system.


Initialization Options


•

initconiter : nonnegative


Indicates the maximum number of constraint projection iterations during initialization. The default value is 100.


Indicates the error tolerance for constraint projection during initialization. The default value is 1e10.


Indicates the maximum number of convergence iterations during initialization. The default value is 50.


Indicates the convergence tolerance for the initialization problem. The default value is 1e8.

•

initweight : nonnegative


Specifies the weight value used to mark fixed initial values for the weighted constraint projection computation within initialization. The default value is 20.



Code Generation Options


Note: These options can only be used with fixedstep solvers and when the ccodeonly option is set to true.

Specifies the name of the compiled procedure. The default value is "MsimModel".


Specifies the directory used to store the generated C code. Default is a writable temporary directory or the current directory if no writable temporary directory exists.


Specifies the system's inputs. The default value is the linked model A subsystem's inputs.


Specifies sample inputs for generated only C code (when ccodeonly = true). This option MUST be provided when ccodeonly = true. Default is a list [0.0, 0.0, ... , 0.0] of length N, where N is the number of subsystem's inputs.

•

addoutputs : one of the following: "none", "states", "statevals", "continuous", "all"


Specifies which additional variables need to be included in outputs. Valid settings for this option are:

–

"none": add no additional output variables

–

"states": add all of the state variables

–

"statevals": add all of the state variables except for the derivative variables

–

"continuous": add all of the state variables and the index1 variables

–

"all": add all of the internal variables (state variables, index1 variables, and discrete variables).

•

optimize: one of the following: false, "subexpronly", "fast", true


Specifies level of code optimization. Valid settings for this option are:

–

"subexpronly": perform common subexpression optimization only

–

"fast": perform only fast optimizations (subexpression elimination, power, and partial product optimization)

–

true: perform a full optimization.


Specifies a list of preferred variables that should remain part of the core equation system. The equation simplification algorithm will avoid isolating for these variables when possible. The list is ordered in decreasing preference: the variables appearing on the left have stronger preference than the ones on the right. The default is an empty list.

•

singleprec = true or false


Specifies whether the code should be generated to work with single precision floating point. Note that when this is set, all tolerances are loosened to work with the lower precision, which can result in accuracy degradation when compared with double precision. Default is false.



Variablestep Solver Specific Options



The limit on the absolute error tolerance for a successful integration step if you are using an adaptive solver to run the simulation.


The limit on the relative error tolerance for a successful integration step if you are using an adaptive solver to run the simulation.


The lower limit on the step size used for the integration. If the solver is unable to achieve the requested error tolerance with this minimum then it will take the step anyway, so this option should be used with caution. The default value for this option is 0.


The upper limit on the step size used for the integration. This option is most useful for simpler models, as it limits the growth of the step size when the error is low. The default value for this option is 0 (disabled).


Controls the relative error on algebraic variables compared to differential variables.

•

ix1errctl : true or false


Turns on error control for all algebraic variables if true. By default this is false, and error control is only enabled for algebraic variables that directly influence probes or events, or are outputs of black box functions.


Specifies the width of the event hysteresis for all event triggers at the start of the simulation.

•

reduceevents : true or false


If true, heuristics are used to reduce the number of events encountered during the simulation.

•

plotevents : true or false or nonnegative integer


This option is used to determine the number of event points stored for plotting. If a fixedstep solver is used and plotevents is set to true, then the before and after value is stored for each simulation step. If false, then the output contains only the simulation step value. Setting this option to a nonnegative integer has the same effect as true when a fixedstep solver is used. For variable step solvers, if plotevents is set to true then the maximum number of events plotted is equal to half the number of plot points. If false then no event points are stored in the plot. If a nonnegative integer is specified then it will be used to determine the maximum number of event points stored in the plot result (with 0 being equivalent to false).

•

maxfun : positive integer


Maximum number of righthandside evaluations to perform during integration. In the event that the integration cannot be completed within the limit the integration will halt with an error. The default for this value is 0 (disabled).



Output Options



The ds option specifies the sampling time in seconds. For variablestep solvers, the default value is set to (tft0)/minpoints, where minpoints is a MapleSim model setting described in MapleSim[LinkModel][GetSettings]; for fixedstep solvers, the default is set to the stepsize. If the provided sampling time ds does not divide the simulation duration time evenly, the last point of the simulation result will be lost. This option only has an effect when ccodeonly = false and it is ignored otherwise.

•

diagnosticinfo : true or false


If true, four additional outputs will be added, LogStepSize, EventIterations, ConstraintIterations and ConstraintResidual which act as probes to report these quantities. The EventIterations output will only have a nonzero value if the model has events, and the ConstraintIterations and ConstraintResidual outputs will only have nonzero values if the model has constraints. Note that if the model has constraints, but constraint projection is turned off, this option will add expense to the integration. By default, this value is false.

•

witherror : true or false


If true, the return from the compiled procedure will always be a sequence of two elements, the computed data and the error string. If no error occurred during the simulation, the second return value will be the empty string "". By default, this value is false, and only the computed data will be returned.

•

withinsight : true or false


If true, in addition to returning a Matrix of data, each invocation of the returned procedure will pass the simulation data to a current running version of MapleSim Insight (launching it if no instance is running  this may take some time). The MSIM_INSIGHT operating system environment variable must point to the insight binary for this option to work. If MSIM_INSIGHT is not set, the compiled procedure behaves as though this option was specified as false. By default, this value is false and the computed data will only be returned.



•

Note that simulations in MapleSim and simulations through the GetCompiledProc procedure may have different results. This is prevalent in cases of large changes to parameter values. The reasoning is that the module produced by GetCompiledProc is optimal for the default parameter values and given initial conditions. This differs from a MapleSim which starts with specified parameters and initial conditions and finds an optimal solution from there.

•

The A := MapleSim:LinkModel() statement needs to be run prior to successfully using any of the ModelObject A's export functions.



