Functions
double	clipm_math_rng_uniform50 (void)
	Generate random number between 0 and 1. More...

double	clipm_math_rng_gaussian (void)
	Generate gaussian-distributed random number. More...

void *	clipm_math_rng_poisson_pointpattern_2d (double xmin, double ymin, double xmax, double ymax, cpl_size homogeneity, cpl_size N, cpl_type type)
	Generate 2-dimensional pattern of Poisson-distributed points. More...

Detailed Description

This module provides functions to generate random values, patterns etc.

Synopsis:: #include "clipm_math_rng.h"

*

Function Documentation

double clipm_math_rng_gaussian ( void )

Generate gaussian-distributed random number.

Returns: Random number between $-\infty$ and $+\infty$ with the probability density of a gaussian normal distribution with a standard deviation $\sigma=1$

Note: Before usage, the random number generation should be initialized once using the C function srand(), cp. also clipm_math_rng_uniform50().

Algorithm:: This implementation uses the algorithm developed by Peter J. Acklam. The probability density error at a certain point never exceeds 1.15*10^-9.

See Also: http://home.online.no/~pjacklam/notes/invnorm/

void* clipm_math_rng_poisson_pointpattern_2d	(	double	xmin,
		double	ymin,
		double	xmax,
		double	ymax,
		cpl_size	homogeneity,
		cpl_size	N,
		cpl_type	type
	)

Generate 2-dimensional pattern of Poisson-distributed points.

Parameters

xmin	Left limit
ymin	Lower limit
xmax	Right limit
ymax	Upper limit
homogeneity	Homogeneity factor
N	Number of points
type	Output type, either CPL_TYPE_INT, or CPL_TYPE_DOUBLE

Returns: Integer or double array of size 2*N containing value pairs like [x1, y1, x2, y2, ..., xN, yN], NULL in the case of error

Overview:: A list of 2-dimensional point coordinates in a rectangular box is created. The output array has to be freed using cpl_free().

Note: Before usage, the random number generation should be initialized once using the C function srand(), cp. also clipm_math_rng_uniform50().

Purpose and Usage:

This function replaces the ESO eclipse software function poisson with slight modifications:

A homogenous Poisson process is simulated, in the original sense that the rate parameter is constant (equal distribution independent from location or time).

The type of the simulated Poisson process is a spatial one. The parameter homogeneity influences the behaviour with respect to spatial regions (as finite-sized areas of the vector space):

homogeneity h	Interpretation
h <= 0	There is no special homogeneity. Every point is completely random, with equal probability distribution over the whole box area. In Poisson terminology, this corresponds to infinitesimal small Poisson intervals, or alternatively the whole box as one spatial region. This is new with respect to eclipse.
1 <= h <= N	Respectively h points will have a certain minimum distance $d_{min}$ , this means that the theoretical maximum number of points in a closer distance (inside this one spatial region) is N - h + 1.
h >= N	The criterion of a minimum distance limit is applied to each pair of points. This means, that within any spatial region with the radius $\frac{d_{min}}{2}$ , the rate function is zero for a number of 2 or greater (i.e. that in such a region, only none or one point may occur).

Minimum Point Distance:

For a homogeneity factor h = N, a minimum distance for events is defined. For a box size of $S_x\cdot S_y$ (= N) points this minimum distance is defined as

$d_{min} = \sqrt{ S_x \cdot S_y \cdot \frac{1}{(N+1) \cdot \sqrt{2}} }.$

This ensures a global homogeneity in the output point set, featuring spatial regions with radius $\frac{d_{min}}{2}$ with at most one point inside.

With a specified homogeneity factor 1 <= h <= N, the distance criterion applies for any h consecutive points in the final output, but not for the whole point set. This results in groups of h points which satisfy the distance criterion, without constraining the whole set, or in other words which results in a maximum limit of N - h + 1 points inside one spatial region with radius $\frac{d_{min}}{2}$ .
With a homogeneity factor h, the minimum distance $d_{min}$ is defined as

$d_{min} = \sqrt{ S_x \cdot S_y \cdot \frac{1}{(h+1) \cdot \sqrt{2}} }.$

The homogeneity factor influences this minimum distance. A homogeneity of 1 means a high minimum distance but small groups of points whose distance must conform to this. A homogeneity of N means a smaller minimum distance but that this applies to all points, which results in the most homogenous distribution which can be generated using this function.

Integer Coordinates:

If the specified type is CPL_TYPE_INT, then integer coordinates are created by rounding the internally determined random coordinates.

Rounding equally distributed real numbers in a range between two natural numbers means, that both the first and the last natural numbers have only half of the occurrence probability than the natural numbers inbetween (e.g. rounding real numbers between 1 and 3 results in 25% 1's (for real numbers between 1 and 1.5), 50% 2's (1.5 ... 2.5), and 25% 3's (2.5 ... 3)). Therefore the creation box is internally enlarged by 0.5 on each border. So in the case of integers, it is:
$S_x = |x_B - x_A| + 1$

, and

.

Due to the rounding, in fact the minimum distance that can occur is:

$d_{min, INT} = d_{min} - \sqrt{2}$

Rounding also means, that theoretically equal points can be generated. This can be avoided by using a homogeneity factor of h = N, and ensuring that the minimum distance is greater than one pixel diagonal: $d_{min, INT} \geq \sqrt{2}$ , what results in

$N \leq \frac{1}{8\sqrt{2}}\cdot S_x \cdot S_y - 1 = \\ \frac{1}{8\sqrt{2}}\cdot (|x_B-x_A|+1) \cdot (|y_B-y_A|+1) - 1,$

with $x_A,x_B,y_A,y_B\in \mathbf{N} , h = N$ .

Error Handling:

The following error codes can be set by this function:

CPL_ERROR_ILLEGAL_INPUT: N <= 0
CPL_ERROR_INVALID_TYPE: type is neither CPL_TYPE_INT nor CPL_TYPE_DOUBLE

Example:: (Error handling, CPL initialization etc. is omitted)
#include <cpl.h>

#include <clipm.h>

#include <time.h>

#include <stdlib.h>

#include <stdio.h>

int main (void) {

int *points;

int n, number = 13, homog = 0;

srand(time(NULL));

// create 13 points in a rectangle

// of width 100 and height 50

points = (int*)clipm_math_rng_poisson_pointpattern_2d(

1,

1,

100,

50,

homog,

number,

CPL_TYPE_INT);

for (n = 0; n < number; n++)

printf( "Point %2d: (%3d, %3d)\n",

n+1,

points[2*n],

points[2*n+1]);

cpl_free(points);

return 0;

}

*

Todo:

default values?
error handling
optimize computation, and test using same random initialization
Correct eclipse bugs:
- first entry always (0,0): done
- round error for negative numbers: done
- correct rectangle limits for integers: done

double clipm_math_rng_uniform50 ( void )

Generate random number between 0 and 1.

Returns: Random number of type double between 0 and 1 (excluding)

Note: Before usage, the random number generation should be initialized once using the C function srand().

Overview:: This function provides double random numbers while still conforming to strict ANSI-C. This way it is portable in contrary to the SVID standard function drand48(), which is not available on all systems.

Error Handling:: No runtime errors can occur in this function.

Example:: (Error handling is omitted)
#include <clipm.h>

#include <time.h>

#include <stdlib.h>

#include <stdio.h>

int main (void) {

int i;

srand(time(NULL));

for (i = 1; i <= 10; i++) {

printf( "%2d. Random: %f\n",

i,

clipm_math_rng_uniform50());

}

return 0;

}

*

Functions

Detailed Description

Function Documentation