Package: restage
restageSemiautomatic two-stage McCode simulations for parameter scans.MotivationSome instrument simulations are very costly.
This is especially true for instruments with a large number of components.
In order to reduce the runtime of a simulated parameter scan, it is possible to run the simulations in two stages.
In the first stage, the instrument is simulated up to a predefined point and the particle states are saved in an MCPL file.
The output particle states are then used as input for the second stage,
where the instrument is simulated from the predefined point to the end of the instrument.
On its own, such a split simulationis detrimentalto the simulation runtime,
since writing and reading the MCPL file takes time.Where such a technique is useful, however, is when the first stage output can be reused
for multiple second stage simulations.
This is the case, e.g., when a 'standard' sample-rotation scan is performed,
where the sample is rotated around a single axis and the rest of the instrument is kept fixed.
In this case, the first stage simulation only needs to be performed once,
and the second stage simulations can be performed for each sample rotation angle.InstallationTherestagemodule is installable viapip:pipinstallrestageor directly from the source code:pipinstallgit+https://github.com/g5t/restage.gitUsagerestageTherestagemodule provides a function,restage, which takes a McStas instrument file as input.
The function will then parse the instrument file and generate new instrument files for the first and second stage simulations.
The new instrument files will be namedrestaged_lower_<original instrument file name>.instr,
andrestaged_upper_<original instrument file name>.instr, respectively.splitrunA more useful function,splitrun, is also provided by therestagemodule.
Thesplitrunfunction takes the same arguments as therestagefunction,
but will also run the simulations for the first and second stage.
The function will return the output of the second stage simulation.Thesplitrunfunction can be used as a replacement for themcrunfunction distributed as part of McStas.
One optional argument,splitpoint, is added to thesplitrunfunction; it should be the name of
anArmcomponent inside the instrument file and defaults tosplit_at.
In contrast tomcrun, instrument parameters forsplitrunare specified as 'MATLAB'-range style keyword arguments.
A valid range is inclusive of its end points and of the formstart:step:endorstart:end(with implicitstep=1).The-Nargument ofmcrunis removed since the number of scan steps is now determined by the range
of the scan parameter; this means that multiple scanned parameters must have ranges that agree on the number of steps.The switch to MATLAB-style range specification is done to allow for flexible mesh scans, via the optional-mflag.
When the-mflag is specified, the scan parameters are interpreted as mesh scan parameters and the number of steps
along each mesh parameter is not constrained to be the same.ExampleAs an example, for the instrument filemy_instrument.instrDEFINE INSTRUMENT my_instrument(sample_angle=0, sample_radius)
COMPONENT source = Source(...) AT (0, 0, 0) ABSOLUTE
COMPONENT guide = GuideGravity(l=10) AT (0, 0, 0.1) RELATIVE source
COMPONENT end_of_guide = Arm() AT (0, 0, 10) RELATIVE guide
COMPONENT slits = Slit(...) AT (0, 0, 0.2) RELATIVE end_of_guide
COMPONENT split_at = Arm() AT (0, 0, 0) RELATIVE slits
COMPONENT sample_pos = Arm() AT (0, 0, 0.2) RELATIVE split_at
COMPONENT sample = Sample(radius=sample_radius) AT (0, 0, 0) RELATIVE sample_pos 
                   ROTATED (0, sample_angle, 0) RELATIVE split_at
COMPONENT detector_arm = Arm() AT (0, 0, 0) RELATIVE sample_pos ROTATED (0, 45, 0) RELATIVE sample_pos
COMPONENT detector = Monitor(...) AT (0, 0, 2) RELATIVE detector_arm
ENDthe McStasmcruncommandmcrunmy_instrument.instr-N90-n1000000-d/data/outputsample_angle=1,90sample_radius=10.0can be replaced by thesplitruncommandsplitrunmy_instrument.instr-n1000000-d/data/outputsample_angle=1:90sample_radius=10.0