[BUG][stdlib][random] randn_float64() generates values from a wrong distribution: variance argument should be std

[forFudan]

Bug description

This is related to the function randn_float64() in /stdlib/src/random/random.mojo.

fn randn_float64(mean: Float64 = 0.0, variance: Float64 = 1.0) -> Float64:

This function should return a random double sampled from a normal distribution with mean and variance. However, It actually returns a random value from the normal distribution with mean and squared variance.

Solution 1

To fix it, the second argument should be changed to std (sigma), where std is the standard deviation of the Normal distribution

fn randn_float64(mean: Float64 = 0.0, std: Float64 = 1.0) -> Float64:

Or mu-sigma expression:

fn randn_float64(mu: Float64 = 0.0, sigma: Float64 = 1.0) -> Float64:

Solution 2

Another way to fix it is to change the variance in the return line to sqrt(variance).

fn randn_float64(mean: Float64 = 0.0, variance: Float64 = 1.0) -> Float64:
    """Returns a random double sampled from a Normal(mean, variance) distribution.

    Args:
        mean: Normal distribution mean.
        variance: Normal distribution variance.

    Returns:
        A random float64 sampled from Normal(mean, variance).
    """
    return external_call["KGEN_CompilerRT_NormalDouble", Float64](
        mean, sqrt(variance)
    )

Steps to reproduce

See the following evaluation code:

We draw 1000,000 random values from a normal distribution with mean 0 and variance 2, using function randn_float64(0, 2).

We then calculate the variance of sample. It shows that the sample variance is ~3.9985, which is 2^2. This means that the argument variance is actually std.

from random import randn_float64
from python import Python

fn main() raises:
    var np = Python.import_module("numpy")

    var obs = 1000000
    var l = List[Float64]()
    for i in range(obs):
        l.append(randn_float64(0, 2))

    var sum: Float64 = 0.0
    for i in range(len(l)):
        sum += l[i]
    var mean = sum / obs

    var sum_sq: Float64 = 0.0
    for i in range(len(l)):
        sum_sq += (l[i] - mean) * (l[i] - mean)
    var variance = sum_sq / obs

    print(String("mean: {}, variance: {}").format(mean, variance))

mean: 0.002467043920765725, variance: 3.998468697001007

Changing the variance from 2 to other values witness the same issue.

System information

- What OS did you do install Mojo on ?
MacOS 15.2
- Provide version information for Mojo by pasting the output of `mojo -v`
mojo 24.6.0 (4487cd6e)
- Provide Magic CLI version by pasting the output of `magic -V` or `magic --version`
magic 0.6.3 - (based on pixi 0.40.3)

[illiasheshyn]

Hi @forFudan, I've raised a PR for this to address your points.

[forFudan]

@illiasheshyn Thank you!