montecarlo(n)

1simulation::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 pa‐
48              rameters.
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  in‐
180              terpretation  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) (de‐
191              fault: 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

COPYRIGHT

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