Added more probability distributions

Author: A-Herzog

README.md

@@ -15,7 +15,8 @@ The zip package also includes some example files (as plain Python files and as J
 
 ## Requirements
 
-* **Python 3.7 or higher** is needed to execute QueueSim.
+* **Python 3.9 or higher** is needed to execute QueueSim.
+* **`scipy`** is used to generate pseudo-random numbers of some probability distributions
 * **`numpy`** is used by `queuesim.statistics` and in several example files.
 * **`pandas`** and **`scipy`** are used in `queuesim.analytic`.
 * The visualizations in the example Jupyter notebooks use **`matplotlib`** and **`seaborn`**.

README_distributions.md

@@ -7,13 +7,17 @@ To make thinks as easy as possible there are some lambda factory methods in `que
 * Exponential distribution: `exp(mean)`
 * Log-normal distribution: `log_normal(mean, sd)`
 * Gamma distribution: `gamma(mean, sd)`
-* Continuous Uniform distribution: `uniform(low, high)`
+* Erlang distribution: `erlang(mean, sd)`
+* Half-normal distribution: `half_normal(low, mean)`
+* Continuous uniform distribution: `uniform(low, high)`
 * Triangular distribution: `uniform(low, most_likely, high)`
+* Trapezoid distribution: `trapezoid(a, b, c, d)`
+* Beta distribution: `beta(alpha, beta, low, high)`
 * Deterministic: `deterministic(fixed_value)`
 * Empirical: `empirical(options)` where `options` is a `dict` of values to rates
 
 Since the gamma distribution is a generalization of the Erlang distribution, the quite common Erlang distribution is also covered.
 
-Note that the parameters for `log_normal` and `gamma` are mean (`mean`) and standard deviation (`sd`). So no manual converting from mean and standard deviation to $\mu$, $\sigma$, ... is needed.
+Note that the parameters for `log_normal`, `gamma` and `erlang`are mean (`mean`) and standard deviation (`sd`). So **no** manual converting from mean and standard deviation to $\mu$, $\sigma$, ... is needed.
 
 The generator functions will return strings containing lambda expressions. The strings are evaluated inside the stations on first usage. This is needed for serialization for multi-process simulation. If you do not want to use multi-process parallelization, you can also add the parameter `as_lambda=True` to get lambda expressions directly. The stations will understand both: strings and lambdas.

queuesim/analytic/tools.py

@@ -23,10 +23,7 @@
 __license__ = "Apache 2.0"
 
 
-# "prod" is introduced in Python 3.8.
-# We are 3.7 compatible.
-
-# from math import prod
+from math import prod
 
 
 def power_factorial(x: float, n: int) -> float:
@@ -42,7 +39,4 @@ def power_factorial(x: float, n: int) -> float:
     if n == 0:
         return 1
 
-    # return prod([x / i for i in range(1, n + 1)])
-    prod: float = 1
-    for i in range(1, n + 1): prod *= x / i
-    return prod
+    return prod([x / i for i in range(1, n + 1)])

queuesim/random_dist.py

@@ -3,6 +3,7 @@
 from typing import Callable, Union
 import math
 import random
+import scipy.stats as stats
 
 
 __title__ = "queuesim"
@@ -75,8 +76,9 @@ def gamma(mean: float, std: float, as_lambda: bool = False) -> Union[str, Callab
     Returns:
         Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
     """
-    assert std >= 0
-    beta: float = mean / (std * std)
+    assert mean > 0
+    assert std > 0
+    beta: float = mean / (std ** 2)
     alpha: float = mean * beta
     beta: float = 1 / beta
     if as_lambda:
@@ -85,6 +87,28 @@ def gamma(mean: float, std: float, as_lambda: bool = False) -> Union[str, Callab
         return "lambda: random.gammavariate(" + str(alpha) + ", " + str(beta) + ")"
 
 
+def erlang(mean: float, std: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
+    """Generates a lambda expression or a string that can be evaluated to a lambda expression, with a pseudorandom number generator for the Erlang distribution
+
+    Args:
+        mean (float): Mean
+        std (float): Standard deviation
+        as_lambda (bool, optional): Should a lambda expression (True) or a string (False) be returned? Defaults to False.
+
+    Returns:
+        Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
+    """
+    assert mean > 0
+    assert std > 0
+
+    scale: float = std**2 / mean
+    a: int = max(1, round(mean / scale))
+    if as_lambda:
+        return lambda: stats.erlang.rvs(a, scale=scale)
+    else:
+        return "lambda: stats.erlang.rvs(" + str(a) + ", scale = " + str(scale) + ")"
+
+
 def uniform(low: float, high: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
     """Generates a lambda expression or a string that can be evaluated to a lambda expression, with a pseudorandom number generator for the uniform distribution
 
@@ -120,6 +144,70 @@ def triangular(low: float, most_likely: float, high: float, as_lambda: bool = Fa
         return "lambda: random.triangular(" + str(low) + ", " + str(high) + ", " + str(most_likely) + ")"
 
 
+def trapezoid(a: float, b: float, c: float, d: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
+    """Generates a lambda expression or a string that can be evaluated to a lambda expression, with a pseudorandom number generator for the trapezoid distribution
+
+    Args:
+        a (float): Minimum value of the support
+        b (float): x value of the left side of the highest density
+        c (float): x value of the right side of the highest density
+        d (float): Maximum value of the support
+        as_lambda (bool, optional): Should a lambda expression (True) or a string (False) be returned? Defaults to False.
+
+    Returns:
+        Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
+    """
+    c_shape = (b - a) / (d - a)
+    d_shape = (c - a) / (d - a)
+    loc = a
+    scale = d - a
+    if as_lambda:
+        return lambda: stats.trapezoid.rvs(c_shape, d_shape, loc=loc, scale=scale)
+    else:
+        return "lambda: stats.trapezoid.rvs(" + str(c_shape) + ", " + str(d_shape) + ", loc=" + str(loc) + ", scale=" + str(scale) + ")"
+
+
+def beta(alpha: float, beta: float, low: float, high: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
+    """Generates a lambda expression or a string that can be evaluated to a lambda expression, with a pseudorandom number generator for the beta distribution
+
+    Args:
+        alpha (float): Alpha parameter of the beta distribution
+        beta (float): Beta parameter of the beta distribution
+        low (float): Minimum value of the support
+        high (float): Maximum value of the support
+        as_lambda (bool, optional): Should a lambda expression (True) or a string (False) be returned? Defaults to False.
+
+    Returns:
+        Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
+    """
+    loc = low
+    scale = high - loc
+    if as_lambda:
+        return lambda: stats.beta.rvs(alpha, beta, loc=loc, scale=scale)
+    else:
+        return "lambda: stats.beta.rvs(" + str(alpha) + ", " + str(beta) + ", loc=" + str(loc) + ", scale=" + str(scale) + ")"
+
+
+def half_normal(low: float, mean: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
+    """Generates a lambda expression or a string that can be evaluated to a lambda expression, with a pseudorandom number generator for the half-normal distribution
+
+    Args:
+        low (float): Minimum value of the support
+        mean (float): Mean of the half-normal distribution
+        as_lambda (bool, optional): Should a lambda expression (True) or a string (False) be returned? Defaults to False.
+
+    Returns:
+        Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
+    """
+    assert mean > low
+    loc = low
+    scale = (mean - low) * math.sqrt(math.pi / 2)
+    if as_lambda:
+        return lambda: stats.halfnorm.rvs(loc=loc, scale=scale)
+    else:
+        return "lambda: stats.halfnorm.rvs(loc=" + str(loc) + ", scale=" + str(scale) + ")"
+
+
 def deterministic(mean: float, as_lambda: bool = False) -> Union[str, Callable[[], float]]:
     """Generates a lambda expression or a string that can be evaluated to a lambda expression, which returns a fixed number (which is a special case of a pseudorandom number generator)
 
@@ -136,13 +224,13 @@ def deterministic(mean: float, as_lambda: bool = False) -> Union[str, Callable[[
         return "lambda: " + str(mean)
 
 
-def empirical_helper(values: dict) -> float:
-    rate_sum: float = sum(values.values())
+def empirical_helper(rate_sum, values: dict) -> float:
     rnd: float = random.random() * rate_sum
     s: float = 0
     for key in values:
         s += values[key]
-        if s >= rnd: return key
+        if s >= rnd:
+            return float(key)
     return 0
 
 
@@ -156,7 +244,8 @@ def empirical(values: dict, as_lambda: bool = False) -> Union[str, Callable[[],
     Returns:
         Union[str, Callable[[], float]]: Lambda expression or string with lambda expression for random number generator
     """
+    rate_sum: float = sum(values.values())
     if as_lambda:
-        return lambda: empirical_helper(values)
+        return lambda: empirical_helper(rate_sum, values)
     else:
-        return "lambda: empirical_helper(" + str(values) + ")"
+        return "lambda: empirical_helper(" + str(rate_sum) + ", " + str(values) + ")"

queuesim/stations.py

@@ -1,7 +1,10 @@
 """Classes for modelling the stations of a queueing model"""
 
 from typing import Any, Optional
+import math  # math, random, and scipy.stats are used when evaluating pseudo-random number generators from strings
 import random
+import scipy.stats as stats
+from .random_dist import empirical_helper
 from .descore import Event, Simulator
 from .statistics import RecordDiscrete, RecordContinuous, RecordOptions
 

queuesim/stations.pyx

@@ -1,7 +1,10 @@
 """Classes for modelling the stations of a queueing model"""
 
 from typing import Any, Optional
+import math  # math, random, and scipy.stats are used when evaluating pseudo-random number generators from strings
 import random
+import scipy.stats as stats
+from .random_dist import empirical_helper
 from .descore import Event, Simulator
 from .statistics import RecordDiscrete, RecordContinuous, RecordOptions
 import cython