% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(random): Random numbers}

\label{sec:random}

\begin{tags}
    \tag{author}
R.A. O'Keefe, V.S. Costa, L. Damas, Jan Wielemaker
    \tag{See also}
Built-in function \predref{random}{1}: A is \verb$random(10)$
\end{tags}

This library is derived from the DEC10 library random. Later, the core
random generator was moved to C. The current version uses the SWI-Prolog
arithmetic functions to realise this library. These functions are based
on the GMP library.\vspace{0.7cm}

\begin{description}
    \predicate[det]{random}{1}{-R:float}
Binds \arg{R} to a new random float in the \textit{open} interval (0.0,1.0).

\begin{tags}
\mtag{See also}- \predref{setrand}{1}, \predref{getrand}{1} may be used to fetch/set the state. \\- In SWI-Prolog, \predref{random}{1} is implemented by the function
\predref{random_float}{0}.
\end{tags}

    \predicate[semidet]{random_between}{3}{+L:int, +U:int, -R:int}
Binds \arg{R} to a random integer in [\arg{L},\arg{U}] (i.e., including both \arg{L} and
\arg{U}). Fails silently if \arg{U}$<$\arg{L}.

    \predicate[det]{random}{3}{+L:int, +U:int, -R:int}
\nodescription
    \predicate[det]{random}{3}{+L:float, +U:float, -R:float}
Generate a random integer or float in a range. If \arg{L} and \arg{U} are
both integers, \arg{R} is a random integer in the half open interval
[\arg{L},\arg{U}). If \arg{L} and \arg{U} are both floats, \arg{R} is a float in the open
interval (\arg{L},\arg{U}).

\begin{tags}
    \tag{deprecated}
Please use \predref{random}{1} for generating a random float
and \predref{random_between}{3} for generating a random integer. Note that
\predref{random_between}{3} includes the upper bound, while this
predicate excludes it.
\end{tags}

    \predicate[det]{setrand}{1}{+State}
\nodescription
    \predicate[det]{getrand}{1}{-State}
Query/set the state of the random generator. This is intended
for restarting the generator at a known state only. The
predicate \predref{setrand}{1} accepts an opaque term returned by
\predref{getrand}{1}. This term may be asserted, written and read. The
application may not make other assumptions about this term.

For compatibility reasons with older versions of this library,
\predref{setrand}{1} also accepts a term \verb$rand(A,B,C)$, where A, B and C are
integers in the range 1..30,000. This argument is used to seed
the random generator. Deprecated.

\begin{tags}
    \tag{Errors}
\verb$existence_error(random_state, _)$ is raised if the
underlying infrastructure cannot fetch the random state.
This is currently the case if SWI-Prolog is not compiled
with the GMP library.
    \tag{See also}
\predref{set_random}{1} and \predref{random_property}{1} provide the SWI-Prolog
native implementation.
\end{tags}

    \predicate[semidet]{maybe}{0}{}
Succeed/fail with equal probability (variant of \predref{maybe}{1}).

    \predicate[semidet]{maybe}{1}{+P}
Succeed with probability \arg{P}, fail with probability 1-\arg{P}

    \predicate[semidet]{maybe}{2}{+K, +N}
Succeed with probability \arg{K}/\arg{N} (variant of \predref{maybe}{1})

    \predicate[semidet]{random_perm2}{4}{?A, ?B, ?X, ?Y}
Does \arg{X}=\arg{A},\arg{Y}=\arg{B} or \arg{X}=\arg{B},\arg{Y}=\arg{A} with equal probability.

    \predicate[semidet]{random_member}{2}{-X, +List:list}
\arg{X} is a random member of \arg{List}. Equivalent to random_between(1,
\Sbar{}\arg{List}\Sbar{}), followed by \predref{nth1}{3}. Fails of \arg{List} is the empty list.

\begin{tags}
    \tag{Compatibility}
Quintus and SICStus libraries.
\end{tags}

    \predicate[semidet]{random_select}{3}{-X, +List, -Rest}
\nodescription
    \predicate[det]{random_select}{3}{+X, -List, +Rest}
Randomly select or insert an element. Either \arg{List} or \arg{Rest} must
be a list. Fails if \arg{List} is the empty list.

\begin{tags}
    \tag{Compatibility}
Quintus and SICStus libraries.
\end{tags}

    \predicate[det]{random_subseq}{3}{+List, -Subseq, -Complement}
\nodescription
    \predicate[semidet]{random_subseq}{3}{-List, +Subseq, +Complement}
Selects a random subsequence \arg{Subseq} of \arg{List}, with \arg{Complement}
containing all elements of \arg{List} that were not selected. Each element
of \arg{List} is included with equal probability in either \arg{Subseq} or
\arg{Complement}.

\predref{random_subseq}{3} may also be called with \arg{Subseq} and \arg{Complement} bound
and \arg{List} unbound, which will recreate \arg{List} by randomly interleaving
\arg{Subseq} and \arg{Complement}. This mode may fail randomly, matching SICStus
behavior. The failure probability corresponds to the probability of
the "forward" mode selecting a \arg{Subseq}/\arg{Complement} combination with
different lengths.

\begin{tags}
    \tag{Compatibility}
SICStus 4
\end{tags}

    \predicate[det]{randset}{3}{+K:int, +N:int, -S:list(int)}
\arg{S} is a sorted list of \arg{K} unique random integers in the range 1..\arg{N}.
The implementation uses different techniques depending on the ratio
\arg{K}/\arg{N}. For small \arg{K}/\arg{N} it generates a set of \arg{K} random numbers, removes
the duplicates and adds more numbers until \Sbar{}\arg{S}\Sbar{} is \arg{K}. For a large \arg{K}/\arg{N}
it enumerates 1..\arg{N} and decides randomly to include the number or
not. For example:

\begin{code}
?- randset(5, 5, S).
S = [1, 2, 3, 4, 5].          (always)
?- randset(5, 20, S).
S = [2, 7, 10, 19, 20].
\end{code}

\begin{tags}
    \tag{See also}
\predref{randseq}{3}.
\end{tags}

    \predicate[det]{randseq}{3}{+K:int, +N:int, -List:list(int)}
S is a list of \arg{K} unique random integers in the range 1..\arg{N}. The
order is random. Defined as

\begin{code}
randseq(K, N, List) :-
      randset(K, N, Set),
      random_permutation(Set, List).
\end{code}

\begin{tags}
    \tag{See also}
\predref{randset}{3}.
\end{tags}

    \predicate[det]{random_permutation}{2}{+List, -Permutation}
\nodescription
    \predicate[det]{random_permutation}{2}{-List, +Permutation}
\arg{Permutation} is a random permutation of \arg{List}. This is intended to
process the elements of \arg{List} in random order. The predicate is
symmetric.

\begin{tags}
    \tag{Errors}
instantiation_error, \verb$type_error(list, _)$.
\end{tags}

    \predicate[det]{random_numlist}{4}{+P, +L, +U, -List}
Unify \arg{List} with an ascending list of integers between \arg{L} and \arg{U}
(inclusive). Each integer in the range \arg{L}..\arg{U} is included with
probability \arg{P}.

\begin{tags}
    \tag{Compatibility}
SICStus 4
\end{tags}
\end{description}