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.

callable functions

overview of functions provided

// namespaces

namespace conf;

// typedefs

typedef float spc_;
typedef double rpc_;
typedef int ipc_;

// structs

struct lhs_control_type;
struct lhs_inform_type;

// global functions

void lhs_initialize(
    void **data,
    struct lhs_control_type* control,
    struct lhs_inform_type* inform
);

void lhs_read_specfile(struct lhs_control_type* control, const char specfile[]);

void lhs_ihs(
    ipc_ n_dimen,
    ipc_ n_points,
    ipc_ *seed,
    int** X,
    const struct lhs_control_type* control,
    struct lhs_inform_type* inform,
    void **data
);

void lhs_get_seed(int *seed);
void lhs_information(void **data, struct lhs_inform_type* inform, ipc_ *status);

void lhs_terminate(
    void **data,
    struct lhs_control_type* control,
    struct lhs_inform_type* inform
);

typedefs

typedef float spc_

spc_ is real single precision

typedef double rpc_

rpc_ is the real working precision used, but may be changed to float by defining the preprocessor variable REAL_32 or (if supported) to __real128 using the variable REAL_128.

typedef int ipc_

ipc_ is the default integer word length used, but may be changed to int64_t by defining the preprocessor variable INTEGER_64.

function calls

void lhs_initialize(
    void **data,
    struct lhs_control_type* control,
    struct lhs_inform_type* inform
)

Set default control values and initialize private data

Parameters:

data	holds private internal data
control	is a struct containing control information (see fit_control_type)
inform	is a struct containing output information (see fit_inform_type)

void lhs_read_specfile(struct lhs_control_type* control, const char 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	a struct containing control information (see above)
specfile	a character string containing the name of the specfile

void lhs_ihs(
    ipc_ n_dimen,
    ipc_ n_points,
    ipc_ *seed,
    int** X,
    const struct lhs_control_type* control,
    struct lhs_inform_type* inform,
    void **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 ipc_ that specifies the spatial dimension
n_points	is a scalar variable of type ipc_ that specifies the number of points to be generated
seed	is a scalar variable of type ipc_, that gives a seed for the random number generator used
X	is an array variable of type ipc_ with dimensions [n_dimen][n_points] that gives the hyper-cube points
control
inform
data	see lhs_initialize

void lhs_get_seed(int *seed)

Get a seed for the random number generator.

Parameters:

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

void lhs_information(void **data, struct lhs_inform_type* inform, ipc_ *status)

Provides output information

Parameters:

data	holds private internal data
inform	is a struct containing output information (see lhs_inform_type)
status	is a scalar variable of type ipc_, that gives the exit status from the package. Possible values are (currently): 0 The values were recorded successfully

void lhs_terminate(
    void **data,
    struct lhs_control_type* control,
    struct lhs_inform_type* inform
)

Deallocate all internal private storage

Parameters:

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

available structures

lhs_control_type structure

#include <galahad_lhs.h>

struct lhs_control_type {
    // fields

    ipc_ error;
    ipc_ out;
    ipc_ print_level;
    ipc_ duplication;
    bool space_critical;
    bool deallocate_error_fatal;
    char prefix[31];
};

detailed documentation

control derived type as a C struct

components

ipc_ error

error and warning diagnostics occur on stream error.

ipc_ out

general output occurs on stream out.

ipc_ print_level

the level of output required. Possible values are:

• < 1 no output.

• > 0 debugging.

ipc_ 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.

char prefix[31]

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

#include <galahad_lhs.h>

struct lhs_inform_type {
    // fields

    ipc_ status;
    ipc_ alloc_status;
    char bad_alloc[81];
};

detailed documentation

inform derived type as a C struct

components

ipc_ 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.

ipc_ alloc_status

the status of the last attempted allocation/deallocation.

char bad_alloc[81]

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

Index

example calls

This is an example of how to use the package to … ; the code is available in $GALAHAD/src/lhs/C/lhst.c .

The floating-point type rpc_ is set in galahad_precision.h to double by default, but to float if the preprocessor variable SINGLE is defined. Similarly, the integer type ipc_ from galahad_precision.h is set to int by default, but to int64_t if the preprocessor variable INTEGER_64 is defined.

/* lhss.c */
/* Spec test for the LHS C interface */

#include <stdio.h>
#include <math.h>
#include "galahad_precision.h"
#include "galahad_cfunctions.h"
#include "galahad_lhs.h"

int main(void) {

    // Derived types
    void *data;
    struct lhs_control_type control;
    struct lhs_inform_type inform;

    // Initialize LHS
    lhs_initialize(&data, &control, &inform);

    // Parameters
    ipc_ n_dimen = 7; // dimension
    ipc_ n_points = 2; // points required
    ipc_ X[n_dimen][n_points]; // points
    ipc_ seed;

    // Set a random seed
    lhs_get_seed(&seed);

    // Generate points
    lhs_ihs(n_dimen, n_points, &seed, (ipc_**)X, &control, &inform, &data);
    if(inform.status == 0){ // successful return
        printf("LHS successful\n");
        for(ipc_ j = 0; j < n_points; j++){
            printf("Point %" d_ipc_ " = ", j);
            for(ipc_ i = 0; i < n_dimen; i++){
                printf("%" d_ipc_ " ", X[i][j]);
            }
            printf("\n");
        }
    }else{ // error returns
        printf("LHS exit status = %" d_ipc_ " \n", inform.status);
    }

    // Delete internal workspace
    lhs_terminate(&data, &control, &inform);

    return 0;
}