doc(unitproc/.../sleepRand.py): Add comments

[BK-2020-03.git] / unitproc / python / sleepRand.py

#!/usr/bin/env python3
# Desc: Pauses a random amount of time. Random distribution is inverse gaussian.
# Version: 0.0.2
# Depends: python 3.7.3
# Usage: ./sleepRand.py arg1
# Input: arg1: float seconds (mean of inverse gaussian distribution)
# Example: python3 sleepRand.py 4.0

import math, time, random, sys

# Define functions
def randInvGau(mu, lam):
    """Returns random variate of inverse gaussian distribution"""
    # input: mu:  mean of inverse gaussian distribution
    #        lam: shape parameter
    # output: float sampled from inv. gaus. with range 0 to infinity, mean mu
    # example: sample = float(randInvGau(1.0,4.0));
    # Ref/Attrib: doi:10.1080/00031305.1976.10479147
    nu = random.gauss(0,1);
    y = nu ** 2;
    xTerm1 = mu;
    xTerm2 = mu ** 2 * y / (2 * lam);
    xTerm3 = (- mu / (2 * lam)) * math.sqrt(4 * mu * lam * y + mu ** 2 * y ** 2);
    x = xTerm1 + xTerm2 + xTerm3;
    z = random.uniform(0.0,1.0);
    if z <= (mu / (mu + x)):
        return x;
    else:
        return (mu ** 2 / x);

# Check input (TODO)
arg1 = float(sys.argv[1]); # first argument
desMean = arg1;

# Configure
lambdaFactor = 4; # spread factor; inversely proportional to variance

# Calculate delay
delay = randInvGau(desMean, desMean * lambdaFactor);
#print('DEBUG:delay:' + str(float(delay)));

# Sleep
time.sleep(float(delay));

# Author: Steven Baltakatei Sandoal
# License: GPLv3+