MonteCarlo - MapleSim Help

 MonteCarlo
 perform a Monte Carlo analysis of a MapleSim model

 Calling Sequence MonteCarlo(C, params, options)

Parameters

 C - module; output of GetCompiledProc params - set or list of equations; model parameters to vary options - (optional) equation(s) of the form option = value; specify options for MonteCarlo

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.

include_nominal

 • include_nominal = true or false
 True means include, as the first data record, the result of using the nominal values of the random variables. Depending on use_mean, the nominal value of a parameter is either retrieved from the model or computed from the random variable using Statistics[Mean]. The default is false.

num_sims

 • num_sims = positive integer
 The number of simulations. Does not include the simulation using nominal values; see include_nominal. The default is 10.

ret_record

 • ret_record = true or false
 True means return a record with the following fields:
 – data: a list of Matrices, these are the simulation results;
 – params : a list of the parameter names;
 – values : a Matrix of the parameter values. The k-th column contains the values for the k-th name in the params field.
 – 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 of records, one for each simulation. Each record has the following fields:
 – data: the Matrix that is the simulation result; the first column is the time samples, the remaining columns are the values of the outputs of C.
 – params: the set of equations specifying the value of each parameter.
 – errors: a string corresponding to an error that occurred during the simulation; the empty string indicates no error occurred. This field is present only if the C module was generated with the witherror option to GetCompiledProc.
 The default is false.

use_mean

 • use_mean = true or false
 True means use Statistics[Mean] to compute the nominal value of the parameters, otherwise use the values assigned by the model. This option is used with include_nominal. 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 MonteCarlo command performs a Monte Carlo analysis of a MapleSim model. A MapleSim model is repeatedly simulated with selected model parameters varied using specified random variables.
 • The C parameter is a module, the output of GetCompiledProc. See the Advanced Usage section in the Examples for further details.
 • The params parameter specifies the model parameters that are varied. It is either a set or list of equations. The left side of each equation is the name of the parameter, the right side is a random variable.
 • By default, the result is a list of records, one for each simulation. If the include_nominal option is set to true, the first record corresponds to the output of the model with nominal parameter values.  Each record has the following fields:
 – params: the set of equations specifying the value of each parameter;
 – data: the Matrix whose first column is the time samples of a simulation and whose remaining columns are the values of the outputs of C.
 – errors : a string corresponding to an error that occurred during the simulation; the empty string indicates no error occurred. This field is present only if the C module was generated with the witherror option to GetCompiledProc.

Examples

 > $\mathrm{with}\left(\mathrm{MapleSim}:-\mathrm{Analysis}\right):$
 > $\mathrm{with}\left(\mathrm{Statistics}\right):$

Assign model the filename 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 MonteCarlo. Assign nominal values for the two model parameters of interest.

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

Assign a simple procedure that generates a random variable uniformly distributed around a nominal value.

 > $\mathrm{rv}≔\left(\mathrm{nom},\mathrm{tol}\right)↦\mathrm{RandomVariable}\left(\mathrm{UniformDistribution}\left(\mathrm{nom}\cdot \left(1-\mathrm{tol}\right),\mathrm{nom}\cdot \left(\mathrm{tol}+1\right)\right)\right):$

Call MonteCarlo, using C1 and assigning random variables for the L and C model parameters. The C_opts option specifies that the final time of the simulation is 0.5 seconds. The include_nominal option means the first simulation corresponds to the given nominal values of the model parameters. The num_sims option specifies that 100 randomized simulations are made.

 > $\mathrm{results}≔\mathrm{MonteCarlo}\left(\mathrm{C1},\left\{C=\mathrm{rv}\left(5,0.1\right),L=\mathrm{rv}\left(4,0.1\right)\right\},\mathrm{C_opts}=\left\{\mathrm{ds}=0.01,\mathrm{tf}=1\right\},\mathrm{include_nominal},\mathrm{num_sims}=100\right):$

Verify that the values of the parameters for the first simulation are the nominal values. The subexpression results[1] accesses the first element of the list results. That element is a record.  The full expression results[1]:-params specifies the params field of that record.  The params field, as seen below, is a set of equations that express the sampled values of the parameters.

 > $\mathrm{results}\left[1\right]:-\mathrm{params}$
 $\left\{{C}{=}{5.}{,}{L}{=}{4.}\right\}$ (2)

Display the data for the final two sample times for the first (nominal) simulation. The notation results[1] accesses the first record stored in the list results; results[1]:-data references the data field (a Matrix) in that record; the [-2..-1,..] indices extract a sub-block of the Matrix (the last two rows, all columns), see rtable_indexing.

 > results[1]:-data[-2..-1,..];
 $\left[\begin{array}{cc}{0.990000000000001}& {-0.00640891843135199}\\ {1.}& {-0.00647314869227591}\end{array}\right]$ (3)

The first column is the time, the remaining column(s) corresponds to the output(s) of C1:

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

Plot the output versus time for all records. To do that, generate a set of two-column matrices, the first column being the time, the second being the output of interest. The seq command is used to sequentially access the Matrices in results. The expression rec:-data[..,[1,2]] corresponds to the appropriate sub-block of the Matrix in the data field; 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 rec:-data, however, if the system has more than one output (probe), we would then use the notation rec:-data[..,[1,k]], where k is the column of interest.

 > plot({seq(rec:-data[..,[1,2]], rec=results)});

Generate a histogram of the final output point by creating a Vector of the data and passing it to Statistics[Histogram]. The expression rec:-data[-1,2] evaluates to the final row (-1), second column, of the data Matrix of a record in the results list.

 > X := Vector([seq(rec:-data[-1,2], rec=results)]):
 > $\mathrm{Histogram}\left(X\right)$

Assigning an Objective Procedure

 • The module returned by GetCompiledProc has a SetObjective export that uses a provided procedure to manipulate the output. Here we pass it a procedure to square the output (column two of the matrix).
 > C1:-SetObjective( proc(M)                   local i;                       for i to upperbound(M,1) do                           M[i,2] := M[i,2]^2;                       end do;                       M;                   end proc):
 • Run a MonteCarlo analysis with the squared output.
 > $\mathrm{results2}≔\mathrm{MonteCarlo}\left(\mathrm{C1},\left\{C=\mathrm{rv}\left(5,0.1\right),L=\mathrm{rv}\left(4,0.1\right)\right\},\mathrm{C_opts}=\left\{\mathrm{ds}=0.01,\mathrm{tf}=1\right\},\mathrm{include_nominal}\right):$
 > plot({seq(rec:-data[..,[1,2]], rec=results2)});
 • The objective procedure is not limited to modifying the matrix of simulation data, it can also compute a value from the matrix and return that. Here we assign a procedure that returns the peak of the squared result.
 > C1:-SetObjective(proc(M) max(map(x->x^2, M[..,2])) end proc):
 • Run a MonteCarlo analysis; use the ret_record option to return a record.
 > $\mathrm{results3}≔\mathrm{MonteCarlo}\left(\mathrm{C1},\left\{C=\mathrm{rv}\left(5,0.1\right),L=\mathrm{rv}\left(4,0.1\right)\right\},\mathrm{C_opts}=\left\{\mathrm{ds}=0.01,\mathrm{tf}=1\right\},\mathrm{include_nominal},\mathrm{ret_record}\right):$
 • Compute the range over which the peak value varied.
 > $\mathrm{evalf}\left[2\right]\left(\left(\mathrm{min}..\mathrm{max}\right)\left(\mathrm{results3}:-\mathrm{data}\right)\right)$
 ${0.0031}{..}{0.0042}$ (5)