```1`simulation::montecarlo(n)    Tcl Simulation Tools    simulation::montecarlo(n)`
2
3
4
5`______________________________________________________________________________`
6
```

## NAME

```8`       simulation::montecarlo - Monte Carlo simulations`
9
```

## SYNOPSIS

```11`       package require Tcl  ?8.4?`
12
13`       package require simulation::montecarlo  0.1`
14
15`       package require simulation::random`
16
17`       package require math::statistics`
18
19`       ::simulation::montecarlo::getOption keyword`
20
21`       ::simulation::montecarlo::hasOption keyword`
22
23`       ::simulation::montecarlo::setOption keyword value`
24
25`       ::simulation::montecarlo::setTrialResult values`
26
27`       ::simulation::montecarlo::setExpResult values`
28
29`       ::simulation::montecarlo::getTrialResults`
30
31`       ::simulation::montecarlo::getExpResult`
32
33`       ::simulation::montecarlo::transposeData values`
34
35`       ::simulation::montecarlo::integral2D ...`
36
37`       ::simulation::montecarlo::singleExperiment args`
38
39`______________________________________________________________________________`
40
```

## DESCRIPTION

```42`       The technique of Monte Carlo simulations is basically simple:`
43
44`       ·      generate random values for one or more parameters.`
45
46`       ·      evaluate  the  model  of  some  system you are interested in and`
47`              record the interesting results for  each  realisation  of  these`
48`              parameters.`
49
50`       ·      after  a suitable number of such trials, deduce an overall char‐`
51`              acteristic of the model.`
52
53`       You can think of a model of a network of  computers,  an  ecosystem  of`
54`       some  kind or in fact anything that can be quantitatively described and`
55`       has some stochastic element in it.`
56
57`       The package simulation::montecarlo offers a basic framework for such  a`
58`       modelling technique:`
59
60
61`              #`
62`              # MC experiments:`
63`              # Determine the mean and median of a set of points and compare them`
64`              #`
65`              ::simulation::montecarlo::singleExperiment -init {`
66`                  package require math::statistics`
67
68`                  set prng [::simulation::random::prng_Normal 0.0 1.0]`
69`              } -loop {`
70`                  set numbers {}`
71`                  for { set i 0 } { \$i < [getOption samples] } { incr i } {`
72`                      lappend numbers [\$prng]`
73`                  }`
74`                  set mean   [::math::statistics::mean \$numbers]`
75`                  set median [::math::statistics::median \$numbers] ;# ? Exists?`
76`                  setTrialResult [list \$mean \$median]`
77`              } -final {`
78`                  set result [getTrialResults]`
79`                  set means   {}`
80`                  set medians {}`
81`                  foreach r \$result {`
82`                      foreach {m M} \$r break`
83`                      lappend means   \$m`
84`                      lappend medians \$M`
85`                  }`
86`                  puts [getOption reportfile] "Correlation: [::math::statistics::corr \$means \$medians]"`
87
88`              } -trials 100 -samples 10 -verbose 1 -columns {Mean Median}`
89
90`       This example attemps to find out how well the median value and the mean`
91`       value of a random set of numbers correlate. Sometimes a median value is`
92`       a more robust characteristic than a mean value - especially if you have`
93`       a statistical distribution with "fat" tails.`
94
```

## PROCEDURES

```96`       The package defines the following auxiliary procedures:`
97
98`       ::simulation::montecarlo::getOption keyword`
99`              Get the value of an option given as part of the  singeExperiment`
100`              command.`
101
102`              string keyword`
103`                     Given keyword (without leading minus)`
104
105
106`       ::simulation::montecarlo::hasOption keyword`
107`              Returns 1 if the option is available, 0 if not.`
108
109`              string keyword`
110`                     Given keyword (without leading minus)`
111
112
113`       ::simulation::montecarlo::setOption keyword value`
114`              Set the value of the given option.`
115
116`              string keyword`
117`                     Given keyword (without leading minus)`
118
119`              string value`
120`                     (New) value for the option`
121
122
123`       ::simulation::montecarlo::setTrialResult values`
124`              Store the results of the trial for later analysis`
125
126`              list values`
127`                     List of values to be stored`
128
129
130`       ::simulation::montecarlo::setExpResult values`
131`              Set  the results of the entire experiment (typically used in the`
132`              final phase).`
133
134`              list values`
135`                     List of values to be stored`
136
137
138`       ::simulation::montecarlo::getTrialResults`
139`              Get the results of all individual trials for analysis (typically`
140`              used in the final phase or after completion of the command).`
141
142
143`       ::simulation::montecarlo::getExpResult`
144`              Get  the results of the entire experiment (typically used in the`
145`              final phase or even after  completion  of  the  singleExperiment`
146`              command).`
147
148
149`       ::simulation::montecarlo::transposeData values`
150`              Interchange  columns  and rows of a list of lists and return the`
151`              result.`
152
153`              list values`
154`                     List of lists of values`
155
156`       There are two main procedures: integral2D and singleExperiment.`
157
158`       ::simulation::montecarlo::integral2D ...`
159`              Integrate a function over a two-dimensional region using a Monte`
160`              Carlo approach.`
161
162`              Arguments PM`
163
164
165`       ::simulation::montecarlo::singleExperiment args`
166`              Iterate  code over a number of trials and store the results. The`
167`              iteration is gouverned by parameters given via a  list  of  key‐`
168`              word-value pairs.`
169
170`              int n  List  of  keyword-value pairs, all of which are available`
171`                     during the execution via the getOption command.`
172
173`       The singleExperiment command predefines the following options:`
174
175`       ·      -init code: code to be run at start up`
176
177`       ·      -loop body: body of code that defines the computation to be  run`
178`              time  and again. The code should use setTrialResult to store the`
179`              results of each trial (typically a  list  of  numbers,  but  the`
180`              interpretation is up to the implementation). Note: Required key‐`
181`              word.`
182
183`       ·      -final code: code to be run at the end`
184
185`       ·      -trials n: number of trials in the experiment (required)`
186
187`       ·      -reportfile file: opened file to send the  output  to  (default:`
188`              stdout)`
189
190`       ·      -verbose:   write  the  intermediate  results  (1)  or  not  (0)`
191`              (default: 0)`
192
193`       ·      -analysis proc: either "none" (no automatic analysis),  standard`
194`              (basic statistics of the trial results and a correlation matrix)`
195`              or the name of a procedure that will take care of the analysis.`
196
197`       ·      -columns list: list of column names, useful for  verbose  output`
198`              and the analysis`
199
200`       Any other options can be used via the getOption procedure in the body.`
201
```

## TIPS

```203`       The procedure singleExperiment works by constructing a temporary proce‐`
204`       dure that does the actual work. It loops for the given number  of  tri‐`
205`       als.`
206
207`       As  it constructs a temporary procedure, local variables defined at the`
208`       start continue to exist in the loop.`
209
```

## KEYWORDS

```211`       math, montecarlo simulation, stochastic modelling`
212
```

## CATEGORY

```214`       Mathematics`
215
```
```217`       Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net>`
218
219
220
221
222`tcllib                                0.1            simulation::montecarlo(n)`
```