traverse_grid - Traverse an N-dimensional grid of points

The *traverse_grid* module defines three types with accompanying routines
to traverse a block of grid points through N-dimensional space. The types
have different purposes:

Objects of the type

*grid_traversing*can be used to traverse a grid along all the grid points. These objects use integer coordinates only.The type

*grid_coordinates*traverses a grid along the same grid points but you can convert the indices to (real) coordinates of the midpoints.The type

*grid_sampler*is meant to sample the grid points in a quasi-random way. It is useful as an alternative to Monte Carlo, because the selected points are more uniformly distributed. (See the test program for an example.)

The idea is that the N-dimensional space in question is split up into rectangular cells with indices running from 0 up to but not including a maximum value. This maximum can differ per dimension.

Traversing such a grid, for instance a 4 by 3 grid, gives the following ordering of the points;

2| 9 10 11 12 1| 5 6 7 8 0| 1 2 3 4 +---+---+---+---+ 0 1 2 3

That is, the grid points are visited in the shown order, with indices (0,0), (1,0), ... (0,1), (0,2), ..., (3,2).

All three types can return the raw indices, but the *grid_coordinates* and *grid_sampler*
types can also return the actual coordinates (real numbers).

The *grid_sampler* type samples the grid points using steps of the size of a prime,
so that the whole space is effectively covered in a fairly small number of samples.

Each type contains a number of methods:

**call traverse%init( dimensions, max_index )**Initialise a

*grid_traversing*object with uniform dimensions, that is, each index runs from 0 to*max_index-1*.- integer
*dimensions* The number of dimensions

- integer
*max_index* The maximum index for each dimension (actually the index runs up to that value, but does not reach it)

- integer
**call traverse%init( max_index )**Initialise a

*grid_traversing*object with different dimensions, that is, index i runs from 0 to*max_index(i)-1*.- integer, dimension(:)
*max_index* The maximum index per dimension. The number of dimensions is equal to the size of the array.

- integer, dimension(:)
**call coordinates%init( max_index, range )**Initialise a

*grid_coordinates*object with uniform dimensions, that is, each index runs from 0 to*max_index-1*. The*range*argument contains the minimum and maximum values of the coordinates. The number of dimensions is equal to the second dimension of*range*(that is,*size(range,2)*).- integer
*max_index* The maximum index for each dimension (actually the index runs up to that value, but does not reach it)

- real(kind=wp), dimension(2,:)
*range* The minimum (

*range(1,:)*) and the maximum (*range(2,:)*) coordinate per dimension. This is used to determine the midpoint coordinates of a cell.

- integer
**call coordinates%init( max_index, range )**Initialise a

*grid_coordinates*object with uniform dimensions, that is, index i runs from 0 to*max_index(i)-1*. The*range*argument contains the minimum and maximum values of the coordinates. The number of dimensions is equal to the second dimension of*range*(that is,*size(range,2)*), but the size of*max_index*should be equal to that.- integer, dimension(:)
*max_index* The maximum index per dimension

- real(kind=wp), dimension(2,:)
*range* The minimum (

*range(1,:)*) and the maximum (*range(2,:)*) coordinate per dimension.

- integer, dimension(:)
**call sampler%init( max_index, range )**Initialise a

*grid_sampler*object, analogous to the initialisation of a*grid_coordinates*object. Both variants are allowed.**call object%reset**Resets the current point in a

*grid_traversing*,*grid_coordinates*or*grid_sampler*object to the point with indices all zero.**indices = object%indices()**Returns the indices of the current point in a

*grid_traversing*,*grid_coordinates*or*grid_sampler*object. The receiving variable must be an array of the correct dimension.**coords = object%coords()**Returns the coordinates of the current point in a

*grid_coordinates*or*grid_sampler*object. The receiving variable must be an array of the correct dimension.**call object%next( indices )**Determine the next point for a

*grid_traversing*,*grid_coordinates*or*grid_sampler*object. The argument*indices*will contain the indices of this new point.- integer, dimension(:), optional
*indices* The indices for the new point.

- integer, dimension(:), optional

Copyright © 2013 Arjen Markus <arjenmarkus at sourceforge dot net>