ParameterSweep
 perform a parameter sweep of a MapleSim model

 Calling Sequence ParameterSweep(C, params, options)

Parameters

 C - module; output of GetCompiledProc params - list of equations specifying parameter values options - (optional) equation(s) of the form option = value; specify options for ParameterSweep

Options

The options parameters are optional parameters of the form option = value, where option is one of the names listed below. These are keyword parameters; the left side of the equation is the keyword and the right side is the value. Each keyword parameter has a default value that is assigned if the parameter is not passed.

C_opts

 • C_opts = set or list of equations
 Options passed to C.  The available options depend on C; see GetCompiledProc for details. The default is an empty set.
 • num_points = positive integer
 The number of points used when converting a range in the params parameter to a list of equally-spaced points. The default is 5.

ret_record

 • ret_record = true or false
 True means return a record with the following fields:
 – data: a list or Array of Matrices
 – params : a list of the parameter names
 – values : a list of lists of the parameter values. The k-th sublist contains the values for the k-th swept parameter.
 – errors : a list of strings of the errors that occurred during the corresponding simulation. This field is present only if the C module was generated with the witherror option to GetCompiledProc.
 False means return a list or Array of Matrices, with a list of error strings if C was built with the witherror option. The default is false.

use_array

 • use_array = true or false
 True means return a multi-dimensional Array of the results; the k-th dimension corresponds to the k-th swept parameter. False means return a list of all the results. The default is false.

 • use_threads = true or false
 True means use the Threads package to compute the results in parallel. The default is true.

Description

 • The ParameterSweep command performs a parameter sweep of a MapleSim model.
 • The C parameter is a module, the output of GetCompiledProc.
 • The params parameter specifies the model parameters that are swept. It is a list of equations.  Each equation has the form
 – name = value: specifies a constant value.
 – name = [value1, value2, ..., valuek]: specifies discrete values.
 – name = value1 .. value2: specifies a range of values. The num_points option is used to convert the range to a list of values.
 • The result is a list of Matrices or, if use_array is true, a multi-dimensional Array of Matrices. Each Matrix is the output of C.
 • If C is built with the witherror option to GetCompiledProc the returned result includes a list of strings of errors that occurred with the corresponding simulation.  An empty string indicates no error occurred.

Examples

Assign model the file name of the MapleSim model we want to analyze.

 > $\mathrm{model}≔\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{model}\right):$

Inspect the available parameters.

 > $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]$ (1)

Use the GetCompiledProc export of A to assign the module that will be passed to ParameterSweep.  Assign nominal values for the three model parameters of interest.

 > $\mathrm{C1}≔A:-\mathrm{GetCompiledProc}\left(\mathrm{params}=\left[R=4,L=4,C=5\right]\right):$

Call ParameterSweep, using C1. Specify that the parameter R will be varied from 3.1 to 5.2, the parameter L will be varied from 1.2 to 3.5, and the parameter C to take values 4, 5, and 6. The number of elements used for R and L is five each, from the default of num_points. The C_opts argument specifies that the simulation should be for 1 second.

 > $\mathrm{results}≔\mathrm{MapleSim}:-\mathrm{Analysis}:-\mathrm{ParameterSweep}\left(\mathrm{C1},\left[R=3.1..5.2,L=1.2..3.5,C=\left[4,5,6\right]\right],\mathrm{C_opts}=\left[\mathrm{tf}=1\right]\right):$

The list results contains 75 elements ($\mathrm{5×5×3}$). Inspect the first element.

 > ${\mathrm{results}}_{1}$
 $\left[\begin{array}{c}{\mathrm{20 x 2}}{\mathrm{Matrix}}\\ {\mathrm{Data Type:}}{\mathrm{float}}{[}{8}{]}\\ {\mathrm{Storage:}}{\mathrm{rectangular}}\\ {\mathrm{Order:}}{\mathrm{C_order}}\end{array}\right]$ (2)

Plot the output versus time for all simulations. To do that, generate a list of two-column matrices with the first column being the time and the second column being the output of interest. The seq command is used to sequentially access the Matrices in results. The expression A[..,[1,2]] corresponds to the appropriate sub-block of a Matrix. In this case, all rows (..) and the first and second columns, ([1,2]). Because each Matrix is already two-columns, we could have used the simpler notation A, however, if the system has more than one output (probe), we would then use the notation A[..,[1,k]], where k is the column of interest.

 > plot([seq(A[..,[1,2]], A=results)]);

Using the use_array option makes it easy to plot a slice of the results.

 > $\mathrm{results}≔\mathrm{MapleSim}:-\mathrm{Analysis}:-\mathrm{ParameterSweep}\left(\mathrm{C1},\left[R=3.1..5.2,L=1.2..3.5,C=\left[4,5,6\right]\right],\mathrm{C_opts}=\left[\mathrm{tf}=1\right],\mathrm{use_array}\right)$
 ${\mathrm{results}}{≔}\left[\begin{array}{c}{\mathrm{1..5 x 1..5 x 1..3}}{\mathrm{Array}}\\ {\mathrm{Data Type:}}{\mathrm{anything}}\\ {\mathrm{Storage:}}{\mathrm{rectangular}}\\ {\mathrm{Order:}}{\mathrm{Fortran_order}}\end{array}\right]$ (3)

Plot all results with the first parameter (R) fixed at its second value and the second parameter (L) fixed at its third value.

 > plot(results[2,3,..]);

Passing the ret_record option to ParameterSweep causes it to return a record which can be used to determine the values of the swept parameters.

 > $\mathrm{results}≔\mathrm{MapleSim}:-\mathrm{Analysis}:-\mathrm{ParameterSweep}\left(\mathrm{C1},\left[R=3.1..5.2,L=1.2..3.5,C=\left[4,5,6\right]\right],\mathrm{C_opts}=\left[\mathrm{tf}=1\right],\mathrm{ret_record}\right):$

Print the discrete values of the swept parameters.

 > for i to nops(results:-params) do     printf("%a = %a\n", results:-params[i], results:-values[i]); end do:
 R = [3.1, 3.625000000, 4.150000000, 4.675000000, 5.200000000] L = [1.2, 1.775000000, 2.350000000, 2.925000000, 3.500000000] C = [4, 5, 6]