Contents     Functions              PDF Index

fe_range

• DirScan
• Grid
• GridFace
• lab[,Cell,def]
• ValCell
• labFcn
• Loop
• Res
• Sel
• Simple
• UI Tree
• Val
• Vect

Purpose

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

Description

A range is the description of a set of experiments 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 fieldnames (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
  

.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};.
• .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.
• .SetFcn={fun,command} provides the callback used in fe_range Loop to execute parameter setting.

Commands

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

Grid

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

par is expected to be either

• a cell array with as many elements as parameters. Each cell can be
  • 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.
  • a range data structure
  • 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.
• a structure where each field will be a parameter
• a matrix following the model of the visco tools parameters definition (see fevisco Range for more details).

As an illustration, following example defines a grid 6x7 of 2 parameters named length and thickness

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

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('Grid',par);
fe_range('Tree',Range);

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 take the diagonal of the hypercube.

GridFace

lab[,Cell,def]

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.

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.

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.

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.

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 Grid 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)

Val

Val commands are used to ease range manipulations.

Vect

Range=fe_range('Vect',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 Grid 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('Vect',par);