SDT-base         Contents     Functions         Previous Next     PDF Index

fe_range

Purpose

fe_range commands are used to manipulate experiment (series of design points) specifications.

Description

Experiments (series of design points) are used extensively in SDT. The figure below describes a 3 D design space with selected points. fe_range is used to generate experiment descriptions fe_range Build, run the solutions fe_range Loop and manipulate the associated results fe_range DirScan.


Figure 10.4: Sample experiments. a) Hypercube face center. b) Classical 2NP factorial plan.

A range structure is the description of a set design points through a data structure with fields

.param fields must match string values in .lab. Each field is a struct with possible fields

Commands

Build[R,stra,URN]

Build commands handle generation of the Range structure.

Range=fe_range('Buildstra',par);
Range is defined by a grid of all the parameter values defined in par.

par is expected to be either

By default a grid type is generated. As an illustration, following example defines a grid 6x7 of 2 parameters named length and thickness

Range=fe_range('BuildGrid',struct('length',1:3, ...
   'thickness',[1 2],'Name',{{'a','data_for_a';'b','data_for_b'}}))
Range=fe_range('BuildGrid',Range);
fe_range('Tree',Range);

% String format (to be phased out)
par={'lab "length" min 10 max 20 cur 10 scale "lin" NPoints 6',...
     'lab "KCoupling" min 4 max 8 cur 1e6 scale "log" NPoints 7'};
Range=fe_range('BuildGrid',par);
fe_range('Tree',Range);

A Range type must be defined by token stra. The following strategies are supported

Accepted options are

Range=fe_range('BuildVect',par);
Simply concatenate all parameter ranges (they must have the same length) into a functional Range. par has the same format than for the fe_range BuildGrid input. In addition, all par entries provided should have the same number of points.

Vect command is used to generate single par structures to feed Range.param entries.

par={'lab "length" min 10 max 20 cur 10 scale "lin" NPoints 7',...
     'lab "thickness" min 1e-3 max 2e-3 cur 0 scale "log" NPoints 7'};
Range=fe_range('BuildVect',par);


DirScan

Scans a directory mat files and provides displayable information about property variations. It is assumed that files are saved with a variable RO (for Run Options) in struct format, each option considered as a field. Command DirScan will build a synthesis between constant and variable options, by providing in output a structure RB with fields

By default DirScan saves a file named RangeScan.mat in the scanned directory. This file contains the output to avoid scanning if possible. By default scanning is skipped if the file RangeScan.mat exists, refers to the same search in the dirlist field and if this file is more recent than all files to be scanned.

Options sorting is performed by the flatParamFcn. Typical options are hierarchically sorted in nested structure format that gather parameters of the same type, or belonging to a configuration set. To ensure a clean view of varying parameters, the hierarchical structure has to be flattened, that is to recursively flush back all nested structure fields to the root structure. The default flatParamFcn only performs this simple operation, one should not use identical parameter names in different locations.

For advanced applications it is recommended to add intelligence to the flatParamFcn to help sorting relevant parameters, possibly remove some irrelevant ones and to convert complex options into human readable format. The typical call to flatParamFcn is

r1=feval(flatParamFcn,fname,RO);

The output r1 is in the same format than output RConstant field, that is a two column cell array with fieldnames in first column defining found parameters and a second column containing current values for the currently scanned file.

Input fname is a structure with field fname providing the file name containing a parameter structure names RO. Input RO is a structure with fields wd providing the name of the scanned directory and Content, a cell array that will keep track of all parameter field names encountered during scanning.

A sample call would be

% Example of flatParamFcn behavior
% build a dummy result file with a parameter structure
tname=nas2up('tempname_RES.mat');
% sample 2 level parameter structure
RO=struct('MeshCfg',...
struct('lc',4,'name','toto'),...
'SimuCfg',...
struct('dt',1e-2','Tend',10));
% save RO in result file
save(tname,'RO');
% Options to call flatParam
R1=struct('flatParamFcn',fe_range('@flatParam'),'wd',pwd,'Content',{{}});
% call to flatParam
[r1,RO]=feval(R1.flatParamFcn,struct('fname',tname),R1);
delete(tname); % clean up example

Command DirScan takes a structure in input with fields

The following command options are accepted

fname [,LabCell,Labdef]

Design point labelling function. This function generates a list of strings describing parameters values for each point of Range. It can be used for direcory or file naming and datatip labelling for example.

This functionality is controlled by the field Range.FileName. It is a cell array providing a list of entries to be interpreted that will form the label: in that cell array, each string starting with '@' is dynamically replaced depending on the current parameters values. The name is then generated by concatenating the resolved cell array.

For a parameter value to be integrated in the label, field .FileName must contain a dynamic reference to the parameter in one of its cells e.g. @par for parameter name par. By default a string of the type par=value will be generated with par the parameter name and value a string interpretation of the parameter current value. One can alter this behavior by providing rules on in the parameter description structure stored in Range.param.

Command option dir forces names to be compatible with directories naming requirements.

% Label generation from Range values
% Generate a Range structure with 3 parametered values
Range=fe_range('BuildGrid',struct('length',1:3, ...
   'thickness',[1 2],'Name',{{'a','data_for_a';'b','data_for_b'}}))
% Name built out of differnt labels:
% provide labelling rule with cell sequence
Range.FileName={'Root','@length','@thickness','@Name'};
fe_range('fname',Range) %display results
% Alter the interpretation of thickness values
Range.param.thickness.LabFcn='sprintf(''h=%.1f'',val)';
fe_range('fname',Range)%display results
% Remove parameter name reference for thickness
Range.param.thickness.ShortFmt=1;
fe_range('fname',Range)%display results

GeneLoop

Provides a genetic algorithm implementation inspired from the NSGA-II [57].

Command GeneLoop peforms the complete loop, taking into argument a set of parameters in a cell array, and a parameter structure with fields

The logic is to exploit a discretized pool gene based on a Range structure with available parameters. From a randomly chosen initial population using randi of size .PopSize, individuals are selected for mating, based on their fitness in a tournament phase. The tournament consists in running .MatSize tours in which the fittest individual is taken between .NbTour randomly picked candidates. The .MatSize selected individuals are then mated with a crossover and mutation strategy to produce a children gene pool of size PopSize. Crossover and mutation are sequential events. First, a crossover generates one child from two randomly picked parents in the mating pool (based on randperm) each gene is randomly picked from one or the other parent. Each gene can then mutate with a probability event driven by .RatioMut (based on rand threshold). In case of a mutation event, the gene will be forced to mutate by taking another available value in the gene pool. The children gene pool is forced to be gene combinations that have not been tested before. The parent and children populations are then combined, and only the .PopSize fittest individuals are kept for the next generation, ensuring elitism.

The output is a Range structure with field .val containing the current population, .Res the fitness values of the current population, .val0 the archive of all tested individuals, .Res0 the archive of fitness values of all tested individuals.

% define a set of parameters with discretized varying values
par={'lab "p1" min 10 max 20 cur 10 scale "lin" NPoints 100',...
  'lab "p2" min 1 max 100 cur 1 scale "lin" NPoints 100',...
  'lab "p3" min 2 max 5 cur 100 scale "log" NPoints 100'};
 
% define a callback function updating Range.Res 
% with fitness function based on Range.val
RunExp=@(x,~)setfield(x,'Res',abs(sqrt(x.val(:,1)+x.val(:,2).^3)-x.val(:,3)));

% Define genetic algorithm options
RO=struct('MaxGen',100,'PopSize',25,'MatSize',10,'NbTour',4,...
 'RatioMut',0.4,'RunExp',RunExp,'Optim','min');

% Run genetic algorithm
Range=fe_range('GeneLoop',par,RO);
 

labFcn

Loop

Loop the generic handler of parametric studies.

Standard calls are:

fe_range('Loop',Range,RO)
fe_range('Loop',Range,UI,RO)

RO is (you can also see the full list in sdtweb fe_range LoopRO)

Res

R1=fe_range('Res',R1,Range);
This command reshapes the last dimension of the result curve R1 according to the Range. For a grid DOE last dimension is split in as many dimensions as parameters. For a vector DOE, last dimension is only redefined by a cell array of labels defining each design point.

The following command options are available

Sel

This command allows selection of design points in a series of experiments described by a Range structure. The main output is the indices in Range.val rows corresponding to the sequential application of selection rules.

The selection rules a provided in a cell array of three columns and as many lines as rules to apply under the format
{param_name,'rule','crit';...}.
The following types of rules are supported, defined by a string,

Excepted for sortrows, other rules are sequentially applied to the current sampled Range. Sorting is thus only fully effective if last performed.

The optional .SortCol field can be used to specify a reformatting of the indices as a multi-dimensional grid.

Stats

fe_range('Stats',UI,sel,RA);
This command can be used to call a stack of post-treatments for a subpart of all computation results that have been priorly scanned through the DirScan command, and then displayed in the RVar tab. Results of the Stats command is a Stats tab in the UI.

UI is the interface data (where the Stats tab will be displayed), that can be obtained through the MainFcn('ParamUI') command. If it is left empty (UI=[]), sdtroot interface is implicitely defined.

sel is a selection cell array to select a sub set of results in all scanned results. See Sel for more details. If sel is empty (sel={}), all results are post-treated.

RA defines the post-treatments to be computed from selected results. It is a data structure with following fields:

Simple

Generates a set of experiments with sequential variation of each parameter, the other ones being fixed to their nominal value. par has the same format than for the fe_range BuildGrid input. They may feature a field nom providing a nominal value to each parameter, if this field is omitted the nominal value is considered to be the starting value of the parameter. In the case where par has been defined as a string input, field nom is taken to be the cur input value.

par={'lab "length" min 10 max 20 cur 10 scale "lin" NPoints 6',...
     'lab "thickness" min 1e-3 max 2e-3 cur 0 scale "log" NPoints 7'};
Range=fe_range('Simple',par);

UI Tree

Basic display of an experiment design as a tree. See also the sdtroot version.

par={'lab "length" min 10 max 20 cur 10 scale "lin" NPoints 6',...
     'lab "thickness" min 1e-3 max 2e-3 cur 0 scale "log" NPoints 7'};
Range=fe_range('Simple',par);
fe_range('Tree',Range);
sdtroot('setRange',Range); % Initialize range in PA.Range
PA=sdtroot('PARAMVh');PA.Range
sdtroot('InitRange'); % Initialize display

Val

Val commands are used to ease range manipulations.

ValCell

r2=fe_range('ValCell',Range);
This command can be used to convert a Range.Val as a cell array with as many rows as Range.val and each row of the form param1, val1, param2 val2, .... One can give ind as a 2nd argument, with the indices of rows to convert.


©1991-2024 by SDTools
Previous Up Next