simulation::montecarlo(3tcl)

💖 simulation::montecarlo — bestie's guide to Monte Carlo simulations 💖

okay so this is the manual for simulation::montecarlo, a page from the 3tcl section of the Tcl Simulation Tools docs. yes it's math, yes it's iconic, no you don't need to be scared. let's go 🎀

---

✨ NAME ✨

simulation::montecarlo — Monte Carlo simulations. that's it, that's the vibe. literally just doing a thing a bunch of times with random numbers until the truth falls out. 🦋

---

🌸 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 💅

so the whole Monte Carlo technique is, lowkey, super simple. like it's giving "why didn't I think of that" energy:

• 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 those parameters.
• after a suitable number of such trials, deduce an overall characteristic of the model. ✨

and bestie, the "model" can be literally anything. a network of computers? an ecosystem? anything that can be quantitatively described and has some stochastic element in it. if it's got randomness in it, it's fair game. periodt.

the simulation::montecarlo package gives you a basic framework for exactly that kind of 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}

so what's this example even doing? it's trying to figure out how well the median value and the mean value of a random set of numbers correlate. and honestly? sometimes a median value is just a more robust characteristic than a mean value — especially when you're dealing with a statistical distribution that has "fat" tails. the median said "I got this" and the mean said "…ok". 🫶

---

🔥 PROCEDURES 🔥

the package defines the following auxiliary procedures (auxiliary = the little helpers that do the real work, iykyk):

• ::simulation::montecarlo::getOption keyword — grab the value of an option that was given as part of the singleExperiment command. it's giving "what did I set this to again".
  • string keyword — the given keyword (without a leading minus, bestie, no dashes here)
• ::simulation::montecarlo::hasOption keyword — returns 1 if the option is available, 0 if not. simple yes/no, no notes. ✅
  • string keyword — the given keyword (without leading minus)
• ::simulation::montecarlo::setOption keyword value — set the value of the given option.
  • string keyword — the given keyword (without leading minus)
  • string value — the (new) value for the option
• ::simulation::montecarlo::setTrialResult values — store the results of the trial for later analysis. hoard those numbers, queen. 💾
  • 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 the 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. it's giving "flip it, reverse it" ✨
  • list values — list of lists of values

then there are two main procedures: integral2D and singleExperiment. the headliners. the main characters. 👑

• ::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.

and 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: this is a Required keyword. not optional. do not skip it. 💀

• -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

and literally any other options? you can use them via the getOption procedure in the body. the framework said "bring your own". 🎀

---

🧚 TIPS 🧚

the procedure singleExperiment works by constructing a temporary procedure that does the actual work. it loops for the given number of trials. slay.

and because it constructs a temporary procedure, local variables defined at the start continue to exist in the loop. so yes bestie, your setup variables survive. 🫶

---

⭐ KEYWORDS ⭐

math, montecarlo simulation, stochastic modelling

---

👑 CATEGORY 👑

Mathematics

---

💜 COPYRIGHT 💜

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

---

and that's the whole page, bestie!! 💖 this one's from tcllib, version 0.2, and it's the simulation::montecarlo(3tcl) manual page. go forth and run a hundred trials, you absolute icon. ✨🎀🦋