Ctrl+K

fe_range

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

  • .val numeric array containing one design point per row and one design parameter per column.
  • .lab cell array of strings giving a parameter label for each column. These labels should be acceptable field names (no spaces, braces, ...)
  • .param optional structure with fields associated with parameter labels used for formatting and analysis. Accepted values are detailed below. It is not necessary to define a .param field for each design parameter.

    param.MainFcn={FcnHandle,'command'} can be used specify the user handling function in fe_range Loop.

  • .edge optional connectivity matrix used to define lines connecting different design points of the experiment
  • .FileName optional cell array of strings used to build file names associated with each experiment with command fe_range fname.

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

  • .type a string. Typically double or pop.
  • .choices, for .type='pop', contains a cell array of strings. The parameter value then gives the index within .choices.
  • .data possible cell array containing data associated with the .choices field.
  • .LabFcn a command to be evaluated with st1=eval(r2.LabFcn) to generate the proper label. For example 'sprintf("%.1f ms",val/1000)' is used to generate a label in a different unit. For choices, the default is r2.choices{val};.. Use .ShortFmt=1 to avoid adding the Field= to the string.
  • .Xlab long name to be used to fill Xlab when generating curve data structures.
  • .level is an integer specifying the computational step at which a given parameter can be modified. This is used to generate tree type experiments.
  • .uProp is a cell array giving a coefficient to go from value to engineering unit and a string for the unit. Or a structure with fields .coef multiplicative coefficient to go from storage value in val to display value. .coef can be a callback string based on the assumption that the value is in a val variable. .Xlab to be used for display after unit conversion, .unit string for unit of storage value. .fmt java formatting for display in tables.
  • .nom optional, defines the parameter nominal value. This is used to evaluate the nominal version of values and is required in the case where one uses absolute values.
  • .mode optional string, defines the parameter application modality from declared values. It can be either Rel to declare that the value associated to the parameter will be directly used, or Abs in which case a relative value is generated by dividing by the nominal value (if defined and non-zero, 1 is taken otherwise).
  • .SetFcn={fun,command} provides the callback used in fe_range Loop to execute parameter setting.
  • .RepList={tokenString,subsasgn} optionally provides the mechanism to aggregate parameter modifications in a Loop step. For example, {'Acq_(.*)',struct('type','.','subs',{{'@token{1}'}})} will merge .Acq_t parameter as .t field.

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

  • a structure where each field will be a parameter (for example struct('a',(1:3)','b',(1:2)'). For configurations, the field can contain a cell array with the configuration name and associated data (for example struct('MesCfg',{'a',data1;'b',data2}). To allow easier connection with graphical interfaces, the value can be replaced by a structure struct('a',struct('Eval','1:3')). Note that .param is a reserved field.
  • a cell array defining parameters. Each cell can be
    • a range data structure. This is for example used for visco parameter definitions (see fevisco Range for more details).
    • (to be phased out) a string 'lab "label" min min max max cur cur scale "scale" NPoints NPoints'. "label" is the parameter name. Then the minimum, maximum and nominal values are defined. Scale can be "lin" for linear scale or "log" for logarithmic scale. NPoints defines the number of point for the parameter vector.
    • (to be phased out) a numeric vector in the old upcom format [type cur min max scale] with type defining the matrix type (unused here), scale==2 indicates a logarithmic variation.

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

  • Grid Generates a grid type, with all possible parameter combinations.
  • Vect generates a vector for a single parameter or a matrix with all parameters varying (the initial definition of each vector must have the same length).
  • Simple Generates a sequential parameter combination. One parameter varies at a time, the others being kept at their nominal value.
  • randperm Generates a Latin Hypercube Sampling on the parameters, the initial definition of each vector must have the same length, and the number of samples must be provided in the command, using BuildType"randperm"ns with ns the number of samples.
  • URN lets one quickly generate and compose Range structures. The syntax accepts a string following the urn format to define the Range as a tree whose leaves are parameters and branches a composition of Range types. e.g Grid(p1{x1... xn}:p2{y1...ym}) defines a factorial range with parameter p1 taking values x1 to xn and parameter p2 taking values y1 to ym. The following definition rules hold
    • It is possible to define parameters in a more refined way (with usual formatting options) by providing it in a .param field in option arguments and leaving its definition empty, as p1{}.
    • Range composition goes as
      • a composition type is applied to the substring in parentheses
      • parameters are defined as their name with taken values between braces
      • parameters in the same composition are separated by a semicolon
      • different ranges composition are separated by a semicolon 
    % Build a Range with to parameters taking coupled values, in factorial analysis on a third one
st='Grid(Vect(p1{1,22}:p2{5,6}):Vect(p3{1:3}))';
Range=fe_range('BuildURN',st)
% Alternate definition with param that can allow advaced parameter definition
 RO=struct('urn','Grid(Vect(p1{}:p2{}):Vect(p3{}))',...
'param',{{struct('val',[1;22],'lab','p1'),struct('val',[5;6],'lab','p2'),...
struct('lab','p3','val',[1:3]')}})
 Ra1=fe_range('BuildURN',RO)
  • Rstra Generates reduced ranges spanning the parameters simplex. If omitted this token is set to MinMax the available strategies are
    • MinMax base point with all max, then successive set of one parameter to min. Dedicated variants include
      • MinMaxP to add the nominal configuration at the list end
      • MinMaxm to add the full minimal configuration at the list end
    • MinNom uses the first design point with the nominal values of each parameters, then variations with one parameter set to the minimum value while the other remain at their nominal value.
    • NomMax uses the first design point with the maximum values of each parameters, then variations with one parameter set to the nominal value while the other remain at their maximum value.
    • NomMin uses the first design point with the minimum values of each parameters, then variations with one parameter set to the nominal value while the other remain at their minimum value.
    • MaxMin uses the first design point with the minimum values of each parameters, then variations with one parameter set to the maximum value while the other remain at their minimum value.
    • MaxNom uses the first design point with the nominal values of each parameters, then variations with one parameter set to the maximum value while the other remain at their nominal value.
    • Nom only uses the nominal value of each parameters.
    • Grid generates a grid type, considering minimum and maximum values of each parameter (corners of a hypercube).
    Command option -flip allows generating a reverted list from down to bottom (flipud).
  • @cbk Allows customized definition, using cbk as a function handle. Range is sequentially built with a expansion applied for each parameter. The typical call at the j1-th parameter is 
    Range.val=cbk(Range.val,par{j1}.val,i1,RO);
    with Range.val the current Range before handling the j1-th parameter, par{j1}.val are the values considered for the j1-th parameter, i1 is the column index associated to the j1-th parameter in Range.val. RO is the current running option structure.

Accepted options are

  • replace >0 keep first value. 3 Reuse parameters in range.
  • level handles levels if present.
  • FileName augments the Range.FileName field if present.
  • diag in Grid type, takes the diagonal of the hypercube.

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

  • wd the scanned directory.
  • dirlist the file names scanned. (By default *.mat).
  • RVar a structure that can be displayed by comstr -17 in Java tabs. In its basic version it contains fields table that list the differing options between each scanned file, one per line, and a field ColumName that provides the relative varying option fields. This list is handled by the flatParamFcn as explained below.
  • RConstant a cell array with two columns providing the constant options for all scanned files. The first column contains the option fields and the second their value.

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

  • wd the directory to scan.
  • list the file names to scan. This allows restriction to filenames matching specific expressions. The default is *.mat.
  • flatParamFcn. A function handle to sort the running options, by defaultset to fe_range('@flatParam').
  • NoSave not to save the result in RangeScan.mat if set to one.

The following command options are accepted

  • -reset to force a new scanning.
  • -reload to force a reload of RangeScan.mat.

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.

  • .LabFcn: The interpretation of the parameter value can be given by field .LabFcn that will be evaluated using the variable name val as containing the current parameter current value.
  • .ShortFmt: To avoid a reference to the parameter name par= one can set field .ShortFmt to 1, thus triggering the short format mode.

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

  • .PopSize the population size,
  • .MatSize the mating group size,
  • .NbTour the number of candidates to retain for a tournament round,
  • .RatioMut the threshold ratio under which a gene mutation occurs when there is no crossover, between 0 (impossible) and 1 (always)
  • .Optim the extremum to consider for the fitness function, min or max
  • .RunExp the callback to the fitness function

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.

  • The outer loop performs a loop on rows of Range.val (design points)
  • For each design point, a loop on levels is performed. At a given level, an action is performed if .param.lab.SetFcn={'FcnName','Command'} is defined. When aggregating parameters of a given level (typically with a LabCfg parameter), it is expected that only the configuration parameter has a SetFcn and fe_range ValEvtMerge is called.
  • Range.param.MainFcn={'FcnName','Command'} is used to implement standard methods.

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)

  • .restart do a restart. Possibly associated with .rFile to specify file.
  • .StepStart defines the minimum step level to be computed. If omitted starts at 1.
  • .nSteps defines the maximum step level to be computed. If omitted, all steps are computed.
  • .Verbose define the verbosity level. 0 by default.
  • .WaitAt can be used to generate wait files at a given step number. It is then possible to open MATLAB slaves that will consume waiting files present in a given directory by calling sdtjob('StudySlaveStart reset',pwd). This provides a simple mechanism for parallel execution of a series of steps. It is however then expected that the step saves its results to a file that will not interact with other jobs.
  • .ifFail can be set to stop,skip,keyboard,error to control how errors are handled.

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

  • -varOnly to expand only varying parameters in Range. In such case, constant parameters are gathered in the last dimension of label RConst.
  • -varname to only extract parameter name from Range. For this to be possible, this parameter must be gridded against the remaining ones.
  • -noRConst not to keep dimension RConst when using -varOnly
  • -noParLab not to forward parameter LabFcn that possibly exist in Range to the .Xlab curve entry.

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,

  • ismember applies selection by only taking the values specified using MATLAB ismember command. crit is then either a list of values (then corresponding to values appearing in the DOE table), or a cell array of values (then corresponding to the values in the DOE table where string values are used for pop style parameters. Regular expressions are supported for the pop entries, in which case the string must start by # followed by the regular expression to apply.
  • <,>,<=,>=,== applies sampling by using the logical operator specified on the parameter values. crit is then a numerical value corresponding to the values appearing in the DOE table for all parameters.
  • sort applies a sorting algorithm for a given parameter. crit is then either
    • a string specifying an argument to the sort command of MATLAB, either ascend or descend. Support for pop types is provided based on alphabetical sorting.
    • a function_handle to a sorting function that will be called with the val or choices field of the parameter and that will rethrow the sorted values and the corresponding index to the unsorted values.
    • a cell array callback with first field a function_handle that will be called, the second entry will be replaced by the val or choices field of the parameter, and any further entries provided.
  • sortrows will perform a post-treatment of the sampled Range to the selection applied and output a java compatible table.

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:

  • .SortCols defines a subset and the order of input parameters to consider for stats output or display. Parameters must be RVar parameters.
  • .PostPar is a data structure with a .list field that defines the stack of post-treatments to be computed. PostPar.list is a cell array with as many rows as post-treatments to compute. Each row is of the form 'PostName' PostData. PostData is a cell array of the form {cbk data}.
    • cbk is callback cell array of the form {FcnHandle Arg1 Arg2 ...}. The callback is called with [Full,Stat]=feval(cbk{1},obj0,evt0,cbk{2:end});. obj0 contains the results read in the current mat result file and evt0 is a structure with evt0.j1 containing the indices in the results stack. There are 2 output arguments Full that should contain a full signal (for example the observation of time deformation at sensors, ...) and Stats that should be a SDT curve table (1 or 2 dimensions) of scalar results (for example time statistics for time signals...).
    • data is a cell array with as many rows as scalar results (1 by column in the Stats tab that will be displayed) to extract from the post-treatment result curve Stats. Each row is of the form i1 i2 CritFcn. i1 (resp. i2) can be either the row (resp column) indices of the scalar result in the Stats.Y table or the label of the row (resp column) in the Stat.X{1} abscissa (resp Stat.X{2}). CritFcn is the handle of a criterion function that can be used to color cell in the result tab (for example a threshold function) and also to display boundary lines in iiplot displays (needs critfcn doc and example).

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.

Contents