McStas tutorial: simplified SANS instrument

In this tutorial, you will write a simplified SANS instrument from scratch, simulate neutrons and transform the raw results into q-space. In the process, you will acquaint yourself with a few mcstas best practices.

Instrument code examples will be provided for you to prevent you from getting stuck. When you have completed this tutorial, you will have learned the basics of the mcstas tool.

This tutorial uses the mcgui-py python tool for editing and simulating a basic, idealized instrument. The tool is a rewrite of the original and ever popular mcgui. The tool provides an easy interface for inserting components into your instrument, automatically giving you the right parameter names and default values, for your particular version of mcstas.

• Time: A couple of hours.
• Requirements: mcstas 2.2 or newer.

Getting started

• Run "mcgui-py" in a terminal (or the mcstas command line environment on Windows)
• Select the menu "File -> New Instrument..." to create a new instrument. (Tip: Create a new directory and put the instrument file inside it. This eases the work or keeping track of multiple instrument versions and simulation runs later on.) (Example: tutorial_SANS.)
• Open the instrument editor (it may already be open).
• If the instrument is blank, you should copy-paste the following instrument template into the instrument editor: template_instrument_basic.
• Header - name your instrument: Replace the (instrument name) text at the top of the header section with the instrument name.
• Body - define your instrument: After the words "DEFINE INSTRUMENT" just below the header section, replace the current text with your instrument name, followed by parentheses "()". You may delete the parameter definition Par1=1 inside the parentheses, or leave it as is. (Example: "DEFINE INSTRUMENT tutorial_SANS()")
• Fill out/delete the rest of the instrument header section.
• Press ctr-s to save.

Instrument sketch

Scientists often have an idealized vision of their instrument (upper region). As a computer program, mcstas understands lines of coded text (lower region). The words are the names of the mcstas component types, and the numbers are the distance in the z-direction that components are placed, relative to the previous component. Each component has a name as well as a type - the words in the sketch refer to the type. The name is optional.

Inserting components

A component is defined by using the keyword "COMPONENT" following by the name, an equals symbol "=", the type, and finally a open-close parentheses "()". Then, a position is specified using the word "AT" followed by an x- y- z coordinate specification and finally the word "RELATIVE" followed by the name of another component above the current one, or the keyword "PREVIOUS", in order to specify relative position. The keyword "ABSOLUTE" in place of PREVIOUS or a component name should only be used for the first component, usually a Progress_bar.

Within the parentheses following the component type, parameter values are specified

However, don't worry too much about all this - the gui will teach you how to do it.

• Put the cursor below the progress bar specification in the middle of the instrument body text.

• Go to the "Insert -> Optics" menu and select "Arm". Name the arm something like "arm_source". You can position it RELATIVE origin rather than RELATIVE PREVIOUS. Press enter or click Insert. Congrats - you have added your first component without reading any documentation what so ever :)

• Ignore the ROTATED part - this is SANS and we don't rotate anything in this tutorial. In fact, you can delete all lines that start with ROTATED.

Now insert the following components and enter their relative positions according to the sketch above.

• "Insert -> Source -> Source_simple". Use the parameters radius=0.02, dist=3, focus_xy=0.01, focus_yh=0.01, lambda0=6, dlambda=0.05 and flux=1E8. After you have inserted the component, you must delete all other parameters! (Delete these: yheight, xwidth, E0,dE,gauss,target_index.) And you must also delete any comma between the last parameter and the exit parentheses.

• "Insert -> Optics -> Slit" twice, make them of radius=0.005 and delete the rest of the parameters (including the excess comma), as above. Select different names for each slit. Position the slits correctly in the z direction according to the sketch. Delete the ROTATED line. (This makes your instrument really neat and easy to read.)

• "Insert -> Sample -> Sans_spheres". Use the default values for R, Phy, Delta_rho and sigma_abs. Use xwidth=0.01, yheight=0.01 and zdepth=0.005. After inserting the component into the instrument definition, delete all other parameters.

• "Insert -> Optics -> Beamstop". Use radius=0.02 and delete all other parameters after inserting the component.

• "Insert -> Monitor -> PSD_monitor". Use nx=128, ny=128, filename="PSD_mon.dat", xmin=-0.05, xmax=0.05, ymin=-0.05 and ymax=0.05. Delete the rest. NOTE: Please be careful with the filename. It must be in quotes ("), it must have a unique name, and it must be there.

• "Insert -> Monitor -> L_monitor". Make it the same size as the PSD monitor above. Use nL=1000, , Lmin=5.5 and Lmax=6.5.

• "Insert -> Monitor -> PSD_monitor_rad". Use filename="psd_rad.dat", filename_av="psd_rad_av.dat" and rmax=0.6.

• "Insert -> Contrib -> SANSQMonitor". Use RFilename="RDetector", qFilename="QDetector", NumberOfBins=100, RadiusDetector=0.6 and DistanceFromSample=5.8.

• If you do get stuck or fed up, here is the link to the solution that works (tested with mcstas 2.2). --> tutorial_SANS.instr

A bit of Discussion:

As you may have gleamed from the sketch above, mcstas requires a couple of "virtual" components that don't seem to do anything, such as "Progress_bar()" and "Arm()". These do indeed not affect the simulated neutrons, but they take the place of the stopwatches and gears-and-wheels of real life instruments. mcstas also gives you the option of measuring anything, anywhere, by means of monitors. This is a very convenient way to check various properties of the propagated neutrons at various places of the beamline, before and after the sample, etc.

Components are usually laid out RELATIVE to one another. This means that if a component changes position or orientation, all of the components down the line also translate and/or rotate accordingly. This is particularly useful for variable collimation, sample and detector distances, or for defining the rotational axes of spectrometers.

Headache removals:

• All components must have unique names, although components of the same type are often allowed.
• Neutrons are propagated along Z-axis.
• Components may NOT be placed on top of each other. This is why we put a very small space between them instead (see above). Exception: Arm() and Progress_bar() are exceptions to the above.
• Warning: Only a single Progress_bar is allowed in your instrument definition.
• Warning: Only a single neutron source is allowed.
• Components must be placed chronologically from the neutron's perspective, and sequentially from the mcstas instrument definition perspective.
• When referencing component names to specify the position of other components down the line, you must reference to the component name, NOT the component type. A common error.
• Each and every monitor MUST have a "filename="some_file.dat" parameter value, because that part isn't automatic.

Run a simulation and plot results