.. This file is auto-generated by the Sphinx pre-build hook in ``docs/source/conf.py`` from ``docs/source/_data/patcher_objects.json`` and the notes in ``docs/source/_data/patcher_notes/``. Do not edit by hand — run ``dart run tool/gen_patcher_snapshot.dart`` to refresh the JSON from the bound engine and ``dart run tool/port_patcher_notes.dart`` to refresh the notes from the engine submodule, then rebuild the docs. Random ====== Random numbers, random walks and probabilistic choices. 5 objects. Every entry is pulled directly from the engine registry, which reads the ``ADD_DESCRIPTION`` / ``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks control-rate objects. Links into the patcher guide (messages, time, data, files, ...) lead to the libYSE documentation, which also has this :yse-cpp:`category's page `. .. contents:: :local: :depth: 1 ``.decide`` ----------- A coin flip: each bang sends 0 or 1 with equal chance. Use it for random branching, fills and gating. :Dart: ``Obj.gDecide`` :Kind: Control-rate An int or float at the left inlet flips the coin just like a bang; its value is ignored. **Seeds** ``.decide``, ``.drunk``, ``.prob`` and ``.urn`` each keep their own random sequence, set by the ``seed`` argument: - Any seed other than 0 gives the same sequence on every run, so a generative patch can replay exactly. - Seed 0, the default, takes a sequence from the engine's generator. That too repeats from run to run, until the host calls ``System.randomize()``. - ``seed `` (or an int at the seed inlet, where there is one) restarts the sequence while the patch runs. A saved patch keeps the seed it was created with, not the last one sent. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - control - FLOAT, INT, BANG, LIST - — - A bang, int or float flips the coin. 'seed ' restarts the random sequence. * - 1 - seed - FLOAT, INT - any int - Restarts the random sequence with this seed. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 0 or 1. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - seed - 0 - any int - Random seed. Any other value than 0 gives the same flips on every run. ``.drunk`` ---------- A random walk: each bang moves the value up or down by a small random step and sends it, kept within 0 to range-1. Successive values drift rather than jump. :Dart: ``Obj.gDrunk`` :Kind: Control-rate Each bang adds a random step to the current position and sends the result, clipped to 0 to range-1. The walk stays at an edge once it reaches it, until a step leads back; for a walk that bounces or wraps, pass the output through ``.pong``. The step size is a limit that steps never reach: with the default 2, each step is -1, 0 or +1. A negative step size gives the same steps without 0, so the walk moves on every bang (if it is not held at an edge). **Messages** - bang: take a step and send the new position. - an int or float: move to that position (clipped) and send it. - ``set ``: move to ``n`` without sending. - ``seed ``: restart the random sequence; see ``.decide``. Changing the range clips the current position into it straight away. Floats are truncated. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - control - FLOAT, INT, BANG, LIST - 0 to range-1 - A bang takes a step. An int or float sets the position and sends it. 'set ' sets it without sending; 'seed ' restarts the random sequence. * - 1 - range - FLOAT, INT - 1+ - The walk stays below this value. * - 2 - stepSize - FLOAT, INT - any int - Steps are smaller than this value. A negative value also rules out a zero step. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 to range-1 - The position of the walk. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - range - 128 - 1+ - The walk stays below this value. * - stepSize - 2 - any int - Steps are smaller than this value; negative rules out a zero step. * - seed - 0 - any int - Random seed. Any other value than 0 gives the same walk on every run. ``.prob`` --------- A Markov chain of weighted transitions between numbered states. Each bang jumps from the current state to a next one, chosen by weight, and sends it. :Dart: ``Obj.gProb`` :Kind: Control-rate A list `` `` stores a transition. Storing the same pair again replaces its weight. For each state, the weights of its transitions are added up, and each weight's share is the chance of that jump: .. code-block:: text 1 1 3, 1 2 4, 1 3 1 => from state 1: to 1 37.5%, to 2 50%, to 3 12.5% A weight of 0 keeps the transition but switches it off; negative weights count as 0. A state may jump to itself. Each bang makes one jump from the current state and sends the new state, which becomes the current state. When the current state has no transition with a weight above 0, nothing comes out of the left outlet: the middle outlet bangs and the current state becomes the ``reset`` state, so the next bang can start again. **Messages** - bang: make one jump. - an int or float: set the current state without sending anything. - `` ``: store a transition. A list of any other length is ignored. - ``clear``: forget every transition. - ``dump``: send every transition out of the right outlet, in the order they were first stored. - ``reset ``: set the state to return to after a dead end. - ``seed ``: restart the random sequence; see ``.decide``. **Limits** The table holds 1024 transitions. Once it is full, a new pair is ignored; changing the weight of a stored pair still works. ``.anal`` builds the same kind of table from a stream of numbers. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - control - FLOAT, INT, BANG, LIST - — - A bang makes a jump. An int or float sets the current state without sending. A list ' ' stores a transition; also 'clear', 'dump', 'reset ' and 'seed '. * - 1 - seed - FLOAT, INT - any int - Restarts the random sequence with this seed. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The state jumped to. * - 1 - stuck - BANG - bang - A bang when the current state has no way out. The chain then goes back to the reset state. * - 2 - dump - LIST - — - One ' ' list per stored transition, on 'dump'. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - reset - 0 - any int - The state the chain starts in and returns to after a dead end. * - seed - 0 - any int - Random seed. Any other value than 0 gives the same walk on every run. ``.random`` ----------- Sends a random integer from 0 to range-1 on each bang, every value equally likely. :Dart: ``Obj.gRandom`` :Kind: Control-rate ``.random`` draws from the engine's generator, so its numbers repeat from run to run until the host calls ``System.randomize()``, and ``System.randomSeed()`` makes them replay. It has no seed of its own. A range of 0 or less always gives 0. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - bang - BANG - bang - A bang sends a new random number. * - 1 - range - FLOAT, INT - 1+ - Sets the range for the next numbers. A float is truncated. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 to range-1 - A random integer from 0 to range-1. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - range - 2 - 1+ - How many different values can come out. ``.urn`` -------- Random numbers without repeats: each bang sends a number from 0 to limit-1 that has not come out yet, like dealing from a shuffled deck. When all have been sent, the right outlet bangs. :Dart: ``Obj.gUrn`` :Kind: Control-rate Each bang deals one number from 0 to limit-1 that has not come out since the last refill, so every number appears once before any repeats. When all are dealt, a bang sends nothing from the left outlet and bangs the right one instead. **Messages** - bang: deal the next number. - ``clear``: put every number back, in a new order. - ``seed ``: restart the random sequence and reshuffle the numbers not yet dealt; see ``.decide``. - an int or float at the right inlet: set the limit, clamped to 1-4096, and refill. The urn is refilled only by ``clear`` or a new limit. To deal round after round, send ``clear`` when the right outlet bangs. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - control - BANG, LIST - — - A bang deals the next number. 'clear' refills and reshuffles; 'seed ' restarts the random sequence. * - 1 - limit - FLOAT, INT - 1-4096 - Sets how many numbers there are, and refills. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 to limit-1 - The next number. Nothing once all have been dealt. * - 1 - empty - BANG - bang - A bang for each bang that arrives after all numbers have been dealt. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - limit - 1 - 1-4096 - How many numbers there are, clamped to 1-4096. * - seed - 0 - any int - Random seed. Any other value than 0 gives the same order on every run.