# 9.7. Samplers¶

This module provides a set of sampling functions for rapidly generating samples of 1D, 2D and 3D functions.

These functions use C calls when sampling Function1D, Function2D and Function3D objects and are therefore considerably faster than the equivalent Python code.

## 9.7.1. 1D Sampling¶

cherab.core.math.samplers.sample1d()

Samples a 1D function over the specified range.

Parameters
• function1d – a Python function or Function1D object

• x_range – a tuple defining the sample range: (min, max, samples)

Returns

a tuple containing the sampled values: (x_points, function_samples)

```>>> from cherab.core.math import sample1d
>>>
>>> def f1(x):
>>>     return x**2
>>>
>>> x_pts, f_vals = sample1d(f1, (0, 3, 5))
>>> x_pts
array([0.  , 0.75, 1.5 , 2.25, 3.  ])
>>> f_vals
array([0.    , 0.5625, 2.25  , 5.0625, 9.    ])
```
cherab.core.math.samplers.sample1d_points()

Sample a 1D function at the specified points

Parameters
• function1d – a Python function or Function1D object

• x_points – an array of points at which to sample the function

Returns

an array containing the sampled values

```>>> from cherab.core.math import sample1d_points
>>>
>>> def f1(x):
>>>     return x**2
>>>
>>> f_vals = sample1d_points(f1, [1, 2, 3])
>>> f_vals
array([1., 4., 9.])
```

## 9.7.2. 2D Sampling¶

cherab.core.math.samplers.sample2d()

Samples a 2D function over the specified range.

Parameters
• function2d – a Python function or Function2D object

• x_range – a tuple defining the x sample range: (x_min, x_max, x_samples)

• y_range – a tuple defining the y sample range: (y_min, y_max, y_samples)

Returns

a tuple containing the sampled values: (x_points, y_points, function_samples)

```>>> from cherab.core.math import sample2d
>>>
>>> def f1(x, y):
>>>     return x**2 + y
>>>
>>> x_pts, y_pts, f_vals = sample2d(f1, (1, 3, 5), (1, 3, 5))
>>> x_pts
array([1. , 1.5, 2. , 2.5, 3. ])
>>> y_pts
array([1. , 1.5, 2. , 2.5, 3. ])
>>> f_vals
array([[ 2.  ,  2.5 ,  3.  ,  3.5 ,  4.  ],
[ 3.25,  3.75,  4.25,  4.75,  5.25],
[ 5.  ,  5.5 ,  6.  ,  6.5 ,  7.  ],
[ 7.25,  7.75,  8.25,  8.75,  9.25],
[10.  , 10.5 , 11.  , 11.5 , 12.  ]])
```
cherab.core.math.samplers.sample2d_points()

Sample a 2D function at the specified points.

This function is for sampling at an unstructured sequence of points. For sampling over a regular grid, consider sample2d or sample2d_grid instead.

Parameters
• function2d – a Python function or Function2D object

• points – an Nx2 array of points at which to sample the function

Returns

a 1D array containing the sampled values at each point

```>>> from cherab.core.math import sample2d
>>>
>>> def f1(x, y):
>>>     return x**2 + y
>>>
>>> f_vals = sample2d_points(f1, [[1, 1], [2, 2], [3, 3]])
>>> f_vals
array([ 2.,  6., 12.])
```
cherab.core.math.samplers.sample2d_grid()

Sample a 2D function on a rectilinear grid

Note that v[i, j] = f(x[i], y[j])

Parameters
• function2d – a Python function or Function2D object

• x – the x coordinates of each column in the grid

• y – the y coordinates of each row in the grid

Return v

a 2D array containing the sampled values at each grid point

```>>> from cherab.core.math import sample2d_grid
>>>
>>> def f1(x, y):
>>>     return x**2 + y
>>>
>>> f_vals = sample2d_grid(f1, [1, 2], [1, 2, 3])
>>> f_vals
array([[2., 3., 4.],
[5., 6., 7.]])
```
cherab.core.math.samplers.samplevector2d()

Samples a 2D vector function over the specified range.

The function samples returns are an NxMx3 array where the last axis are the x, y, and z components of the vector respectively.

Parameters
• function2d – a Python function or Function2D object

• x_range – a tuple defining the x sample range: (x_min, x_max, x_samples)

• y_range – a tuple defining the y sample range: (y_min, y_max, y_samples)

Returns

a tuple containing the sampled values: (x_points, y_points, function_samples)

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector2d
>>>
>>> def my_func(x, y):
>>>     return Vector3D(x, y, 0)
>>>
>>> x_pts, y_pts, f_vals = samplevector2d(my_func, (1, 3, 3), (1, 3, 3))
>>> x_pts
array([1., 2., 3.])
>>> y_pts
array([1., 2., 3.])
>>> f_vals
array([[[1., 1., 0.],
[1., 2., 0.],
[1., 3., 0.]],
[[2., 1., 0.],
[2., 2., 0.],
[2., 3., 0.]],
[[3., 1., 0.],
[3., 2., 0.],
[3., 3., 0.]]])
```
cherab.core.math.samplers.samplevector2d_points()

Sample a 2D vector function at the specified points.

This function is for sampling at an unstructured sequence of points. For sampling over a regular grid, consider samplevector2d or samplevector2d_grid instead.

Parameters
• function2d – a Python function or Function2D object

• points – an Nx2 array of points at which to sample the function

Returns

a Nx3 array containing the sampled values at each point

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector2d_points
>>>
>>> def my_func(x, y):
>>>     return Vector3D(x, y, 0)
>>>
>>> f_vals = samplevector2d_points(my_func, [[1, 1], [2, 2], [3, 3]])
>>> f_vals
array([[1., 1., 0.],
[2., 2., 0.],
[3., 3., 0.]])
```
cherab.core.math.samplers.samplevector2d_grid()

Sample a 2D vector function on a rectilinear grid

Parameters
• function2d – a Python function or Function2D object

• x – the x coordinates of each column in the grid

• y – the y coordinates of each row in the grid

Return v

a 3D array containing the sampled values at each grid point

Note that v[i, j] = f(x[i], y[j])

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector2d_grid
>>>
>>> def my_func(x, y):
>>>     return Vector3D(x, y, 0)
>>>
>>> f_vals = samplevector2d_grid(my_func, [1, 2], [1, 2, 3])
>>> f_vals
array([[[1., 1., 0.],
[1., 2., 0.],
[1., 3., 0.]],
[[2., 1., 0.],
[2., 2., 0.],
[2., 3., 0.]]])
```

## 9.7.3. 3D Sampling¶

cherab.core.math.samplers.sample3d()

Samples a 3D function over the specified range.

Parameters
• function3d – a Python function or Function2D object

• x_range – a tuple defining the x sample range: (x_min, x_max, x_samples)

• y_range – a tuple defining the y sample range: (y_min, y_max, y_samples)

• z_range – a tuple defining the z sample range: (z_min, z_max, z_samples)

Returns

a tuple containing the sampled values: (x_points, y_points, z_points, function_samples)

```>>> from cherab.core.math import sample3d
>>>
>>> def f1(x, y, z):
>>>     return x**3 + y**2 + z
>>>
>>> x_pts, y_pts, z_pts, f_vals = sample3d(f1, (1, 3, 3), (1, 3, 3), (1, 3, 3))
>>> x_pts
array([1., 2., 3.])
>>> f_vals
array([[[ 3.,  4.,  5.],
[ 6.,  7.,  8.],
[11., 12., 13.]],
[[10., 11., 12.],
[13., 14., 15.],
[18., 19., 20.]],
[[29., 30., 31.],
[32., 33., 34.],
[37., 38., 39.]]])
```
cherab.core.math.samplers.sample3d_points()

Sample a 3D function at the specified points.

This function is for sampling at an unstructured sequence of points. For sampling over a regular grid, consider sample3d or sample3d_grid instead.

Parameters
• function3d – a Python function or Function3D object

• points – an Nx3 array of points at which to sample the function

Returns

a 1D array containing the sampled values at each point

```>>> from cherab.core.math import sample3d_points
>>>
>>> def f1(x, y, z):
>>>     return x**3 + y**2 + z
>>>
>>> f_vals = sample3d_points(f1, [[1,1,1], [2,2,2], [3,3,3]])
>>> f_vals
array([ 3., 14., 39.])
```
cherab.core.math.samplers.sample3d_grid()

Sample a 3D function on a rectilinear grid

Note that v[i, j, k] = f(x[i], y[j], z[k])

Parameters
• function3d – a Python function or Function3D object

• x – the x coordinates of each column in the grid

• y – the y coordinates of each row in the grid

• z – the z coordinates of each plane in the grid

Return v

a 3D array containing the sampled values at each grid point

```>>> from cherab.core.math import sample3d_grid
>>>
>>> def f1(x, y, z):
>>>     return x**3 + y**2 + z
>>>
>>> f_vals = sample3d_grid(f1, (1, 3, 3), (1, 3, 3), (1, 3, 3))
>>> f_vals
array([[[ 3.,  5.,  5.],
[11., 13., 13.],
[11., 13., 13.]],
[[29., 31., 31.],
[37., 39., 39.],
[37., 39., 39.]],
[[29., 31., 31.],
[37., 39., 39.],
[37., 39., 39.]]])
```
cherab.core.math.samplers.samplevector3d()

Samples a 3D vector function over the specified range.

The function samples returns are an NxMxKx3 array where the last axis are the x, y, and z components of the vector respectively.

Parameters
• function3d – a Python function or Function2D object

• x_range – a tuple defining the x sample range: (x_min, x_max, x_samples)

• y_range – a tuple defining the y sample range: (y_min, y_max, y_samples)

• z_range – a tuple defining the z sample range: (z_min, z_max, z_samples)

Returns

a tuple containing the sampled values: (x_points, y_points, z_points, function_samples)

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector3d
>>>
>>> def my_func(x, y, z):
>>>     return Vector3D(x, y, z)
>>>
>>> x_pts, y_pts, z_pts, f_vals = samplevector3d(my_func, (1, 2, 2), (1, 3, 3), (1, 3, 3))
>>> x_pts
array([1., 2.])
>>> f_vals
array([[[[1., 1., 1.],
[1., 1., 2.],
[1., 1., 3.]],
[[1., 2., 1.],
[1., 2., 2.],
[1., 2., 3.]],
[[1., 3., 1.],
[1., 3., 2.],
[1., 3., 3.]]],

[[[2., 1., 1.],
[2., 1., 2.],
[2., 1., 3.]],
[[2., 2., 1.],
[2., 2., 2.],
[2., 2., 3.]],
[[2., 3., 1.],
[2., 3., 2.],
[2., 3., 3.]]]])
```
cherab.core.math.samplers.samplevector3d_points()

Sample a 3D vector function at the specified points.

This function is for sampling at an unstructured sequence of points. For sampling over a regular grid, consider samplevector3d or samplevector3d_grid instead.

Parameters
• function3d – a Python function or Function3D object

• points – an Nx3 array of points at which to sample the function

Returns

an Nx3 array containing the sampled values at each point

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector3d_points
>>>
>>> def my_func(x, y, z):
>>>     return Vector3D(x, y, z)
>>>
>>> f_vals = samplevector3d_points(my_func, [[1,1,1], [2,2,2], [3,3,3]])
>>> f_vals
array([[1., 1., 1.],
[2., 2., 2.],
[3., 3., 3.]])
```
cherab.core.math.samplers.samplevector3d_grid()

Sample a 3D vector function on a rectilinear grid

Note that v[i, j, k] = f(x[i], y[j], z[k])

Parameters
• function3d – a Python function or Function3D object

• x – the x coordinates of each column in the grid

• y – the y coordinates of each row in the grid

• z – the z coordinates of each plane in the grid

Return v

an NxMxkx3 array containing the sampled values at each grid point

```>>> from raysect.core.math import Vector3D
>>> from cherab.core.math import samplevector3d_grid
>>>
>>> def my_func(x, y, z):
>>>     return Vector3D(x, y, z)
>>>
>>> f_vals = samplevector3d_grid(my_func, [1,2], [1,2,3], [1,2,3])
>>> f_vals
array([[[[1., 1., 1.],
[1., 1., 2.],
[1., 1., 3.]],
[[1., 2., 1.],
[1., 2., 2.],
[1., 2., 3.]],
[[1., 3., 1.],
[1., 3., 2.],
[1., 3., 3.]]],

[[[2., 1., 1.],
[2., 1., 2.],
[2., 1., 3.]],
[[2., 2., 1.],
[2., 2., 2.],
[2., 2., 3.]],
[[2., 3., 1.],
[2., 3., 2.],
[2., 3., 3.]]]])
```