simulation::montecarlo(n)

🎀 NAME 🎀

okay so, this page is simulation::montecarlo(n) — yes bestie, the (n) is the Tcl manual-page flex, we love that for her — and it's literally all about Monte Carlo simulations. ✨

---

✨ SYNOPSIS ✨

package require Tcl ?8.5 9?

package require simulation::montecarlo 0.2

package require simulation::random

package require math::statistics

::simulation::montecarlo::getOption keyword

::simulation::montecarlo::hasOption keyword

::simulation::montecarlo::setOption keyword value

::simulation::montecarlo::setTrialResult values

::simulation::montecarlo::setExpResult values

::simulation::montecarlo::getTrialResults

::simulation::montecarlo::getExpResult

::simulation::montecarlo::transposeData values

::simulation::montecarlo::integral2D ...

::simulation::montecarlo::singleExperiment args

---

💅 DESCRIPTION 💅

The whole Monte Carlo simulation thing is genuinely so simple, like it's giving "why is this not obvious":

• generate random values for one or more parameters. 🎲
• evaluate the model of some system you're interested in and record the interesting results for each realisation of these parameters.
• after a suitable number of such trials, deduce an overall characteristic of the model.

You can think of a model of a network of computers, an ecosystem of some kind, or in fact anything that can be quantitatively described and has some stochastic element in it. no cap, that's the whole range. 🌈

The package simulation::montecarlo offers a basic framework for such a modelling technique:

#
# MC experiments:
# Determine the mean and median of a set of points and compare them
#
::simulation::montecarlo::singleExperiment -init {
    package require math::statistics

    set prng [::simulation::random::prng_Normal 0.0 1.0]
} -loop {
    set numbers {}
    for { set i 0 } { $i < [getOption samples] } { incr i } {
        lappend numbers [$prng]
    }
    set mean   [::math::statistics::mean $numbers]
    set median [::math::statistics::median $numbers] ;# ? Exists?
    setTrialResult [list $mean $median]
} -final {
    set result [getTrialResults]
    set means   {}
    set medians {}
    foreach r $result {
        foreach {m M} $r break
        lappend means   $m
        lappend medians $M
    }
    puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]"

} -trials 100 -samples 10 -verbose 1 -columns {Mean Median}

This example attempts to find out how well the median value and the mean value of a random set of numbers correlate. Sometimes a median value is a more robust characteristic than a mean value — especially if you have a statistical distribution with "fat" tails. 👑

---

🦋 PROCEDURES 🦋

The package defines the following auxiliary procedures:

• ::simulation::montecarlo::getOption keyword — Get the value of an option given as part of the singleExperiment command.
  • string keyword — Given keyword (without leading minus)
• ::simulation::montecarlo::hasOption keyword — Returns 1 if the option is available, 0 if not.
  • string keyword — Given keyword (without leading minus)
• ::simulation::montecarlo::setOption keyword value — Set the value of the given option.
  • string keyword — Given keyword (without leading minus)
  • string value — (New) value for the option
• ::simulation::montecarlo::setTrialResult values — Store the results of the trial for later analysis.
  • list values — List of values to be stored
• ::simulation::montecarlo::setExpResult values — Set the results of the entire experiment (typically used in the final phase).
  • list values — List of values to be stored
• ::simulation::montecarlo::getTrialResults — Get the results of all individual trials for analysis (typically used in the final phase or after completion of the command).
• ::simulation::montecarlo::getExpResult — Get the results of the entire experiment (typically used in the final phase or even after completion of the singleExperiment command).
• ::simulation::montecarlo::transposeData values — Interchange columns and rows of a list of lists and return the result.
  • list values — List of lists of values

There are two main procedures: integral2D and singleExperiment. 🫶

• ::simulation::montecarlo::integral2D ... — Integrate a function over a two-dimensional region using a Monte Carlo approach.
  • Arguments PM
• ::simulation::montecarlo::singleExperiment args — Iterate code over a number of trials and store the results. The iteration is gouverned by parameters given via a list of keyword-value pairs.
  • int n — List of keyword-value pairs, all of which are available during the execution via the getOption command.

The singleExperiment command predefines the following options:

• -init code: code to be run at start up
• -loop body: body of code that defines the computation to be run time and again. The code should use setTrialResult to store the results of each trial (typically a list of numbers, but the interpretation is up to the implementation). Note: Required keyword. ⚠️
• -final code: code to be run at the end
• -trials n: number of trials in the experiment (required)
• -reportfile file: opened file to send the output to (default: stdout)
• -verbose: write the intermediate results (1) or not (0) (default: 0)
• -analysis proc: either "none" (no automatic analysis), standard (basic statistics of the trial results and a correlation matrix) or the name of a procedure that will take care of the analysis.
• -columns list: list of column names, useful for verbose output and the analysis

Any other options can be used via the getOption procedure in the body. 💖

---

🌸 TIPS 🌸

The procedure singleExperiment works by constructing a temporary procedure that does the actual work. It loops for the given number of trials. 🔁

As it constructs a temporary procedure, local variables defined at the start continue to exist in the loop. (iconic behaviour, honestly)

---

🍓 KEYWORDS 🍓

math, montecarlo simulation, stochastic modelling

---

💜 CATEGORY 💜

Mathematics

---

👑 COPYRIGHT 👑

Copyright (c) 2008 Arjen Markus <arjenmarkus@users.sourceforge.net>

---

okay that's the whole page bestie, you ate that 🫶 this was simulation::montecarlo(n) from tcllib, version 0.2, and the copyright vibes go all the way back to 2008 — periodt. 💅✨