Home > Applications > McStas > mcstas.m

iFit/mcstas

PURPOSE ^

[OPTIMUM,MONITORS,EXITFLAG,OUTPUT] = mcstas(INSTRUMENT, PARAMETERS, OPTIONS) : run and optimize a McStas/McXtrace simulation

SYNOPSIS ^

function [pars,fval,exitflag,output] = mcstas(instrument, parameters, options)

DESCRIPTION ^

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

 example: 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: Mar. 22, 2017
 (c) E.Farhi, ILL. License: EUPL.
 See also: fminsearch, fminpso, optimset, http://www.mcstas.org

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:
Generated on Wed 22-Mar-2017 09:13:30 by m2html © 2005. iFit (c) E.Farhi/ILL EUPL 1.1