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.

• Requirements: mcstas 2.4.1

Getting started

• cd to your wanted working directory and run "mcgui" in a terminal (or the mcstas command line environment on Windows)
• Select the menu "File -> New Instrument..." to create a new instrument (or click Edit/New if you are using mcgui.pl rather than mcgui). You might name your instrument something like: tutorial_SANS. The .instr ending required for all mcstas instrument files will be added automatically.
• Open the instrument editor.
• If the instrument is blank, you should copy-paste the following instrument template into the instrument editor: template_instrument_basic.
• Header top: Replace (instrument name) with your instrument name.
• Instrument body: After the words "DEFINE INSTRUMENT" just below the header section, replace the text with your instrument name. You may delete the parameter definition Par1=1 inside the parentheses, or leave it. The parenthesis is required. (Example: "DEFINE INSTRUMENT tutorial_SANS()")
• Fill out/delete/ignore the rest of the instrument header section.
• Press ctr-s to save.

Instrument sketch

Scientists often imagine an idealized vision of their instrument. As a computer program, mcstas only understands lines of coded text.

Each component has a unique "name" in addition to its "type", and the words in the sketch refer to the type. The numbers in parenthesis indicate the relative distances between components.

Inserting components

• Put the cursor in the middle of the instrument body (a couple of lines below the Progress_bar).

• Go to the menu "Insert -> Optics" and select "Arm". Name the Arm "arm_source". (And enter a zero in each of the spaces in AT( , , ) if you are using mcgui.pl rather than mcgui.) Position should be RELATIVE origin rather than RELATIVE PREVIOUS, since origin is the name of the Progress_bar above the Arm. Click "Insert".

Now insert the following components sequentially. Give each component a unique name. The relative z-positions are given by 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. Remember to check the right distance in the z direction to the previous component.

• "Insert -> Optics -> Slit" twice, make them of radius=0.005. Select a different name for each slit. Position the slits correctly in the z direction according to the sketch.

• Press ctr-s to save.

• "Insert -> Contrib -> SANSspheres". Use the default values for R. Use xwidth=0.01, yheight=0.01, zdepth=0.005, SampleToDetectorDistance=3.8 and DetectorRadius=1. 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", xwidth=1.2 and yheight=1.2. Delete the rest. WARNING: the filename value must be in quotes "..."!

• "Insert -> Monitor -> L_monitor". Make it the same as the PSD monitor above (but use a new filename, also in quotes). Use nL=1000, , Lmin=5.5 and Lmax=6.5.

• "Insert -> Contrib -> 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.

• Press ctr-s to save. (meta-s on mac)

Keep reading to learn a few mcstas tricks and tips which may help you debug your instrument. If results do not appear, it is probably due to small yet typical mistakes in the code.

You may also skip directly to the "Simulate and Plot" section. Here's 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 timers 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 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

If you get errors simulating, or if nothing happens when you click Plot, then refer to the tested example above.

• In the mcgui main window, click "Run...". A dialog box will open. Set the number of neutrons to 100000000 (10^8). Click "Start".

• After some time you will see that the simulation has completed.

• Press "Plot". Press "l" to view your results in log scale. You should now be able to witness the characteristic "rings" of the simulated SANS results.

• Press q AND close the window with the mouse to exit pgplot.

You have now completed this simple tutorial, and you should be able to create and/or modify your instruments, and run simulations.

One of the best places to look for inspiration and working code snippets is in the library of instruments that are distributed with mcstas. These are accessed through the menu "File -> New from Template...".