(See also: McStas on the ESS cluster)

Prerequisites:

The following guide assumes the use of either

1. McStas 2.3 (Apr. 06, 2016) plus
   1. - Component library: McStas-2.3, built Sep. 15, 2016 (which includes MCPL v. 0.6)
   2. The instrument file ESS_butterfly_MCPL from the McStas GitHub repository
   3. The updated MCPL_input component from the McStas GitHub repository
   4. If you need to WRITE MCPL files, also download the updated MCPL_output component from the McStas GitHub repository
      
      
2. McStas 2.4 (May. 17, 2017) (which includes MCPL v. 1.1)
   1. If you need to WRITE MCPL files, also also download the updated MCPL_output component from the McStas GitHub repository
   2. The instrument file ESS_butterfly_MCPL from the McStas GitHub repository
      
      
3. McStas 2.4.1. and later includes the right versions of all of the above!

Input datasets:

You will also need an MCPL input file for the beamline in question. The files are available in easy-to-use limited-statististics files here, named <Sector><Beamline>.mcpl.gz  (e.g. W8.mcpl.gz). The key numbers and properties of these files are:

• Each around 3-6Gb in size
• Based on 1e5 protons on target (as a Dirac deltafunction in time, the ESS pulse timing is generated on the McStas side!)
• Include multiple particle types, i.e. neutrons, gammas, protons and muons etc.
• Particles can have "any" physical energy, i.e. up to the linac proton energy
• Particles originate from "anywhere" within the monolith, but of course mainly from the target, moderators and their surroundings
• In the file, the particles are "located" on a "r=9cm DXtran sphere" at 2 m from the moderator centre, positioned on the beamline axis of choice (a DXTran sphere is an attractor of statistics. In the process, the event weight is reduced so that the game is fair in a statistical sense)
• Please consult the below figur to understand the geometry!

Figure 1: Visualisation of events in the file W8.mcpl.gz within the ESS_butterfly_MCPL instrument. The coordinate system of choice is the TARGET coordinate system. 

1. For use on your own computer, download the relevant file from http://public.esss.dk/users/willend/MCPL/ - REMEMBER THEY ARE BIG!
2. If you need any special type of MCPL datafile (bigger, smaller, filtered one way or another...) please write Esben Klinkby [X] an email, putting Peter Willendrup cc

The ESS_butterfly_MCPL instrument file

We now turn our attention to the supplied ESS_butterfly_MCPL instrument file. The below text is a summary only, PLEASE STUDY IT YOURSELF!

• IMPORTANT: It is meant as a template for you to do further work - it does not resemble any physical instrument concept or design!

The most important properties of the file is

• The ABSOLUTE coordinate system of the instrument is the TARGET coordinate system
• The sector and beamline input parameters selects the orientation of your beamline wrt. the TARGET coordinate system and defines the expected MCPL input filename, e.g. sector=W, beamline=8 → W8.mcpl.gz
• An MCPL_input component is placed at (0,0,0) ABSOLUTE
• An inactive ESS_butterfly component is also placed, but is inactive - only included for visualisation purposes!
• The various beamline elements are placed with respect to the moderator "FOCAL POINT" relevant for your instrument
• Events are read in from the file "where they are", i.e. at the DxTran sphere / beamport crossing point
• Events are then propagated back to a plane perpendicular to the instrument axis, to make the source look "normal" to a McStas user - i.e. events are shown close to the moderator surface.
• The below EXTEND block performs several tasks:
  • Removes events with "high" weight, defaults to 0.003 - recommended value
  • Renormalises the neutron intensity to neutrons/s. (Intensity in the file is neutrons/1e5 protons - renormalisation factors are 1e5 protons / file and 1.56e16 protons / s) 
  • BEWARE! if using a different "NPS" on the MCNP side WILL give you a wrong normalisation. ADJUST accordingly here if you are using any kind of "special" file from Esben! 
  • The TARGET z-value (vertical) is shifted to around the plane of the moderator - defaults to being the plane of the target

• EXTEND %{
    if(p>mcipthres) {ABSORB;}
    else {SCATTER;}
    p*=1.56e16;
    p/=1e5;
    z=z-0.137;
  %}

• Several "filters" are applied in the instrument file, to let it only contain events that are "normal" to a McStas user, i.e.

  • Non-neutrons are quietly removed (McStas can do nothing with them!)
  • Neutrons hitting outside a 12x12 cm (WxH) rectangle at the beamport are ABSORBED
  • Neurons originating from outside a 24 x 6 cm (WxH) rectangle at the moderator "surface" are ABSORBED
  • Neutrons outside the chosen  (Lmin,Lmax) wavelength range are ABSORBED
  • Neutrons with starting timing outside the (0,3*ESS_PULSE_DURATION) are ABSORBED
• The instrument file further contains Brilliance_monitors to and other monitors for looking at
  • Source brilliance
  • Transport through a "standard" m=2 curved Guide of dimension 10x10cm with ROC of 3km

Varying statistics

To ensure conservation of the original simulated intensity, the full content of the MCPL file must used. Therefore the normal user-controlled McStas -n (ncount) is effectively disabled. To allow varying statistics anyway, the instrument parameter 'repeat' (corresponding to the component parameter repeat_count of the MCPL_input component) may be used to repeat the content of the file an integer number of times. See next paragraph wrt. the possibility of slightly varying energy, position and direction when repeating.

MCPL and parallel simulations using MPI

As the MCPL parallelisation in McStas is handled by very simple means, running on multiple processors / cores means repeating the contents of the MCPL file. To do this without wasting time, every repetition of an event will result in a small Monte-Carlo choice being done inside a "sphere of confusion" around the initial event, dimensioned by the parameters E_smear (Gaussian MC choice within E_smear*E around initial particle energy E), pos_smear (m) (flat MC choice of position within radius pos_smear around initial particle position), dir_smear (degrees) (Gaussian MC choice of direction within dir_smear around initial particle direction).

Output data

Instrument geometry

Using the above-mentioned W8.mcpl.gz MCPL file and choosing parameters sector=W and beamline=8, you will get the below instrument geometry, showed as different types of mcdisplay output:

1. mcdisplay-webgl (McStas 2.4 only)
2. mcdisplay.pl/mcdisplay (McStas 2.4/McStas 2.3)
3. mcdisplay-pyqtgraph (McStas 2.4 only)
4. mcdisplay-pyqtgraph, zoomed (McStas 2.4 only)

Figure(s) 2: Various types of mcdisplay geometry output

Monitor data

Running the instrument file with sector=W and beamline=8 will produce this type of graphics:

Figure(s) 3: ESS_butterfly_MCPL.instr - overview plot and "end of curved guide" PSD for the W8 beamline

Output data from similar, analytic model

Based on the analytical ESS_butterfly.comp, a similar set of simulations can be run. The relevant instrument file is ESS_butterfly_Guide_curved_test.instr from the McStas GitHub page

Monitor data

Running the instrument file with sector=W and beamline=8 will produce this type of graphics:

Figure(s) 4: ESS_butterfly_Guide_curved_test.instr - overview plot and "end of curved guide" PSD for the W8 beamline