{
"title": "normrnd",
"category": "stats/random",
"keywords": [
"normrnd",
"normal",
"gaussian",
"random",
"distribution",
"statistics"
],
"summary": "Normally-distributed random numbers with mean mu and standard deviation sigma.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"f64"
],
"broadcasting": "none",
"notes": "Uses the provider random_normrnd hook (Philox CSPRNG + Box-Muller sampling) when an F64-precision provider is active. F32 providers and providers without the hook fall back to host generation."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "none"
},
"requires_feature": null,
"tested": {
"unit": "builtins::stats::random::normrnd::tests",
"integration": null
},
"description": "`normrnd` draws pseudorandom samples from the normal distribution with mean `mu` and standard deviation `sigma`. It is part of the **Statistics and Machine Learning Toolbox** family in MATLAB and Octave's `statistics` package. RunMat implements it by generating standard normal variates and scaling them as `r = mu + sigma * Z` where `Z ~ N(0, 1)`.",
"behaviors": [
"`normrnd(mu, sigma)` returns a scalar double drawn from `N(mu, sigma^2)`.",
"`normrnd(mu, sigma, n)` returns an `n × n` matrix of samples.",
"`normrnd(mu, sigma, m, n)` returns an `m × n` matrix of samples.",
"`normrnd(mu, sigma, sz)` accepts a size vector and returns an array with shape `sz`.",
"`mu` and `sigma` must be scalar numeric values.",
"`sigma` must be non-negative; `normrnd` errors if `sigma < 0`.",
"All outputs are double precision regardless of input type."
],
"examples": [
{
"description": "Single sample from N(0, 1)",
"input": "rng(0);\nr = normrnd(0, 1)"
},
{
"description": "Matrix of Gaussian noise with mean 10 and standard deviation 2",
"input": "rng(0);\nX = normrnd(10, 2, 2, 3)"
},
{
"description": "Simulating normally-distributed measurement errors",
"input": "rng(0);\ntrueValue = 100;\nsigma = 0.5;\nmeasurements = trueValue + normrnd(0, sigma, 1, 5)"
},
{
"description": "Specifying dimensions with a size vector",
"input": "rng(0);\nT = normrnd(5, 1.5, [2 3])"
}
],
"faqs": [
{
"question": "What do mu and sigma mean?",
"answer": "`mu` is the distribution mean and `sigma` is the standard deviation. The variance is `sigma^2`, so `normrnd(mu, sigma)` draws from `N(mu, sigma^2)`."
},
{
"question": "What is the workaround if normrnd is unavailable?",
"answer": "`normrnd(mu, sigma)` is mathematically equivalent to `mu + sigma * randn()`. For arrays, use `mu + sigma * randn(sz)` with the same requested size."
},
{
"question": "Can sigma be zero?",
"answer": "Yes. `sigma = 0` is allowed and returns deterministic samples equal to `mu`. Negative standard deviations are undefined and raise an error."
},
{
"question": "What use cases does normrnd support?",
"answer": "Common uses include Gaussian noise generation, measurement error simulation, confidence interval experiments, Monte Carlo sampling, and normally-distributed model residuals."
},
{
"question": "Does normrnd fuse with other operations?",
"answer": "No. Random generation is excluded from fusion planning to preserve statistical properties."
},
{
"question": "How do I control reproducibility?",
"answer": "Use `rng` before calling `normrnd` to seed the global generator."
}
],
"links": [
{
"label": "exprnd",
"url": "./exprnd"
},
{
"label": "unifrnd",
"url": "./unifrnd"
},
{
"label": "rand",
"url": "./rand"
},
{
"label": "randn",
"url": "./randn"
},
{
"label": "rng",
"url": "./rng"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/stats/random/normrnd.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/stats/random/normrnd.rs"
}
}