perform a Monte Carlo analysis of a MapleSim model
MonteCarlo(C, params, options)
module; output of GetCompiledProc
set or list of equations; model parameters to vary
(optional) equation(s) of the form option = value; specify options for MonteCarlo
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 = 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 = 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 = positive integer
The number of simulations. Does not include the simulation using nominal values; see include_nominal. The default is 10.
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 = 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.
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.
Assign model the filename of the MapleSim model we want to analyze.
model ≔ cat⁡kernelopts⁡'toolboxdir'=MapleSim,/data/examples/RLCcircuit.msim:
Use MapleSim[LinkModel] to link to the MapleSim model.
A ≔ MapleSim:-LinkModel⁡filename=model:
Inspect the available parameters.
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.
C1 ≔ A:-GetCompiledProc⁡params=L=4,C=5:
Assign a simple procedure that generates a random variable uniformly distributed around a nominal value.
rv ≔ nom,tol→RandomVariable⁡UniformDistribution⁡nom⁢1−tol,nom⁢1+tol:
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.
results ≔ MonteCarlo⁡C1,L=rv⁡4,0.1,C=rv⁡5,0.1,C_opts=tf=1,ds=0.01,include_nominal,num_sims=100:
Verify that the values of the parameters for the first simulation are the nominal values. The subexpression results accesses the first element of the list results. That element is a record. The full expression results:-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.
Display the data for the final two sample times for the first (nominal) simulation. The notation results accesses the first record stored in the list results; results:-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.
The first column is the time, the remaining column(s) corresponds to the output(s) of C1:
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.
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)]):
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).
for i to upperbound(M,1) do
M[i,2] := M[i,2]^2;
Run a MonteCarlo analysis with the squared output.
results2 ≔ MonteCarlo⁡C1,L=rv⁡4,0.1,C=rv⁡5,0.1,C_opts=tf=1,ds=0.01,include_nominal:
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.
results3 ≔ MonteCarlo⁡C1,L=rv⁡4,0.1,C=rv⁡5,0.1,C_opts=tf=1,ds=0.01,include_nominal,ret_record:
Compute the range over which the peak value varied.
Download Help Document