# 1.2.4. Random¶

## 1.2.4.1. Random samplers¶

raysect.core.math.random.seed()

Seeds the random number generator with the specified integer.

If a seed is not specified the generator is automatically re-seed using the system cryptographic random number generator (urandom).

Parameters: d (int) – Integer seed.
>>> from raysect.core.math.random import seed
>>> seed(1)

raysect.core.math.random.uniform()

Generate random doubles in range [0, 1).

Values are uniformly distributed.

Returns: Random double.
>>> from raysect.core.math.random import uniform
>>>
>>> uniform()
0.7151068954493792
>>> uniform()
0.21476630242370853

raysect.core.math.random.normal()

Generates a normally distributed random number.

The mean and standard deviation of the distribution must be specified.

Parameters: mean (float) – The distribution mean. stddev (float) – The distribution standard deviation. Random double.
>>> from raysect.core.math.random import normal
>>>
>>> normal(0, 1)
0.5775399543387388
>>> normal(0, 1)
-2.247813575930409

raysect.core.math.random.probability()

Samples from the Bernoulli distribution where P(True) = prob.

For example, if probability is 0.8, this function will return True 80% of the time and False 20% of the time.

Values of prob outside the [0, 1] range of probabilities will be clamped to the nearest end of the range [0, 1].

Parameters: prob (double) – A probability from [0, 1]. True or False. bool
>>> from raysect.core.math.random import probability
>>>
>>> probability(0.8)
True
>>> probability(0.8)
True


## 1.2.4.2. 3D Surface Samplers¶

class raysect.core.math.sampler.surface3d.SurfaceSampler3D

Base class for an object that generates samples from a surface in 3D.

__call__

If samples is not provided, returns a single Point3D sample from the distribution. If samples is set to a value then a number of samples equal to the value specified is returned in a list.

If pdf is set to True the Point3D sample is returned inside a tuple with its associated pdf value as the second element.

Parameters: samples (int) – Number of points to generate (default=None). pdf (bool) – Toggle for returning associated sample pdfs (default=False). A Point3D, tuple or list.
class raysect.core.math.sampler.surface3d.DiskSampler3D

Generates Point3D samples from a disk centred in the x-y plane.

Parameters: radius (double) – The radius of the disk in metres (default=1).
>>> from raysect.core.math import DiskSampler3D
>>>
>>> disk_sampler = DiskSampler3D()
>>> disk_sampler(2)
[Point3D(-0.8755314944066419, -0.36748751614554004, 0.0),
Point3D(-0.7515341075950953, 0.15368157833817775, 0.0)]

class raysect.core.math.sampler.surface3d.RectangleSampler3D

Generates Point3D samples from a rectangle centred in the x-y plane.

Parameters: width (double) – The width of the rectangle. height (double) – The height of the rectangle.
>>> from raysect.core.math import RectangleSampler3D
>>>
>>> rectangle_sampler = RectangleSampler3D(width=3, height=3)
>>> rectangle_sampler(2)
[Point3D(0.8755185034767394, -1.4596971179451579, 0.0),
Point3D(1.3514601271010727, 0.9710083493215418, 0.0)]

class raysect.core.math.sampler.surface3d.TriangleSampler3D

Generates Point3D samples from a triangle in 3D space.

Parameters: v1 (Point3D) – Triangle vertex 1. v2 (Point3D) – Triangle vertex 2. v3 (Point3D) – Triangle vertex 3.
>>> from raysect.core.math import TriangleSampler3D
>>>
>>> tri_sampler = TriangleSampler3D(Point3D(0,0,0),
Point3D(1,0,0),
Point3D(1,1,0))
>>> tri_sampler(2)
[Point3D(0.9033819087428726, 0.053382913976399715, 0.0),
Point3D(0.857350441035813, 0.4243360393025779, 0.0)]


## 1.2.4.3. Solid Angle Samplers¶

class raysect.core.math.sampler.solidangle.SolidAngleSampler

Base class for an object that generates samples over a solid angle.

__call__

If samples is not provided, returns a single Vector3D sample from the distribution. If samples is set to a value then a number of samples equal to the value specified is returned in a list.

If pdf is set to True the Vector3D sample is returned inside a tuple with its associated pdf value as the second element.

Parameters: samples (int) – Number of points to generate (default=None). pdf (bool) – Toggle for returning associated sample pdfs (default=False). A Vector3D, tuple or list of Vector3D objects.
pdf()

Generates a pdf for a given sample value.

Vectors must be normalised.

Parameters: sample (Vector3D) – The sample point at which to get the pdf. float
class raysect.core.math.sampler.solidangle.SphereSampler

Generates a random vector on a unit sphere.

>>> from raysect.core.math import SphereSampler
>>>
>>> sphere_sampler = SphereSampler()
>>> sphere_sampler(2)
[Vector3D(-0.03659868898144491, 0.24230159277890417, 0.9695104301149347),
Vector3D(-0.6983609515217772, -0.6547708308112921, -0.28907981684698814)]

class raysect.core.math.sampler.solidangle.HemisphereUniformSampler

Generates a random vector on a unit hemisphere.

The hemisphere is aligned along the z-axis - the plane that forms the hemisphere base lies in the x-y plane.

>>> from raysect.core.math import HemisphereUniformSampler
>>>
>>> sampler = HemisphereUniformSampler()
>>> sampler(2)
[Vector3D(-0.5555921819133177, -0.41159192618517343, 0.7224329821485018),
Vector3D(0.03447410534618117, 0.33544044138689, 0.9414304256517041)]

class raysect.core.math.sampler.solidangle.HemisphereCosineSampler

Generates a cosine-weighted random vector on a unit hemisphere.

The hemisphere is aligned along the z-axis - the plane that forms the hemisphere base lies in the x-y plane.

>>> from raysect.core.math import HemisphereCosineSampler
>>>
>>> sampler = HemisphereCosineSampler()
>>> sampler(2)
[Vector3D(0.18950017731212562, 0.4920026797683874, 0.8497193924463526),
Vector3D(0.21900782218503353, 0.918767789013818, 0.32848336897387853)]

class raysect.core.math.sampler.solidangle.ConeUniformSampler

Generates a uniform weighted random vector from a cone.

The cone is aligned along the z-axis.

Parameters: angle – Angle of the cone in degrees (default=45).
>>> from raysect.core.math import ConeUniformSampler
>>> sampler = ConeUniformSampler(5)
>>> sampler(2)
[Vector3D(-0.032984782761108486, 0.02339453130328099, 0.9991820154562943),
Vector3D(0.0246657314750599, 0.08269560820438482, 0.9962695609494988)]