McStas tutorial: simplified SANS instrument

In this tutorial, you will write a simplified SANS instrument. When you have completed this tutorial, you will have learned the basics 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. As a computer program, mcstas understands lines of coded text. These two views are indicated in the sketch.

The words are the names of the mcstas component types, and the numbers are the distance in the z-direction that components are placed with respect to each other. Each component has a unique "name" in addition to its "type", and the words in the sketch refer to the type. The name is optional.

Inserting components

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

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

• 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 a different name for each slit. Position the slits correctly in the z direction according to the sketch.

• "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. All monitors are like that.

• "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 make a mistake by accident, here is the link to the solution that works (tested with mcstas 2.2). --> tutorial_SANS.instr

A few notes:

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.

A few extras:

Take a look at your sample definition. If you put the word SPLIT before the word COMPONENT, this will significantly improve statistics for your simulations below.

Debugging mcstas instruments takes place by pressing "Run" and then seeing what happens in the "Simulation" tab in the main mcgui-py window. If you see strange messages with errors and linenumbers, something is amiss. Use this information to look at your instrument and try to spot errors and correct them. It's usually things along the lines of a misplaced comma, the use of non-unique component names, or illegal positioning of components relative to one another (see below).

Headache removers:

• 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