Sampling tools

Functions for sampling properties in high-dimensional space.

These are implemented in a generic way for application in euphonic.powder

golden_square(npts, offset=True, jitter=False)

Yield a series of well-distributed points in 2-D unit square

These are obtained by the golden ratio method

(x_i, y_i) = (i / npts, (i / Phi) % 1)

Parameters

  • npts (int) – Number of points to distribute

  • offset (bool) – Offset x-coordinates away from origin. (This is recommended for spherical sampling by Marques et al. (2013))

  • jitter (bool) – Randomly displace points by a distance of up to 1/(2 sqrt(N))

Return type

Iterator[Tuple[float, float]]

Returns

Iterator[Tuple[float, float] – Sequence of (x, y) pairs in range 0-1

regular_square(n_rows, n_cols, offset=True, jitter=False)

Yield a regular grid of (x, y) points in 2-D unit square

Parameters

  • n_rows (int) – number of rows

  • n_cols (int) – number of columns

  • offset (bool) – offset points to avoid origin

  • jitter (bool) – randomly displace each point within its “cell”

Return type

Iterator[Tuple[float, float]]

Returns

Iterator[tuple[float, float]] – sequence of (x, y) pairs in range 0-1

golden_sphere(npts, cartesian=True, jitter=False)

Yield a series of 3D points on unit sphere surface

These resemble spherical Fibonacci point sets, using the golden ratio to obtain an appropriate point set for any positive inter NPTS. The method is outlined for “Quasi-Monte Carlo” sampling by Marques et al. (2013) DOI:10.1111/cgf.12190

Parameters

  • npts (int) – Number of points at sphere surface

  • cartesian (bool) – Yield points in Cartesian coordinates. If False, the 3-tuple points are given in spherical coordinates.

  • jitter (bool) – Randomly displace points about their positions on surface

Return type

Iterator[Tuple[float, float, float]]

Returns

Iterator[Tuple[float, float, float]] – Sequence of (x, y, z) coordinates (if cartesian=True) or (r, phi, theta) spherical coordinates.

sphere_from_square_grid(n_rows, n_cols, cartesian=True, jitter=False)

Yield a series of 3D points on a unit sphere surface

The points are projected from a uniform 2-D grid

Parameters

  • n_rows (int) – Number of rows in the Cartesian generating grid

  • n_cols (int) – Number of columns in the Cartesian generating grid

  • cartesian (bool) – Yield points in Cartesian coordinates. If False, instead yield points in spherical coordinates.

  • jitter (bool) – Randomly displace each point within its own “cell” of the grid

Return type

Iterator[Tuple[float, float, float]]

Returns

Iterator[Tuple[float, float, float]] – Sequence of (x, y, z) coordinates (if cartesian=True) or (r, phi, theta) spherical coordinates.

spherical_polar_grid(n_phi, n_theta, cartesian=True, jitter=False)

Yield a series of 3D points on a unit sphere surface

The points form a grid in spherical coordinates

Parameters

  • n_phi (int) – Number of longitude-like radial subdivisions at poles

  • n_theta (int) – Number of lattitude-like rings of points dividing polar axis

  • cartesian (bool) – Yield points in Cartesian coordinates. If False, instead yield points in spherical coordinates.

  • jitter (bool) – Randomly displace each point within its own “cell” of the grid

Return type

Iterator[Tuple[float, float, float]]

Returns

Iterator[Tuple[float, float, float]] – Sequence of (x, y, z) coordinates (if cartesian=True) or (r, phi, theta) spherical coordinates.

spherical_polar_improved(npts, cartesian=True, jitter=False)

Yield a series of 3D points on a unit sphere surface

The points form rings of common theta in polar coordinates. However, the number of samples in each ring is scaled to achieve as uniform a sampling density as possible.

Analytically we find that for evenly-divided theta, the average length of a “latitude” line is 4.

To obtain parity between nearest-neighbours (NN) along each axis, we solve (NN distance along theta) = (NN distance along phi):

4 n_theta / npts = pi / n_theta

Exact solutions with integer npts will be an irrational number, so n_theta is rounded down. The requested npts is then distributed between the constant-theta rings, according to their circumference.

Parameters

  • npts (int) – Number of points at sphere surface

  • cartesian (bool) – Yield points in Cartesian coordinates. If False, instead yield points in spherical coordinates.

  • jitter (bool) – Randomly displace each point within its own “cell” of the irregular grid

Return type

Iterator[Tuple[float, float, float]]

Returns

Iterator[Tuple[float, float, float]] – Sequence of (x, y, z) coordinates (if cartesian=True) or (r, phi, theta) spherical coordinates.

Raises

ValueError – If the number of points is not supported by this method

random_sphere(npts, cartesian=True)

Yield a series of 3D points on a unit sphere surface

Points are distributed randomly in polar coordinates: phi is evenly-distributed from 0 to 2pi while theta is scaled with an arccos function from an even distribution over the range (-1, 1), to account for warping at the poles.

Parameters

  • npts – Number of points at sphere surface

  • cartesian (bool) – Yield points in Cartesian coordinates. If False, instead yield points in spherical coordinates.

Return type

Iterator[Tuple[float, float, float]]

Returns

Iterator[Tuple[float, float, float]] – Sequence of (x, y, z) coordinates (if cartesian=True) or (r, phi, theta) spherical coordinates.

recurrence_sequence(npts, order=3)

Yield a series of well-distributed points in square or cube

This implements the R_d method of Martin Roberts (2018) published at http://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/

The Krcadinac (2005) method defines a set of irrational numbers beginning with the golden ratio. (x^{d+1} = x + 1). The number corresponding to the desired dimensionality is transformed to irrational factors alpha = (1/x_d, (1/x_d)^2, (1/x_d)^3, …)

For each of these factors a recurrence sequence t = (n alpha) % 1 yields a sequence of n low-discrepancy quasirandom numbers ranging 0 <= t < 1. These are packed into n-tuples to form the output n-dimensional samples.

Parameters

  • npts (int) – Number of points sampled in unit of n-dimensional space

  • order – Number of dimensions in sampled space

Return type

Iterator[tuple]

Returns

n-tuples of floats ranging 0-1, where n=order