[OPTIMUM,MONITORS,EXITFLAG,OUTPUT] = mcstas(INSTRUMENT, PARAMETERS, OPTIONS) : run and optimize a McStas/McXtrace simulation
A wrapper to the <a href="http://www.mcstas.org">McStas</a> package to either execute a simulation, or optimize a
set of parameters. When given as strings, the PARAMETERS and OPTIONS are
searched for name=value pairs, separated by the ';' character.
The default execution mode is 'simulate', which also includes scanning capability.
Scans of parameters with vectors and cell strings are possible. Multiple
dimension scans are also possible
mcstas('instrument','parameter1=1; parameter2=[2 3 4]','dir=scan_test')
mcstas('instrument',struct('p1',1,'p2',[2 3 4],'p3',{'Al.laz','Cu.laz'}))
The resulting integrated monitors are returned in OPTIMUM, MONITORS holds the
monitors content as iData objects. The EXITFLAG is set to 0, and OUTPUT
holds the options used. If the options.dir is not set, a temporary directory
is created for the simulations, then deleted.
To select neutron (McStas) or X-rays (McXtrace) flavour, set the options.particle
to 'n' or 'x'.
To select the optimization mode, set the options.mode='optimize' or any other
optimization configuration parameter (TolFun, TolX, ...).
Only numerical parameters can be optimized, others are kept fixed. The search
is restricted to a bounded range when parameters are given as vectors [min,max].
As McStas simulations are noisy, it is recommended to constraint all parameters.
The criteria used for the search can be given in the options.monitors as a
string or cell of strings. The sum of the monitor content is then used.
The default optimization maximizes the criteria.
Each entry should begin by the monitor filename possibly followed by any
expression using 'this' to refer to the monitor content:
options.monitors='Monitor' will match all files starting by 'Monitor'
options.monitors={'Monitor1','Monitor2'} uses two monitor integrals
options.monitors='Monitor1/std(this)^4' divides the monitor by its half width^4
options.monitors='Monitor1; this = this/std(this)^4' same as above
The OuputFcn is set to 'fminplot' as default. Define options.OutputFcn=''
to override this choice.
mcstas('instrument','parameter1=[0 1]; parameter2=[2 4]','dir=optim_test; mode=optimize')
The best optimized parameter set is returned in OPTIMUM, MONITORS holds the
optimized monitors content as iData objects. The EXITFLAG is the return value
from the optimizer, and OUTPUT holds additional simulation and optimization stuff.
The Trace 3D view mode is executed when using mode=display, but does not show neutron
trajectories.
mcstas('instrument','parameter1=Al.laz; parameter2=3','mode=display')
The syntax:
mcstas(instrument,'--compile') assemble and compile the instrument
mcstas(instrument,'--compile mpi') same with MPI support
mcstas(instrument,'--info') returns instrument information
The MCSTAS and MCXTRACE environment variables can be specified to indicate which
McCode library to use, else default locations are used.
If McStas executables (e.g. 'mcrun') are not found, you may have to extend the PATH
setenv('PATH', [getenv('PATH') ':/usr/local/bin' ':/usr/bin' ':/usr/share/bin' ]);
input: INSTRUMENT: name of the instrument description to run (string)
when the instrument is not found, it is searched in the McStas
examples, and copied locally.
PARAMETERS: a structure that gives instrument parameter names and
values (structure)
parameters.name = scalar (optimization, simulation and display)
define a single value when options.mode='simulation' and 'display'
define the starting value when options.mode='optimization'
parameters.name = vector and cell array (simulation)
define a scanning range for a series of simulations, when
options.mode='simulation' multi-dimensional scans (that is more
than one parameter given vector) are possible.
parameters.name = vector (optimize)
the vector can be 3 elements to define [min start max].
the vector can be 2 elements to define [min max].
the vector can be 4+ elements to define [min ... max].
For 2 and 4+ vectors, the parameter starting value is the mean of the vector.
parameters.name = string (simulation, optimization and display)
defines a fixed parameter, that can not be optimized.
when PARAMETERS is given as a string with 'name=val; ...', it is
converted into a structure.
OPTIONS: a structure or string that indicates what to do (structure)
options.dir: directory where to store results (string)
options.overwrite: 0 or 1 to either keep or force output
directory to be overwritten (boolean)
options.ncount: number of neutron events per iteration, e.g. 1e5 (double)
options.mpi: number of processors/cores to use with MPI on localhost (integer)
options.machines: filename containing the list of machines/nodes to use (string)
options.seed: random number seed to use for each iteration (double)
options.gravitation: 0 or 1 to set gravitation handling in neutron propagation (boolean)
options.compile: 0 or 1 to force re-compilation of the instrument (boolean)
options.mode: 'simulate' (default), 'optimize' or 'display' (string)
options.type: 'minimize' or 'maximize', which is the default (string)
options.particle: 'n' (default) or 'x' depending if you use McStas or McXtrace (string)
options.monitors: cell string of monitor names, or empty for all (cellstr)
the monitor names can contain expressions made of the monitor name
followed by any expression using 'this' to refer to the monitor content
such as in 'Monitor1/std(this,1)' which divides the Signal by its X peak width.
options.help: set it to 'yes' or 1 to get help on the instrument and exit
options.info: set it to 'yes' or 1 to get information on the instrument and exit
options.optimizer: function name of the optimizer to use (string or function handle)
options.OutputFcn: monitors the scan/optimization process on a plot (string)
as well as other optimizer options such as
options.TolFun ='0.1%' stop when criteria changes are smaller that 0.1%
options.Display='final' set the verbosity level during optimization
options.mcrun: set the executable path to 'mcrun' or 'mxrun'
options.mcdisplay: set the executable path to 'mcdisplay' or 'mxdisplay'
output: OPTIMUM is the parameter set that maximizes the instrument output, or
the integral monitor values for the simulation (as iData object)
MONITORS contains the instrument output as iData objects. Each object has an
additional Parameter member alias which holds the instrument parameters.
EXITFLAG return state of the optimizer, or 0.
OUTPUT additional information returned as a structure.
examples:
Run a single simulation
[p,f]=mcstas('templateDIFF', 'RV=1', 'monitors=Banana');
Optimize templateDIFF instrument parameter RV
[p,f]=mcstas('templateDIFF', 'RV=[0.5 1 1.5]', struct('TolFun','0.1%','monitors','Banana'));
Display result
subplot(f); disp(f.Parameters)
Perform a scan of instrument parameter RV
[monitors_integral,scan]=mcstas('templateDIFF' ,struct('RV',[0.5 1 1.5]))
plot(monitors_integral)
Display instrument geometry
fig = mcstas('templateDIFF','RV=0','mode=display');
Type <a href="matlab:doc(iData,'McStas')">doc(iData,'McStas')</a> to access the iFit/McStas Documentation.
Version: Aug. 22, 2017
(c) E.Farhi, ILL. License: EUPL.
See also: fminsearch, fminpso, optimset, http://www.mcstas.org