Compiled Procedure - MapleSim Help

Home : Support : Online Help : MapleSim : MapleSim Application Programming Interface : API Commands : Code Generation Details : MapleSim/CodeGeneration/CompiledProcedure

MapleSim CodeGeneration - Compiled Procedure

details of the compiled module of the MapleSim model

 Calling Sequence A := MapleSim:-LinkModel(...) cProc := A:-GetCompiledProc(...) cProc(opts) cProc:-f(...)

Parameters

 cProc - arbitrary name assigned the module returned by GetCompiledProc f - some export of module cProc (see Exports, below) opts - (optional) equation(s) of the form option = value; specify options for cProc

Description

 • When GetCompiledProc is called with option ccodeonly = false (the default) it returns a module that simulates the linked model using a compiled procedure. Reusing this procedure avoids the overhead of recompiling the model. The module allows changing some simulation settings and some model parameters, however, settings that select a different solver, or parameters that modify the structure of the model, cannot be changed without recompilation.
 • The module, cProc, has exported procedures that return the state of the module and modify its operation. See the Exports section for descriptions of these procedures.
 • The module, cProc, acts like a normal Maple procedure: it accepts arguments and returns a result. The following bullets describes the operation.
 • All arguments to cProc are keyword options; see the Options section for descriptions of the available options.
 • The call cProc(...) returns a Matrix of the simulation data:
 – Each row of the matrix corresponds to one time sample.
 – The first column of the matrix is time. The remaining columns correspond to the signals returned by GetOutputs.
 • If GetCompiledProc was called with the witherror option, cProc(...) returns two elements:
 – The matrix previously described.
 – Any error message generated during the integration. An empty string means no error was generated.
 • The SetObjective export assigns a procedure that modifies what is returned.  See the Exports section.

Options

cProc takes the keyword options listed below. Unless otherwise stated, the default for each option comes from same option used by GetCompiledProc and can be inspected with cProc:-GetSettings() (see below). The availability of some options depends on whether the solver specified for GetCompiledProc was a fixed-step or variable-step solver.

 – fixed-step solvers:  Euler, RK2, RK3, RK4, ImplicitEuler.
 – variable-step solvers:  RKF45, CK45, Rosenbrock.
 • abserr = nonnegative
 Specifies the absolute tolerance for the solver.  See relerr. This is only available with a variable-step solver.
 • ds = numeric
 Specifies the sample time, in seconds. This is the duration between consecutive data steps in the generated matrix. For a variable-step solver the default is (tf-t0)/minpoints; for a fixed-step solver the default is dt.
 • dt = numeric
 Specifies the time step. This is only available with a fixed-step solver. The default comes from the stepsize option to GetCompiledProc.
 • ics = list of numbers or set of equations
 Specifies the initial conditions.
 – A list of numbers must match the order of the system's state variables; see the GetICs export, in the Exports section.
 – A set of equations of the form $x\left(\mathrm{t0}\right)=\mathrm{numeric}$, can specify initial conditions for just the state variables that differ from the default values.
 • params = list of numbers or set of equations
 Specifies the values of parameters.
 – A list of numbers must match the order of the system's parameters; see the GetParameters export, in the Exports section.
 – A set of equations, of the form $k=\mathrm{numeric}$, can specify just the parameters that differ from the default values.
 • relerr = nonnegative
 Specifies the relative tolerance for the solver.  See abserr. This is only available with a variable-step solver.
 • returntype = datapoint, simrec, or list of those
 Specifies what is returned; it can be one of the symbols datapoint or simrec, or a list of those symbols. If a list, then a list of the corresponding values is returned. The default is datapoint.
 – datapoint : return a Matrix of data
 – simrec : return a simulation record. This can only be used if GetCompiledProc was called with the addoutputs option set to "all" or "continuous".
 • settings = list or set of equations
 Specify additional solver settings. The available settings depend on the calling arguments to GetCompiledProc. The following is supported:
 – baumgarte = [alpha,beta]

The alpha and beta values are numeric values. This setting is available if the active model's Baumgarte option was selected under the Settings tab in the MapleSim GUI, or GetCompiledProc was called with baumgarte option set to a non-empty list.

 • t0 = numeric
 Specifies the simulation start time, in seconds.
 • tf = numeric
 Specifies the simulation final time, in seconds.

Exports

 • The following procedures are exports of the module returned by GetCompiledProc. Most take no arguments. They are accessed in the usual way, for example, cProc:-GetICs() or cProc[GetICS](), where cProc is the name to which the module was assigned.

GetICs()

 • Return a list of equations of the initial conditions of the system. Each equation has the form $x\left(\mathrm{t0}\right)=\mathrm{value}$, where $\mathrm{t0}$ is the simulation start time.

GetObjective()

 • Return the objective procedure (see SetObjective, below). If no objective procedure is assigned, the string "NONE" is returned.

GetOutputs()

 • Return a list of the outputs of the system. The list is in the same order as columns two through M of the returned M-column matrix. Each term has the form $x\left(t\right)$.

GetParameters()

 • Return a list of equations of the available parameters of the model. Each equation has the form $\mathrm{name}=\mathrm{value}$.

GetSettings()

 • Return a list of equations of the simulation settings of the system. Each equation has the form $\mathrm{name}=\mathrm{value}$.

 • Assign a procedure that modifies the return value.
 • The argument obj must be a Maple procedure, or other appliable expression.
 • When cProc is called, obj is passed the matrix of data that would otherwise be returned. The expression returned by obj is returned by the call to cProc.
 • If the module was generated with the witherror option to GetCompiledProc, an error string is also returned.
 • The keyword parameter threadsafe is optional. Passing the name threadsafe, or the equation threadsafe = true indicates that the objective procedure is threadsafe and can be safely run in parallel using the Threads package. This is used by the ParameterSweep and MonteCarlo procedures. The default is false.
 • If obj is the string "NONE", the assigned procedure is cleared.

 • Return true if Cproc is assumed threadsafe, false otherwise. Normally this is true, but when the SetObjective procedure has been called to create an objective procedure, the Threadsafe procedure then depends on the value of the threadsafe option passed to SetObjective.

Examples

Linking to a MapleSim model located in the following .msim file:

 > $\mathrm{file}≔\mathrm{cat}\left(\mathrm{kernelopts}\left('\mathrm{toolboxdir}'=\mathrm{MapleSim}\right),"/data/examples/RLCcircuit.msim"\right):$
 > $A≔\mathrm{MapleSim}:-\mathrm{LinkModel}\left(\mathrm{filename}=\mathrm{file}\right):$

Creating a module with the compiled version of the model.

 > $\mathrm{cProc}≔A:-\mathrm{GetCompiledProc}\left(\right):$
 Warning, 'plotevents' option being ignored; number of plot points fixed to 200. Increase number of plot points in the model or use 'ds' option to plot any missing events.

Displaying the module exports:

 > $\mathrm{exports}\left(\mathrm{cProc}\right)$
 ${\mathrm{GetICs}}{,}{\mathrm{GetObjective}}{,}{\mathrm{GetOutputs}}{,}{\mathrm{GetParameters}}{,}{\mathrm{GetSettings}}{,}{\mathrm{ModuleApply}}{,}{\mathrm{SetObjective}}{,}{\mathrm{Threadsafe}}$ (1)

Displaying the output signals stored in the returned matrix.

 > $\mathrm{cProc}:-\mathrm{GetOutputs}\left(\right)$
 $\left[{\mathrm{Vout}}{}\left({t}\right)\right]$ (2)

Executing the compiled procedure:

 > $\mathrm{simData}≔\mathrm{cProc}\left(\right)$
  (3)

Plotting the data. The indices to $\mathrm{simData}$ select the rows and columns to plot. The first index, 1..-1, is a range that selects the rows of interest (all of them). The second index, [1,2], select the first column, $t$, and the second column, $\mathrm{Vout}\left(t\right)$, so that the plot is $\mathrm{Vout}\left(t\right)$ versus $t$. The labels option passed to plot specifies the axes labels.

 > $\mathrm{plot}\left({\mathrm{simData}}_{1..-1,\left[1,2\right]},\mathrm{labels}=\left[t,\mathrm{Vout}\right]\right)$

Selected options

 • Display the initial conditions of the module:
 > $\mathrm{cProc}:-\mathrm{GetICs}\left(\right)$
 $\left[{\mathrm{I1_p_i}}{}\left({0}\right){=}{0.}{,}{\mathrm{SC1_n_v}}{}\left({0}\right){=}{0.}\right]$ (4)
 • Select a simulation time of five seconds (tf=5.0) and set the initial conditions of both state variables to 1.0.
 > $\mathrm{simData}≔\mathrm{cProc}\left(\mathrm{tf}=5.0,\mathrm{ics}=\left[1.0,1.0\right]\right)$
  (5)
 • Because, in this simple example, $\mathrm{simData}$ has just two columns, the output of cProc can be passed directly to plot without specifying the rows or columns as was previously done.
 > $\mathrm{plot}\left(\mathrm{simData}\right)$
 • Set the initial condition of I1_p_i to 2 and leave the initial condition of SC1_n_v at its default (0). Use a sample step of 0.1 seconds (ds=0.1); this returns fewer rows of data than the default, so the plot is somewhat coarser.
 > $\mathrm{plot}\left(\mathrm{cProc}\left(\mathrm{tf}=5.0,\mathrm{ds}=0.1,\mathrm{ics}=\left\{\mathrm{I1_p_i}\left(0\right)=2\right\}\right)\right)$

Parameters

 • The cProc module has no available parameters, as can be seen by callings its GetParameters export:
 > $\mathrm{cProc}:-\mathrm{GetParameters}\left(\right)$
 $\left[\right]$ (6)
 • To determine what model parameters are available, call the GetParameters export of A, the linked model, with the allparams option.
 > $A:-\mathrm{GetParameters}\left(\mathrm{allparams}\right)$
 $\left[{C}{=}{1}{,}{L}{=}{1}{,}{\mathrm{R1_T_ref}}{=}\frac{{6003}}{{20}}{,}{\mathrm{R1_alpha}}{=}{0}{,}{R}{=}{1}{,}{\mathrm{S1_amplitude}}{=}{1}{,}{\mathrm{S1_freqHz}}{=}{1}{,}{\mathrm{S1_offset}}{=}{0}{,}{\mathrm{S1_phase}}{=}{0}\right]$ (7)
 • To generate a new compiled module with accessible parameters, call A's GetCompiledProc export with the params option. Here the parameters C, L, and R are selected and given new values. The new compiled module is assigned to cProc.
 > $\mathrm{cProc}≔A:-\mathrm{GetCompiledProc}\left(\mathrm{params}=\left[C=5,L=2,R=5\right]\right):$
 Warning, 'plotevents' option being ignored; number of plot points fixed to 200. Increase number of plot points in the model or use 'ds' option to plot any missing events.
 • To verify that the new module has the selected parameters, call its GetParameters export. Note that the order of the parameters matches that of the call to GetCompiledProc.
 > $\mathrm{cProc}:-\mathrm{GetParameters}\left(\right)$
 $\left[{C}{=}{5}{,}{L}{=}{2}{,}{R}{=}{5}\right]$ (8)
 • Executing and plotting the new procedure:
 > $\mathrm{plot}\left(\mathrm{cProc}\left(\right)\right)$
 • The params option of cProc can be used to modify parameters without recompiling. Here the R parameter is set to 0.1, while the C and L parameters keep their values, 5 and 2, respectively.
 > $\mathrm{plot}\left(\mathrm{cProc}\left(\mathrm{params}=\left\{R=0.1\right\}\right)\right)$
 • The params option of cProc can also be called without specifying the names of the parameters.  With this call, the values are in a list and the order matches that of the order as returned by GetParameters.
 > $\mathrm{plot}\left(\mathrm{cProc}\left(\mathrm{params}=\left[1,2,3\right]\right)\right)$

Settings

 • Displaying the current simulation settings:
 > $\mathrm{cProc}:-\mathrm{GetSettings}\left(\right)$
 $\left[{\mathrm{t0}}{=}{0}{,}{\mathrm{tf}}{=}{10}{,}{\mathrm{minpoints}}{=}{200}{,}{\mathrm{method}}{=}{"RKF45"}{,}{\mathrm{ds}}{=}\frac{{10}}{{199}}{,}{\mathrm{abserr}}{=}\frac{{1}}{{10000000}}{,}{\mathrm{relerr}}{=}\frac{{1}}{{10000000}}{,}{\mathrm{minstep}}{=}{0}{,}{\mathrm{maxstep}}{=}{0}{,}{\mathrm{ix1relfac}}{=}{1}{,}{\mathrm{ix1errctl}}{=}{\mathrm{false}}{,}{\mathrm{ratehyst}}{=}\frac{{1}}{{10000000000}}{,}{\mathrm{reduceevents}}{=}{\mathrm{false}}{,}{\mathrm{coniter}}{=}{50}{,}{\mathrm{evtiter}}{=}{100}{,}{\mathrm{scalemethod}}{=}{"none"}{,}{\mathrm{numericjacobian}}{=}{\mathrm{false}}{,}{\mathrm{compile}}{=}{\mathrm{false}}{,}{\mathrm{optimize}}{=}{\mathrm{fast}}{,}{\mathrm{diagnosticinfo}}{=}{\mathrm{false}}{,}{\mathrm{plotevents}}{=}{\mathrm{true}}\right]$ (9)

Objective Procedure

 • The SetObjective export of cProc assigns a procedure that modifies the data cProc returns. Here it assigns a procedure that returns the minimum value of Vout(t) (the first output, which is in column 2 of the matrix). The threadsafe option indicates that this procedure can be safely executed in parallel.
 > cProc:-SetObjective(proc(M) min(M[..,2]) end proc, threadsafe):
 • Compute the minimum value.
 > $\mathrm{cProc}\left(\right)$
 ${-0.0580100521407440}$ (10)
 • Pass cProc to ParameterSweep, varying C from 5 to 50, and return a record of the results.
 > $\mathrm{rec}≔\mathrm{MapleSim}:-\mathrm{Analysis}:-\mathrm{ParameterSweep}\left(\mathrm{cProc},\left[C=5..50\right],\mathrm{num_points}=20,\mathrm{ret_record}\right):$
 • Plot the results.
 > $\mathrm{plot}\left({\mathrm{rec}:-\mathrm{values}}_{1},\mathrm{rec}:-\mathrm{data},\mathrm{style}=\mathrm{pointline},\mathrm{labels}=\left["C","min\left(Vout\right)"\right]\right)$
 • Pass the string "NONE" to SetObjective to clear the objective procedure so subsequent calls return the full data set.
 > $\mathrm{cProc}:-\mathrm{SetObjective}\left("NONE"\right):$