.. index:: single: sampling_protocol
.. _sampling_protocol/0:

.. rst-class:: right

**protocol**

``sampling_protocol``
=====================

Predicates for sampling probability distributions.

| **Availability:** 
|    ``logtalk_load(random(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2025-02-25

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: normal/3
.. _sampling_protocol/0::normal/3:

``normal/3``
^^^^^^^^^^^^

Returns a scaled normally (Gaussian) distributed random value with the given mean and standard deviation.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``normal(Mean,Deviation,Value)``
| **Mode and number of proofs:**
|    ``normal(+float,+non_negative_float,-float)`` - ``one``


------------

.. index:: lognormal/3
.. _sampling_protocol/0::lognormal/3:

``lognormal/3``
^^^^^^^^^^^^^^^

Returns a scaled log normally distributed random value with the given mean and standard deviation for the normal distribution.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lognormal(Mean,Deviation,Value)``
| **Mode and number of proofs:**
|    ``lognormal(+float,+non_negative_float,-float)`` - ``one``


------------

.. index:: wald/3
.. _sampling_protocol/0::wald/3:

``wald/3``
^^^^^^^^^^

Returns a scaled Wald (inverse Gaussian) distributed random value with the given mean.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``wald(Mean,Scale,Value)``
| **Mode and number of proofs:**
|    ``wald(+positive_float,+positive_float,-float)`` - ``one``


------------

.. index:: chi_squared/2
.. _sampling_protocol/0::chi_squared/2:

``chi_squared/2``
^^^^^^^^^^^^^^^^^

Returns a chi-squared distributed random value given the degrees of freedom.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``chi_squared(DegreesOfFreedom,Value)``
| **Mode and number of proofs:**
|    ``chi_squared(+positive_integer,-float)`` - ``one``


------------

.. index:: fisher/3
.. _sampling_protocol/0::fisher/3:

``fisher/3``
^^^^^^^^^^^^

Returns a Fisher distributed random value given the degrees of freedom in the numerator and in the denominator.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fisher(DegreesOfFreedomNumerator,DegreesOfFreedomDenominator,Value)``
| **Mode and number of proofs:**
|    ``fisher(+positive_integer,+positive_integer,-float)`` - ``one``


------------

.. index:: logseries/2
.. _sampling_protocol/0::logseries/2:

``logseries/2``
^^^^^^^^^^^^^^^

Returns a logseries distributed random value. Requires ``0.0 < Shape < 1`` and fails otherwise.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``logseries(Shape,Value)``
| **Mode and number of proofs:**
|    ``logseries(+non_negative_integer,-positive_integer)`` - ``zero_or_one``


------------

.. index:: geometric/2
.. _sampling_protocol/0::geometric/2:

``geometric/2``
^^^^^^^^^^^^^^^

Returns a geometric distributed random value (trials until the first success).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``geometric(Probability,Value)``
| **Mode and number of proofs:**
|    ``geometric(+probability,-positive_integer)`` - ``one``


------------

.. index:: hypergeometric/4
.. _sampling_protocol/0::hypergeometric/4:

``hypergeometric/4``
^^^^^^^^^^^^^^^^^^^^

Returns a hypergeometric distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``hypergeometric(Population,Successes,Draws,Value)``
| **Mode and number of proofs:**
|    ``hypergeometric(+non_negative_integer,+non_negative_integer,+non_negative_integer,-non_negative_integer)`` - ``one``


------------

.. index:: exponential/2
.. _sampling_protocol/0::exponential/2:

``exponential/2``
^^^^^^^^^^^^^^^^^

Returns a scaled exponentially distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``exponential(Scale,Value)``
| **Mode and number of proofs:**
|    ``exponential(+positive_float,-float)`` - ``one``


------------

.. index:: binomial/3
.. _sampling_protocol/0::binomial/3:

``binomial/3``
^^^^^^^^^^^^^^

Returns a binomial distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``binomial(Trials,Probability,Value)``
| **Mode and number of proofs:**
|    ``binomial(+positive_integer,+positive_float,-float)`` - ``one``


------------

.. index:: bernoulli/2
.. _sampling_protocol/0::bernoulli/2:

``bernoulli/2``
^^^^^^^^^^^^^^^

Returns a Bernoulli distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``bernoulli(Probability,Value)``
| **Mode and number of proofs:**
|    ``bernoulli(+positive_integer,-float)`` - ``one``


------------

.. index:: beta/3
.. _sampling_protocol/0::beta/3:

``beta/3``
^^^^^^^^^^

Returns a beta distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``beta(Alpha,Beta,Value)``
| **Mode and number of proofs:**
|    ``beta(+positive_float,+positive_float,-float)`` - ``one``


------------

.. index:: gamma/3
.. _sampling_protocol/0::gamma/3:

``gamma/3``
^^^^^^^^^^^

Returns a scaled gamma distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``gamma(Shape,Scale,Value)``
| **Mode and number of proofs:**
|    ``gamma(+positive_float,+positive_float,-float)`` - ``one``


------------

.. index:: logistic/3
.. _sampling_protocol/0::logistic/3:

``logistic/3``
^^^^^^^^^^^^^^

Returns a scaled logistic distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``logistic(Location,Scale,Value)``
| **Mode and number of proofs:**
|    ``logistic(+float,+positive_float,-float)`` - ``one``


------------

.. index:: poisson/2
.. _sampling_protocol/0::poisson/2:

``poisson/2``
^^^^^^^^^^^^^

Returns a Poisson distributed random value given the expected number of events.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``poisson(Mean,Value)``
| **Mode and number of proofs:**
|    ``poisson(+non_negative_float,-non_negative_integer)`` - ``one``


------------

.. index:: power/2
.. _sampling_protocol/0::power/2:

``power/2``
^^^^^^^^^^^

Returns a power distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``power(Exponent,Value)``
| **Mode and number of proofs:**
|    ``power(+positive_float,-float)`` - ``one``


------------

.. index:: weibull/3
.. _sampling_protocol/0::weibull/3:

``weibull/3``
^^^^^^^^^^^^^

Returns a scaled Weibull distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``weibull(Shape,Scale,Value)``
| **Mode and number of proofs:**
|    ``weibull(+float,+positive_float,-float)`` - ``one``


------------

.. index:: uniform/3
.. _sampling_protocol/0::uniform/3:

``uniform/3``
^^^^^^^^^^^^^

Returns a uniform distributed random value in the interval``[Lower, Upper[``. Fails if ``Lower`` or ``Upper`` are not integers or if ``Lower > Upper``. Same as ``random/3``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``uniform(Lower,Upper,Value)``
| **Mode and number of proofs:**
|    ``uniform(+float,+float,-float)`` - ``zero_or_one``


------------

.. index:: uniform/1
.. _sampling_protocol/0::uniform/1:

``uniform/1``
^^^^^^^^^^^^^

Returns a uniform distributed random value in the interval``[0.0, 1.0[``. Same as ``random/1``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``uniform(Value)``
| **Mode and number of proofs:**
|    ``uniform(-float)`` - ``one``


------------

.. index:: triangular/4
.. _sampling_protocol/0::triangular/4:

``triangular/4``
^^^^^^^^^^^^^^^^

Returns a triangular distributed random value. Fails if the ``Left =< Mode =< Right`` condition does not hold.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``triangular(Left,Mode,Right,Value)``
| **Mode and number of proofs:**
|    ``triangular(+float,+float,+float,-float)`` - ``zero_or_one``


------------

.. index:: von_mises/3
.. _sampling_protocol/0::von_mises/3:

``von_mises/3``
^^^^^^^^^^^^^^^

Returns a von Mises distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``von_mises(Mode,Concentration,Value)``
| **Mode and number of proofs:**
|    ``von_mises(+float,+non_negative_float,-float)`` - ``zero_or_one``


------------

.. index:: gumbel/3
.. _sampling_protocol/0::gumbel/3:

``gumbel/3``
^^^^^^^^^^^^

Returns a Gumbel distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``gumbel(Location,Scale,Value)``
| **Mode and number of proofs:**
|    ``gumbel(+float,+non_negative_float,-float)`` - ``zero_or_one``


------------

.. index:: dirichlet/2
.. _sampling_protocol/0::dirichlet/2:

``dirichlet/2``
^^^^^^^^^^^^^^^

Returns a Dirichlet distributed list of random values.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``dirichlet(Alphas,Thetas)``
| **Mode and number of proofs:**
|    ``dirichlet(+list(positive_float),-list(positive_float))`` - ``one``


------------

.. index:: circular_uniform_polar/3
.. _sampling_protocol/0::circular_uniform_polar/3:

``circular_uniform_polar/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a circular uniform distributed random point in polar coordinates given the circle radius.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``circular_uniform_polar(Radius,Rho,Theta)``
| **Mode and number of proofs:**
|    ``circular_uniform_polar(+float,+float,-float)`` - ``one``


------------

.. index:: circular_uniform_cartesian/3
.. _sampling_protocol/0::circular_uniform_cartesian/3:

``circular_uniform_cartesian/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a circular uniform distributed random point in cartesian coordinates given the circle radius.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``circular_uniform_cartesian(Radius,X,Y)``
| **Mode and number of proofs:**
|    ``circular_uniform_cartesian(+float,+float,-float)`` - ``one``


------------

.. index:: standard_t/2
.. _sampling_protocol/0::standard_t/2:

``standard_t/2``
^^^^^^^^^^^^^^^^

Returns a standard Student's t distributed random value given the degrees of freedom.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_t(DegreesOfFreedom,Value)``
| **Mode and number of proofs:**
|    ``standard_t(+positive_integer,-float)`` - ``one``


------------

.. index:: standard_cauchy/3
.. _sampling_protocol/0::standard_cauchy/3:

``standard_cauchy/3``
^^^^^^^^^^^^^^^^^^^^^

Returns a standard Cauchy distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_cauchy(Location,Scale,Value)``
| **Mode and number of proofs:**
|    ``standard_cauchy(+float,+float,-float)`` - ``one``


------------

.. index:: standard_exponential/1
.. _sampling_protocol/0::standard_exponential/1:

``standard_exponential/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Returns a standard exponential distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_exponential(Value)``
| **Mode and number of proofs:**
|    ``standard_exponential(-float)`` - ``one``


------------

.. index:: standard_gamma/2
.. _sampling_protocol/0::standard_gamma/2:

``standard_gamma/2``
^^^^^^^^^^^^^^^^^^^^

Returns a standard gamma distributed random value.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_gamma(Shape,Value)``
| **Mode and number of proofs:**
|    ``standard_gamma(+positive_float,-float)`` - ``one``


------------

.. index:: standard_normal/1
.. _sampling_protocol/0::standard_normal/1:

``standard_normal/1``
^^^^^^^^^^^^^^^^^^^^^

Returns a standard normally (Gaussian) distributed random value (using a default mean of 0.0 and a default deviation of 1.0).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_normal(Value)``
| **Mode and number of proofs:**
|    ``standard_normal(-float)`` - ``one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`random_protocol <random_protocol/0>`, :ref:`pseudo_random_protocol <pseudo_random_protocol/0>`

