Skip to content

Commit

Permalink
docs: simpler example for randn (JuliaLang#52252)
Browse files Browse the repository at this point in the history
As noted here:
https://discourse.julialang.org/t/how-do-we-julians-win-big-when-the-situation-is-so-unfair/106433/63?u=lmiq

The randn example is overly complicated and does not indicate the
simplest usage, which is probably the most typical one.

Co-authored-by: Steven G. Johnson <stevenj@mit.edu>
  • Loading branch information
2 people authored and mkitti committed Dec 9, 2023
1 parent 35965de commit 139e443
Showing 1 changed file with 36 additions and 10 deletions.
46 changes: 36 additions & 10 deletions stdlib/Random/src/normal.jl
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,51 @@
Generate a normally-distributed random number of type `T`
with mean 0 and standard deviation 1.
Optionally generate an array of normally-distributed random numbers.
The `Base` module currently provides an implementation for the types
[`Float16`](@ref), [`Float32`](@ref), and [`Float64`](@ref) (the default), and their
[`Complex`](@ref) counterparts. When the type argument is complex, the values are drawn
from the circularly symmetric complex normal distribution of variance 1 (corresponding to real and imaginary part having independent normal distribution with mean zero and variance `1/2`).
Given the optional `dims` argument(s), generate an array of size `dims` of such numbers.
Julia's standard library supports `randn` for any floating-point type
that implements [`rand`](@ref), e.g. the `Base` types
[`Float16`](@ref), [`Float32`](@ref), [`Float64`](@ref) (the default), and [`BigFloat`](@ref),
along with their [`Complex`](@ref) counterparts.
(When `T` is complex, the values are drawn
from the circularly symmetric complex normal distribution of variance 1, corresponding to real and imaginary parts
having independent normal distribution with mean zero and variance `1/2`).
See also [`randn!`](@ref) to act in-place.
# Examples
Generating a single random number (with the default `Float64` type):
```julia-repl
julia> randn()
-0.942481877315864
```
Generating a matrix of normal random numbers (with the default `Float64` type):
```julia-repl
julia> randn(2,3)
2×3 Matrix{Float64}:
1.18786 -0.678616 1.49463
-0.342792 -0.134299 -1.45005
```
Setting up of the random number generator `rng` with a user-defined seed (for reproducible numbers)
and using it to generate a random `Float32` number or a matrix of `ComplexF32` random numbers:
```jldoctest
julia> using Random; rng = Xoshiro(123);
julia> using Random
julia> rng = Xoshiro(123);
julia> randn(rng, ComplexF64)
-0.45660053706486897 - 1.0346749725929225im
julia> randn(rng, Float32)
-0.6457307f0
julia> randn(rng, ComplexF32, (2, 3))
2×3 Matrix{ComplexF32}:
-1.14806-0.153912im 0.056538+1.0954im 0.419454-0.543347im
0.34807+0.693657im -0.948661+0.291442im -0.0538589-0.463085im
-1.03467-1.14806im 0.693657+0.056538im 0.291442+0.419454im
-0.153912+0.34807im 1.0954-0.948661im -0.543347-0.0538589im
```
"""
@inline function randn(rng::AbstractRNG=default_rng())
Expand Down

0 comments on commit 139e443

Please sign in to comment.