GALAHAD LHS package#

purpose#

The lhs package computes an array of Latin Hypercube samples.

Currently only the options and inform dictionaries are exposed; these are provided and used by other GALAHAD packages with Python interfaces. Please contact us if you would like full functionality!

See Section 4 of $GALAHAD/doc/lhs.pdf for a brief description of the method employed and other details.

parametric real type T#

Below, the symbol T refers to a parametric real type that may be Float32 (single precision) or Float64 (double precision). Calable functions as described are with T as Float64, but variants (with the additional suffix _s, e.g., lhs_initialize_s) are available with T as Float32.

callable functions#

    function lhs_initialize(data, control, inform)

Set default control values and initialize private data

Parameters:

data	holds private internal data
control	is a structure containing control information (see lhs_control_type)
inform	is a structure containing output information (see lhs_inform_type)

    function lhs_read_specfile(control, specfile)

Read the content of a specification file, and assign values associated with given keywords to the corresponding control parameters. An in-depth discussion of specification files is available, and a detailed list of keywords with associated default values is provided in $GALAHAD/src/lhs/LHS.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/lhs.pdf for a list of how these keywords relate to the components of the control structure.

Parameters:

control	is a structure containing control information (see lhs_control_type)
specfile	is a one-dimensional array of type Vararg{Cchar} that must give the name of the specification file

    function lhs_ihs(n_dimen, n_points, seed, X, control, inform, data)

The improved distributed hyper-cube sampling algorithm.

Discussion:

n_points points in an n_dimen dimensional Latin hyper-cube are to be selected. Each of the coordinate dimensions is discretized to the values 1 through n. The points are to be chosen in such a way that no two points have any coordinate value in common. This is a standard Latin hypercube requirement, and there are many solutions.

This algorithm differs in that it tries to pick a solution which has the property that the points are “spread out” as evenly as possible. It does this by determining an optimal even spacing, and using the DUPLICATION factor to allow it to choose the best of the various options available to it.

Reference:

Brian Beachkofski, Ramana Grandhi, Improved Distributed Hypercube Sampling, American Institute of Aeronautics and Astronautics Paper 2002-1274

Parameters:

n_dimen	is a scalar variable of type int that specifies the spatial dimension
n_points	is a scalar variable of type int that specifies the number of points to be generated
seed	is a scalar variable of type Int32 that gives a seed for the random number generator used
X	is an array variable of type int with dimensions [n_dimen][n_points] that gives the hyper-cube points
control	is a structure containing control information (see lhs_control_type)
inform	is a structure containing output information (see lhs_inform_type)
data	holds private internal data

    function lhs_get_seed(seed)

Get a seed for the random number generator.

Parameters:

seed	is a scalar variable of type int that gives the pseudorandom seed value.

    function lhs_information(data, inform, status)

Provides output information

Parameters:

data

holds private internal data

inform

is a structure containing output information (see lhs_inform_type)

status

is a scalar variable of type Int32 that gives the exit status from the package. Possible values are (currently):

0
The values were recorded successfully

    function lhs_terminate(data, control, inform)

Deallocate all internal private storage

Parameters:

data	holds private internal data
control	is a structure containing control information (see lhs_control_type)
inform	is a structure containing output information (see lhs_inform_type)

available structures#

lhs_control_type structure#

    struct lhs_control_type
      error::Int32
      out::Int32
      print_level::Int32
      duplication::Int32
      space_critical::Bool
      deallocate_error_fatal::Bool
      prefix::NTuple{31,Cchar}

detailed documentation#

control derived type as a Julia structure

components#

Int32 error

error and warning diagnostics occur on stream error.

Int32 out

general output occurs on stream out.

Int32 print_level

the level of output required. Possible values are:

< 1 no output.
> 0 debugging.

Int32 duplication

the duplication factor. This must be at least 1, a value of 5 is reasonable.

Bool space_critical

if .space_critical true, every effort will be made to use as little space as possible. This may result in longer computation time.

Bool deallocate_error_fatal

if .deallocate_error_fatal is true, any array/pointer deallocation error will terminate execution. Otherwise, computation will continue.

NTuple{31,Cchar} prefix

all output lines will be prefixed by .prefix(2:LEN(TRIM(prefix))-1) where .prefix contains the required string enclosed in quotes, e.g. “string” or ‘string’

lhs_inform_type structure#

    struct lhs_inform_type
      status::Int32
      alloc_status::Int32
      bad_alloc::NTuple{81,Cchar}

detailed documentation#

inform derived type as a Julia structure

components#

Int32 status

return status. Possible values are:

0

The call was successful.
-1

An allocation error occurred. A message indicating the offending array is written on unit control.error, and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively.
-2

A deallocation error occurred. A message indicating the offending array is written on unit control.error and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively.
-3

The random number seed has not been set.

Int32 alloc_status

the status of the last attempted allocation/deallocation.

NTuple{81,Cchar} bad_alloc

the name of the array for which an allocation/deallocation error occurred.

Index