Automatically characterise borders in a parameter space

Repeatedly subdivide borders in some parameter space that separate regions of differing state

Usage: [mfParams, mbState, vfShadingVal] = ParameterRegions(fhEvalFun, mfParamsRange, vfMinSpacing, vfJitter, bHighResBorders, fhPlotFunction, nNumPointsInit);
Explore a parameter space through recursive subdivision, using an arbitrary metric function to make decisions about subdivision. This function tries to numerically characterise borders separating regions in parameter space, by measuring the output of a user-defined function, and subdividing points in parameter space that result in different binary measures.

--- Parameter evaluation function ---

The function 'fhEvalFun' must have the signature:

function [vbState, fScalarMeasure] = fhEvalFun(fParam1, fParam2, ..., fParamN);

'vbState' is a logical vector, defining several yes or no characteristic variables that apply to the parameter combination passed as arguments to 'fhEvalFun'. 'fScalarMeasure' is an arbitrary scalar quantity that applies at the same point in parameter space.

For example, 'vbState(1)' could signal whether the requested point in parameter space corresponds to a stable or unstable system. 'vbState(2)' could signal the satisfaction of some other constraint concerning the system. 'fScalarMeasure' could return an estimate of the time taken to reach a fixed point of a dynamic system.

ParameterRegions will then repeatedly evaluate 'fhEvalFun' over an appropriate parameter space, while subdividing the mesh more finely over spaces within the space where elements of 'vbState' differ between points in the space.

NOTE: 'fhEvalFun' is must be a deterministic function, such that each evaluation for a given parameter combination produces the same state and scalar measure. ParameterRegions does not perform multiple sampling or averaging to analyse the parameter space.

--- Input arguments ---

ParameterRegions will automatically construct a parameter mesh spanning 'mfParamsRange', which is an Nx2 matrix, with each row ['fMin' 'fMax'] signalling the range for the corresponding parameter to be evaluated over. The number of rows of 'mfParamsRange' corresponds to the number of parameters passed to 'fhEvalFun'. If a particular parameter should not be varied, then the corresponding row of 'mfParamsRange' should have identical 'fMin' and 'fMax'.

The optional parameter 'vfMinSpacing' is a Nx1 vector, with each entry defining the minimum desired spacing for the corresponding parameter. Subdivision will not occur between two points in parameter space that are closer than the corresponding entries in 'vfMinSpacing'. By default, 'vfMinSpacing' will be set at a 100th of the range for the corresponding parameters in 'mfParamsRange'.

The optional parameter 'vfJitter' is a Nx1 vector, with each entry defining the amount of noise to be added to a location in parameter space. By default, 'vfJitter' is set to half of 'vfMinSpacing'.

The optional parameter 'bHighResBorders' is a logical flag which determines whether or not the edges of the parameter space are sampled at higher resolution than the contained volume. By default it is 'false'. NOTE This facility is currently not implemented.

- Plotting function -

The optional parameter 'fhPlotFunction' defines a function handle that is called at the end of each batch evaluation of 'fhEvalFun', which can be used to plot the parameter space. It must have the signature:

function fhPlotFunction(mfParams, mbStates, vfShadingVal)

where 'mfParams' is an MxN matrix, defining the M points in the N-imensional parameter space that have been sampled so far. 'mbSstates' is an MxP logical matrix, with each row specifying the vector of states associated with the corresponding point in parameter space. 'vfShadingVal' is an Mx1 vector, which each entry specifying the scalar quantity associated with the corresponding point in parameter space. The entries of 'mbStates' and 'vfShadingVal' are the values that are returned by 'fhEvalFun' for each point in parameter space.

By default, if only a 2D parameter space is being sampled, ParameterRegions contains a built-in plotting function that displays the plane in parameter space that is being sampled, plotting only the sampled points that subdivide the parameter space according to 'vbStates', and plotting the scalar values returned by 'fhEvalFun' as a shaded surface. If a 'nan' is returned as a scalar value, no surface is plotted at that point.

The optional parameter 'nNumPointsInit' defines the inital sampling density of the parameter space mesh. 'nNumPointsInit' samples will be placed along each dimension in parameter space. By default, 20 initial samples will be made.

--- Return arguments ---

'mfParams' will be an MxN matrix, where each row contains a set of values defining a point in the N-dimensional parameter space.