math::probopt(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 math::probopt — Probabilistic Optimisation Methods 💖

okay bestie, so this is math::probopt(n) from the Tcl Math Library, and it's literally the package that does optimisation the ✨random✨ way. buckle up.

🌸 NAME 🌸

math::probopt — probabilistic optimisation methods. yes. it's giving "let the chaos find the minimum" energy and honestly? iconic.

✨ SYNOPSIS ✨

first off, you need the right stuff installed, no skipping:

package require Tcl 8.6 9

package require TclOO

package require math::probopt 1.1

and then the actual algorithms, all vibing with the same shape:

::math::probopt::pso function bounds args

::math::probopt::sce function bounds args

::math::probopt::diffev function bounds args

::math::probopt::lipoMax function bounds args

::math::probopt::adaLipoMax function bounds args

🦋 DESCRIPTION 🦋

so the whole point of math::probopt is to hand you a bunch of optimisation algorithms that are built on probabilistic techniques. which means — and this is important, bestie — the results can be different every single run. not a bug. that's the whole vibe. 🔥

these algorithms are all well-known, well-documented, and the people who love them swear they're efficient and reliable. lowkey they're not wrong.

and because most of these algorithms have one or more tunable parameters (or even whole variations on how they run), every interface takes options so you can set those parameters or pick your flavour. the options come as key-value pairs, like -iterations 100. cute, right?

ngl, this manual does not give you recommendations on which algorithm to use, and it doesn't really give you guidelines for the parameters either. for that, go read online articles about the specific algorithm you're eyeing. this page is just the mechanics, bestie. 💅

a couple of notes though, and these actually matter:

  • with the exception of LIPO, all the algorithms can handle irregular (non-smooth) and even discontinuous functions. slay.
  • the results depend on the random number seeding, and they're probably not going to be super accurate — especially if the function varies slowly in the vicinity of the optimum. but here's the thing: they give you a really good starting point for a deterministic algorithm. so they ate, just not the whole meal. 🍓

here's the full collection:

  • PSO — particle swarm optimisation
  • SCE — shuffled complexes evolution
  • DE — differential evolution
  • LIPO — Lipschitz optimisation

and the best part? every procedure has the same uniform interface:

set result [::math::probopt::algorithm function bounds args]

🎀 the arguments, explained 🎀

  • the argument function is the name of the procedure that evaluates your function. its interface looks like this:
set value [function coords]

where coords is a list of coordinates at which to evaluate the function. it's supposed to return the function value. that's it, that's the job.

  • the argument bounds is a list of pairs of minimum and maximum for each coordinate. this list is quietly deciding the dimension of the coordinate space where the optimum is hiding — for instance, for a function like x**2 + (y-1)**4, you might specify the bounds as {{-1 1} {-1 1}}, i.e. two pairs for the two coordinates. see how that works? ✨
  • the rest (args) is zero or more key-value pairs to specify the options. which options belong to which algorithm is documented below, don't worry.

👑 what you get back 👑

the result of all these optimisation procedures is a dictionary, and it contains at least these elements:

  • optimum-coordinates — a list with the coordinates of the optimum that was found.
  • optimum-value — the function value at those coordinates.
  • evaluations — the number of function evaluations.
  • best-values — a list of successive best values, collected as part of the iterations.

🌈 DETAILS ON THE ALGORITHMS 🌈

here's the lineup, one by one. 💜

💫 ::math::probopt::pso function bounds args

the particle swarm optimisation algorithm runs on the idea that the candidate optimum points should swarm around the best point found so far, with variations so improvements can sneak in. it's giving group project where everyone follows the smartest friend. main character energy fr.

it recognises these options:

  • -swarmsize number — number of particles to consider (default: 50)
  • -vweight value — weight for the current "velocity" (0-1, default: 0.5)
  • -pweight value — weight for the individual particle's best position (0-1, default: 0.3)
  • -gweight value — weight for the "best" overall position as per particle (0-1, default: 0.3)
  • -type local/global — type of optimisation
  • -neighbours number — size of the neighbourhood (default: 5, used if "local")
  • -iterations number — maximum number of iterations
  • -tolerance value — absolute minimal improvement for minimum value

💫 ::math::probopt::sce function bounds args

the shuffled complex evolution algorithm is basically an extension of the Nelder-Mead algorithm, except it uses multiple complexes and then reorganises those complexes to hunt down the "global" optimum. it's the friend group that keeps reshuffling seats until the vibe is perfect. 🫶

it recognises these options:

  • -complexes number — number of particles to consider (default: 2)
  • -mincomplexes number — minimum number of complexes (default: 2; not currently used)
  • -newpoints number — number of new points to be generated (default: 1)
  • -shuffle number — number of iterations after which to reshuffle the complexes (if set to 0, the default, a number will be calculated from the number of dimensions)
  • -pointspercomplex number — number of points per complex (if set to 0, the default, a number will be calculated from the number of dimensions)
  • -pointspersubcomplex number — number of points per subcomplex (used to select the best points in each complex; if set to 0, the default, a number will be calculated from the number of dimensions)
  • -iterations number — maximum number of iterations (default: 100)
  • -maxevaluations number — maximum number of function evaluations (when this number is reached the iteration is broken off. Default: 1000 million)
  • -abstolerance value — absolute minimal improvement for minimum value (default: 0.0)
  • -reltolerance value — relative minimal improvement for minimum value (default: 0.001)

💫 ::math::probopt::diffev function bounds args

the differential evolution algorithm starts with a number of initial points, then updates them using randomly selected points. it's more or less akin to genetic algorithms — glow-up by crossover, basically. it's controlled by two parameters, factor and lambda: the first decides the update via random points, the second decides the update with the best point found sofar.

it recognises these options:

  • -iterations number — maximum number of iterations (default: 100)
  • -number number — number of point to work with (if set to 0, the default, it is calculated from the number of dimensions)
  • -factor value — weight of randomly selected points in the updating (0-1, default: 0.6)
  • -lambda value — weight of the best point found so far in the updating (0-1, default: 0.0)
  • -crossover value — fraction of new points to be considered for replacing the old ones (0-1, default: 0.5)
  • -maxevaluations number — maximum number of function evaluations (when this number is reached the iteration is broken off. Default: 1000 million)
  • -abstolerance value — absolute minimal improvement for minimum value (default: 0.0)
  • -reltolerance value — relative minimal improvement for minimum value (default: 0.001)

💫 ::math::probopt::lipoMax function bounds args

the Lipschitz optimisation algorithm uses the "Lipschitz" property of the given function to find a maximum in the given bounding box. heads up — there are two variants, and lipoMax assumes a fixed estimate for the Lipschitz parameter. it knows what it is and it's not changing. 💅

it recognises these options:

  • -iterations number — number of iterations (equals the actual number of function evaluations, default: 100)
  • -lipschitz value — estimate of the Lipschitz parameter (default: 10.0)

💫 ::math::probopt::adaLipoMax function bounds args

the adaptive Lipschitz optimisation algorithm also uses the "Lipschitz" property of the given function to find a maximum in the given bounding box — but this adaptive variant actually uses two phases to find a suitable estimate for the Lipschitz parameter. that's controlled by the "Bernoulli" parameter.

⚠️ real talk bestie: when you specify a large number of iterations, the algorithm may take a very long time to complete, because it's out here trying to improve on the Lipschitz parameter, and the chances of hitting a better estimate diminish fast. it's giving "diminishing returns" and it's not cute. 😭

it recognises these options:

  • -iterations number — number of iterations (equals the actual number of function evaluations, default: 100)
  • -bernoulli value — parameter for random decisions (exploration versus exploitation, default: 0.1)

okay that's part 1, bestie — there's more coming, don't go anywhere ✨

📚 REFERENCES 📚

ok so the algorithms in here aren't vibes-based, bestie — they're all published. If you wanna go read the actual papers (iconic behaviour honestly), here's the reading list 💖

  • PSO — Maurice Clerc, Standard Particle Swarm Optimisation (2012)

https://hal.archives-ouvertes.fr/file/index/docid/764996/filename/SPSO_descriptions.pdf

orrr if you want the chill wikipedia version:

https://en.wikipedia.org/wiki/Particle_swarm_optimization

  • SCE — Qingyuan Duan, Soroosh Sorooshian, Vijai K. Gupta, Optimal use offo the SCE-UA global optimization method for calibrating watershed models (1994), Journal of Hydrology 158, pp 265-284

https://www.researchgate.net/publication/223408756_Optimal_Use_of_the_SCE-UA_Global_Optimization_Method_for_Calibrating_Watershed_Models

  • DE — Rainer Storn and Kenneth Price, Differential Evolution - A simple and efficient adaptivescheme for globaloptimization over continuous spaces (1996)

http://www1.icsi.berkeley.edu/~storn/TR-95-012.pdf

  • LIPO — Cedric Malherbe and Nicolas Vayatis, Global optimization of Lipschitz functions, (june 2017)

https://arxiv.org/pdf/1703.02628.pdf

🔑 KEYWORDS 🔑

mathematics, optimisation, probabilistic calculations ✨

like. yeah. that's the whole vibe in three words 🫶

🏷️ CATEGORY 🏷️

Mathematics 💅

and that's the whole page bestie, you made it to the end, so proud of you 😭💖 this one's from tcllib, version 1.1, and the page itself is math::probopt(n) — go forth and optimise probabilistically, you absolute main character 👑🦋

📦 where this page comes from