y = mccode(instr, options, parameters) : McCode (McStas/McXtrace) instrument
iFunc/mccode a McCode instrument
y=model instrument
MODEL CREATION:
------------------------------------------------------------------------------
mccode(description)
creates a model with specified McCode instrument
The instrument may be given as an '.instr' McCode description, or directly
as an executable. Distant URL (ftp, http, https) can also be used.
mccode('')
requests a McCode file (*.instr,*.out) with a file selector.
mccode('gui') and 'mccode' alone.
list all available instruments in a list for a selection.
mccode('defaults')
uses templateDIFF.instr neutron powder diffractometer as example.
mccode(description, options) also specifies additional McCode options, e.g.
options.dir: directory where to store results, or set automatically (string)
the last simulation files are stored therein 'sim'.
dir can also be 'pwd' for current, or 'tmp' for temporary location.
options.ncount: number of neutron events per iteration, e.g. 1e6 (double)
options.mpi: number of processors/cores to use with MPI on localhost (integer)
when MPI is available, and mpi options is not given,
all cores are then used.
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.monitor: a single monitor name to read, or left empty for the last (string).
this can be a wildcard expression.
options.mccode: set the executable path to 'mcrun' (default, neutrons) or 'mxrun' (xrays)
options.mpirun: set the executable path to 'mpirun'. You can set
it to 'none' to not use MPI.
options.compile: 0 or 1 to compilation the executable. The default is to compile.
All options are stored and assignable in model.UserData.options.
options can also be given as a string, e.g. 'ncount=1e6; monitor=*Theta*; compile=1'
the 'monitor' option can also include further expressions, such as:
options.monitor='*Theta*; signal=max(signal)/std(signal)^2;'
When the instrument file name contains a path specification, it is used for
compilation and execution (recommended). If it is used as a single file name,
or the target directory as no read, write or execute permissions,
a temporary directory is created and the instrument is copied there, which may
cause issues if local components are to be used.
mccode(description, options, parameters)
Specifies the instrument parameters values to use as default. These values can
be given as a string e.g. 'QM=1; lambda=2.36' or a structure.
The instrument parameters of type 'double' are used as model parameters. Other
parameters (e.g. of type string and int) are stored in UserData.Parameters_Constant
You may still specify their value when using e.g. syntax with a string or structure:
feval(model, 'lambda=2.36; Powder="Al.laz"')
iData(model, 'lambda=2.36; Powder="Al.laz"')
iData(model, struct('lambda',2.36,'Powder','Al.laz'))
The options ncount, seed, gravitation, monitor can be changed for the model
evaluation, with e.g.:
model.UserData.options.ncount =1e5;
model.UserData.options.gravitation=1;
model.UserData.options.monitor ='*Theta*';
Additional information is stored in the model.UserData, such as the instrument
source, which you may view with:
TextEdit(model.UserData.instrument_source)
Example: model = mccode('templateDIFF');
MODEL EVALUATION:
------------------------------------------------------------------------------
model(p)
evaluates the model with given parameters (vector, cell, structure). Only
scalar/double parameters of the instrument can be varied. Other parameters are kept fixed.
model(p, nan)
evaluates the model and return the raw McCode data set (monitor).
model(p, x,y,...)
evaluates the model and interpolates the McCode data set onto given axes.
The model 'value' is the last monitor, or set from
model.UserData.options.monitor
It can be converted to an iData with iData(model, ...)
The raw monitors of the last simulation are stored as iData objects in
model.UserData.monitors
You can plot them all with e.g.:
subplot(model)
input: p: variable instrument parameters (double, struct, char)
p = [ double_type_instrument_parameters ]
x,y,...: axes (double)
output: y: monitor value
ex: model =mccode('templateDIFF');
signal=iData(model, [], linspace(-10,100,100));
signal=iData(model, [], nan); % to get the raw monitor
signal=iData(model, 'lambda=2.36; Powder=Al.laz', nan); % to get the raw monitor
MODEL GEOMETRY
------------------------------------------------------------------------------
To view the model geometry, use the plot routine:
model = mccode('templateDIFF');
plot(model)
plot(model, parameters)
MODEL PARAMETER SCAN
------------------------------------------------------------------------------
It is possible to scan model parameters when using vectors as value for the
parameters. To achieve that, the parameter values must be given as a named
structure.
For instance, to scan the RV parameter in the templateDIF instrument, use:
model = mccode('templateDIFF');
p.RV= [ 0:.25:2 ]; % from 0 to 2 by steps of .25
v=iData(model, p, nan); % we want the raw monitors as iData sets.
subplot(v);
MODEL OPTIMISATION
------------------------------------------------------------------------------
To optimise instrument parameters, you should first fix the non-varying
parameters, and possibly bound the others. Then the optimiser is launched
with e.g. 'fmax' or 'fmin':
model = mccode('templateDIFF'); % maximize
fix(model, 'all'); model.RV='free';
model.RV=[0 1 2]; % bounds and starting value
p = fmax( model , [], '', nan) % return the optimal parameters using the raw monitors
Version: Nov. 26, 2018
See also iFunc, iFunc/fits, iFunc/plot, iFunc/feval, mcstas
<a href="http://www.mcstas.org">McStas</a>, <a href="http://www.mccode.org">McCode</a>
(c) E.Farhi, ILL. License: EUPL.