Home

User and programmers guide to the neutron ray-tracing

1. 8 1 5 Neutron site ISIS 8 1 6 Neutron site Risy 8 1 7 Neutron site PSI 8 1 8 Neutron site Iutorial 8 1 9 Neutron site ESS 8 2 A test instrument for the component V_sample 8 2 1 Scattering from the V sample test instrument 8 3 The triple axis spectrometer TAS1I 8 3 1 Simulated and measured resolution of TAS1 97 97 97 97 98 99 100 101 101 108 108 108 108 108 109 109 109 109 109 109 109 110 110 112 8 4 The time of flight spectrometer PRISMA 115 8 4 1 Simple spectra from the PRISMA instrument 116 A Random numbers in McStas 117 A l Transformation of random numbers 117 A 2 Random peneraton lt 4 o s oos eve 4 os Sos ak PR ama Boe Yo eer klen 118 B Libraries and constants 119 B 1 Run time calls and functions mcstas r sss ss 119 B 1 1 Neutron propagatlon s s esse 119 B 1 2 Coordinate and component variable retrieval 120 B 1 3 Coordinate transformations 122 B 14 Mathematical routines sss 122 B 1 5 Output from detectors ss sss 122 B 1 6 Ray geometry intersections 123 B 1 7 Random numbers sss ee 123 B 2 Reading a data file into a vector matr
2. 8 gravitation Toggles the gravitation approximation handling for the whole neutron propagation within the instrument May pro duce wrong results if the used components do no comply with this option format FORMAT Sets the file format for result simulation and data files N STEPS Divide simulation into STEPS varying parameters within given ranges min max param value min max Set the value of an instrument parameter rather than hav ing to prompt for each one Scans ranges are specified as min max Table 4 1 Options accepted by McStas simulations For options specific to MPI and parallel computing see section 4 7 42 f file file file Write all data into a single file file Avoid when using binary formats format_data FORMAT Sets the file format for result data files from monitors This enables to have simulation files in one format e g HTML and monitor files in an other format e g VRML mpi NB CPU Distributes the simulation over NB CPU node re quires MPI to be installed Speedup has been demonstrated to be linear in number of nodes when the simulation task is ncount is sufficiently large multi NB CPU grid NB CPU Distributes the simulation over NB CPU node re quires SSH to be installed Speedup has been demonstrated to be linear in number of nodes when the simulation task is ncount is sufficiently large m
3. Records Accuracy 108 10 104 2 5 10 1 10 0 25 107 0 05 Table 3 1 Accuracy estimate as a function of the number of statistical events used to estimate an integral with McStas McStas uses a space with d 10 parameters to describe neutrons position velocity spin time We show in Table a rough estimate of the accuracy on integrals as a function of the number of records reaching the integration point This stands both for integrated flux as well as for histogram bins for which the number of events per bin should be used for N 30 4 This Running McStas chapter describes usage of the McStas simulation package In case of problems regarding installation or usage the McStas mailing list or the authors should be contacted Performing a simulation using McStas can be divided into the following steps elements 4 1 The structure of McStas is illustrated in Figure 4 1 To use McStas an instrument definition file describing the instrument to be simu lated must be written Alternatively an example instrument file can be obtained from the examples directory in the distribution or from another source The input files instrument and component files are written in the McStas meta language and are edited either by using your favorite editor or by using the built in editor of the graphical user interface mcgui Next the McStas compiler mcstas is invoked to translate the instrument and c
4. 12 x 10 to di f 10 POA f amp 8 f k gt 4 5 8 i i i 4 i 4 4 2 1 ji K Ya Mee GOOLGOOGPLJ fe Sh SSSeb000 45 i 0 5 0 0 5 1 1 5 2 2T deg TAS1 Scans of 26 in the direct beam with 1 mm slit on the sample po sition x measurements o simulations scaled to the same intensity Collimations open 30 open open Figure 8 4 In contrast a simulated 20 scan in triple axis mode on a V sample showed a surprising offset from 0 degrees However a simulation with a PSD on the sample position showed that the beam center was 1 5 mm off from the center of the sample and this was important since the beam was no wider than the sample itself A subsequent centering of the beam resulted in a nice agreement between simulation and measurements For a comparison on a slightly different instrument analyser detector collimator inserted see Figure The result of a 29 scan on an AlgO3 powder sample in two axis mode is shown in Fig ure 8 6 Both for the scan in focusing mode and for the one in defocusing mode not shown the agreement between simulation and experiment is excellent As a final result we present a scan of the energy transfer Ea hw on a V sample The data are shown in Figure 8 7 113 intensity 0 2TA deg Figure 8 5 TAS1 Corrected 26 scan on a V sample Collimations open 30 28 67 x measurements
5. 6 M 4 Vi N 5 ri kuni NY i 24 i 1 i Mi uj S EV ia li 3 FA li ul JI l l li fh M M a 2 LAA yey J W f Y A M M U NO l 1 hx l r A A A SZ SL LA l MV Stoo 6000 6500 7000 7500 time usec Figure 8 9 Test result from PRISMA instrument using colored neutrons shows the neutrons scattered from one analyser blade 116 Each graph A Random numbers in McStas A 1 Transformation of random numbers In order to perform the Monte Carlo choices one needs to be able to pick a random number from a given distribution However most random number generators only give a uniform distribution over a certain interval We thus need to be able to transform between probability distributions and we here give a short explanation on how to do this Assume that we pick a random number x from a distribution d z We are now interested in the shape of the distribution V y of the transformed y f x assuming f x is monotonous All random numbers lying in the interval x z dz are transformed to lie within the interval y y f x dz so the resulting distribution must be V y o a f z If the random number generator selects numbers uniformly in the interval 0 1 we have x 1 inside the interval zero outside and we reach WW Fay af A 1 By indefinite integration we reach I iu p z A 2 which is the essential formula f
6. 34 41 57 61 MOSTAS 37 TOI T19 126 PGPLOT DEV 48 56 58 PGPLOT DIR 48 56 58 Error estimate Example McDoc section EXTEND McStas keyword File search path 37 FINALLY McStas keyword i 91 FLT MAX constant 128 Focusing importance sampling Formats see Data formats FWHM2RMS constant 128 Graphical User Interface see mcgui Gravitation 69 Grid computing 50 61 63 GROUP McStas keyword 79 120 GUI see mcgui HBAR constant 128 HDF5 see NeXus format HUP signal Identification McDoc section IDL Importance sampling direction focusing INDEX CURRENT COMP C macro mccode r h INITIALIZE McStas keyword 134 Input parameter 129 inside rectangle C function mcstas r c Installation oLa test Instrument Instrument definition units Instrument site McDoc section 96 INT signal EIF ITERATE McStas keyword 82 83 JUMP McStas keyword K2V constant ano Keywords MeDoc 95 E DE kill Language see Meta language Library adapt tree lib components 37 59 77 contrib data misc 105 monitors 105 stn 101 optics 1 samples 104 share 69 71 106 17 sources 102 instruments 107 mccode r 119 mestas r monitor nd lib read table lib run time shared see Library components share vitess lib Link McDoc section Ke Mailing lists mcstas users 9
7. B 1 3 Coordinate transformations coords set z y z returns a Coord structure like POS A CURRENT COMP with x y and z members coords get P kr amp y amp z copies the x y and z members of the Coord structure P into x y z variables coords add a b coords sub a b coords neg a enable to operate on coor dinates and return the resulting Coord structure rot_set_rotation Rotation t dz dy z Get transformation matrix for rotation first z around x axis then around y and last 9 around z t should be a Rotation 3 3 double matrix rot mul Rotation t1 Rotation t2 Rotation t3 performs t3 t1 12 rot copy Rotation dest Rotation src performs dest src for Rotation arrays t rot transpose Rotation src Rotation dest performs dest src rot_apply Rotation t Coords a returns a Coord structure which is t a B 1 4 Mathematical routines NORM z y z Normalizes the vector x y z to have length 1 scalar_prod daz ay az br by bz Returns the scalar product of the two vectors ax ay az and bz by bz vec_prod amp az amp ay amp az bz by bz Cx Cy Cz Sets ax ay az equal to the vector product bz by bz X Cx Cy z rotate amp z amp y amp z Vr Vy Uz P Ax Ay az Set x y z to the result of rotating the vector vz Uy Uz the angle p in radians around the vector az dy az normal_vec amp n amp ny nz x Y 2 Computes a unit vector nz ny nz
8. JUMPs MPI and grid reporting SPLIT system errors WHEN vs GROUP wrong metadata in translating and merging results files C code embedded C functions Citing McStas 9 Code generation options Comments Compilation failure instrument definition see mcstas com piler COMPONENT McStas keyword Component declaration TRACE instance 129 translation to Vitess Constants 127 Contributors 9 Conversion of units 127 Coordinate retrieval functions 120 system 70 coords add C function mccode r c 122 coords_get C function mccode r c 122 coords set C function mccode r c 122 COPY McStas keyword cylinder intersect C function mccode r c Data formats 61 62 date McDoc keyword 96 DECLARE McStas keyword DEFINE COMPONENT McStas keyword DEFINE INSTRUMENT McStas keyword Definition parameter 129 DEFINITION PARAMETERS McStas key word DEG2RAD constant 128 DEPENDENCY McStas keyword Description McDoc section DETECTOR_OUT_OD C macro mecode r h 89 722 DETECTOR_OUT_1D C macro mecode r h 133 DETECTOR_OUT_2D C macro mecode r h DETECTOR_OUT_3D C macro mecode r h Direction focusing Documentation generator see McDoc EDITOR environment variable Embedded C code see C code END McStas keyword 78 93 Environment variables BROWSER 59 101 EDITOR 48 MCSTAS FORMAT
9. McStas is distributed using easy to use meta packages for the Windows and Mac OS X systems these already existed for the deb and rpm based Linux packages see below The content of these packages are 19 64 65 66 67 68 69 70 71 72 73 74 TO 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 20 Windows See http www mcstas org download install_windows for details Strawberry Perl including a gcc compiler Perl PPD extensions for PDL PGPLOT and Tk The core mcstas package The mcstas component package with comps instruments datafiles The mcstas Perl tools package with mcgui mcplot etc The mcstas manuals package with PDF docs For VRML and X3D viewing of instruments we recommend Instant Player from http www instantreality org The mcstas Python tool packages are installed by default but if you want to make use of our OPTIONAL Python based packages their dependencies need to be installed by hand Needed dependencies for the Python packages are all available in the Python x y package available from https code google com p pythonxy We are only distributing a 32bit package for windows since we feel the 64 bin gcc on windows is not mature gives problems in a few specific cases In any case the 32 bit McStas for windows works perfectly fine on a
10. Physics Department Technical University of Denmark Kongens Lyngby Denmark Emmanuel Farhi lt farhi ill fr gt Institut Laue Langevin Grenoble France Erik Knudsen lt erkn fysik dtu dk gt Physics Department Technical University of Denmark Kongens Lyngby Denmark Kim Lefmann lt lefmann fys ku dk gt Niels Bohr Institute University of Copenhagen Denmark Jonas Stein Jonas Stein uni koeln de gt Institute of Physics II University of Cologne Germany as well as authors who left the project Peter Christiansen pchristiOhep lu se Materials Research Department Riso National Laboratory Roskilde Den mark Present address University of Lund Lund Sweden Klaus Lieutenant lt klaus lieutenant helmholtz berlin de gt Institut Laue Langevin Grenoble France Present address Helmotlz Zentrum Berlin Germany Kristian Nielsen lt kristian nielsen mail tele dk gt Materials Research Department Riso National Laboratory Roskilde Den mark Presently associated with MySQL AB Sweden ISBN 978 87 550 3679 6 ISSN 0106 2840 Information Service Department Ris DTU 2015 Contents Preface and acknowledgments Introduction to McStas 1 1 Development of Monte Carlo neutron simulation 1 2 Scientific background 1 2 1 The goals of McStas 1 3 The design of McStas bd a ode di koj Ek Se ka mu New features in McStas 2 1 Monte Carlo Techniques and s
11. filename For 1D 2D and 3D monitors detectors the data histogram store in the files is given per bin when the signal is the neutron intensity i e most of the cases Most monitors define binning for an x axis value as the sum of events falling into the z x 41 range i e the bins are not centered but left aligned Using the Monitor nD component it is possible to monitor other signals using the signal variable name in the options parameter refer to that component documentation Single detectors monitors The results of a single detector monitor are written using the following macro 1 DETECTOROUTOD t N p p2 Here t is a string giving a short descriptive title for the results e g Single monitor 89 CI k VO 19 FR CI l VO IV Sh One dimensional detectors monitors The results of a one dimensional detector mon itor are written using the following macro DETECTOR OUTID t xlabel ylabel xvar x min x max m SN 0 amp p 0 p2 0 filename Here t is a string giving a descriptive title e g Energy monitor xlabel is a string giving a descriptive label for the X axis in a plot e g Energy meV ylabel is a string giving a descriptive label for the Y axis of a plot e g Intensity zvar is a string giving the name of the variable on the X axis e g E Tmin is the lower limit for the X axis Tmax is the upper limit for the X axis
12. force compile this option is required on heterogeneous systems The C code is sent to all slaves and simulation is compiled on each node before starting com putation The default is to send directly the executable from the master node which only works on homogeneous systems computation This method shows similar efficiency as MPI but without MPI installation It is especially suited on multi core machines but may also be used on any set of distant machines grids as well as clusters For Windows master machines we recommend the installation of the PuTTY SSH client The overhead is proportional to the number of nodes and the amount of data files to transfer per simulation It is usually larger than the pure MPI method We thus recommend to launch long runs on fewer nodes rather than many short runs on many nodes Requirements and limitation SSH grids 64 1 2 3 A master machine with an SSH client and McStas installation A set of machines homogeneous or heterogeneous with SSH servers On heterogeneous grids a C compiler must also be installed on all slave nodes ssh access from the master node where McStas is installed to the slaves through e g DSA keys without a password These keys should be generated using the command ssh keygen Run e g ssh keygen t dsa on master node enter no passphrase and add resulting ssh id_dsa pub to ssh authorized_keys on all the slave nodes The key generation and registering m
13. o simulations 800 r o o 4 a a o o o oO Kg oe eo intensity a o o skema opopon W 1095 32 5 33 33 5 34 34 5 35 35 5 2T deg Figure 8 6 TAS1 26 scans on AlgO3 in two axis focusing mode Collimations open 30 28 67 x measurements o simulations A constant background is added to the simulated data 114 140 intensity co lI iD o o x x 9 o o x L o x e 20 AN 05 35 sa e 3 i 2 1 5 1 0 5 0 EA meV Figure 8 7 TAS1 Scans of the analyser energy on a V sample Collimations open 30 28 67 x measurements o simulations 8 4 The time of flight spectrometer PRISMA In order to test the time of flight aspect of McStas we have in collaboration with Mark Hagen now at SNS written a simple simulation of a time of flight instrument loosely based on the ISIS spectrometer PRISMA The simulation was used to investigate the effect of using a RITA style analyser instead of the normal PRISMA backend We have used the simple time of flight source Tof_source The neutrons pass through a beam channel and scatter off from a vanadium sample pass through a collimator on to the analyser The RITA style analyser consists of seven analyser crystals that can be rotated independently around a vertical axis After the analysers we have placed a PSD and a time of flight detector To ill
14. 4 7 Using computer Grids and Clusters Parallelizing a computation is in general possible when dependencies between each com putation are not too strong The situation of McStas is ideal since each neutron ray can be simulated without interfering with other simulated neutron rays Therefore each neutron ray can be simulated independently on a set of computers When computing N neutron rays with p computers each computer will simulate x neutrons As a result there will be p N neutrons simulated As a result McStas p generates two kinds of data sets e intensity measurements internally represented by three values po p1 p2 where Po Pi p2 are additive Therefore the final value of po is the sum of all local value of p computed on each node The same rule applies for p and p The evaluation of the intensity errors is performed using the final po p and p arrays see Section 3 2 1 e event lists the merge of events is done by concatenation McStas provides three methods in order to distribute computations on many comput ers e when using a set of nodes grid cluster or multi cores it is possible to distribute simulations on a list of computers and multi core machines see section 47 1 Results are automatically merged after completion This method is very efficient and only requires SSH server to be installed configured on slave machines In order to use an heterogeneous system a C compiler should be opti
15. E See cit on p 12h See fitepr EEE mewtroncodo org cit on p f8 See Ep Taw neutron an gov nexus ct on pp E 3 A Abrahamsen N B Christensen and E Lauridsen McStas simulations of the TAS1 spectrometer Student s report Niels Bohr Institute University of Copenhagen 1998 cit on p 110 L Alianelli In J Appl Cryst 37 2004 p 732 cit on p 13 C D Clark et al In J Sci Instrum 43 1966 p 1 cit on p 13 K N Clausen et al The RITA spectrometer at Risg design considerations and recent results In Physica B 241 243 1998 pp 50 55 cit on p 12 J R D Copley et al Improved Monte Carlo calculation of multiple scat tering effects in thermal neutron scattering experiments In Comput Phys Commun 40 1986 p 337 ISSN 0010 4655 DOI http dx doi org 10 1016 0010 4655 86 90118 9 cit on p 13 J R D Copley In J Neut Research 1 1993 p 21 cit on pp 12 131 25 J R D Copley In Nucl Instr Meth A510 2003 p 318 cit on p 13 L D Cussen In J Appl Cryst 36 2003 p 1204 cit on p 13 EF14 Far 02 FMM47 Fre83 GRR92 Jams80 KKW14 LW02 LN99 Lef 00 Lie05 Low60 MLS63 Man 04 Mas 95 Mil90 MPC77 NM65 P Willendrup E Farhi Y Debab iFit A new data analysis framework In Journal of Neutron Research 17 1 2014 pp 5 18 ISSN 1023 8166 DOI 10 823
16. To see details in the instrument it is possible to zoom in on a part of the instrument using the middle mouse button or the Z key on systems with a one or two button mouse The right mouse button or the X key resets the zoom Note that after zooming the aspect ratio of the plot may have changed and thus the angles as seen on the display may not match the actual angles Another way to see details while maintaining an overview of the instrument is to use the zoom factor option This magnifies the display of each component along the selected axis only e g a Soller collimator is magnified perpendicular to the neutron beam but not along it This option may produce rather strange visual effects as the neutron passes between components with different coordinate magnifications but it is occasionally useful When debugging it is often the case that one is interested only in neutrons that reach a particular component in the instrument For example if there is a problem with the sample one may prefer not to see the neutrons that are absorbed in the monochromator shielding For these cases the inspect comp option is useful With this option only neutrons that reach the component named comp are shown in the graphics display As of McStas 1 10 the PGPLOT version has a special mode for time of flight ap plications Using the new commandline options TOF T and tmax TMAX chopper acceptance diagrams can be generated from the statisti
17. all the parameters for the component figure 4 8 See section for details of the meaning of the different fields The dialog will also pick up those of the users own components that are present in the current directory when mcgui is started See section 5 7 for how to write components to integrate well with this facility Editor Insert Type These menu entries give quick access to the entry dialog for the various component types available i e Sources Optics Samples Monitors Misc Contrib and Obsolete 53 Component definition Slit Rectangular slit Date June 16 1997 Lower x bound max m Upper x bound ymin n Lower y bound ymax n Upper y bound DESCRIPTION A simple rectangular slit No transmission around the slit is allowed at RELATIVE J J REKTE 007 Cancel Figure 4 8 Component parameter entry dialog 4 5 2 Running simulations on the commandline mcrun The mcrun front end mcrun pl on Windows provides a convenient command line inter face for running simulations with the same automatic compilation features available in the mcgui front end It also provides a facility for running a series of simulations while Va rying an input parameter The command 1 mcrun sim args will compile the instrument definition sim instr if necessary into an executable simulation sim out It will then run sim out passing the argument list args as 54 The possible
18. brings up the McStas website in a web browser Help Tutorial opens the McStas tutorial for a quick start Help Current instrument info generates a description web page of the current edited instrument Help Test McStas installation launches a self test procedure to check that the McStas package is installed properly generates accurate results and may use the plotter to display the results Help Generate component index re generates locally the component index html The run dialog a Run simulation h8 test instr x Instrument source h8 test instr HTML docs Instrument parameters D floating point I integer S string Lambda D 2 36 Output to dir i force Browse Neutron count 1000000 i gravity BEWARE Random seed Simulate steps 0 i Plot results Format PGPLOT Clustering None single CPU Number of nodes 2 cancel Figure 4 7 The run dialog in mcgui The run dialog is used to run simulations It allows the entry of instrument parameters as well as the specifications of options for running the simulation see section for details It also allows to run the mcdisplay section 4 5 3 and mcplot coon ee front ends together with the simulation The meaning of the different fields is as follows Run Instrument parameters allows the setting of the values for the input parameters of the instrument The type of each instrument parameter is
19. http www instantreality org If you want to use our OPTIONAL Python based packages select these for installation in the Metapackage installer For the Python mcrun you need to install PyYAML from http www pyyaml org wiki PyYAML Most other needed dependencies for the Python packages are available through the SciPy superpack available from http fonnesbeck github io ScipySuperpack You may also choose the commerical Anaconda or Enthought Python distributions The install location of the McStas components and libraries on Mac OS X has changed Your files are now placed in Applications McStas 2 1 app Contents Resources mcstas 2 1 but for ease of use a link is also available in usr local mestas 2 1 Note that we have dropped lib in that path Links to binaries are in usr local bin x For Linux Debian and RPM based IMPORTANT Please ensure to use our migration scripts for McStas 2 0 and 1 12c if you want these to co exist with 2 1 They MUST be applied before installing 2510 See http www mcstas org download install linux for details For some RPM based systems you may futher need to install the EPEL extensions see https fedoraproject org wiki EPEL For Deb and RPM type systems we provide a set of APT and YUM repositories Simply follow the instructions on the link provided to add the relevant repository to your Linux Afterwards simply choose to insta
20. 0 3 2 RELATIVE sampleMantid e Cylindrical monitor 1 COMPONENT nD_Mantid_01 Monitor nD xwidth 4 0 0 0005 0 00002 2 yheight 3 2 options mantid banana theta limits 73 36735 73 36765 bins 100 y limits 1 5 1 5 bins 300 neutron pixel t list all neutrons restore_neutron 1 3 AT 0 0 0 RELATIVE center det The two instruments templateSANS_Mantid instr and ILL_H16_IN5_Mantid instr have these features enabled Other ordinary McStas monitors will also be visible in the resulting Mantid workspace but will not be easily processible using the Mantid TOF data reduction schemes 6 1 3 Compiling and running your simulation for Mantid output Geometry information in Mantid is handled via a so called Instrument Definition File IDF in xml format possibly embedded in a NeXus file The creation of the IDF and related NeXus file is handled in the following steps 1 First of all enable NeXus in the compilation process 1 export MCSTAS CFLAGS g lm O2 DUSE NEXUS INeXus 2 Compile the instrument via the merun utility add mpi if you need parallelization support 1 mcrun c ILL_H16_IN5_Mantid instr n0 3 Generate the IDF via the mcdisplay utility and press enter until the simulation runs 1 mcdisplay format Mantid ILL_H16_IN5_Mantid instr n0 98 4 Finally run a simulation with NeXus output 1 mcrun format NeXus ILL_H16_IN5_Mantid
21. 00 08 2003 AQ 0 3263 A X along Q in plane None AQ 0 3838 A Y perp to X in plane Z upwards Aw 2 2128 meV Resolution matrix l a o 56 464535 0 050060985 0 14036386 7 8074575 0 050060985 52 049324 0 090785419 0 0049608603 0 14036386 0 090785419 37 642463 0 022637548 7 8074575 0 0049608603 0 022637548 1 1323679 Covariance matrix lo 4 o 0 37970629 0 0001159642 0 00015882804 2 6180041 0 0001159542 0 01921267 4 6335128e 05 0 00071623812 0 00015882804 4 6335128e 05 0 02856624 0 0016259803 2 6180041 0 00071623812 0 0016259803 18 933768 Figure 4 9 Output from mcresplot with PGPLOT backend Use P C and G keys to write hardcopy files 4 5 6 Creating and viewing the library component instrument help and Manuals mcdoc McStas provides an easy way to generate automatically an HTML help page about a given component or instrument or the whole McStas library mcdoc mcdoc comp instr mcdoc tools The first example generates an index html catalog file using the available components and instruments both locally and in the McStas library The library catalog of components is opened using the BROWSER environment variable e g netscape konqueror nautilus MSIE mozilla If the BROWSER is not defined the help is displayed as text in the current terminal This latter output may be forced with the t or text option Alternatively ifa component or instrument comp is specified a
22. 1997 p 35 cit on p 13 P A Seeger et al In Physica B 283 2000 p 433 cit on pp 11 13 G Shirane S M Shapiro and J M Tranquada Neutron Scattering with a Triple Aris Spectrometer Cambridge University Press 2002 cit on p 13 D Wechsler et al In Neutron News 25 2000 p 11 cit on pp 11 3 P Willendrup E Farhi and K Lefmann In Physica B 350 2004 p 735 cit on p m Peter Kj r Willendrup et al McStas Past present and future In Journal of Neutron Research 17 1 2014 pp 35 43 ISSN 1023 8166 DOI 10 3233 NR 130004 cit on pp LI 3 G Zsigmond K Lieutenant and S Manoshin et al In Nucl Instr Meth A 529 2004 p 218 cit on pp 25 Index ZBUGS McDoc section YD ESCRIPTION McDoc section 4E ND McDoc section EX AMPLE McDoc section I DENTIFICATION McDoc section 96 IN STRUMENT SITE McDoc section 96 4L INK McDoc section 4P ARAMETERS McDoc section 96 VALIDATION McDoc section include McStas keyword 37 71 ABSOLUTE McStas keyword ABSORB C macro mestas r h 71 Absorption adapt_tree lib library 127 Adaptive sampling ALLOW BACKPROP C macro mestas r h Arm 729 AT McStas keyword author McDoc keyword Authors 4 Backpropagation box intersect C function mccode r c BROWSER environment variable Bugs hard to detect integer versus floating point division 76
23. 64 bit operating system If you experience strange behavior from perl mcgui on Windows like a ppm shell not being able to install the extra Perl packages b mcgui not being able to run compile a simulation all you get is mcrun help output c mcgui not being able to access local component files Solution can be to ensure your user has full control to the executables in c strawberry perl bin Right click Properties Security Authenticated users Edit Mac OS X IMPORTANT Please ensure to use our migration scripts for McStas 2 0 and 1 12c if you want these to co exist with 2 1 They MUST be applied before installing 2 1 See http www mcstas org download install mac os z for details A McStas app bundle in Applications McStas 2 1 app you can uninstall all of McStas 2 1 by dragging this bundle to the trash bin Tk perl package for mcgui SciPDL package for mcplot including the core pgplot package The core mcstas package The mcstas component package with comps instruments datafiles The mcstas Perl tools package with mcgui mcplot etc The mcstas manuals package with PDF docs For VRML and X3D viewing of instruments we recommend Instant Player 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 from
24. Array Table free the Table array e Table Info Array T able display information about all data blocks The format of text files is free Lines starting by characters are considered to be comments and stored in T able header Data blocks are vectors and matrices Block numbers are counted starting from 1 and changing when a comment is found or the column number changes For instance the file MCSTAS data BeO trm Transmission of a Berylium filter looks like 125 oR WN FH woorna 10 11 12 oF WN 5 OLI ODO GVI IH BeO transmission as measured on IN12 Thickness 0 05 m k Angs 1 Transmission 0 1 wavevector multiply 1 0500 0 74441 1 0750 0 76727 1 1000 0 80680 Binary files should be of type float i e REAL 32 and double i e REAL 64 and should not contain text header lines These files are platform dependent little or big endian The filename is first searched into the current directory and all user additional locations specified using the I option see the Running McStas chapter in the User Manual and if not found in the data sub directory of the MCSTAS library location This way you do not need to have local copies of the McStas Library Data files see table 7 8 A usage example for this library part may be t Table Table declare a t Table structure char file BeO trm a file name double x y Table Read gTabl
25. Mantid transfer events and monitor data Matlab B3 E 55 BAES E1 MC_GETPAR C macro mccode r h mccode r library 119 MCDISPLAY McStas keyword mcdisplay McStas tool 55 McDoc 95H96 mcdoc McStas tool 59 mcformat McStas tool mcgui McStas tool MCNP exchange events mcplot McStas tool 34 mcresplot McStas tool 58 mcrun McStas tool MCSTAS environment variable 126 McStas authors citing 9 compiler see mcstas contributors 9 design 14 installation mailing lists p meta language see Meta language name pronunciation 129 release scheme running from the GUI structure mcstas McStas compiler 35H38 mcstas hosts McStas tool 64 64 mcstas r library 119 mcstas2vitess McStas tool MCSTAS FORMAT environment variable 34 MENI Meta language Microsoft Windows see Windows MIN2RAD constant 128 MNEUTRON constant 128 modified by McDoc keyword 96 monitor nd lib library 127 Monte Carlo method accuracy 29 adaptive sampling direction focusing stratified sampling MPI 48 50 63 65 basic usage 66 limitations 68 mcrun 67 performance MS Windows see Windows MYSELF McStas keyword NAME CURRENT COMP C macro mccode r h 120 Neutron absorption state position velocity time spin weight 70 weight see Weight NEXT McStas keyword NeXus extension NORM C macro mccode
26. TRACE ENABLED macro Most Unix like C compilers allow preprocessor macros to be defined using the D option e g 1 cc DMC_TRACE_ENABLED DMC PORTABLE Finally the verbose option will list the components and libraries being included in the instrument 4 3 2 Specifying the location of files The McStas compiler mcstas needs to be able to find various files during compilation some explicitly requested by the user such as component definitions and files referenced by Zinclude and some used internally to generate the simulation executable McStas looks for these files in three places first in the current directory then in a list of directories given by the user and finally in a special McStas directory Usually the user will not need to worry about this as mcstas will automatically find the required files But if users build their own component library in a separate directory or if mcstas is installed in an unusual way it will be necessary to tell the compiler where to look for the files The location of the special McStas directory is set when mcstas is compiled It defaults to usr share mcstas version on Debian and derivatives to usr local mcstas version on RedHat and derivatives and on other Unix like systems including Mac OS X where it is a link to the actual location Applications McStas version app Contents Resources mcstas version and C mcstas version lib on Windows sys tems but it can be changed to somethin
27. The multiline command takes the following form texttt multiline n xl yl zl xn yn z n It draws a series of lines through the n points 1 y1 21 2 Y2 22 En Un Zn It thus accepts a variable number of arguments depending on the value of n This exposes 92 one of the nasty quirks of C since no type checking is performed by the C compiler It is thus very important that all arguments to multiline except n are valid numbers of type double A common mistake is to write 1 multiline 3 x y 0 which will silently produce garbage output This must instead be written as 1 multiline 3 double x double y 0 0 The rectangle command The rectangle command takes the following form 1 rectangle plane x y z width height Here plane should be either xy xz or yz The command draws a rectangle in the specified plane with the center at x y z and the size width x height Depending on plane the width and height are defined as plane width height xy x i XZ x Z yz y Z The box command The box command takes the following form 1 box x y z xwidth yheight zlength The command draws a box with the center at x y z and the size zwidth x yheight x zlength The circle command The circle command takes the following form 1 circle plane x y Z r Here plane should be either xy xz or yz The command draws a circle in the specified plan
28. a simulation quality measurement from this data usually the integrated counts or some peak width For instance for the prisma2 instrument we could write a function for Matlab see section for details about the Matlab data format in order to study the effects of the TT parameter function y instr value p 99 p may be a vector matrix containing many parameters syscmd mcrun prisma2 instr nle5 TI num2str TT gt PHA 22 PHAI 3 PHA2 2 PHA3 1 PHA4 0 PHA5 1 gt PHA6 2 PHA7 3 TTA 44 format Matlab binary system syscmd path path execute simulation and rehash files s mcstas get the simulation data and the monitor data s s prisma2 m_mcstas detector prisma2 tof signal eval s we could also use the statistics field y Mean value of the simulation Then a numerical optimization should be available such as those provided with Mat lab IDL and Perl PDL high level languages In this example we may wish to maximize the instr_value function value The fminsearch function of Matlab is a minimization method that s why we have a minus sign for y value and matlab TT fminsearch instr_value 25 will determine the best value of TT starting from 25 estimate in order to minimize function instr value and thus maximize the mean detector counts 4 5 Using simulation front ends McStas includes a number of front end prog
29. a simulation with PGPLOT output and want to view it using Matlab you may use 1 mcformat file dir d target dir format ARGET FORMAT j to translate files into format TARGET FORMAT e g NeXus When given a directory the translation works recursively The conversion works only for text files The merge option may be used to merge similar files e g obtained from grid systems just as if a longer run was achieved The scan option may be used to reconstruct the scan data from a set of directo ries which vary by instrument parameters For instance you ran a scan but finally realized you should have prolonged it Then simply simulate the missing bits and ap ply mcformat d scan data format PGPLOT scan stepO stepN The result ing scan data is compatible with mcplot only when generating PGPLOT McStas format You may conjugate this option with the merge in order to add merge similar data sets before re building the scan The data files are analyzed by searching keywords inside data files e g Source for the source instrument description file If some file names or component names match these keywords e g using a file Source psd the extracted metadata information may be wrong even though the data itself will be correct 4 6 Data formats Analyzing and visualizing the simulation results To analyze simulation results one uses the same tools as for analyzing experimental data i e programs such as Matla
30. a single detector All this has been copied into the instrument definition On the spectrometer Soller collimators may be inserted at three positions Between monochromator and sample between sample and analyser and between analyser and detector In our instrument definition we have used 30 28 and 67 collimators on these three positions respectively An illustration of the TAS1 instrument is shown in figure Test results and data from the real spectrometer are shown in Appendix 8 3 1 8 3 1 Simulated and measured resolution of TAS1 In order to test the McStas package on a qualitative level we have performed a very detailed comparison of a simulation with a standard experiment from TAS1 The mea 112 surement series constitutes a complete alignment of the spectrometer using the direct beam and scattering from V and Al O3 samples at an incoming energy of 20 0 meV using the second order scattering from the monochromator In these simulations we have tried to reproduce every alignment scan with respect to position and width of the peaks whereas we have not tried to compare absolute intensities Below we show a few comparisons of the simulations and the measurements Figure 8 4 shows a scan of 20m on the collimated direct beam in two axis mode A 1 mm slit is placed on the sample position Both the measured width and non Gaussian peak shape are well reproduced by the McStas simulations 2T scan on 1 mm slit
31. a way to copy a component instance duplicating parameter set as well as any EXTEND GROUP JUMP and WHEN keyword Position AT and rotation ROTATED specification must be explicitly entered in order to avoid component overlapping The syntax for instance copy is 1 COMPONENT name COPY instance_name where instance_name is the name of a preceding component instance in the instrument It may be PREVIOUS as well If you would like to change only some of the parameters in the instance copy you may write e g 1 COMPONENT name COPY instance_name parl 0 par2 1 which will override the original instance parameter values This possibility to over ride parameters is very useful in case of describing e g sample environments using the Isotropic Sqw and PowderN components which allow concentric geometry first instance must have concentric 1 and the second concentric 0 In case EX TEND GROUP JUMP and WHEN keywords are defined for the copied instance these will override the settings from the copied instance 80 In the case where there are many duplicated components all originating from the same instance there is a mechanism for automating copied instance names 1 COMPONENT COPY root name COPY instance name will concatenate a unique number to root_name avoiding name conflicts As a side effect referring to this component instance for e g further positioning is not straight forward as the name is
32. and McStas is all about Thanks to Jonas Stein from Uni Cologne for helping us modernize the TeX documentation General Via NeXus libraries and a new format Mantid setting for the mcdisplay tool we are now able to generate NeXus HDF files that can be read and treated by Mantid Mcdisplay generates a Mantid IDF description for embedding in the NeXus file including the usual McStas instrument geometry Please read the specific guide for this method documented in the McStas manual Chapter 6 Use of STATEPARAMETERS and POLARIZATION parameters is no longer supported If you have home grown components using these you will get this type of error with McStas 2 1 Translating instrument definition BNL_H8 instr into C mcstas t o BNLH8 c BNL_H8 instr Compiling simulation BNLH8 instr 18 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5l 52 53 54 55 56 57 58 59 60 61 62 63 Arm comp is using STATE PARAMETERS mcstas 2 1 does NOT support this keyword Please remove line 36 mcstas 2 1 1 Errors encountered during parse of BNLH8 instr xx Error exit xx As the error message suggests this can be fixed by simply removing commenting out the STATE and POLARISATION parameter lines in the top of the component i e STATE PARAMETERS z y z vur vuy vuz t sl s2 p POLARISATION PARAMETERS sz sy sz In case of nega
33. and section Whenever possible the simulation will try to save the data before ending Most errors appear when using a newly written component in the INITIALIZE TRACE or FINALLY sections Memory errors usually show up when C pointers have not been allocated unallocated before usage whereas mathematical errors are found when for instance dividing by zero 4 4 4 Optimizing simulation speed There are various ways to speed up simulations 44 USR1 Request information status USR2 HUP Request information and performs an intermediate saving of all monitors status and save This triggers the execution of all SAVE sections see chapter 5 INT TERM Save and exit before end status Table 4 3 Signals supported by McStas simulations e Optimize the compilation of the instrument as explained in section 4 3 4 e Execute the simulation in parallel on a computer grid or a cluster with MPI or ssh grid as explained in section 4 7 e Divide simulation into parts using a file for saving or generating neutron events In this way a guide may be simulated only once saving the neutron events at the guide exit as a file which is being read quickly by the second simulation part Use the Virtual_input and Virtual output components for this technique e Use source optimizers like the components Source adapt or Source Optimizer Such component may sometimes not be very efficient when no neutron importance sampling can b
34. arguments are the same as those accepted by the simulations themselves described in section 4 4 with the following extensions e The c or force compile option may be used to force the recompilation of the instrument definition regardless of file dates This may be needed in case any component definitions are changed in which case mcrun does not automatically recompile or if a new version of McStas has been installed e The p file or param file option may be used to specify a file containing assignment of values to the input parameters of the instrument definition The file should consist of specifications of the form name value separated by spaces or line breaks Multiple p options may be given together with direct parameter specifications on the command line If a parameter is assigned multiple times later assignments override previous ones e The N count or numpoints count option may be used to perform a series of count simulations while varying one or more parameters within specified intervals Such a series of simulations is called a scan To specify an interval for a parameter X it should be assigned two values separated by a comma For example the command 1 mcrun sim instr N4 X 2 8 Y 1 would run the simulation defined in sim instr four times with X having the values 2 4 6 and 8 respectively After running the simulation the results will be written to the file mcstas dat by default This file contains one
35. as all the DECLARE instrument variables except instrument parameters may be used To use instrument parameters you should copy them into global variables in the DECLARE instrument section and refer to these latter This component dec laration modifier is of course optional You will find numerous usage examples and in particular in the Sources section of the Component manual In some peculiar configurations it is necessary to position one or more groups of com ponents nested in parallel or overlapping One example is a multiple crystal monochro mator One would then like the neutron ray to interact with one of the components of the group and then continue In order to handle such arrangements without removing neutrons groups are defined by the GROUP modifier after the AT ROTATED positioning 1 GROUP name to all involved component declarations All components of the same named group are tested one after the other until one of them interacts uses the SCATTER macro The selected component acts on the neutron ray and the rest of the group is skipped Such groups are thus exclusive only one of the elements is active Within a GROUP all EXTEND sections of the group are executed In order to discriminate components that are active from those that are skipped one may use the SCATTERED flag which is set to zero when entering each component or group and incremented when the neutron is SCATTERed as in the following example
36. distribution The location of this library is detailed in section 4 3 2 All of them are believed to be reliable and some amount of systematic tests have been carried out However no absolute guaranty can be given concerning their accuracy The contrib directory of the library contains components that were submitted by McStas users but where responsibility has not yet been taken by the McStas core team Additionally the obsolete directory of the library gathers components that were renamed or considered to be outdated These component are kept for backwards com patibility and they still all work as before The mcdoc front end section 4 5 6 enables to display both the catalog of the McStas library e g using mcdoc as well as the documentation of specific components e g with mcdoc text name mcdoc file comp The first line will search for all components matching the name and display their help section as text where as the second example will display the help corresponding to the file comp component using your BROWSER setting or as text if unset The help option will display the command help as usual 101 MCSTAS sources Description Adapt_check ESS_moderator_long ESS moderator short Moderator Monitor Optimizer Source MaxwelL3 Source Optimizer Source adapt Source div Source simple Source gen VirtuaLinput Virtual output Optimization specifier for the Source adapt compone
37. eee a ie ee a a es 77 ere he G ea ae He aS 78 78 se T8 5 4 1 Embedding instruments in instruments TRACE 78 ee 79 Seb toe Soe SE 80 TEL 81 LALN 82 sa amio 84 ea de Oe hae ha ead ed AS 84 5 5 1 The component definition header 85 5 0 2 The DEPENDENCY line 22s se sa aa es TTT ee y eae TT TE ce aes gee a 5 5 11 A component example Slit 5 6 Extending component definitions 5 6 1 Extending from the instrument definition 5 6 2 Component heritage and duplication 5 7 McDoc the McStas library documentation tool 5 7 1 Documentation generators mcdoc and mcgui 5 7 2 The format of the comments in the library source code b Links to other computing codes 61 McStas and MANTID 6 1 1 System requirements 6 1 2 Requirements for the instrument file 6 1 3 Compiling and running your simulation for Mantid output 6 1 4 Looking at instrument output in Mantid 62 McStas and MONP X o The component library Abstract 7 1 A short overview of the McStas component library 8 Instrument examples 8 1 A quick tour of instrument examples 8 1 1 Neutron site Brookhaven 8 1 2 Neutron site lools 8 1 3 Neutron site ILLI 8 1 4 Neutron site tests
38. g component positions are given in meters and units of angles e g rotations are given in degrees The state of the neutron is given by its position x y z in meters its velocity vz Vy Uz in meters per second the time t in seconds and the three spin parameters Sz Sy Sz and finally the neutron weight p described in BB 5 2 Syntactical conventions Comments follow the C and C syntax C style comment C style comment Keywords are not case sensitive for example DEFINE define and dEfInE are all equivalent However by convention we always write keywords in uppercase to dis 70 tinguish them from identifiers and C language keywords In contrast McStas identifiers names like C identifiers and keywords are case sensitive another good reason to use a consistent case convention for keywords All McStas keywords are reserved and thus should not be used as C variable names The list of these reserved keywords is shown in table It is possible and usual to split the input instrument definition across several different files For example if a component is not explicitly defined in the instrument mcstas will search for a file containing the component definition in the standard component library as well as in the current directory and any user specified search directories see section 4 3 2 It is also possible to explicitly include another file using a line of the form 1 include f
39. given in parenthe sis after each name Floating point numbers are denoted by D for the C type double I denotes integer parameters and S denotes strings For parameter 51 scans and optimizations enter the minimum and maximum values to scan opti mize separated by a comma e g 1 10 and do not forget to set the Scanpoints to more than 1 Run Output to allows the entry of a directory for storage of the resulting data files in like the dir option If no name is given the results are stored in the current directory to be overwritten by the next simulation Run Force Forces McStas to overwrite existing data files Neutron count sets the number of neutron rays to simulate the ncount option Run Gravity Activates gravitation handling Not all components full support the use of gravitation but all transport in free space using the PROP_DT PROP ZO etc macros will include propagation with gravity Only local internal component propagation without the PROP routines will be gravity less As a conclusion it is considered safe and to high precision correct to apply the gravitation setting if one takes care to use the Guide_gravity component and other gravity supporting guide types in combination with non gravity components that are small in size i e samples lenses etc Run Random seed Set seed to selects between using a random seed different in each simulation for the random number generator or using a f
40. gt for links to other web pages but see also the LINK section In the generated web documentation pages the text is set in PRE lt PRE gt so that the line breaks in the source will be obeyed The EXAMPLE lines in instrument headers indicate an example parameter set or command that may be run to test the instrument A following Detector name I value indicates what value should be obtained for a given monitor More than one example line may be specified in instruments Any number of 4LINK sections may be given each one contains HTML code that will be put in a list item in the link section of the description web page This usually consists of an lt A HREF lt A gt pointer to some other source of information Optionally an INSTRUMENT SITE section followed by a single word is used to sort instruments by origin location in the Neutron Site menu in mcgui After WEND no more comment text is read by McDoc 6 Links to other computing codes This chapter provides information on interoperability of McStas with other codes and provide links to other sources of information on this topic 6 1 McStas and MANTID As of McStas 2 1 and MANTID 3 2 the teams of the two codes provide a mechanism to transfer simulated McStas events and monitor data to MANTID via NeXus files 6 1 1 System requirements To enable the software link you need the following codes installed on your system e McStas 2 1 or newer
41. home directory or in the MCSTAS tools perl mcstas hosts on the master node one node per line The machines file option enables to specify the hosts file to use If it does not exist only the current machine will be used for multi processor core machines 5 Without ssh keys passwords will be prompted many times To avoid this we recommend to use only the local machine for multi cores cpu i e do not use a machine hosts file 6 Signals are not supported while simulating with MPI since asynchronous events cannot be easily transmitted to all nodes This means it is not possible to cancel an on going computation However simulation scans can be interrupted as soon as the on going computation step ends 7 MPI must be correctly configured if using ssh you have to set ssh keys to avoid use of passwords if using rsh you have to set a rhosts file On non local accounts this procedure may fail and ssh always require passwords MPI Basic usage To enable parallel computation compile mcstas generated C code with mpicc with the flag DUSE_MPI and run it using the wrapper of your MPI implementation mpirun for mpich or lammpi generate a C source file sim c mcstas sim instr generate an executable with MPI support sim mpi mpicc DUSE MPI o sim mpi sim c execute with parallel processing over lt N gt computers here you have to list the computers you want to use 9 Zin a file machines list using
42. instr 6 1 4 Looking at instrument output in Mantid In Mantid your new NeXus file should behave more or less as usual that is e Start by loading the file using either the Load button or the algorithm LoadMcStas to load the event file e After a succesful load you should have a workspace group with this content e Plot the histogram event data stored in the monitor Cp_0 e Plot the TOF events on the full instrument geometry In this step a bit of zooming and translation may be needed to show a nice view of the instrument 99 The instrument ILL_H16_IN5_Mantid instr included in McStas 2 1 will load and present simulated event data but the current time definition of the event data does not comply fully with Mantid for data reduction purposes this should be corrected for the next McStas release 6 2 McStas and MCNP X As of McStas 2 1 we provide a a series of mechanisms to interchange simulated events between McStas and MCNP or MCNPX 1 Typically the intensity parameters in our McStas source components are derived from MCNP X simulations though parametric fits to MCNP tallies 2 The PTRAC method to read MCNP X events into McStas has been available since McStas 1 10 and is a contribution from Chama Hennane ENSIMAG and Emmanuel Farhi ILL 3 The SSR SSW method to send events via the MCNP source surface mechanism between both codes has been available since McStas 2 0 This work has ma
43. line for each simulation run giving the values of the scanned input variables along with the integrated intensity and estimated error in all monitors Additionally a file mcstas m when using Matlab format is written that can be read by the mcplot front end to plot the results on the screen or in a Postscript file see section e When performing a scan the f file and file file options make mcrun write the output to the files file dat and file sim instead of the default names e When performing a scan the d dir and dir dir options make mcrun put all output in a newly created directory dir Additionally the directory will have subdirectories 1 2 3 containing all data files output from the different simula tions When the d option is not used no data files are written from the individual simulations in order to save disk space e The mcrun test command will test your McStas installation accuracy and plotter The h option will list valid options The mcrun front end requires a working instal lation of Perl to run 4 5 3 Graphical display of simulations mcdisplay The front end mcdisplay mcdisplay pl on Windows is a graphical visualization tool very useful for debugging It presents a schematic drawing of the instrument definition showing the position of the components and the paths of the simulated neutrons through the instrument It is thus very useful for debugging a simulation for example to spot components
44. mpich implementation 10 refer to MPI documentation for a complete description 11 mpirun machinefile machines list n 12 sim mpi lt instrument parameters gt LO JAI ODO GG VIO IS If you don t want to spread the simulation run it as usual 66 1 sim mpi lt instrument parameters gt 4 7 3 McRun script with MPI support mpich The mcrun script has been adapted to use MPICH implementation of MPI Two new options have been added e mpi lt number gt tells mcrun to use MPI and to spread the simulation over lt number gt nodes e machines lt file gt defines a text file where the nodes which are to be used for parallel computation are listed by default mcrun will look at HOME mcstas hosts and MCSTAS tools perl mcstas hosts When used on a single SMP machine multi core cpu this option may be omitted When available the MPI option will show up in the mcgui Run dialog Specify the number of nodes required Suppose you have four machines named node1 to node4 A typical machine list file machines list looks like nodel node2 node3 node4 e IW Li You can then spread a simulation sim instr using mcrun 1 mcrun c mpi 4 machines machines list 2 sim instr instrument parameters gt Warning when using mcrun with MPI be sure to recompile your simulation with MPI support see c flag of mcrun a simulation compiled without MPI support cannot be used with
45. neutron ray tracing simulations The goal is that simulations should be of benefit to not only instrument builders but also to users for training experiment planning diagnostics and data analysis In the late 90 ies at Riso National Laboratory simulation tools were urgently needed not only to better utilize existing instruments e g RITA 1 and RITA 2 Lef 00 but also to plan completely new instruments for new sources e g the Spallation Neutron Source SNS and the planned European Spallation Source ESS Ess Writing programs in C or FORTRAN for each of the different cases involves a huge effort with debugging presenting particularly difficult problems A higher level tool specially designed for simulating neutron instruments was needed As there was no existing simulation software that would fulfil our needs the McStas project was initiated In addition the ILL required an efficient and general simulation package in order to achieve renewal of its instruments and guides A significant contribution to both the component library and the McStas kernel itself was early performed at the ILL and included in the package ILL later became a part of the core McStas team Similarly the PSI has applied McStas extensively for instrument design and upgrades provided important component additions and contributed several systematic comparative studies of the European instrument Monte Carlo codes Hence PSI has also become a part of the core McStas te
46. normal to the vector x y z solve 2nd order t A B C Solves the 2 4 order equation At Bt C 0 and returns the smallest positive solution into pointer t B 1 5 Output from detectors Details about using these functions are given in the McStas User Manual 122 DETECTOR_OUT_OD Used to output the results from a single detector The name of the detector is output together with the simulated intensity and estimated statistical error The output is produced in a format that can be read by McStas front end programs e DETECTOR OUT 1D Used to output the results from a one dimensional detector Integrated intensities error etc is also reported as for DETECTOR_OUT_OD e DETECTOR_OUT_2D Used to output the results from a two dimentional detector Integrated intensities error etc is also reported as for DETECTOR_OUT_OD e DETECTOR OUT 3D Used to output the results from a three dimentional detector Arguments are the same as in DETECTOR OUT 2D but with an ad ditional z axis Resulting data files are treated as 2D data but the 3rd dimension is specified in the type fleld Integrated intensities error etc is also reported as for DETECTOR OUT OD e mcinfo simulation FILE f mcformat char pre char name is used to ap pend the simulation parameters into file f see for instance Res monitor Inter nal variable mcformat should be used as specified Please contact the authors for further informat
47. on A usage example of the SPLIT keyword can be found in the Neutron site ILL ILL_H15_IN6 instrument from the mcgui to enhance statistics for neutrons scattering on monochromators and sample 5 5 Writing component definitions The purpose of a McStas component is to model the interaction of a neutron with a physical component of a real instrument Given the state of the incoming neutron ray the component definition calculates the state of the neutron ray when it leaves the component The calculation of the effect of the component on the neutron is performed by a block of embedded C code One example of a component definition is given in section 5 5 11 and all component definitions can be found on the McStas web page and are described in the McStas component manual There exists a large number of functions and constants available in order to write efficient components See appendix B for e neutron propagation functions 84 e geometric intersection time computations e mathematical functions e random number generation e physical constants e coordinate retrieval and operations e file generation routines for monitors e data file reading 5 5 1 The component definition header DEFINE COMPONENT name This marks the beginning of the definition and defines the name of the component DEFINITION PARAMETERS d_1 d 2 SETTING PARAMETERS s 1 s 2 This declares the definition and setting parameters
48. the detector component e p 0 0 is a pointer to the first element in the array of p values for the detector component e amp p2 0 0 is a pointer to the first element in the array of p2 values for the detector component e filename is a string giving the name of the file in which to store the data Note that for a two dimensional detector array the first dimension is along the X axis and the second dimension is along the Y axis This means that element iz i can be obtained as pli n ty if p is a pointer to the first element Three dimensional detectors monitors The results of a three dimensional detector monitor are written to a file using the following macro 1 DETECTOR_OUT 3D t 2 xlabel ylabel 3 xvar x min x max m n j 4 eN 0 0 0 amp p O O 0 amp p2 0 0 0 5 filename The meaning of parameters is the same as those used in the 1D and 2D versions of DETECTOR OUT The available data format currently saves the 3D arrays as 2D with the 3rd dimension specified in the type field of the data header 5 5 8 The FINALLY section FINALLY Zi C code to execute at end of simulation Ae I Ne 91 Wi WW mi This gives code that will be executed when the simulation has ended This might be used to free memory and print out final results from components e g the simulated intensity in a detector This section also triggers the SAVE section to be executed 5 5 9 The M
49. thus useful to get a quick overview of the simulation results In the simplest case the front end is run simply by typing 1 mcplot This will plot any simulation data stored in the current directory which is where simu lations store their results by default If the dir or file options have been used see section 4 4 the name of the file or directory should be passed to mcplot e g mcplot dir or mcplot file It is also possible to plot one single text not binary data file from a given monitor passing its name to mcplot The drawing back end program may be selected among PGPLOT Matlab and Gnu plot using either the pPLOTTER option e g mcplot pMatlab file or using the current MCSTAS FORMAT environment variable Except for the NeXus format all other plotters read the legacy McStas PGPLOT text based data format The mcformat utility will convert any McStas result into an other data format see section 4 5 8 but restricting to text data sets In this case we recommend to generate data sets using PGPLOT McStas format and translate into any other format using mcformat The mcplot front end can also be run from the mcgui front end The initial display shows plots for each detector in the simulation Examples of plotter appearence for mcplot is shown in figures 4 3 McStas PGPLOT back end Clicking the left mouse button on a plot produces a full window version of that plot The P key saves a postscript
50. time shared library is included by default equivalent to include mcstas r in the DECLARE section For an example of include see the monitors Monitor nD component See also section 5 4 for insertion of full instruments in instruments instrument concatenation If the instrument description compilation fails check that the keywords syntax is correct that no semi colon sign is missing e g in C blocks and after an ABSORB macro and there are no name conflicts between instrument and component instances variables 71 Keyword Scope Meaning ABSOLUTE I Indicates that the AT and ROTATED keywords are in the absolute coordinate system AT I Indicates the position of a component in an instrument defi nition COPY LC copy duplicate an instance or a component definition DECLARE LC Declares C internal variables DEFINE LC Starts an INSTRUMENT or COMPONENT definition DEFINITION C Defines component parameters that are constants define DEPENDENCY C I Indicates any library dependency required to create the in strument END LC Ends the instrument or component definition SPLIT I Enhance incoming statistics by event repetition EXTEND I Extends a component TRACE section plug in FINALLY LC Embeds C code to execute when simulation ends GROUP I Defines an exclusive group of components include LC Imports an instrument part a component or a piece of C code when within embedded C JUMP I
51. 1 4 just like parameter scans Optionally the starting guess value might be given with the syntax param min guess max The optimization accuracy criterion is controlled using the Precision entry box in the configuration options See Figure 4 6 Finally run the simulation The optimum set of parameters is then printed at the end of the simulation process You may ask to maximize only given monitors instead of all by selecting their component names in the lower lists in the Run Dialog up to 3 If you would like to maximize the flux at a given monitor with some divergence con strains you should for instance simply add a divergence collimator before the monitor Alternatively write a new component that produce the required figure of merit The optimization search interval constrains the evolution of parameters It should be chosen carefully In particular it is safer for it to indeed contain a high signal domain and be preferably symmetric with respect to that maximum Using custom optimization routines The user should write a function script or a program that e inputs the simulation parameters which are usually numerical values such as TT in the prisma2 instrument from the examples directory of the package 46 BR SCO OANOOBWNH OOI ODO GVI I e builds a command line from these parameters e executes that command and waits until the end of the computation e reads the relevant data from the monitors e outputs
52. 9 INR 190001 cit on p 1 E Farhi et al In Appl Phys A 74 2002 S1471 cit on pp 12 13 25 E Fermi J Marshall and L Marshall In Phys Rev 72 1947 p 193 cit on p 13p A K Freund In Nucl Instr Meth 213 1983 p 495 cit on p 13 Grimmett G R and Stirzakerand D R Probability and Random Processes 2nd Edition Clarendon Press Oxford 1992 cit on p 25 F James In Rep Prog Phys 43 1980 p 1145 cit on pp 13 25 29 Erik Bergback Knudsen Esben Bryndt Klinkby and Peter Kje r Willen drup McStas event logger Definition and applications In Nuclear In struments and Methods in Physics Research Section A Accelerators Spec trometers Detectors and Associated Equipment 738 0 2014 pp 20 24 ISSN 0168 9002 DOI http dx doi org 10 1016 j nima 2013 11 071 cit on p 100 W T Lee and X L Wang In Neutron News 13 2002 See website http www sns gov ideas p 30 cit on pp 11 13 K Lefmann and K Nielsen McStas a general software package for neutron ray tracing simulations In Neutron News 10 1999 pp 20 23 DOI 40 11080 10448639908283684 cit on pp D TI 13 K Lefmann et al Added flexibility in triple axis spectrometers the two RITAs at Riso In Physica B 283 2000 pp 343 354 cit on p 12 K Lieutenant In J Phys Condens Matter 17 2005 S167 cit on pp 12 19 5 R A Lowde In J Nucl E
53. ACE section As a summary the usual grammar for component instances within the instrument TRACE section is COMPONENT name comp parameters AT RELATIVE reference PREVIOUS ABSOLUTE ROTATED RELATIVE reference PREVIOUS ABSOLUTE The TRACE keyword starts a section giving the list of components that constitute the instrument Components are declared like this COMPONENT name comp p 1 This declares a component named name that is an instance of the component definition named comp The parameter list gives the setting and definition parameters for the component The expressions e1 2 define the values of the parameters For setting parameters arbitrary ISO C expressions may be used while for definition parameters only constant numbers strings names of instrument parameters or names of C iden tifiers are allowed see section for details of the difference between definition and TO setting parameters To assign the value of a general expression to a definition parame ter it is necessary to declare a variable in the DECLARE section assign the value to the variable in the INITIALIZE section and use the variable as the value for the parameter The McStas program takes care to rename parameters appropriately in the output so that no conflicts occur between different component definitions or between component and instrument definitions It is thus possible and usual to use a component defini
54. AGS g 02 wd177 266 1011 181 To use icc with MPI on Unix system see Section installations it seems that editing the mpicc shell script and setting the CC variable to icc is the only requirement On Windows the Intel c compiler is icl not icc and has a dependency for Microsoft Visual C If you have both these softwares available running McStas with the Intel compiler should be possible currently untested by the McStas developer team 38 The O option typically enables the optimization phase of the compiler which can make quite a difference in speed of mcstas generated simulations The o name out sets the name of the generated executable The 1m options is needed on many systems to link in the math runtime library like the cos and sin functions Monte Carlo simulations are computationally intensive and it is often desirable to have them run as fast as possible Some success can be obtained by adjusting the compiler optimization options Here are some example platform and compiler combinations that have been found to perform well up to date information will be available on the McStas WWW home page Mes e Intel x86 PC with Linux and GCC using options gcc O3 e Intel x86 with Linux and EGCS GCC derivate using options egcc 06 e Intel x86 with Linux and PGCC pentium optimized GCC derivate using options gcc O6 mstack align double e HPPA machines running HPUX with the optional ISO C co
55. AT 0 0 0 ABSOLUTE COMPONENT B Guide Parameters AT 0 0 1 RELATIVE A AT 0 0 1 RELATIVE B Instrument file DEFINE INSTRUMENT Example Param1 1 string Param2 two COMPONENT C DiskChopper Parameters COMPONENT D TOF monitor Parameters filename Tof dat AT 0 0 Paraml RELATIVE PREVIOUS Source comp c code Guide comp c code DiskChopper comp c code TOF monitor comp c code Component library The simulation executable produces data output which can be visualized using the mcplot and mcdisplay tools Random VO Physical numbers consts Kernel and runtime c code Figure 4 1 An illustration of the structure of McStas 32 will hopefully be solved in a further release We recommend to use ActiveState Perl 5 10 Note that as of McStas 1 10 all needed support tools for Windows are bundled with McStas in a single installer file 4 1 2 New releases of McStas Releases of new versions of a software package can today be carried out more or less continuously However users do not update their software on a daily basis and as a compromise we have adopted the following policy of McStas e The versions 2 1 x will possibly contain bug fixes and minor new functionality A new manual will however not be released and the modifications are documented on the McStas web page The extensions of the forthcoming vers
56. C macro mestas r h 121 RMS2FWHM constant 128 ROT A COMP C macro mccode r h ROT A CURRENT COMP C macro mcecode r h rot_apply C function mccode r c ROT_R_COMP C macro mccode r h ROT_R_CURRENT_COMP C macro mecode rh rot_set_rotation C function mccode r c 122 136 rot transpose C function mccode r c 122 rotate C macro mccode r h ROTATED McStas keyword Run time 729 Sampling SAVE McStas keyword scalar_prod C function mccode r c 122 SCATTER C macro mcstas r h 80 729 121 SCATTERED C macro mccode r h 1 SE2V constant Setting parameter SETTING PARAMETERS McStas keyword SHARE McStas keyword SIGHUP 45 SIGINT Signal handler HUP signal INT signal TERM signal USR1 signal USR2 signal 44 SIGTERM SIGUSR1 SIGUSR2 44 45 77 solve_2nd_order C function mccode r c FEZ sphere intersect C function mecode r c 129 SPLIT McStas keyword Statistics uncertainty STORE NEUTRON C macro mestas r h Stratified sampling Table Free C function read table lib c 725 Table_Free_Array C function read_table lib c 125 Table Index C function read table lib c Table Info C function read table lib c Table Info Array C function read table lib c 125 Table Init C function read table lib c 12 Table Read C function read_table lib c ZI Table Read Array C func
57. CDISPLAY section MCDISPLAY Zi C code to draw a sketch of the component n This gives C code that draws a sketch of the component in the plots produced by the mcdisplay front end see section 4 5 3 The section can contain arbitrary C code and may refer to the parameters of the component but usually it will consist of a short sequence of the special commands described below that are available only in the MCDISPLAY section When drawing components all distances and positions are in meters and specified in the local coordinate system of the component The MCDISPLAY section is optional If it is omitted mcdisplay will use a default symbol a small circle for drawing the component The magnify command This command if present must be the first in the section It takes a single argument a string containing zero or more of the letters x y and z It causes the drawing to be enlarged along the specified axis in case mcdisplay is called with the zoom option For example magnify xy The line command The line command takes the following form line x I yl z x2 y2 22 It draws a line between the points x1 y1 z1 and xo yo 22 The dashed_line command The dashed_line command takes the following form dashed line x 1 yel zel x2 y2 2722 ru It draws a dashed line between the points x1 yi 21 and 2 yo z2 with n equidistant spaces The multiline command
58. CLARE section This section is optional Component setting parameters may be modified in this section affecting the rest of the component 5 5 6 The TRACE section C code to compute neutron interaction with component 7 This performs the actual computation of the interaction between the neutron ray and the component The C code should perform the appropriate calculations and assign the resulting new neutron state to the state parameters Most components will require propagation routines to reach the component entrance area Special macros PROP ZO and PROP DT are provided to automate this process see section B 1 The C code may also execute the special macro ABSORB to indicate that the neutron has been absorbed in the component and the simulation of that neutron will be aborted On the other hand if the neutron event should be allowed be backpropagated the special macro ALLOW BACKPROP should precede the call to the PROP call inside the 88 component When the neutron state is changed or detected for instance if the com ponent simulates multiple events as multiple reflections in a guide the special macro SCATTER should be called This does not affect the results of the simulation in any way but it allows the front end programs to visualize the scattering events properly and to handle component GROUPs in an instrument definition see section 5 3 6 It basically increments the SCATTERED counter The SCATTER macro shou
59. COMPONENT name0 comp p l e l p2 e 2 ozo AT 0 0 0 ABSOLUTE COMPONENT namel comp GROUP GroupName EXTEND 79 zi if SCATTERED printf I scatter else printf I do not scatter COMPONENT name2 comp AT ROTATED GROUP GroupName Components namel and name2 are at the same position If the first one intercepts the neutron and has a SCATTER within its TRACE section the SCATTERED variable becomes true the code extension will result in printing I scatter and the second component will be skipped Thus we recommend to make use of the SCATTER keyword each time a component uses the neutron scatters detects within component definitions see section 5 5 Also the components to be grouped should be consecutive in the TRACE section of the instrument and the GROUPed section should not contain components which are not part of the group A usage example of the GROUP keyword can be found in the Neutron site ILL ILL_H15_IN6 instrument from the mcgui to model 3 monochroma tors Combining EXTEND GROUP and WHEN can result in unexpected behavior Please read the related warning at the end of section 5 4 4 5 4 3 Duplication of component instances COPY Often one has a set of similar component instances in an instrument These could be e g a set of identical monochromator blades or a set of detectors or guide elements Together with JUMPs see below there is
60. CTOROUT infrastructure x Simplified code structure x Proper support for MPI when generating NeXus event lists New logic wrt negative time propagation Neutrons are restored rather than ABSORB ed Improvement of the interpolation routines e g for magnetic fields search is performed roughly in constant time Read_Table better search for files including from full executable path from source instr location from PWD and from McCode lib ref lib c If components use alpha 0 and w 0 in parametrizing the reflectivity the StdReflecFunc applies a phenomenological fit of Swiss Neutronics mirrors above m 3 including a 2nd order beta term The fits were done by Henrik Jacobsen University of Copenhagen Tools Since 2 0 mcgui Perl and mcrun Python has been generating time stamped output directories if no output dir was specified The legacy mcrun Perl now exhibit this behavior also This is balanced by the possiblitiy to choose dot as the output directory then the legacy behaviour of storing data in the working directory is enabled Documentation Modernized and facelifted TeX documentation in the manuals which include slightly updated Component manual A few components docs parameter tables are now extracted from mcdoc and included in the manual New Components Rotator and Derotator components that allow a section of the instrument to rotate in time New ESS_moderator component by P Willendrup
61. E Klinkby and T Schoenfeldt DIU new ess source lib with brilliance defintitions corresponding to Mezei 2001 TDR and 2014 brilliances support for geometrical brilliance variation i e pancake geometry x much simplified input parameter setup various fixes wrt McStas 2 0 and later updated source modules Monitor_Sqw generates an Sqw between a sample and a detector a kind of inelastic resolution monitor 22 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 Emmanuel Farhi Analyzer ideal comp ideal analyzer for Spin Echo techniques Erik Knudsen Pol_pi_2_rotator comp idealized pi 2 flipper for Spin Echo Erik Knudsen Pol triafield comp idealized triangular coil Delft for Spin Echo Erik Knudsen Scatter log iterator comp see above notice about Scatter logging Scatter_log_iterator_stop comp see above notice about Scatter logging Scatter logger comp see above notice about Scatter logging Scatter logger stop comp see above notice about Scatter logging SANS benchmark2 comp benchmarked SANS component from Heinrich Frielinghaus FZJ Updated Components Single_crystal and PowderN have both been optimized for speed especially in connection with using the SPLIT keyword x The first pr
62. Iterative loops and conditional jumps INITIALIZE LC Embeds C code to be executed when starting ITERATE I Defines iteration counter for JUMP MCDISPLAY C Embeds C code to display component geometry OUTPUT C Defines internal variables to be public and protected symbols usually all global variables and functions of DECLARE PARAMETERS C Defines a class of component parameter DEFINITION SET TING PREVIOUS C Refers to a previous component position orientation RELATIVE I Indicates that the AT and ROTATED keywords are relative to an other component REMOVABLE I Indicates that this component will be removed when the in strument is inserted into an other one using the include keyword ROTATED I Indicates the orientation of a component in an instrument definition SAVE LC Embedded C code to execute when saving data SETTING C Defines component parameters that are variables SHARE C Declares global functions and variables to be shared TRACE LC Defines the instrument as a the component sequence WHEN I Condition for component activation and JUMP Table 5 1 Reserved McStas keywords Scope is I for instrument and C for component definitions 72 HD GI k VO IV Gh 5 3 Writing instrument definitions The purpose of the instrument definition is to specify a sequence of components along with their position and parameters which together make up an instrument Each com ponent is given its own l
63. MPI whereas a simulation compiled with MPI support can be used without MPI 4 7 4 McStas MPI Performance Theoretically a computation which lasts 7 seconds on a single computer should lasts at least seconds when it is distributed over p computers In practice there will be overhead time due to the split and merge operations e the split is immediate constant time cost O 1 e the merge is at worst linear against the number of computers linear time cost O p when saving an event list logarithmic time cost O log p when not saving an event list 67 The efficiency of McStas using MPI has been tested on large clusters up to 500 nodes The computation time decreases in the same proportion as the number of nodes showing an ideal efficiency However a small overhead may appear depending on the cluster internal network load which may be estimated at most of about 10 20 s This overhead comes from the spread and the fusion of the computations For instance spreading a computation implies often an rsh or and ssh session to be opened on every node To reach the best efficiency the computation time should not be lower than 30 seconds or the overhead time may become significant compared to total time McStas computation time using MPI f r Execution time s 6 min we j LI Total time e Computing time templateTOF simulation with 10 initial events o o 107 Number of CPUs Figure 4 10
64. McStas MPI execution time as a function of computing nodes with tem 4 7 5 MPI and Grid Bugs and limitations 68 e Some header of output files might contain minor errors plate TOF instrument and 1e8 initial neutron events Tests performed on LonestarQTACC US Teragrid 2008 e The computation split does not take into account the speed or the load of nodes the overall time of a distributed computation is forced by the slowest node for optimal performance the cluster should be homogeneous e Interacting with a running simulation USR1 and USR2 signals is disabled with 5 The McStas kernel and meta language Instrument definitions are written in a special McStas meta language which is translated automatically by the compiler mcstas into a C program which is in turn compiled to an executable that performs the simulation The meta language is custom designed for neutron scattering and serves two main purposes i to specify the interaction of a single neutron ray with a single optical component and ii to build a simulation by constructing a complete instrument from individual components For maximum flexibility and efficiency the meta language is based on C Instrument geometry propagation of neutrons between the different components parameters data input output etc is handled in the meta language and by the compiler mcstas Com plex calculations are written in C embedded in the meta language description of the component
65. PI 0 RELATIVE PREVIOUS 13 JUMP CG 2 Position ITERATE n COMPONENT CG Out Arm AT 0 0 L n RELATIVE PREVIOUS Similarly to the WHEN modifier see section 5 4 4 JUMP only applies within the TRACE section of the instrument definition Other sections INITIALIZE SAVE MCDISPLAY FINALLY are executed independently of the jump As a side effect the 3D view of the instrument mcdisplay will show components as if there was no jump This means that in the following example the very long guide 3D view only shows a single guide element It is not recommended to use the JUMP inside GROUPs as the JUMP condition counter applies to the component instance within its group We would like to emphasize the potential errors originating from such jumps Indeed imbricating many jumps may lead to situations were it is difficult to understand the flow of the simulation We thus recommend the usage of JUMPs only for experienced and cautious users 83 5 4 6 Enhancing statistics reaching components SPLIT The following method applies when the incoming neutron event distribution is considered to be representative of the real beam but neutrons are lost in the course of propagation with low efficiency processes absorption etc Then one may think that it s a pity to have so few events reaching the interesting part of the instrument usually close to the end of the instrument description If some components make extensive use of random num
66. Physics Physics Department Technical University of Denmark 2800 Kongens Lyngby Denmark We User and Programmers Guide to the Neutron Ray Tracing Package McStas version 2 1 P Willendrup E Farhi E Knudsen U Filges K Lefmann J Stein September 2014 The software package McStas is a tool for carrying out Monte Carlo ray tracing sim ulations of neutron scattering instruments with high complexity and precision The simulations can compute all aspects of the performance of instruments and can thus be used to optimize the use of existing equipment design new instrumentation and carry out virtual experiments for e g training experimental planning or data analysis McStas is based on a unique design where an automatic compilation process translates high level textual instrument descriptions into efficient ISO C code This design makes it simple to set up typical simulations and also gives essentially unlimited freedom to handle more unusual cases This report constitutes the reference manual for McStas and together with the man ual for the McStas components it contains documentation of most aspects of the pro gram It covers the various ways to compile and run simulations a description of the meta language used to define simulations and some example simulations performed with the program This report documents McStas version 2 1 released September 2014 The authors are Peter Kj r Willendrup lt pkwi fysik dtu dk gt
67. ROT RCURRENT COMP give the ori entation of the current component as rotation matrices absolute orientation and the orientation relative to the previous component respectively A component of a rotation matrix is referred to as ROT A CURRENT COMP m n where m and n are 0 1 or 2 standing for x y and z coordinates respectively POS_A_COMP comp gives the absolute position of the component with the name comp Note that comp is not given as a string A component of the vector is referred to as POS A COMP comp i where i is x y or z ROT A COMP comp and ROT R COMP comp give the orientation of the component comp as rotation matrices absolute orientation and the orientation relative to its previous component respectively Note that comp is not given as a string A component of a rotation matrice is referred to as ROT A COMP comp m n where m and n are 0 1 or 2 INDEX CURRENT COMP is the number index of the current component starting from 1 POS A COMP INDEX index is the absolute position of component indez POS A COMP INDEX INDEX CURRENT COMP is the same as POS A CURRENT COMP You may use POS A COMP INDEX INDEX CURRENT COMP r1 to make for instance your component access the position of the next component this is usefull for automatic targeting A component of the vector is referred to as POSA COMP INDEX index i where i is x y or z POS R COMP INDEX works the same as above but with relative coordinates S
68. TORE NEUTRON indez x y z uz vy vz t sv sy sz p stores the current neutron state in the trace history table in local coordinate system index is usu ally INDEX CURRENT COMP This is automatically done when entering each component of an instrument RESTORE NEUTRONindez y Z vz vy vz t sx sy sz p restores the neu tron state to the one at the input of the component index To ignore a component effect use RESTORE NEUTRON INDEX_CURRENT_COMP L Y Z VI vy VZ t ST SY SZ p at the end of its TRACE section or in its EXTEND section These neutron states are in the local component coordinate systems SCATTERED is a variable set to 0 when entering a component which is incre mented each time a SCATTER event occurs This may be used in the EXTEND sections to determine whether the component interacted with the current neutron ray extend_list n amp arr amp len elemsize Given an array arr with len elements each of size elemsize make sure that the array is big enough to hold at least n elements by extending arr and len if necessary Typically used when reading a list of numbers from a data file when the length of the file is not known in advance mcset ncount n Sets the number of neutron histories to simulate to n mcget ncount Returns the number of neutron histories to simulate usually set by option n mcget run num Returns the number of neutron histories that have been sim ulated until now 121
69. aches but accurate estimates for the flux resolution and generally the optimum parameter set benefit considerably from MC methods Mathematically the Monte Carlo method is an application of the law of large numbers GRR92 Let f u be a finite continuous integrable function of parameter u for which an integral estimate is desirable The discrete statistical mean value of f computed as a series in the uniformly sampled interval a lt u lt b converges to the mathematical mean value of f over the same interval b lim Ji 5 flui f u du 3 1 In the case were the u values are regularly sampled we come to the well known midpoint integration rule In the case were the u values are randomly but uniformly sampled this is the Monte Carlo integration technique As random generators are not perfect we rather talk about quasi Monte Carlo technique We encourage the reader to consult James for a detailed review on the Monte Carlo method 25 3 2 The neutron weight A totally realistic semi classical simulation will require that each neutron is at any time either present or lost In many instruments only a very small fraction of the initial neutrons will ever be detected and simulations of this kind will therefore waste much time in dealing with neutrons that never hit the relevant detector or monitor An important way of speeding up calculations is to introduce a neutron weight factor for each simulated neutron ray and to adj
70. achines MACHINES Specify a list of distant machines nodes to be used for MPI and grid clustering Default is to use local SMP cluster optim Run in optimization mode to find best parameters in order to maximize all monitor integral values Parameters to be varied are given just like scans min max optim COMP Same as optim but for specified monitors This option may be used more than once optim prec ACCURACY Sets accuracy criteria to end parameter optimization default is 1073 test Run McStas self test c force compile Force to recompile the instrument Table 4 2 Additional options accepted by McStas simulations 43 4 4 3 Interacting with a running simulation Once the simulation has started it is possible under Unix Linux and Mac OS X systems to interact with the on going simulation This feature is not available when using MPI parallelization McStas attaches a signal handler to the simulation process In order to send a signal to the process the process id pid must be known Users may look at their running processes with the Unix ps command or alternatively process managers like top and gtop If a file out simulation obtained from McStas is running the process status command should output a line resembling 1 lt user gt 13277 7140 99 23 52 pts 2 00 00 13 file out where user is your Unix login The pid is there 13277 Once known it is
71. am Since year 2001 Risg was no longer a neutron source and the authors from that site have moved on to positions at University of Copenhagen NBI and Technical University of Denmark DTU Physics hence these two partners have joined the core McStas team It is further envisioned that the future ESS Data Management and Software Centre ESS DMSC will contribute to the project in the future 1 2 Scientific background What makes scientists happy Probably collect good quality data pushing the instru ments to their limits and fit that data to physical models Among available measure ment techniques neutron scattering provides a large variety of spectrometers to probe structure and dynamics of all kinds of materials Neutron scattering instruments are built as a series of neutron optics elements Each of these elements modifies the beam characteristics e g divergence wavelength spread spatial and time distributions in a way which for simple neutron beam configurations may be modeled with analytic methods This is valid for individual elements such 12 as guides Mil90 choppers Low60 Cop03 Fermi choppers FMM47 Pet05 velocity selectors Cla 66 monochromators Fre83 Sea97 SST02 Ali04 and detectors Rad74 Pes 89 Man 04 In the case of a limited number of optical elements the so called acceptance diagram theory Mil90 Cop93 may be used within which the neutron beam distributions are considered to b
72. arent definition In prac tice you could copy a component and only rewrite some of it as in the following example 1 DEFINE COMPONENT child name COPY parent name 2 3 SETTING PARAMEIERS newparl newpar2 4 INITIALIZE COPY parent name EXTEND 5 f 6 C code to be concatenated to the parent_name INITIALIZE T Do 8 SAVE 9 f 0 C code to replace the parent_name SAVE 1 99 where two additional parameters have been defined and should be handled in the ex tension of the original INITIALIZE section On the other hand if you do not derive a component as a whole from a parent you may still use specific parts from any component DEFINE COMPONENT name DECLARE COPY parentl INITIALIZE COPY parent2 EXTEND ni C code to be concatenated to the parent2 INITIALIZE oF WN Gi 94 6 7 TRACE COPY parent3 This mechanism may lighten the component code but a special care should be taken in mixing bits from different sources specially concerning variables This may result in difficulties to compile components 5 7 McDoc the McStas library documentation tool McStas includes a facility called McDoc to help maintain good documentation of com ponents and instruments In the source code comments may be written that follow a particular format understood by McDoc The McDoc facility will read these comments and automatically produce output documentation in various forms By using the source code itself
73. as the source of documentation the documentation is much more likely to be a faithful and up to date description of how the component instrument actually works 5 7 1 Documentation generators mcdoc and mcgui Two forms of documentation can be generated One is the component entry dialog in the mcgui front end see section 4 5 1 The other is a collection of web pages documenting the components and instruments handled via the mcdoc front end see section 4 5 6 and the complete documentation for all available McStas components and instruments may be found at the McStas web page Mes as well as in the McStas library see 7 1 Al available McStas documentation is accessible from the mcgui Help menu Note that McDoc compliant comments in the source code are no substitute for a good reference manual entry The mathematical equations describing the physics and algorithms of the component should still be written up carefully for inclusion in the component manual The McDoc comments are useful for describing the general behavior of the component the meaning and units of the input parameters etc 5 7 2 The format of the comments in the library source code The format of the comments understood by McDoc is mostly straight forward and is designed to be easily readable both by humans and by automatic tools McDoc has been written to be quite tolerant in terms of how the comments may be formatted and broken across lines A good way to get a feeli
74. at mcstas support mcstas org or consult the McStas home page Mes A special bug request reporting service is available Mcz If you appreciate this software please subscribe to the mcstas users mcstas org email list send us a smiley message and contribute to the package We also encourage you to refer to this software when publishing results with the following citations e P Willendrup E Farhi E Knudsen U Filges and K Lefmann Journal of Neutron Research 17 2014 35 e K Lefmann and K Nielsen Neutron News 10 3 20 1999 e P Willendrup E Farhi and K Lefmann Physica B 350 2004 735 McStas 2 1 contributors Several people outside the core developer team have been contributing to McStas 2 1 e Thanks to Jonas Stein from Uni Cologne for helping us modernize the T X docu mentation e Thanks to Esben Klinkby and Troels Schonfeldt from DTU Nutech for helping Peter W with modernizing the ESS_moderator comp e Thanks to R Heenan for contributing the ISIS ISIS_SANS2d instrument Thanks to Klaus Habicht and Markos Skoulatos HZB for contributing the HZB FLEX instrument Thanks to Morten Sales HZB for contributing the SEMSANS instrument Thanks to Henrich Frielinghaus FZJ for contributing the SANS_benchmark2 comp component and the related FZJ_BenchmarkSfin2 test instrument Thanks to Esko Oksanen ESS for contributing lau reflection lists for the macro molecular structures Rubedoxin and Perdeuterated pyrophospha
75. b NumPy IDL The output files from simulations are usually simple text files containing headers and data blocks If data blocks are empty they may be accessed referring to an external file indicated in the header Each data file contains information about the simulation the instrument the param eters used and of course the signal the estimated error on the signal and the number of events used in each bin Additionally all data files indicate their first moment mean value and second moment half width in the statistics field The available data formats are the legacy McStas McCode format and the HD F NeXus binary when the needed libraries are installed In order for the user to choose the data format we recommend to set it using the format FORMAT or alternatively via the MCSTAS_FORMAT environment variable which will also make the front end programs able to import and plot data and instrument consistently see Section 4 4 Note that the neutron event counts in detectors are typically not very meaningful except as a way to measure the performance of the simulation Use the simulated intensity instead whenever analyzing simulation data 61 4 6 1 McStas and PGPLOT format The McStas original format which is equivalent to the PGPLOT format is simply columns of ASCII text that most programs should be able to read One dimensional histogram monitors time of flight energy write one line for each histogram bin Each line c
76. bers MC choices they shuffle this way the distributions so that identical incoming events will not produce the same outgoing event In this case you may use the SPLIT keyword with the syntax 1 SPLIT r COMPONENT name comp where the optional number r specifies the number of repetitions for each event Default is r 10 Each neutron event reaching component name will be repeated r times with a weight divided by r so that in practice the number of events for the remaining part of the simulation down to the END will potentially have more statistics This is only true if following components and preferably component name use random numbers You may use this method as many times as you wish in the same instrument e g at the monochromator and sample position This keyword can also be used within a GROUP The efficiency is roughly r raised to the number of occurrences in the instrument so that enhancing two components with the default r 10 will produce at the end an enhancement effect of 100 in the number of events The execution time will usually get slightly longer This technique is known as the stratified sampling see Appendix 3 If the instrument makes use of global variables e g in conjunction with a WHEN or User Variable monitoring see Monitor nD you should take care that these variables are set properly for each SPLIT loop which usually means that they must be reset inside the SPLITed section and assigned used further
77. cal information from the simu lated neutron rays As the use in non interactive please use with a limited number of neutron rays n ncount For export of graphics combine with e g gif The mcdisplay front end will then require the Perl te PGPLOT and the PGPerl packages to be installed It may be necessary to set the PGPLOT DIR and PGPLOT DEV environment variable consult the documentation for PGPLOT on the local system in case of difficulty 56 Matlab and back end A 3D view of the instrument and various operations zoom export print trace neutrons is available from dedicated Graphical User Interfaces The inspect option may be used see previous paragraph as well as the first and last options to specify a region of interest The mcdisplay front end will then require the Perl and Matlab to be installed VRML OpenGL back ends When using the pVRML option the instrument is shown in Virtual Reality using OpenGL You may then walk aside instrument or go inside elements following neutron trajectories As all neutron trajectories are stored into a VRML file you better limit the number of stored trajectories below 1000 otherwise file size and processing time becomes significant The inspect option is not available in VRML format display 4 5 4 Plotting the results of a simulation mcplot The front end mcplot mcplot pl on Windows is a program that produces plots of all the monitors in a simulation and it is
78. ch they originate In case the data must be analyzed with programs that cannot read files with such headers they may be turned off using the data only or a option The format of the output files from McStas simulations is described in more detail in section It may be chosen either with format FORMAT for each simulation or globally by setting the MCSTAS_FORMAT environment variable The available format list is obtained using the name out help option McStas can presently generate the McStas PGPLOT and the NeXus format It is also possible to create and read Vitess MCNP PTRAC and Tripoli4 batch neu tron event files using components e Vitess input and Vitess output e Virtual tripoli4 input and Virtual tripoli4 output e Virtual mcnp input and Virtual mcnp output Additionally adding the raw keyword to the FORMAT will produce raw N p p data sets instead of N p o see Section 3 2 1 The former representation is fully additive and thus enables to add results from separate simulations e g when using a computer Grid which is automated in the mcformat tool Other acceptable format modifiers are transpose to transpose data matrices and append to concatenate data to existing files 4 4 2 Basic import and plot of results The previous example will result in a mcstas sim file that may be read directly from Matlab using the sim file function matlab gt s mcstas matlab gt s mcstas plot The first line returns
79. ctions used by a set of monitors e g Monitor nD Res monitor Virtual output etc It may monitor any kind of data create the data files and may dis play many geometries for mcdisplay Refer to these components for implementation examples and ask the authors for more details B 4 Adaptive importance sampling Library This library is currently only used by the components Source adapt and Adapt check It performs adaptive importance sampling of neutrons for simulation efficiency optimiza tion Refer to these components for implementation examples and ask the authors for more details B 5 Vitess import export Library This library is used by the components Vitess_input and Vitess_output as well as the mcstas2vitess utility Refer to these components for implementation examples and ask the authors for more details B 6 Constants for unit conversion etc The following predefined constants are useful for conversion between units 127 Name Value Conversion from Conversion to DEG2RAD 27 360 Degrees Radians RAD2DEG 360 27 Radians Degrees MIN2RAD 27 360 60 Minutes of arc Radians RAD2MIN 360 60 27 Radians Minutes of arc V2K 101 my h Velocity m s k vector A K2V 10719 A my k vector T Velocity m s VS2E mn 2e Velocity squared m s Neutron energy meV SE2V 2e mn Square root of neutron Velocity m s energy meVY FWHM2RMS 1 8 log 2 Full width half maximum Root mean square stan
80. dard deviation RMS2FWHM 8log 2 Root mean square stan Full width half maxi dard deviation mum MNEUTRON 1 67492 107 kg Neutron mass mn HBAR 1 05459 10784 Js Planck constant PI 3 14159265 T FLT MAX 3 40282347E 38F a big float value 128 C The McStas terminology This is a short explanation of phrases and terms which have a specific meaning within McStas We have tried to keep the list as short as possible with the risk that the reader may occasionally miss an explanation In this case you are more than welcome to contact the McStas core team e Arm A generic McStas component which defines a frame of reference for other components e Component One unit e g optical element in a neutron spectrometer These are considered as Types of elements to be instantiated in an Instrument description e Component instance A named Component of a given Type inserted in an Instrument description e Definition parameter An input parameter for a component For example the radius of a sample component or the divergence of a collimator e Input parameter For a component either a definition parameter or a setting parameter These parameters are supplied by the user to define the characteris tics of the particular instance of the component definition For an instrument a parameter that can be changed at simulation run time e Instrument An assembly of McStas components defining a neutron spectrometer e Ker
81. determined by mcstas and does not depend completely on the user s choice even though the PREVIOUS keyword may still be used We thus recommend to use this naming mechanism only for components which should not be referred to in the instrument This automatic naming may be used anywhere in the TRACE section of the instru ment so that all components which do not need further referring may be labeled as COPY Origin As an example we show how to build a guide made of equivalent elements Only the first instance of the Guide component is defined whereas following instances are copies of that definition The instance name of Guide components is set automatically COMPONENT CG In Arm AT COMPONENT CG1 Guide gravity l L n m 1 AT 0 0 0 RELATIVE PREVIOUS COMPONENT COPY CG 1 COPY CG_1 AT 0 0 L n d RELATIVE PREVIOUS ROTATED 0 L n d R 180 PI 0 RELATIVE PREVIOUS OL IAJIOOI LV IDO IL 10 COMPONENT COPY CG 1 COPY CG_1 11 AT 0 0 L n d RELATIVE PREVIOUS 12 ROTATED 0 L n d R 180 PI 0 RELATIVE PREVIOUS COMPONENT CG_Out Arm AT 0 0 L n RELATIVE PREVIOUS 5 4 4 Conditional components WHEN One of the most useful features of the extended McStas syntax is the conditional WHEN modifier This optional keyword comes before the AT ROTATED positioning It basi cally enables the component only when a given condition is true non null COMPONENT name comp p l e l p 2 e 2 WEEN c
82. e and the read_table lib c unless the no runtime option is used with mcstas Similarly 1 include read table lib h j will only include the read_table lib h The library embedding is done only once for all components like the SHARE section For an example of implementation see Res_monitor In this Appendix we present a short list of both each of the library contents and the run time features B 1 Run time calls and functions mcstas r Here we list a number of preprogrammed macros which may ease the task of writing component and instrument definitions B 1 1 Neutron propagation Propagation routines perform all necessary operations to transport neutron rays from one point to an other Except when using the special ALLOW_BACKPROP call prior to executing any PROP_ propagation the neutron rays which have negative propagation times are removed automatically e ABSORB This macro issues an order to the overall McStas simulator to interrupt the simulation of the current neutron history and to start a new one e PROP_ZO Propagates the neutron to the z 0 plane by adjusting x y z and t accordingly from knowledge of the neutron velocity vx vy vz If the propaga tion time is negative the neutron ray is absorbed except if a ALLOW_BACKPROP preceeds it 119 For components that are centered along the z axis use the _intersect functions to determine intersection time s and then a PROP_DT cal
83. e file 1 initialize and read the first numerical block Table Info Table display table informations x Table Index Table 2 5 read the 8rd row 6th column element of the table Indexes start at zero in C y Table_Value Table 1 45 1 look for value 1 45 in 1st column a axis and extract 2nd column value of that row Table_Free amp Table free allocated memory for table Additionally if the block number 3rd argument of Table_Read is 0 all blocks will be concatenated The Table_Value function assumes that the x axis is the first column index 0 Other functions are used the same way with a few additional parameters e g specifying an offset for reading files or reading binary data This other example for text files shows how to read many data blocks t Table Table declare a t Table structure array long n double y Table Table Read Array file dat kn initialize and read the all numerical block n Table_Info_Array Table display informations for all blocks also returns n 126 y Table_Index Table 0 2 5 read in 1st block the 8rd row 6th column element ONLY use Table i with i lt n Table Free Array Table free allocated memory for Table You may look into for instance the source files for Monochromator curved or Virtual input for other implementation examples B 3 Monitor nD Library This library gathers a few fun
84. e MCSTAS_FORMAT environment variable Next select Run simulation from the Simulation menu The McStas compiler mcstas will translate the definition into an executable program Then mcgui will pop up a dialog window Type a value for the ROT parameter e g 90 check the Plot results option and select Start The simulation will run and when it finishes after a while the results will be plotted in a window Depending on your chosen plotting backend the presented graphics will resemble one of those shown in figure When vanadium sd vanadium psd 4PI PSD monitor Lattitude deg 100 150 150 100 50 0 Longitude deg 4PI PSD monitor PSD_4pi vanadium psd X0 0 214041 dX 103 684 YO 2 63483 dY 52 337 50 Lattitude deg 0 50 100 0 100 Longitude deg Figure 4 3 Output from mcplot with PGPLOT and Matlab backends using the Matlab backend full 3D view of plots and different display possibilities are available Use the attached McStas window menus to control these Features are quite self explanatory For other options execute mcplot help mcplot pl help on windows to get help 34 To visualize or debug the simulation graphically repeat the steps but check the Trace option instead of the Simulate option A window will pop up showing a sketch of the instrument Depending on your chosen plotting backend the presented graphics will resemble one of those
85. e NeXus libraries from http nexusformat org e Mantid 3 2 or newer e On Mac OS X 10 8 and newer you may need to install one of the below compilers as the default clang on OS X causes problems for the link especially when used together with MPI Intel C gcc from http hpc sourceforge net 6 1 2 Requirements for the instrument file A special naming convention in the instrument file is needed for the automatic transfer of geometry to a Mantid IDF file e The location of the source must be indicated by a component named sourceMantid Note that in the case of a curved instrument geometry you should probably add an Arm where Mantid expects the source to be i e defining a location displaced the correct source sample distance parallel to the incoming beam direction at the sample e The location of the sample must be indicated by a component named sampleMantid 1For Mac OS X you may get better milage via the Mantid github site 97 e One or more Monitor nD components need to be added in either rectangular or cylindrical geometry and with a set of special flags as shown below e Rectangular monitor 1 COMPONENT nD Mantid 0 Monitor nD 2 options mantid square x limits 0 2 0 2 bins 128 y limits 0 2 0 2 bins 128 neutron pixel t list all neutrons 3 xmin 0 2 4 xmax 0 2 5 ymin 0 2 6 ymax 0 2 7 restore neutron 1 8 filename bank01 events dat 9 AT 0
86. e achieved or may even sometimes alter the simulation results Be careful and always check results with a shorter non optimized computation e Complex components usually take into account additional small effects in a simula tion but are much longer to execute Thus simple components should be preferred whenever possible at least in the beginning of a simulation project e The SPLIT keyword may artificially repeat events reaching specified positions in the instrument This is very efficient but requires to cast random numbers in the course of the remaining propagation e g at samples crystals See section for details A general comment about optimization is that it should be used cautiously checking that the results are not significantly affected 4 4 5 Optimizing instrument parameters Often the user may wish to optimize the parameters of a simulation i e the best geometry of a given component for example the optimal curvature of a monochromator The choice of the optimization routine of the simulation quality value to optimize the initial parameter guess and the simulation length all have a large influence on the results The user is advised to be cautious when interpreting the optimization results 45 Using iFit for optimization One of the authors of McStas has developed a very flexible and general data analysis and fitting package called iF it based on Matlab Matlab itself is not required as a stand alone dis
87. e files written for each one and two dimensional monitor component another file by default named mcstas sim is also created This file is in a special Mc Stas ASCII format It contains all available information about the instrument definition used for the simulation the parameters and options used to run the simulation and the monitor components present in the instrument It is read by the mcplot front end see section 4 5 4 This file stores the results from single monitors but by default contains only pointers in the form of file names to data for one and two dimensional monitors By storing data in separate files reading the data with programs that do not know the special McStas file format is simplified The file option may be used to store all data inside the mcstas sim file instead of in separate files 4 6 2 NeXus format The NeXus format is a platform independent HDF binary data file To have McStas use it 1 the HDF and NeXus libraries must have been installed libNeXus and headers 2 the compilation of instruments must be done with the DUSE_NEXUS 1NeXus flag see Section 5 3 5 This is automated with the mcrun tool Section 4 5 2 All results are saved in a single file containing groups of data To view such files install and use HDF View or alternatively HDFExplorer This Java viewer can show 62 content of all detectors including metadata attributes Basic detector images may also be generated
88. e homogeneous triangular or Gaussian However real neutron instruments are constituted of a large number of optical elements and this brings additional complexity by introducing strong correlations between neutron beam parameters like divergence and position which is the basis of the acceptance diagram method but also wavelength and time The usual analytic methods such as phase space theory then reach their limit of validity in the description of the resulting effects In order to cope with this difficulty Monte Carlo MC methods for a general review see Ref Jam80 may be applied to the simulation of neutron instruments The use of probability is common place in the description of microscopic physical processes Inte grating these events absorption scattering reflection over the neutron trajectories results in an estimation of measurable quantities characterizing the neutron instrument Moreover using variance reduction importance sampling where possible reduces the computation time and gives better accuracy Early implementations of the MC method for neutron instruments used home made computer programs see MPC77 but more recently general packages have been designed providing models for most optical components of neutron spectrometers The most widely used packages are NISP See 00 ResTrax SK97 McStas Wil 14 Mes Vitess Wec 00 and IDEAS which allow a wide range of neutron scattering instruments to be s
89. e illustrates all possibilities 1 DEFINE INSTRUMENT test d1 double d2 int i char sl string s2 Here d1 and d2 will be floating point parameters of C type double i will be an integer parameter of C type int and s1 and s2 will be string parameters of C type char The parameters of an instrument may be given default values Parameters with default values are called optional parameters and need not be given an explicit value when the instrument simulation is executed When executed without any parameter value in the command line see section 44 the instrument asks for all parameter values but pressing the Return key selects the default value if any When used with at least one parameter value in the command line all non specified parameters will have their value set to the default one if any A parameter is given a default value using the syntax param value For example 73 1 DEFINE INSTRUMENT test dl 1 string s2 hello Here di and d2 are optional parameters and if no value are given explicitly 1 and hello will be used Optional parameters can greatly increase the convenience for users of instruments for which some parameters are seldom changed or of unclear signification to the user Also if all instrument parameters have default values then the simple command mcdisplay test instr will show the instrument view without requesting any other input which is usually a good starting point t
90. e system that is rotated first the angle in degrees around the x axis then dy around the y axis and finally around the z axis Rotation may also be specified using ABSOLUTE rather than RELATIVE If no rotation is specified the default is 0 0 0 using the same relative or absolute specification used in the AT modifier We strongly recommend to apply all rotations of an instrument description on Arm class components only acting as goniometers and position the optics on top of these This usually makes it much easier to orient pieces of the instrument and avoid positioning errors The position of a component is actually the origin of its local coordinate system Usually this is used as the input window position e g for guide like components or the center position for cylindrical spherical components The PREVIOUS keyword is a generic name to refer to the previous component in the sim ulation Moreover the PREVIOUS n keyword will refer to the n th previous component 76 Id re Ne starting from the current component so that PREVIOUS is equivalent to PREVIOUS 1 This keyword should be used after the RELATIVE keyword but not for the first component instance of the instrument description AT x y z RELATIVE PREVIOUS ROTATED phi x phi y phi z RELATIVE PREVIOUS 2 Invalid PREVIOUS references will be assumed to be absolute placement The order and position of components in the TRACE section does not allow c
91. e used it would be necessary to allocate the arrays dynamically using e g malloc Setting parameters may optionally be declared to be of type int char and string just as in the instrument definition see section 5 3 85 1 OUIPUT PARAMETERS s_1 s 2 This declares a list of C identifiers variables functions that are output parameters i e global for the component Output parameters are used to hold values that are computed by the component itself rather than being passed as input This could for example be a count of neutrons in a detector or a constant that is precomputed to speed up computation Using OUTPUT PARAMETERS is strongly recommended for DECLARE and internal global component variables and functions in order to prevent that instances of the same com ponent use the same variable names Moreover see section below these may be accessed from any other instrument part e g using the MC GETPAR C macro On the other hand the variables from the SHARE sections should not be defined as OUTPUT parameters The OUTPUT PARAMETERS section is optional Optional component parameters Just as for instrument parameters the definition and setting parameters of a compo nent may be given a default value Parameters with default values are called optional parameters and need not be given an explicit value when the component is used in an instrument definition A parameter is given a default value using the syntax pa
92. e with the center at x y z and the radius r 5 5 10 The end of the component definition 1 END This marks the end of the component definition 5 5 11 A component example Slit A simple example of the component Slit is given 93 5 6 Extending component definitions Suppose you are interested by one component of the McStas library but you would like to customize it a little There are different ways to extend an existing component 5 6 1 Extending from the instrument definition If you only want to add something on top of the component existing behavior the simplest is to work from the instrument definition TRACE section using the EXTEND modifier see section 5 4 2 You do not need to write a new component definition but only add a piece of code to execute 5 6 2 Component heritage and duplication There is a heritage mechanism to create children of existing components These are exact duplicates of the parent component but one may override extend original definitions of any section The syntax for a full component child is 1 DEFINE COMPONENT child name COPY parent_name This single line will copy all parts of the parent into the child except for the docu mentation header As for normal component definitions you may add other parameters DECLARE TRACE sections Each of them will replace or extend be concatenated to with the COPY EXTEND keywords see example below the corresponding p
93. echanism may be done automatically for the local machine from the Help menu Install DSA key item of mcgui The machine names listed in the file mcstas hosts in your home directory or in the MCSTAS tools perl mcstas hosts on the master node one node per line The machines file option enables to specify the hosts file to use If it does not exist only the current machine will be used for multi processor core machines 6 Without ssh keys passwords will be prompted many times To avoid this we recommend to use only the local machine for multi cores cpu i e do not use a machine hosts file 7 If your simulation instrument requires data files Powders Sqw source descrip tion these must be copied at the same level as the instrument definition They are sent to all slave nodes before starting each computation Take care to limit as much as possible the required data file volume in order to avoid large data transfers 8 Interrupting or sending Signals may fail during computations However simulation scans can be interrupted as soon as the on going computation step ends 9 With heterogeneous systems we recommend to use the mcrun force compile command rather than McGUI which may skip the required simulation compilation on slaves 4 7 2 Parallel computing MPI The MPI support requires that MPICH recommended or alternatively LAM MPI or OpenMPI is installed on a set of nodes This usually also requires prope
94. ecomputations relating to structure and crossections is kept for each incoming netron so that the component may skip these calculations for the next SPLIT version of the neutron there is a built in check for whether that kind of neutron was processed before This means that a set of SPLIT neutron may be scattered across ALL reflection that are allowed for that specific incoming direction and wavelength Further the components estimate the optimal value of the SPLIT For large single crystal unit cells i e protein crystals etc speedups of a factor of 500 have been observed The method works with all orders of scattering even though the largest gain is seen with order 1 x Use is easy e g SPLIT 43 COMPONENT SX Single crystal order l Single crystal now allows to be used as a Powder mainly for benchmarking purposes at the point of scattering the crystallite is randomly oriented Final validation is pending but in this setting the component already gives the same order of manitude scattering as PowderN where this powder ring intergration has been implemented using a completely different strategy provided the right values of mosaicity and delta d d are given ISIS moderator component allow specification of the accellerator current The component performance defaults to the actual relevant accellerator setting for each target station TS All TS1 and TS2 moderator input files are now included wi
95. eletcs the last component to plot default is first in order to define a region of interest Run Maximize monitor Optimization mode seletcs up to three monitors which inte gral value should be maximized varying instrument parameters If no monitor is selected the sum of all monitors is optimized Run Start runs the simulation Run Cancel aborts the dialog Most of the settings on the run dialog can be saved for your next McStas run using Save configuration in the File menu Before running the simulation the instrument definition is automatically compiled if it is newer than the generated C file or if the C file is newer than the executable The executable is assumed to have a out suffix in the filename NB If components are changed automatic compilation is not performed Instead use the File Compile menu item in mcgui The editor window The editor window provides a simple editor for creating and modifying instrument defini tions Apart from the usual editor functions the Insert menu provides some functions that aid in the construction of the instrument definitions Editor Insert Instrument template inserts the text for a simple instrument skeleton in the editor window Editor Insert Component opens up a dialog window with a list of all the components available for use in McStas Selecting a component will display a description Double clicking will open up a dialog window allowing the entry of the values of
96. ents we define D partitions and shoot r N D events in each partition In conjunction with adaptive sampling we may define partitions so that they represent interesting distributions e g from events scattered on a monochromator or a sample The sum of partitions should equal the total space integrated by the Monte Carlo method and each partition must be sampled randomly In the case of McStas an ad hoc implementation of adaptive stratified is used when re peating events such as in the Virtual sources Virtual_input Vitess_input Virtualmecnp input Virtual tripoli4 input and when using the SPLIT keyword in the TRACE section on instrument descriptions We emphasize here that the number of repetitions r should not exceed the dimensionality of the Monte Carlo integration space which is d 10 for neutron events and the dimensionality of the partition spaces i e the number of random generators following the stratified sampling location in the instrument 3 5 Accuracy of Monte Carlo simulations When running a Monte Carlo the meaningful quantities are obtained by integrating random events into a single value e g flux or onto an histogram grid The theory shows that the accuracy of these estimates is a function of the space dimension d and the number of events N For large numbers N the central limit theorem provides an estimate of the relative error as 1 N However the exact expression depends on the random distributions 29
97. f samples 3 2 1 Statistical errors of non integer counts In a typical simulation the result will consist of a count of neutrons histories rays with different weights The sum of these weights is an estimate of the mean number of neutrons hitting the monitor or detector per second in a real experiment One may write the counting result as r pi Np 3 3 26 where N is the number of rays hitting the detector and the horizontal bar denotes averaging By performing the weight transformations the statistical mean value of I is unchanged However N will in general be enhanced and this will improve the accuracy of the simulation To give an estimate of the statistical error we proceed as follows Let us first for simplicity assume that all the counted neutron weights are almost equal p p and that we observe a large number of neutrons N gt 10 Then N almost follows a normal distribution with the uncertainty c N VN Hence the statistical uncertainty of the observed intensity becomes o I VNp 1 VN 3 4 as is used in real neutron experiments where p 1 For a better approximation we return to Eq 3 3 Allowing variations in both N and p we calculate the variance of the resulting intensity assuming that the two variables are statistically independent 07 I 0 N p N 0 p 3 5 Assuming as before that N follows a normal distribution we reach o N p Np Further assuming t
98. file containing the current plot that can be sent to the printer to obtain a hardcopy the C key produces color postscript The Q key quits the program or CTRL C in the controlling terminal may be used as normal 57 To use the mcplot front end with PGPLOT the programs Perl PGPLOT PgPerl and PDL must all be properly installed on the system It may be necessary to set the PGPLOT_DIR and PGPLOT_DEV environment variable consult the documentation for PGPLOT on the local system in case of difficulty Matlab back end A dedicated McStas Mcplot Dialog or menu attached to the plotting window is available and provides many operations duplication export colormaps The corresponding mcplot Matlab function may be called from these language prompt with the same method as in section 4 4 e g matlab s mcplot matlab help mcplot matlab gt s mcplot mcstas m matlab gt mcplot s i IW Li A full parameter scan simulation result or simply one of its scan steps may be dis played using the Scan step menu item When the nw option is specified a separate Matlab window will appear instead of being launched in the current terminal This will then enable Java support under Matlab resulting in additional menus and tools On the other hand the nw option will force Matlab to run in the current terminal which is usually faster To use the mcplot front end the programs Perl and Matlab are requi
99. g else see the installation instructions for details The location can be overridden by setting the environment variable MCSTAS 1 setenv MCSTAS home joe mestas j for csh tcsh users or 1 export MCSTAS home joe mcstas for bash Bourne shell users Windows users should define MCSTAS from the menu Start Settings Control Panel System Advanced Environment Variables by creating MCSTAS with the value C mcstas lib To make mcstas search additional directories for component definitions and include files use the I switch 1 mcstas I home joe components I home joe neutron include name instr Multiple I options can be given as shown 4 3 3 Embedding the generated simulations in other programs By default mcstas will generate a stand alone C program which is what is needed in most cases However for advanced usage such as embedding the generated simulation in another program or even including two or more simulations in the same program a 37 stand alone program is not appropriate For such usage mcstas provides the following options e no main This option makes mcstas omit the main function in the generated simulation program The user must then arrange for the function mcstas main to be called in some way e no runtime Normally the generated simulation program contains all the run time C code necessary for declaring functions variables etc used during the simulation This option makes mcs
100. g out of IN4 IN5 or IN6 illuminating a sample with a container around and a cylinder shaped sample environment 8 1 4 Neutron site tests This large set of examples shows simple instruments using particular components sam ples polarized beams detectors They may be used as starting point for further more complex models 8 1 5 Neutron site ISIS You will find here examples of ISIS instruments some of them using the ISIS moderator component obtained from MCNP computations 8 1 6 Neutron site Risg This section contains former Risg instruments which constitue the default test series for the McStas distribution 8 1 7 Neutron site PSI The Focus time of flight instrument is with the ILL IN6 and IN12 models the most advanced example It as been built from drawings including the guide and all optics elements Simulated capture fluxes were found in good agreement with measurements 8 1 8 Neutron site Tutorial A typical diffractometer including a powder sample and a Rescal type triple axis models are in this category Instrument parameters enable models to cope with most existing instruments of these classes The TAS model includes a basic in plane UB matrix trans formation It may be used to estimate the resolution functions of a TAS configuration 8 1 9 Neutron site ESS This section contains design studies for the future long pulsed European Spallation Source ESS The only contents is currently the ESS_IN5_re
101. generally all names starting with mc should be avoided If you can not compile the instrument this may be the reason The DECLARE section is optional 74 e ND Li 5 3 4 The INITIALIZE section INITIALIZE Zi C initializations 7 This gives code that is executed when the simulation starts This section is optional Instrument setting parameters may be modified in this section e g doing tests or automatic settings 5 3 5 The NEXUS extension The NeXus format requires to link the simulation to additional libraries HDF and NeXus which must have been pre installed Preferably McStas should have been installed with the configure with nexus on Unix Linux systems To activate the NeXus output the compilation of the instrument must be done with flag DUSE_NEXUS 1NeXus The resulting executable is no longer portable The default NeXus format is HDF5 with compression You may choose the name of the output file with the f filename option from the instrument executable or mcrun see Sections 4 5 2 and Table 4 2 Then the output format is chosen as usual with the format NeXus option when launching the simulation All output files are stored in the output filename as well as the instrument description itself Other formats are still available When run on a distributed system e g MPI detectors are gathered but list of events see e g component Virtual output are stored as one data set per node 5 3 6 The TR
102. get either backward PREVIOUS or forward NEXT so that PREVIOUS 1 is PREVIOUS and NEXT 1 is NEXT MYSELF means that the component will be iterated as long as the condition is true This may be a way to handle multiple scattering if the component has been designed for that The jump arrives directly inside the target component in the local coordinate system i e without applying the AT and ROTATED keywords In order to control better the target positions it is required that except for looping MYSELF the target component type should be an Arm There is a more general way to iterate components which consists in repeating the loop for a given number of times 1 JUMP reference ITERATE number of times This method is specially suited for very long curved guides of similar components but in order to take into account rotation and translation between guide sections the iterations are performed between Arm s In the following example for a curved guide made on n 500 elements of length L on a curvature radius R with gaps d between elements we simply write 1 COMPONENT CG In Arm AT 2 3 GMPONENT CG_1 Guide gravity 1 L n m 1 4 AT 0 0 0 RELATIVE PREVIOUS 5 6 COMPONENT CG 2 Position Arm 7 AT 0 0 L n4d RELATIVE PREVIOUS 8 ROTATED 0 L n4d Rx180 PI 0 RELATIVE PREVIOUS 9 10 COMPONENT CG2 Guide _gravity l L n m 1 11 AT 0 0 0 RELATIVE PREVIOUS 12 ROTATED 0 L ntd R 180
103. h the front end will not notice automatically This might also be required when choosing MPI and NeXus options 48 File Save log file saves the text in the window showing output of compilations and simulations into a file File Clear output erases all text in the window showing output of compilations and simulations File Preferences Opens the choose backend dialog shown in figure 4 6 Several settings can be chosen here e Selection of the desired PGPLOT Matlab HTML VRML output format and possibility to save binary files when applicable improved disk I O e One or three pane view of your instrument in trace mode when using PG PLOT e Clustering option None MPI ssh e Choice of editor to use when editing instrument files e Automatic quotation of strings when inserting in the built in editor e Possibility to not optimize when compiling the generated c code This is very handy when setting up an instrument model which requires regular compilations e Adjustment of final precision when doing parameter optimization To save the chosen settings for your next McStas run use Save Configuration in the File menu File Save configuration saves user settings from Configuration options and Run dia logue to disk File Quit exits the graphical user interface front end The Simulation menu has the following features Simulation Read old simulation prompts for the name of a file from a previous run of a McStas si
104. hat the individual weights p follow a Gaussian distribution which in some cases is far from the truth we have N 0 p 07 3 gt pi No p and reach o I N P 07 p 3 6 The statistical variance of the p s is estimated by o p X p Np N 1 The resulting variance then reads N 2n Dj lt 9 o n e 5x r 3 7 2 For almost any positive value of N this is very well approximated by the simple expres sion oI X pi 3 8 As a consistency check we note that for all p equal this reduces to eq 3 4 In order to compute the intensities and uncertainties the monitor detector compo nents in McStas will keep track of N X p I gt pl and Mo So p 3 3 Weight factor transformations during a Monte Carlo choice When a Monte Carlo choice must be performed e g when the initial energy and direction of the neutron ray is decided at the source it is important to adjust the neutron weight This is not correct in a situation where the detector counts a large fraction of the neutron rays in the simulation but we will neglect that for now 27 so that the combined effect of neutron weight change and Monte Carlo probability of making this particular choice equals the actual physical properties we like to model Let us follow up on the simple example of transmission The probability of trans mitting the real neutron is P but we make the Monte Carlo choice of transmitting the neut
105. hed after reading the Nrows lines e Table Read_Offset_Binary amp Table filename type block amp offset Nrows Ncolumns does the same as Table_Read_Offset but also specifies the type of the file may be float or double the number nrows of rows to read each of them having Neolumns elements No text header should be present in the file e Table Rebin Table rebins all Table rows with increasing evenly spaced first column index 0 e g before using Table Value Linear interpolation is performed for all other columns The number of bins for the rebinned table is determined from the smallest first column step e Table Info Table print information about the table Table e Table Index Table m n reads the Table m n element e Table Value T able z n looks for the closest x value in the first column index 0 and extracts in this row the n th element starting from 0 The first column is thus the x axis for the data e Table Free T able free allocated memory blocks e Table Value2d Table X Y Uses 2D linear interpolation on a Table from X Y coordinates and returns the corresponding value Available functions to read an array of vectors matrices in a text file are e Table Read Array File n read and split file into as many blocks as neces sary and return a t Table array Each block contains a single vector matrix This only works for text files The number of blocks is put into n e Table Free
106. ile j Beware of possible confusion with the C language include statement especially when it is used in C code embedded within the McStas meta language Files referenced with include are read when the instrument is translated into C by mcstas and must contain valid McStas meta language input and possibly C code Files referenced with include are read when the C compiler generates an executable from the generated C code and must contain valid C Embedded C code is used in several instances in the McStas meta language Such code is copied by mcstas into the generated simulation C program Embedded C code is written by putting it between the special symbols and as follows Zi Embedded C code n The and must appear on a line by themselves do not add comments after Additionally if a Zinclude statement is found within an embedded C code block the specified file will be included from the share directory of the standard component library or from the current directory and any user specified search directories as a C library just like the usual include but only once For instance if many components require to read data from a file they may all ask for include read table lib without duplicating the code of this library If the file has no extension both h and c files will be searched and included otherwise only the specified file will be imported The McStas run
107. imulated The neutron ray tracing Monte Carlo method has been used widely for guide studies Sch 04 instrument optimization and design Lie05 Most of the time the conclusions and general behavior of such studies may be obtained using the classical analytic approaches but accurate estimates for the flux resolution and generally the optimum parameter set benefit considerably from MC methods see Chapter 3 Neutron instrument resolution in g and E and flux are often limitations in the experiments This then motivates instrument responsibles to improve the resolution flux and overall efficiency at the spectrometer positions and even to design new machines Using both analytic and numerical methods optimal configurations may be found But achieving a satisfactory experiment on the best neutron spectrometer is not all Once collected the data analysis process raises some questions concerning the signal what is the background signal What proportion of coherent and incoherent scattering has been measured Is possible to identify clearly the purely elastic structure contri bution from the quasi elastic and inelastic one dynamics What are the contributions from the sample geometry the container the sample environment and generally the instrument itself And last but not least how does multiple scattering affect the signal Most of the time the physicist will elude these questions using rough approximations or applying analytic correction
108. imulation strategy 3 1 Neutron spectrometer simulations 3 1 1 Monte Carlo ray tracing simulations 3 2 The neutron weight 3 2 1 Statistical errors of non integer counts 3 3 Weight factor transformations during a Monte Carlo choice 3 3 1 Direction focusing 3 4 Adaptive and Stratified sampling 3 5 Accuracy of Monte Carlo simulations 4 Running McStas 4 1 Installation and updates 4 1 1 Important note for Windows users 4 1 2 New releases of McStas 4 2 Brief introduction to the graphical user interface 4 3 Running the instrument compiler 4 3 1 Code generation options 4 3 2 Specifying the location of files 4 3 3 Embedding the generated simulations in other programs 4 3 4 Running the C compiler 4 4 Running the simulations 4 4 1 Choosing an output data file format 4 4 2 Basic import and plot of results 4 4 3 Interacting with a running simulation 4 4 4 Optimizing simulation speed 4 4 5 Optimizing instrument parameters 11 11 12 14 14 16 18 25 25 25 26 26 27 28 28 29 31 sl sl 33 33 35 36 37 37 38 39 41 41 44 44 45 4 5 Using simulation front ends ee ee eee 47 4 5 1 The graphical user interface mcegui 48 4 5 2 R
109. in the wrong position or to find out where neutrons are getting lost See figures 4 4114 5 To use the mcdisplay front end with a simulation run it as follows 1 mcdisplay sim args where sim is the name of either the instrument source sim instr or the simulation program sim out generated by mcstas and args are the normal command line arguments for the simulation as explained above The h option will list valid options 55 The drawing back end program may be selected among PGPLOT VRML and Matlab using the pPLOTTER option For instance calling 1 mcdisplay pMatlab Samples_vanadium out ROT 90 will output graphics using Matlab The mcdisplay front end can also be run from the mcgui front end Examples of plotter appearence for mcdisplay is shown in figures 4 44 5 McStas PGPLOT back end This will view the instrument from above A multi display that shows the instrument from three directions simultaneously can be shown using the multi option 1 medisplay multi sim out args Click the left mouse button in the graphics window or hit the space key to see the display of successive neutron trajectories The P key saves a postscript file containing the current display that can be sent to the printer to obtain a hardcopy the C key produces color postscript To stop the simulation prematurely type Q or use control C as normal in the window in which mcdisplay was started
110. inly been done by Esben Klinkby DTU Nutech with contributions from Erik Knudsen and Peter Willendrup both DTU Physics 4 With access to an MCNP source code license and a patch developed by Esben Klinkby DTU Nutech it is further possible to directly compile and link a McStas instrument with MCNP The method is however quite speed limited at present but we envision releasing an improved version later If interested please contact Esben Klinkby directly Especially method 3 gives a powerful combination with the scatter logging mechanism discussed in the paper KKW14 allowing to estimate y dose rates in MCNP from neu tron intensity lost in neutron optics i e the non transmitted fraction of the McStas neutron beam and corresponding intensity weight Through the McStas example in struments and also the McStas share at http mcstas org download share we pro vide a couple of examples of the use of the scatter logger 100 IV li T The component library Abstract This chapter presents an abstract of existing components As a complement to this chapter and the detailed description in the McStas component manual you may use the mcdoc s command to obtain the on line component documentation and refer to the McStas web page where all components are documented using the McDoc system 7 1 A short overview of the McStas component library The table in this section gives a quick overview of available McStas components provided with the
111. ins most of what is needed to get a GUI window in VITESS To obtain that the content of this file has to added into vitess tcl To make it accessible within the given GUI structure of VITESS it is necessary to add the name compo NO capital letters to one of the folders in proc makeModuleSets beginning of vitess tcl The component Virtual input transfers all neutron parameters to the McStas defini tion of the co ordinate system and the units used Of course Virtual output transfers it back This means that Compo works with the McStas definition of co ordinate system and units while it is used as a VITESS module Be careful with axis labeling The original parameters of the component and its position have to be given The origin of this shift is the center of the end of the previous module as it is always the case in VITESS It is important to notice that as VITESS uses the standard output stream stdout to send neutron events all information printed to screen must use the error stream stderr so that all printf and fprintf stdout occurrences should be changed manually into fprintf stderr To use the mcstas2vitess front end the program Perl should be available 60 4 5 8 Translating and merging McStas results files all text formats If you have been running a McStas simulation with a given text format output but finally plan to look at the results with an other plotter e g you ran
112. ion B 1 6 Ray geometry intersections e inside _rectangle amp z ky x xw yh Return 1 if xw 2 lt x lt zw 2 AND yh 2 lt y lt yh 2 Else return 0 e box_intersect amp t amp t2 Y Z Ur Uy Vz dx dy dz Calculates the 0 1 or 2 intersections between the neutron path and a box of dimensions dg dy and dz centered at the origin for a neutron with the parameters x y Z Uz Uy Uz The times of intersection are returned in the variables t and to with t lt to In the case of less than two intersections t and possibly t2 are set to zero The function returns true if the neutron intersects the box false otherwise e cylinder_intersect amp t amp t2 x Y Z Uz Uy Uz T h Similar to box_intersect but using a cylinder of height h and radius r centered at the origin e sphere intersect t1 amp t2 x Y Z Uz Vy Uz r Similar to box intersect but using a sphere of radius r B 1 7 Random numbers e rand0l Returns a random number distributed uniformly between 0 and 1 e randnorm Returns a random number from a normal distribution centered around 0 and with o 1 The algorithm used to sample the normal distribution is explained in Ref Pre 86 ch 7 e randpm1 Returns a random number distributed uniformly between 1 and 1 e randtriangle Returns a random number from a triangular distribution between 1 and 1 123 OW LIIO IODO LV IO IL e randvec target ci
113. ion 2 1 x are also listed on the web and new versions may be released quite frequently when it is requested by the user community 4 2 Brief introduction to the graphical user interface This section gives an ultra brief overview of how to use McStas once it has been prop erly installed It is intended for those who do not read manuals if they can avoid it For details on the different steps see the following sections This section uses the Samples_vanadium instr file supplied in the examples directory of the McStas dis tribution To start the graphical user interface of McStas run the mcgui command which will open a window with a number of menus see figure To load an instrument File Simulation Neutron site Help McDoc Instrument file lt N Undefined site Edit New Run Simulation results FZ_Juelich Read Plot Status Ok Brookhaven McStas version ILL 6 ry atory 1997 2006 in 2003 2006 All rights rese tests Plotters Scil Ri Clustering meth RISOE PSI templateDIFF templateTAS vanadium example Figure 4 2 The graphical user interface mcgui select Tutorial from the Neutron site menu and open the file Samples vanadium 33 Next check that the current plotting backend setting select Choose backend from the Simulation menu corresponds to your system setup e by editing the tools perl mcstas config perl setup file of your installation e by setting th
114. is the first stable release with these new features functionality is likely to change To reflect this the documentation is still only available in the appendix of the Component manual A list of library calls that may be used in component definitions appears in 16 appendix B and an explanation of the McStas terminology can be found in appendix C of the Manual 17 Nr 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 2 New features in McStas 2 1 This version of McStas implements both new features as well as many bug corrections Bugs are reported and traced using the McStas Trac Ticket system Mcz We will not present here an extensive list of corrections and we let the reader refer to this bug reporting service for details Only important changes are indicated here Of course we can not guarantee that the software is bullet proof but we do our best to correct bugs when they are reported The listing below contains the McStas 2 1 CHANGES document Changes in McStas v2 1 September 2014 McStas 2 1 is the second release in the 2 x series and fixes various issues with McStas 2 0 plus provide important new developments IMPORTANT Please ensure to use our migration scripts for McStas 2 0 and 1 12c if you want these to co exist with 2 1 Also please read the platform specific notes below Thanks Thanks to all contributors of components instruments etc This is what Open Source
115. ith one Monitor_nD in order to record some neutron parameter cor relations Time of flight vs wavelength monitor Rectangular Time of flight monitor Table 7 4 Selected Monitor components of the McStas library MCSTAS misc Description Progress bar Beam spy Set pol Vitess input Vitess output Displays status of a running simulation May also trigger in termediate SAVE A monitor that displays mean statistics no output file sets polarisation vector Read neutron state parameters from a VITESS neutron file Write neutron state parameters to a VITESS neutron file Table 7 5 Miscellaneous components of the McStas library 105 MCSTAS contrib Description Al window Collimator ROC Exact radial coll FermiChopper ILL Filter graphite Filter powder Guide curved Guide honeycomb Guide tapering He3 cell ISIS moderator Monochromator 2foc multi pipe PSD Detector PSD monitor rad SiC SNS_source Source_multi_surfaces Virtual_mcnp_input Virtual_mcnp_output Virtual_tripoli4_input Virtual_tripoli4_output Aluminium transmission window Radial Oscillating Collimator ROC Radial collimator Fermi Chopper with rotating frame and SM coating straight Pyrolytic graphite filter analytical model Box shaped powder filter based on Single_crystal unstable Non focusing continuous curved guide shown curved Neutron guide with gravity and honeycomb geometr
116. ix Table input read table lib 124 B 3 Monitor nD Library sss 127 B 4 Adaptive importance sampling Library s s 127 B 5 Vitess import export Library so 4960 43 aug eji e044 kaa 127 B 6 Constants for unit conversion etc sss 127 C The McStas terminology 129 Bibliography 130 Index and keywords 132 ioe Preface and acknowledgments This document contains information on the Monte Carlo neutron ray tracing program McStas version 2 1 building on the initial release in October 1998 of version 1 0 as presented in Ref and further developed though version 2 0 as presented in Ref Wil 14 The reader of this document is supposed to have some knowledge of neutron scattering whereas only little knowledge about simulation techniques is required In a few places we also assume familiarity with the use of the C programming language and UNIX Linux If you don t want to read this manual in full go directly to the brief introduction in chapter 4 2 It is a pleasure to thank Prof Kurt N Clausen PSI for his continuous support to this project and for having initiated McStas in the first place Essential support has also been given by Prof Robert McGreevy ISIS We have also benefited from discussions with many other people in the neutron scattering community too numerous to mention here In case of errors questions or suggestions do not hesitate to contact the authors
117. ixed seed to reproduce results for debugging Run Simulate Trace 3D Optimize selects between several modes of running the sim ulation e Simulate perform a normal simulation or a scan when steps is set to non zero value e Trace 3D view View the instrument in 3D tracing individual neutrons through the instrument e Optimize find the optimum value of the simulation parameters in the given ranges see section 4 4 5 e Backgrounding bg Simulate or Optimize in the background Run steps optim sets the number of simulation to run when performing a pa rameter scan or the number of iterations to perform in optimization mode Run Plot results if checked the mcplot front end will be run after the simulation has finished and the plot dialog will appear see below Run Format quick selection of output format Binary mode may be checked from the Simulation Configuration options dialog box Run Clustering method selects the mechanism to be used for running on grids and clusters See section 4 7 on parallel computing for more informations 52 Run Number of nodes sets the number of nodes to use for MPI ssh clustering Run Inspect component Trace mode will trace only neutron trajectories that reach a given component e g sample or detector Run First component Trace mode seletcs the first component to plot default is first in order to define a region of interest Run Last component Trace mode s
118. l PROP_DT dt Propagates the neutron through the time interval dt adjusting x y z and t accordingly from knowledge of the neutron velocity This macro automatically calls PROP_GRAV_DT when the gravitation option has been set for the whole simulation PROP_GRAV_DT dt Ax Ay Az Like PROP_DT but it also includes grav ity using the acceleration Az Ay Az In addition to adjusting x y z and t also vx vy vz is modified ALLOW BACKPROP Indicates that the next propagation routine will not remove the neutron ray even if negative propagation times are found Subsequent propagations are not affected SCATTER This macro is used to denote a scattering event inside a component It should be used e g to indicate that a component has interacted with the neutron ray e g scattered or detected This does not affect the simulation see how ever Beamstop and it is mainly used by the MCDISPLAY section and the GROUP modifier See also the SCATTERED variable below B 1 2 Coordinate and component variable retrieval 120 MC_GETPAR comp outpar This may be used in e g the FINALLY section of an instrument definition to reference the output parameters of a component NAME CURRENT COMP gives the name of the current component as a string POS A CURRENT COMP gives the absolute position of the current compo nent A component of the vector is referred to as POS A CURRENT COMP i where i is y or z ROT A CURRENT COMP and
119. ld be called with the state parameters set to the proper values for the scattering event so that neutron events are displayed correctly For an example of SCATTER see the optics Guide component 5 5 7 The SAVE section C code to execute in order to save data This gives code that will be executed when the simulation ends or is requested to save data for instance when receiving a USR2 signal on Unix systems see section 4 4 or when triggered by the Progress bar flag save 1 component This might be used by monitors and detectors in order to write results An extension depending on the selected output format see table and section 4 4 is automatically appended to file names if these latter do not contain extension In order to work properly with the common output file format used in McStas all monitor detector components should use standard macros for writing data in the SAVE or FINALLY section as explained below In the following we use N Y p to denote the count of detected neutron events p Y p to denote the sum of the weights of detected neutrons and p2 gt gt p to denote the sum of the squares of the weights as explained in section 3 2 1 As a default all monitors using the standard macros will display the integral p of the monitor bins as well as the 2 moment o and the number of statistical events N This will result in a line such as 1 Detector CompName I p CompName ERR sigma CompNameN N
120. le axis spectrometer TAS1 at the now closed neutron source DR3 of Riso National Laboratory Except for the cold source itself all components used have quite realistic properties Furthermore the overall geometry of the instrument has been adapted from the detailed technical drawings of the real spectrometer The TAS 1 simulation was the first detailed work performed with the McStas package For further details see reference ACL98 At the spectrometer the channel from the cold source to the monochromator is asym metric since the first part of the channel is shared with other instruments ln the instrument definition this is represented by three slits For the cold source we use a flat energy distribution component Source flat focusing on the third slit The real monochromator consist of seven blades vertically focusing on the sample The angle of curvature is constant so that the focusing is perfect at 5 0 meV 20 0 meV for 2nd order reflections for a 1x1 cm sample This is modeled directly in the instrument 110 Figure 8 2 Scattering from a V sample measured by a spherical PSD The sphere has been transformed onto a plane and the intensity is plotted as the third dimension 111 monochromator Analyser E I Focusing Collimator 3 Detector Source Figure 8 3 A sketch of the TAS1 instrument definition using seven Monochromator components The mosaicity of the pyrolytic graphite crystals is no
121. ll mcstas suite perl perl tools mcstas suite python python tools or mcstas suite both toolsets and all dependencies should be taken care of The install location of the McStas components and libraries on Linux X has changed x On Debian your files are now placed in usr share mecstas 2 1 links to binaries are in usr bin x On RedHat your files are now placed in usr local mecstas 2 1 links to binaries are in usr local bin Note that we have dropped lib in the mcstas system path A given McStas 2 x release is self contained and can be installed in parallel with other versions of McStas and McXtrace We provide a migration tool for Unix based systems i e Linux amp Mac to let your already 21 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 installed McStas 1 x or 2 0 co exist with the new 2 1 Using McStas with NeXus does no longer require recompilation if you only want to write NeXus Simply install NeXus and update your MCSTAS CFLAGS to include INeXus DUSE_NEXUS For the conversion of files using mcformat NeXus must still be available at compile time Core amp runtime code Backward compatibility 1 As written above STATE and POLARIZATION parameters are no longer supported Complete rework of the DETE
122. m Additionally to use the McStas PGPLOT back end the software packages PGPLOT PgPerl and PDL are required It may be necessary to set the PGPLOT DIR and PGPLOT DEV environment variable consult the documentation for PGPLOT on the local system in case of difficulty The menus When the front end is started the main window is opened see figure 4 2 This window displays the output from compiling and running simulations and contains a few menus and buttons for easy navigation The main purpose of the front end is to edit and compile instrument definitions run the simulations and visualize the results The File menu has the following features File Open instrument selects the name of an instrument file to be used File Edit current opens a simple editor window with McStas syntax highlighting for editing the current instrument definition This function is also available from the Edit button to the right of the name of the instrument definition in the main window File Spawn editor This starts the editor defined in the environment variable VISUAL or EDITOR on the current instrument file It is also possible to start an external editor manually in any case mcgui will recompile instrument definitions as necessary based on the modification dates of the files on the disk File Compile instrument forces a recompile of the instrument definition regardless of file dates This is for example useful to pick up changes in component definitions whic
123. m is the number of elements in the detector arrays amp N 0 is a pointer to the first element in the array of N values for the detector component or NULL in which case no error bars will be computed p 0 is a pointer to the first element in the array of p values for the detector component p2 0 is a pointer to the first element in the array of p2 values for the detector component or NULL in which case no error bars will be computed e filename is a string giving the name of the file in which to store the data Two dimensional detectors monitors The results of a two dimensional detector mon itor are written to a file using the following macro DETECTOR OUT2D t xlabel ylabel xvar x min x max m n eN 0 0 p 0 0 p2 0 0 filename 90 Here tis a string giving a descriptive title e g PSD monitor zlabel is a string giving a descriptive label for the X axis in a plot e g X position cm e ylabel is a string giving a descriptive label for the Y axis of a plot e g Y position cm e Tmin is the lower limit for the X axis e Tmax is the upper limit for the X axis e Ymin is the lower limit for the Y axis e Ymax is the upper limit for the Y axis e m is the number of elements in the detector arrays along the X axis e n is the number of elements in the detector arrays along the Y axis e amp N 0 0 is a pointer to the first element in the array of N values for
124. mal distributions The important normal distribution can not be reached as a simple transformation of a uniform distribution In stead we rely on a specific algorithm for selecting random numbers with this distribution A 2 Random generator Even though there is the possibility to use the system random generator as well as the initial McStas version 1 1 random generator the default algorithm is the so called Mersenne Twister by Makoto Matsumoto and Takuji Nishimura See http www math sci hiroshima u ac jp m mat MT emt htm1 for original source It is considered today to be by far the best random generator which means that both its period is extremely large 219937 1 and cross correlations are negligible i e distri butions are homogeneous and independent up to 623 dimensions It is also extremely fast 118 B Libraries and constants The McStas Library contains a number of built in functions and conversion constants which are useful when constructing components These are stored in the share directory of the MCSTAS library Within these functions the Run time part is available for all component instrument descriptions The other parts are dynamic that is they are not pre loaded but only imported once when a component requests it using the 4include McStas keyword For instance within a component C code block usually SHARE or DECLARE 1 include read table lib j will include the read_table lib h fil
125. meta language in which simulations are written The usage of a special meta language and an automatic compiler has several advan tages over writing a big monolithic program or a set of library functions in C FORTRAN or another general purpose programming language The meta language is more power ful specifications are much simpler to write and easier to read when the syntax of the specification language reflects the problem domain For example the geometry of in struments would be much more complex if it were specified in C code with static arrays and pointers The compiler can also take care of the low level details of interfacing the various parts of the specification with the underlying C implementation language and each other This way users do not need to know about McStas internals to write new component or instrument definitions and even if those internals change in later versions of McStas existing definitions can be used without modification The McStas system also utilizes the meta language to let the McStas compiler generate as much code as possible automatically letting the compiler handle some of the things that would otherwise be the task of the user programmer Correctness is improved by having a well tested compiler generate code that would otherwise need to be specially written and debugged by the user for every instrument or component Efficiency is also improved by letting the compiler optimize the generated code in ways that w
126. minally 30 FWHM in both directions However the simulations indicated that the horisontal mosaicities of both monochromator and analyser were more likely 45 This was used for all mosaicities in the final instrument definition The monochromator scattering angle in effect determining the incoming neutron en ergy is for the real spectrometer fixed by four holes in the shielding corresponding to the energies 3 6 5 0 7 2 and 13 7 meV for first order neutrons In the instrument definition we have adapted the angle corresponding to 5 0 meV in order to test the simulations against measurements performed on the spectrometer The width of the exit channel from the monochromator may be narrowed down from initially 40 mm to 20 mm by an insert piece In the simulations we have chosen the 20 mm option and modeled the channel with two slits to match the experimental set up In the test experiments we used two standard samples An Al O3 powder sample and a vanadium sample The instrument definitions use either of these samples of the correct size Both samples are chosen to focus on the opening aperture of collimator 2 the one between the sample and the analyser Two slits one before and one after the sample are in the instrument definition set to the opening values which were used in the experiments The analyser of the spectrometer is flat and made from pyrolytic graphite It is placed between an entry and an exit channel the latter leading to
127. mpiler using the op tions Aa 0all W1 a archive the Aa option is necessary to enable the ISO C standard e SGI machines running Irix with the options Ofast 032 w Optimization flags will typically result in a speed improvement by a factor about 3 but the compilation of the instrument may be 5 times slower A warning is in place here it is tempting to spend far more time fiddling with compiler options and benchmarking than is actually saved in computation times Even worse compiler optimizations are notoriously buggy the options given above for PGCC on Linux and the ISO C compiler for HPUX have been known to generate incorrect code in some compiler versions mcstas actually puts an effort into making the task of the C compiler easier by in lining code and using variables in an eflicient way As a result McStas simulations generally run quite fast often fast enough that further optimizations are not worthwhile Also optimizations are highly time and memory consuming during compilation and thus may fail when dealing with large instrument descriptions e g more that 100 elements The compilation process is simplified when using components of the library making use of shared libraries see SHARE keyword in chapter 5 Refer to section 4 4 4 for other optimization methods 4 4 Running the simulations Once the simulation program has been generated by the McStas compiler mcstas and an executable has been obtained with the C compile
128. mple 1 Samples_vanadium out ROT 90 The number of neutron histories to simulate may be set using the ncount or n option for example ncount 2e5 The initial seed for the random number generator is by default chosen based on the current time so that it is different for each run However for debugging purposes it is sometimes convenient to use the same seed for several runs so that the same sequence of random numbers is used each time To achieve this the random seed may be set using the seed or s option By default McStas simulations write their results into several data files in the current directory overwriting any previous files stored there The dir dir or ddir option causes the files to be placed instead in a newly created directory dir to prevent over writing previous results an error message is given if the directory already exists Al ternatively all output may be written to a single file file using the file file or f file option which should probably be avoided when saving in binary format see below If the file is given as NULL the file name is automatically built from the instrument name and a time stamp The default file name is mcstas followed by appropriate extension The complete list of options and arguments accepted by McStas simulations appears in Tables and 40 D e 4 4 1 Choosing an output data file format Data files contain header lines with information about the simulation from whi
129. mulation usually called mcstas sim The file will be read and any detector data plotted using the mcplot front end The parameters used in the simulation will also be made the defaults for the next simulation run This function is also available using the Read button to the right of the name of the current simulation data Simulation Run simulation opens the run dialog window explained further below Simulation Plot results plots using mcplot the results of the last simulation run or spawns a load dialogue to load a set of results The Neutron Site menu contains a list of template example instruments as found in the McStas library sorted by neutron site When selecting one of these a local copy of the instrument description is transferred to the active directory so that users have 49 mo McStas Configuration options Plotting options PGPLOT original McStas i Use binary files faster I 3 pane view with PGPLOT trace Clustering None single CPU Editor options Advanced built in editor E Surround strings with quotes Compilation options E Optimize g O2 Optimization options Precision 1e 3 Figure 4 6 The configuration options dialog in mcgui modification rights and loaded One may then view its source Edit and use it directly for simulations trace 3D View The Tools menu gathers minor tools Tools Plot current other results Plot current
130. n a certain solid angle interval AQ only these solid angles are used for the Monte Carlo choice of scattering direction This implies fwc AQ 1 However if the physical events are distributed uniformly over the unit sphere we would have P AQ A9 47 according to Eq 3 9 One thus ensures that the mean simulated intensity is unchanged during a correct direction focusing while a too narrow focusing will result in a lower i e wrong intensity since we cut neutrons rays that should have reached the final detector 3 4 Adaptive and Stratified sampling Another strategy to improve sampling in simulations is adaptive importance sampling also called variance reduction technique where McStas during the simulations will de termine the most interesting directions and gradually change the focusing according to that Implementation of this idea is found in the Source adapt and Source Optimizer components An other class of efficiency improvement technique is the so called stratified sampling It consists in partitioning the event distributions in representative sub spaces which are then all sampled individually The advantage is that we are then sure that each sub space 28 Figure 3 1 Illustration of the effect of direction focusing in McStas Weights of neutrons emitted into a certain solid angle are scaled down by the full unit sphere area is well represented in the final integrals This means that instead of shooting N ev
131. nel The McStas meta language definition and the associated compiler mcstas e McStas Monte Carlo Simulation of Triple Axis Spectrometers the name of this package Pronunciation ranges from mez tas to mac stas and m c stas e Output parameter An output parameter for a component For example the counts in a monitor An output parameter may be accessed from the instrument in which the component is used using MC_GETPAR e Run time C code contained in the files mcstas r c and mcstas r h included in the McStas distribution that declare functions and variables used by the generated simulations e Setting parameter Similar to a definition parameter but with the restriction that the value of the parameter must be a number 129 Bibliography Mcs Mcz Ts2 Ess Nmi Mcn Nis Vit Ibw Nad Sns Ifi Nex ACL98 Ali04 Cla 66 Cla 98 Cop 86 Cop93 Cop03 Cus03 130 See http www mestas org cit on pp PTI BI 16 BT B3 39 73 64 95 L04 See EPI PTR merodo Eg FaROTT cit on pp P E See tepr ee Aets TI eca cit on p 0 See ttp vuv e55 surope aa cit on pp OQ See h8p neutron en net en cit on p 10 See cit on p 10 See http strider lansce lanl gov NISP Welcome html cit on p 11 See http www hmi de projects ess vitess cit on p 1 See http neutrons dev ornl gov eqsans software ib cit on p 11 cit on p
132. nergy Part A Reactor Sci 11 1960 p 69 cit on p 13 H Maier Leibnitz and T Springer In Reactor Sci Technol 17 1963 p 217 cit on p 13 G Manzin et al In Nucl Instr Meth A535 2004 p 102 cit on p 13 T E Mason et al RITA The reinvented triple axis spectrometer In Can J Phys 73 1995 pp 697 702 cit on p 12 D F R Mildner In Nucl Instr Meth A290 1990 p 189 cit on p 13 D F R Mildner C A Pellizari and J M Carpenter In Acta Cryst A 33 1977 p 954 cit on p 13 J A Nelder and R Mead In Computer Journal 7 1965 pp 308 313 cit on p 46 131 Pes 89 Pet05 Pre 86 Pre 02 Rad74 SK97 Sch 04 Sea97 See 00 SST02 Wec 00 WFLO4 Wil 14 ZLa04 132 V Peskov et al In Nucl Instr and Meth A277 1989 p 547 cit on ME J Peters In Nucl Instr Meth A540 2005 p 419 cit on p 13 W H Press et al Numerical Recipes in C Cambridge University Press 1986 cit on p 123 W H Press et al Numerical Recipes 2nd Edition Cambridge University Press 2002 cit on p 46 V Radeka In IEEE Trans Nucl Sci NS 21 1974 p 51 cit on p 13 J Saroun and J Kulda In Physica B 234 1997 See website omega ujf cas cz restrax p 1102 cit on pp 11 18 C Schanzer et al In Nucl Instr Meth A 529 2004 p 63 cit on pp 12 EJE V F Sears In Acta Cryst A53
133. ng for the format is to study some of the examples in the existing components and instruments Below a few notes are listed on the requirements for the comment headers The comment syntax uses IDENTIFICATION DESCRIPTION PARAMETERS 4EXAMPLE ZLINKS and END keywords to mark different sections of the documentation Keywords may be abbreviated except for 4EXAMPLE e g as 4IDENT or 41 Additionally optional keys VALIDATION and 4BUGS may be found to list validation status and possible bugs in the component 95 96 In the IDENTIFICATION section author or written by for backwards com patibility with old comments denote author date version and origin are also supported Any number of Modified by entries may be used to give the revision history The author date etc entries must all appear on a single line of their own Everything else in the identification section is part of a short description of the component In the PARAMETERS section descriptions have the form name unit text or name text unit These may span multiple lines but subsequent lines must be indented by at least four spaces Note that square brackets should be used for units Normal parentheses are also supported for backwards compatibility but nested parentheses do not work well The 4DESCRIPTION section contains text in free format The text may contain HTML tags like lt IMG gt to include pictures and lt A gt lt A
134. ng language C The output is by default written to a file in the current directory with the same name as the instrument file but with extension c rather than instr This can be overridden using the o option as follows 1 mcstas o code c name instr which gives the output in the file code c A single dash may be used for both input and output filename to represent standard input and standard output respectively 4 3 1 Code generation options By default the code generated by mcstas is ISO C with some extensions currently the only extension is the creation of new directories which is not possible in pure ISO C The use of extensions may be disabled with the p or portable option With this option the output is strictly ISO C compliant at the cost of some slight reduction in capabilities The t or trace option puts special trace code in the output This code makes it possible to get a complete trace of the path of every neutron ray through the instrument as well as the position and orientation of every component This option is mainly used with the mcdisplay front end as described in section 4 5 3 The code generation options can also be controlled by using preprocessor macros in the C compiler without the need to re run mcstas If the preprocessor macro MC PORTABLE is defined the same result is obtained as with the portable option The effect of 36 the trace option may be obtained by defining the MC
135. nt A parametrised pulsed source for modelling ESS long pulses A parametrised pulsed source for modelling ESS short pulses A simple pulsed source for time of flight To be used after the Source_Optimizer component Continuous source with up to three Maxwellian distributions Optimizes the neutron flux passing through the Source_Optimizer in order to have the maximum flux at the Monitor_Optimizer position Continuous neutron source with adaptive importance sam pling Continuous neutron source with a specified Gaussian diver gence A simple continuous circular neutron source with flat ener gy wavelength spectrum General continuous neutron source with tunable shape spec trum and divergence Source like component that reads neutron events from an asci i binary virtual source file recorded by Virtual output Detector like component that writes neutron state for use in Virtual_input Table 7 1 Source and source related components of the McStas library 102 MCSTAS optics Description Arm Beamstop Bender Collimator_linear Collimator_radial DiskChopper FermiChopper Filter_gen Guide Guide_channeled Guide_gravity Guide_wavy Mirror Monochromator_curve Monochromator flat Pol bender Pol guide vmirror Pol mirror Pol simpleBfield Selector Slit V selector Vitess ChopperFermi Arm optical bench Rectangular circular beam stop A curved neutron guide shown straight in mcdis
136. o tackle the problems currently faced at reactor and spallation sources The McStas project was designed to provide such a framework McStas is a fast and versatile software tool for neutron ray tracing simulations It is based on a meta language specially designed for neutron simulation Specifications are written in this language by users and automatically translated into efficient simulation codes in ISO C The present version supports both continuous and pulsed source instru ments and includes a library of standard components with in total around 130 compo nents These enable to simulate all kinds of neutron scattering instruments diffractome ters spectrometers reflectometers small angle back scattering for both continuous and pulsed sources The core McStas package is written in ISO C with various tools based on Perl and Python and is freely available for download from the McStas website Mes The package is actively being developed and supported by DTU Physics Institut Laue Langevin ILL Paul Scherrer Institute and the Niels Bohr Institute NBI The system is well tested and is supplied with several examples and with an extensive documentation Besides this manual a separate component manual exists The release at hand McStas 2 1 is a major upgrade from the last 1 12c release meaning partial loss of backward compatibility especially in terms of uniform nam ing of component input parameters Porting your existing personal in
137. o executed when the simulation ends This section is optional 5 3 8 The FINALLY section This gives code that will be executed when the simulation has ended When existing the SAVE section is first executed The FINALLY section is optional A simulation may be requested to end before all neutrons have been traced when receiving a TERM or INT signal on Unix systems or with Control C causing code in FINALLY to be evaluated 77 5 3 9 The end of the instrument definition The end of the instrument definition must be explicitly marked using the keyword 1 END 5 3 10 Code for the instrument vanadium example instr A commented instrument definition taken from the examples directory is here shown as an example of the use of McStas 5 4 Writing instrument definitions complex arrangements and syntax In this section we describe some additional ways to build instruments using groups code extension conditions loops and duplication of components As a summary the nearly complete grammar definition for component instances within the instrument TRACE section is SPLIT COMPONENT name comp parameters WHEN condition AT RELATIVE reference PREVIOUS ABSOLUTE 1 2 3 ROTATED RELATIVE reference PREVIOUS ABSOLUTE 4 GROUP group name 5 6 EXTEND C code JUMP reference PREVIOUS MYSELF NEXT ITERATE number of times WHEN condition 5 4 1 Embedding instruments in instr
138. o study the instrument design 5 3 2 The DEPENDENCY line 1 DEPENDENOCY 1LIB1 ILIB2 If you make use of external library calls in your instrument you may indicate the dependency list to be used for the compilation of the instrument as a single DEPEN DENCY keyword and a string argument all on a single line such as 1 DEPENDENOCY lgsl lgslcblas The concatenation of all found dependencies from the instrument but also from all used components will be printed to the terminal stdout as 1 CFLAGS 1gsl lgslcblas This line is interpreted by mcrun see section 4 5 2 and passed to the compiler It must be indicated just before the DECLARE section This line is optional and if omitted you may need to manually link the instrument with the libraries and add the proper library names to the MCSTAS_CFLAGS or CFLAGS environment variables 5 3 3 The DECLARE section DECLARE Zi C declarations of global variables etc m 2 IW li This gives C declarations that may be referred to in the rest of the instrument def inition A typical use is to declare global variables or small functions that are used elsewhere in the instrument The include file keyword may be used to im port a specific component definition or a part of an instrument Variables defined here are global and may conflict with internal McStas variables specially symbols like x y z sx sy Sz vX Vy vz t and
139. ocal coordinate system the position and orientation of which may be specifled by its translation and rotation relative to another component An ex ample is given in section 5 3 10 and some additional examples of instrument definitions can be found on the McStas web page and in the example directory As a summary the usual grammar for instrument descriptions is DEFINE INSTRUMENT name parameters DECLARE C_code INITIALIZE C code TRACE components FINALLY C code END 5 3 1 The instrument definition head 1 DEFINE INSTRUMENT name al a2 This marks the beginning of the definition It also gives the name of the instrument and the list of instrument parameters Instrument parameters describe the configuration of the instrument and usually correspond to setting parameters of the components see section A motor position is a typical example of an instrument parameter The input parameters of the instrument constitute the input that the user or possibly a front end program must supply when the generated simulation is started By default the parameters will be floating point numbers and will have the C type double double precision floating point The type of each parameter may optionally be declared to be int for the C integer type or char for the C string type The name string may be used as a synonym for char and floating point parameters may be explicitly declared using the name double The following exampl
140. of the component These parameters can be accessed from all sections of the component see below as well as in EXTEND sections of the instrument definition see section 5 3 Setting parameters are translated into C variables usually of type double in the gen erated simulation program so they are usually numbers Definition parameters are translated into define macro definitions and so can have any type including strings arrays and function pointers However because of the use of define definition parameters suffer from the usual problems with C macro definitions Also it is not possible to use a general C expression for the value of a definition parameter in the instrument definition only constants and variable names may be used For this reason setting parameters should be used whenever possible Outside the INITIALIZE section of components changing setting parameter values only affects the current section There are a few cases where the use of definition parameters instead of setting pa rameters makes sense If the parameter is not numeric nor a character string i e an array for example a setting parameter cannot be used Also because of the use of tdefine the C compiler can treat definition parameters as constants when the sim ulation is compiled For example if the array sizes of a multidetector are definition parameters the arrays can be statically allocated in the component DECLARE section If setting parameters wer
141. ompo nents to overlap except for particular cases see the GROUP keyword below Indeed many components of the McStas library start by propagating the neutron event to the beginning of the component itself Anyway when the corresponding propagation time is found to be negative i e the neutron ray is already after or aside the component and has thus passed the active position the neutron event is ABSORBed resulting in a zero intensity and event counts after a given position The number of such removed neutrons is indicated at the end of the simulation Getting such warning messages is an indication that either some components overlap or some neutrons are getting out side of the simulation for instance this usually happens after a monochromator as the non reflected beam is indeed lost A special warning appears when no neutron ray has reached some part of the simulation This is usually the sign of either overlapping components or a very low intensity For experienced users we recommend as well the usage of the WHEN and EXTEND key words as well as other syntax extensions presented in section 5 4 below 5 3 7 The SAVE section SAVE mi C code to execute each time a temporary save is required LA This gives code that will be executed when the simulation is requested to save data for instance when receiving a USR2 signal on Unix systems or using the Progress bar component with intermediate savings It is als
142. omponent files into a C program The program mcstas itself is written in C using the parser flex and the compiler compiler bison The resulting C program can then be compiled with a C compiler and run in combination with various front end programs for example to present the intensity at the detector as a motor position is varied The output data may be analyzed and visualized in the same way as regular ex periments by using the data handling and visualization tools in McStas based on Perl Python in combination with chaco matplotlib Matlab GNUPlot or PG PLOT Further data output formats including NeXus are available see section Installation and updates For installation notes see the web site Mes In case of problems write the support mailing list or contact the authors 4 1 1 Important note for Windows users It is a known problem that some of the McStas tools do not support filenames direc tories with spaces We are working on a more general approach to this problem which sl INSTRUMENT COMPONENT A COMPONENT B Source The tool layer consists of programs manipulated by the McStas user COMPONENT C COMPONENT D TOF_monitor Chopper mcgui graphical user interface meplot visualize histogram outp mcdisplay visualize instrument mcgui is used to assemble an instrument file which is taken over by the McStas system COMPONENT A Source Parameters
143. onally installed on slave machines e when using an homogeneous computer cluster each simulation including scan steps may be computed in parallel using MPI We recommend this method on clusters see section 4 7 2 Last but not least you may run simulations manually on a number of machines Once the distributed simulation have been completed you may merge their results using mcformat see section 4 5 8 in order to obtain a set of files just as if it had been executed on a single machine All of these methods can be used when available from mcgui 4 7 1 Distribute mcrun simulations on grids multi cores and clusters SSH grid This method distributes simulations on a set of machines using ssh connections using a command such as mcrun grid 4 Each of the scan steps is split and executed 63 on distant slave machines sending the executable with scp executing single simulations and then retrieving individual results on the master machine These are then merged using mcformat The mcrun script has been adapted to use transparently SSH grids The syntax is e grid lt number gt tells mcrun to use the grid over number nodes e machines lt file gt defines a text file where the nodes which are to be used for parallel computation are listed by default mcrun will look at HOME mcstas hosts and MCSTAS tools perl mcstas hosts When used on a single SMP machine multi core cpu this option may be omitted
144. ondition The condition has the same scope as the EXTEND modifier i e may use component internal variables as well as all the DECLARE instrument variables except instrument parameters To use instrument parameters you should copy them into global variables in the DECLARE instrument section and refer to these latter It is evaluated before the component TRACE section 81 DO AI QO OL VW WO ISL Usage examples could be to have specific monitors only sensitive to selected processes or to have components which are only present under given circumstances e g removable guide or radial collimator or to select a sample among a set of choices In the following example an EXTEND block sets a condition when a scattering event is encountered and the following monitor is then activated COMPONENT Sample V sample AT EXTEND nt if SCATTERED flag l else flag 0 n COMPONENT MyMon Monitor WHEN flag l AT The WHEN keyword only applies to the TRACE section and related EXTEND blocks of instruments components Other sections INITIALIZE SAVE MCDISPLAY FI NALLY are executed independently of the condition As a side effect the 3D view of the instrument mcdisplay will show all components as if all conditions were true Also the WHEN keyword is a condition for GROUP This means that when the WHEN is false the component instance is not active in the GROUP it belongs to A usage example of the WHEN keyw
145. ontains a number identifying the bin i e the time of flight followed by three numbers the simulated intensity an estimate of the statistical error as explained in section 3 2 1 and the number of neutron events for this bin Two dimensional histogram monitors position sensitive detectors output M lines of N numbers representing neutron intensities where M and N are the number of bins in the two dimensions The two dimensional monitors also store the error estimates and event counts as additional matrices Single point monitors output the neutron intensity the estimated error and the neu tron event count as numbers on the terminal The results from a series of simulations may be combined in a data file using the mcrun front end as explained in section 4 5 2 When using one and two dimensional monitors the integrated intensities are written to terminal as for the single point monitor type supplementing file output of the full one or two dimensional intensity distribution Both one and two dimensional monitor output by default start with a header of comment lines all beginning with the character This header gives such information as the name of the instrument used in the simulation the values of any instrument parameters the name of the monitor component for this data file etc The headers may be disabled using the data only option in case the file must be read by a program that cannot handle the headers In addition to th
146. or details t Table structure most important members double xdata Use Table Index Table i j to get element i j long rows number of rows long columns number of columns char header 4 the header with comments x char kfilename x file name or title x double min x minimum value of 1st column vector double maxx mazimum value of 1st column vector Available functions to read a single vector matrix are e Table_Init amp Table rows columns returns an allocated Table structure Use rows columns 0 not to allocate memory and return an empty table Calls to Table_Init are optional since initialization is being performed by other functions already e Table Read Table filename block reads numerical block number block 0 to concatenate all data from tezt file filename into Table which is as well initialized in the process The block number changes when the numerical data changes its size or a comment is encoutered lines starting by If the data could 124 not be read then Table data is NULL and Table rows 0 You may then try to read it using Table_Read_Offset_Binary Return value is the number of elements read e Table Read_Offset amp T able filename block offset Nrows does the same as Table_Read except that it starts at offset offset 0 means begining of file and reads nrows lines 0 for all The offset is returned as the final offset reac
147. or random number transformation since we in general know W y and like to determine the relation y f x Let us illustrate with a few examples of transformations relevant for the McStas components The circle For finding a random point within the circle of radius R one would like to choose the polar angle 9 from a uniform distribution in 0 27 giving Vg 1 27 and the radius from the normalised distribution Y 2r R For the radial part eg A 2 becomes y 27 x whence is found simply by multiplying a random number x with 27 For the radial part the left side of eq A gives f W r dr f 2r R2dr r R which from should equal x Hence we reach the wanted transformation r Ry z The sphere For finding a random point on the surface of the unit sphere we need to determine the two angles 0 Vy is chosen from a uniform distribution in 0 27 giving 27x as for the circle The probability distribution of 8 should be Wg sin 0 for 6 0 7 whence by eq A 2 9 cos 7 117 Exponential decay In a simple time of flight source the neutron flux decays exponen tially after the initial activation at t 0 We thus want to pick an initial neutron emission time from the normalised distribution Y t exp t 7 7 Use of Eq gives z 1 exp t r For convenience we now use the random variable z 1 x with the same distributions as x giving the simple expression t T In z Nor
148. ord can be found in the Neutron site ILL ILL_TOF_Env instrument from the mcgui to monitor neutrons de pending on their fate WARNING Combining WHEN EXTEND and GROUP can result in unexpected behavior please use with caution Let for instance a GROUP of components all have the same WHEN condition i e if the WHEN condition is false none of the elements SCATTER meaning that all neutrons will be ABSORBed As a solution to this problem we propose to include an EXTENDed Arm component in the GROUP but with the opposite WHEN condition and a SCATTER keyword in the EXTEND section This means that when none of the other GROUP elements are present the Arm will be present and SCATTER 5 4 5 Component loops and non sequential propagation JUMP There are situations for which one would like to repeat a given component many times or under a given condition The JUMP modifier is meant for that and should be placed after the positioning GROUP and EXTEND This breaks the sequential propagation along components in the instrument description There may be more than one JUMP per component instance The jump may depend on a condition COMPONENT name comp p l el p 2 e 2 AT JUMP reference WEEN condition in which case the instrument TRACE will jump to the reference when condition is true 82 The reference may be an instance name as well as PREVIOUS PREVIOUS n MYSELF NEXT and NEXT n where n is the index gap to the tar
149. ould be time consuming or difficult for humans to do Furthermore the compiler can generate several different simulations from the same specification for example to optimize the simulations in different ways to generate a simulation that graphically displays neutron 15 trajectories and possibly other things in the future that were not even considered when the original instrument specification was written The design of McStas makes it well suited for doing what if types of simulations Once an instrument has been defined questions such as what if a slit was inserted what if a focusing monochromator was used instead of a flat one what if the sample was offset 2 mm from the center of the axis and so on are easy to answer Within minutes the instrument definition can be modified and a new simulation program generated It also makes it simple to debug new components A test instrument definition may be written containing a neutron source the component to be tested and whatever monitors are useful and the component can be thoroughly tested before being used in a complex simulation with many different components The McStas system is based on ISO C making it both efficient and portable The meta language allows the user to embed arbitrary C code in the specifications Flexibility is thus ensured since the full power of the C language is available if needed 1 4 Overview The McStas system documentation consists of
150. play A simple analytical Soller collimator A radial Soller collimator Disk chopper Fermi Chopper with rotating frame calculations This components may either set the flux or change it filter like using an external data file Straight neutron guide Straight neutron guide with channels bender section Straight neutron guide with gravity Can be channeled and focusing Straight neutron guide with gaussian waviness Single mirror plate dDoubly bent multiple crystal slabs with anisotropic Gaussian mosaic Flat Monochromator crystal with anisotropic Gaussian mo saic Polarising bender Guide with semi transparent polarising mirror Polarising mirror Numerical precession in analytical B fields A velocity selector helical lamella type such as V_selector component Rectangular circular slit Velocity selector Curved Fermi chopper longer execution time than Fermi Chopper From the Vitess package Table 7 2 Optics components of the McStas library 103 MCSTAS samples Description Inelastic_Incoherent Isotropic_Sqw Phonon_simple Powder1 PowderN Sans spheres Single_crystal V_sample Inelastic incoherent sample with quasielastic and elastic con tributions A general S q w scatterer with multiple scattering for liquids powders glasses polymers May be concentrically arranged Coherent incoherent elastic inelastic scattering Single crystal sample with acoustic iso
151. possible to send one of the signals listed in Table 4 3 using the kill unix command or the functionalities of your process manager e g 1 kill USR2 13277 This will result in a message showing status here 33 achieved as well as the position in the instrument of the current neutron 1 McStas pid 13277 Signal 12 detected SIGUSR2 Save simulation 2 Simulation file file instr 3 Breakpoint MyDetector Trace 33 37 333654 0 1000000 0 4 Date Wed May 7 00 00 52 2003 5 McStas Saving data and resume simulation continue followed by the list of detector outputs integrated counts and files Finally sending a kill 13277 which is equivalent to kill TERM 13277 will end the simulation before the initial ncount preset A typical usage example would be for instance to save data during a simulation plot or analyze it and decide to interrupt the simulation earlier if the desired statistics has been achieved This may be done automatically using the Progress_bar component Whenever simulation data is generated before end or the simulation is interrupted the ratio field of the monitored data will provide the level of achievement of the com putation for instance 3 33e 05 1e 06 Intensities are then usually to be scaled ac cordingly by the user Additionally any system error will result in similar messages giving indication about the occurrence of the error component
152. prate instrument for sim ulating an IN5 TYPE cold chopper multi frame spectrometer for the long pulsed ESS Also serves as example instrument for Tunneling_sample comp 8 2 A test instrument for the component V_sample This is one of many test instruments written with the purpose of testing the individual components We have picked this instrument both to present an example test instrument and because it despite its simplicity has produced quite non trivial results 109 Collimator Source 4pipsd Figure 8 1 A sketch of the test instrument for the component V_sample The instrument consists of a narrow source a 60 collimator a V sample shaped as a hollow cylinder with height 15 mm inner diameter 16 mm and outer diameter 24 mm at a distance of 1 m from the source The sample is in turn surrounded by an unphysical 4r7 PSD monitor with 50 x 100 pixels and a radius of 10 m The set up is shown in figure 8 2 1 Scattering from the V sample test instrument In figure 8 2 we present the radial distribution of the scattering from an evenly illumi nated V sample as seen by a spherical PSD It is interesting to note that the variation in the scattering intensity is as large as 10 This is an effect of anisotropic attenuation of the beam in the cylindrical sample 8 3 The triple axis spectrometer TAS1 With this instrument definition we have tried to create a very detailed model of the conventional cold source trip
153. r the simulation can be run in various ways 39 Simple McStas options In this section the most common simulation parameters are discussed For a full list please consult tables The simplest way is to run it directly from the command line or shell 1 name out Note the leading which is needed if the current directory is not in the path searched by the shell When used in this way the simulation will prompt for the values of any instrument parameters such as angular settings and then run the simulation Default instrument parameter values see section 5 3 if any will be indicated and entered when hitting the Return key This way of running McStas will only give data for one instrument setting which is normally sufficient for e g time of flight SANS or powder instruments but not for e g continuous beam reflectometers or triple axis spectrometers where a scan over various instrument settings is required Often the simulation will be run using one of several available front ends as described in the next section These front ends help manage output from the potentially many detectors in the instruments as well as running the simulation for each data point in a scan The generated simulations accept a number of options and arguments The full list can be obtained using the help option 1 name out help The values of instrument parameters may be specified as arguments using the syntax name val For exa
154. r h normal vec C function mccode r c 122 OpenGL Optimization compiler Hom origin McDoc keyword Output parameter OUTPUT PARAMETERS McStas keyword 86 B7 Parallel computing see MPI Parameters definition Instruments instruments McDoc section optimization optional default value protecting see Keyword OUTPUT scans 54 setting Path file search Perl ActiveState for Windows libraries PGPLOT BA A1 format PGPLOT_DEV environment variable PGPLOT_DIR environment variable 135 PI constant 128 POS A COMP C macro mccode r h POS A COMP INDEX C macro meccode r h POS A CURRENT COMP C macro meccode r h 120 POS R COMP INDEX C macro mccode r h 121 Preprocessor macros PREVIOUS McStas keyword PRISMA PROP DT C macro mcstas r h PROP GRAV DT C macro mecstas r h PROP ZO C macro mcstas r h Propagation backward RAD2DEG constant 128 RAD2MIN constant 128 rand01 C function mccode r c randnorm C function mccode r c 123 Random numbers generator 118 transformations randpm1 C function mccode r c randtriangle C function mccode r c randvec_target_circle C function mecode r c 124 randvec target rect C function mccode r c randvec target rect angular C function mccode r c 124 read table lib library 124 RELATIVE McStas keyword Release scheme Removed neutron events RESTORE_NEUTRON
155. ram value For example 1 SETTING PARAMETERS radius height pack 1 Here pack is an optional parameter and if no value is given explicitly 1 will be used In contrast if no value is given for radius or height an error message will result Optional parameters can greatly increase the convenience for users of components with many parameters that have natural default values which are seldom changed Optional parameters are also useful to preserve backwards compatibility with old instrument definitions when a component is updated New parameters can be added with default values that correspond to the old behavior and existing instrument definitions can be used with the new component without changes However optional parameters should not be used in cases where no general natural default value exists For example the length of a guide or the size of a slit should not be given default values This would prevent the error messages that should be given in the common case of a user forgetting to set an important parameter 5 5 2 The DEPENDENCY line 1 DEPENDENCY ILIB1 ILIB2 This optional line indicates any external library which are needed by the component It should be used when the component code calls external functions and routines which 86 oF WN FH NOR WHR OMW JIO OI LV DO IL should be available when compiling the instrument This line must be indicated just before the SHARE and DECLARE section
156. rams that extend the functionality of the simulations A front end program is an interface between the user and the simulations running the simulations and presenting the output in various ways to the user The list of available McStas front end programs may be obtained from the mcdoc tools command McStas Tools mcstas Main instrument compiler mcrun Instrument build and execution utility mcgui Graphical User Interface instrument builder mcdoc Component library documentation generator viewer mcplot Simulation result viewer mcdisplay Instrument geometry viewer mcresplot Instrument resolution function viewer 47 9 mcstas2vitess McStas to Vitess component translation utility 10 mcformat Conversion tool for text files and MPI grids 11 mcformatgui GUI for mcformat 12 mcdaemon Instrument results on line plotting 13 When used with the h flag all tools display a specific help 14 SEE ALSO mcstas mcdoc mcplot mcrun mcgui mcresplot mcstas2vitess 15 DOC Please visit http www mcstas org 4 5 1 The graphical user interface mcgui The front end mcgui provides a graphical user interface that interfaces the various parts of the McStas package It may be started with the single command 1 mcgui The mcgui mcgui pl on Windows program may optionally be given the name of the instrument file to use Dependencies To run the mcgui front end the programs Perl and Perl Tk must be properly installed on the syste
157. rcle tu amp v amp vz dO aim aimy aim ry Generates a random vector Ur Vy Vz of the same length as aim aimy aim which is targeted at a disk centered at aim aimy aim with radius ry in meters and perpendicular to the aim vector All directions that intersect the circle are chosen with equal probability The solid angle of the circle as seen from the po sition of the neutron is returned in dQ This routine was previously called rand vec target sphere which still works e randvec_target_rect_angular amp v amp v amp vz amp dQ aim aim aim h w Rot does the same as randvec target circle but targetting at a rectangle with angular dimensions h and w in radians not in degrees as other angles The rotation matrix Rot is the coordinate system orientation in the absolute frame usually ROT A CURRENT COMP e randvec_target_rect amp vz Kuy tu amp dQ aim aimy aim height width Rot is the same as randvec target rect angular but height and width dimensions are given in meters This function is useful to e g target at a guide entry window or analyzer blade B 2 Reading a data file into a vector matrix Table input read table lib The read table lib provides functionalities for reading text and binary data files To use this library add a include read table lib in your component definition DE CLARE or SHARE section Tables are structures of type t Table see read table lib h file f
158. red 4 5 5 Plotting resolution functions mcresplot The mcresplot front end is used to plot the resolution function particularly for triple axis spectrometers as calculated by the Res_sample component or TOF_res_sample for time of flight instruments It requires to have a Res_monitor component further in the instrument description at the detector position This front end has been included in the release since it may be useful despite its somewhat rough user interface The mcresplot front end is launched with the command 1 mcresplot outfile Here outfile is the name of a file output from a simulation using the Res_monitor com ponent This front end currently only works with the PGPLOT plotter but port for Matlab may be written in the future The front end will open a window displaying projections of the 4 dimensional resolu tion function R Q w measured at a particular choice of Q and w see the component manual The covariance matrix of the resolution function the resolution along each pro jection axis and the resulting resolution matrix are also shown as well as the instrument name and parameters used for the simulation To use the mcresplot front end the programs Perl PGPLOT PgPerl and PDL must all be properly installed on the system 58 w mevj w meV a a Q 8 4 Q A Q A74 Q A 4 Bragg Gaussian Half Widths File Output res Instrument simulation parameters AQ 0 3133 A Date Thu May 15 10
159. rly setup ssh connections and keys as indicated in the ssh grid system Section 4 7 1 Some OpenMPI implementations do not recognize multi cores as separate nodes In this case you should use MPICH or the SSH grid There are 3 methods for using MPI e Basic usage requires to compile and run the simulation by hand mpicc mpirun This should be used when running LAM MPI e A much simpler way is to use mcrun c mpi NB CPU which will recompile and run MPICH e The McGUI interface supports MPICH from within the Run Dialog The MPI support is especially suited on clusters As an alternative the SSH grid presented above section 4 7 1 is very flexible and requires lighter configuration Requirements and limitation MPI To use MPI you will need 1 A master machine with an SSH client server and McStas installation 2 A set of Unix machines of the same architecture binary compatible with SSH servers 65 3 ssh access from the master node where McStas is installed to the slaves through e g DSA keys without a password These keys should be generated using the command ssh keygen Run e g ssh keygen t dsa on master node enter no passphrase and add resulting ssh id_dsa pub to ssh authorized_keys on all the slave nodes The key generation and registering mechanism may be done automatically for the local machine from the Help menu Install DSA key item of mcgui 4 The machine names listed in the file mcstas hosts in your
160. ron ray each time fmc 1 This must be reflected on the choice of weight mul tiplier 7 P Of course one could simulate without weight factor transformation in our notation written as fmc P 7 1 To generalize weight factor transformations are given by the master equation fuor P 3 9 This probability rule is general and holds also if e g it is decided to transmit only half of the rays fmc 0 5 An important different example is elastic scattering from a powder sample where the Monte Carlo choices are the particular powder line to scatter from the scattering position within the sample and the final neutron direction within the Debye Scherrer cone This weight transformation is much more complex than described above but still boils down to obeying the master transformation rule 3 9 3 3 1 Direction focusing An important application of weight transformation is direction focusing Assume that the sample scatters the neutron rays in many directions In general only neutron rays in some of these directions will stand any chance of being detected These directions we call the interesting directions The idea in focusing is to avoid wasting computation time on neutrons scattered in the other directions This trick is an instance of what in Monte Carlo terminology is known as importance sampling If e g a sample scatters isotropically over the whole 47 solid angle and all interesting directions are known to be contained withi
161. rument examples has been extended considerably see the Neutron Site menu in mcgui See page 4 2 8 1 A quick tour of instrument examples 8 1 1 Neutron site Brookhaven The former Brookhaven reactor hosted the H8 triple axis spectrometer This latter was modelled in order to cross check the NISP Vitess Restrax McStas and IDEAS neutron propagation Monte Carlo codes Results were published in Neutron News 13 No 4 24 29 2002 8 1 2 Neutron site Tools This category currently contains a special Histogrammer that can read any event file from Vitess MCNP tripoli and McStas in order to produce histograms of any type This is a very powerful tool to analyse sparse huge events data sets 8 1 3 Neutron site ILL Cold and thermal guide models are given in the ILL neutron site Descriptions are very accurate based on actual drawings including all elements with curvature and gaps Simulated capture fluxes were found in very good agreement with measurements Additionally the IN12 triple axis instrument has been detailed in its year 2005 con figuration It is located at the end of the H15 cold guide The sample is a Vanadium rod The IN6 instrument is a hybrid time of flight spectrometer with 3 monochromators and a Fermi chopper The sample is an isotropic scatterer liquid It makes use of the SPLIT keyword to enhance statistics 108 The ILL_TOF_Env example is a simple neutron pulse e g from a chopper system comin
162. s Cop 86 Monte Carlo techniques also provide means to evaluate some of these quantities Technicalities of Monte Carlo simulation techniques are explained in detail in Chap 13 ter 1 2 1 The goals of McStas Initially the McStas project had four main objectives that determined its design Correctness It is essential to minimize the potential for bugs in computer simulations If a word processing program contains bugs it will produce bad looking output or may even crash This is a nuisance but at least you know that something is wrong However if a simulation contains bugs it produces wrong results and unless the results are far off you may not know about it Complex simulations involve hundreds or even thousands of lines of formulae making debugging a major issue Thus the system should be designed from the start to help minimize the potential for bugs to be introduced in the first place and provide good tools for testing to maximize the chances of finding existing bugs Flexibility When you commit yourself to using a tool for an important project you need to know if the tool will satisfy not only your present but also your future requirements The tool must not have fundamental limitations that restrict its potential usage Thus the McStas systems needs to be flexible enough to simulate different kinds of instruments as well as many different kind of optical components and it must also be extensible so that future as yet unfore
163. s However it is possible to set up an instrument from existing components and run a simulation without writing a single line of C code working entirely in the meta language Apart from the meta language McStas also includes a number of C library functions and definitions that are useful for neutron ray tracing simulations The definitions avail able for component developers are listed in appendix B The list includes functions for e Computing the intersection between a flight path and various objects such as planes cylinders boxes and spheres e Functions for generating random numbers with various distributions e Functions for reading or writing information from to data files e Convenient conversion factors between relevant units etc The McStas meta language was designed to be readable with a verbose syntax and explicit mentioning of otherwise implicit information The recommended way to get started with the meta language is to start by looking at the examples supplied with McStas modifying them as necessary for the application at hand 5 1 Notational conventions Simulations generated by McStas use a semi classical description of the neutron rays to compute the neutron trajectory through the instrument and its interaction with the different components The effect of gravity is taken into account either in particular components e g Guide gravity or more generally when setting an execution flag g to perform gravitation computa
164. s Refer to the section for more information 5 5 3 The DECLARE section DECLARE Zi C code declarations variables definitions functions These are usually OUTPUT parameters to avoid name conflicts 7 This gives C declarations of global variables functions etc that are used by the com ponent code This may for instance be used to declare a neutron counter for a detector component This section is optional Note that any variables declared in a DECLARE section are global Thus a name conflict may occur if two instances of a component are used in the same instrument To avoid this variables declared in the DECLARE section should be OUTPUT parameters of the component because McStas will then rename variables to avoid conflicts For example a simple detector might be defined as follows DEFINE COMPONENT Detector OUIPUT PARAMETERS counts DECLARE ni int counts Zo The idea is that the counts variable counts the number of neutrons detected In the instrument definition the counts parameter may be referenced using the MC_GETPAR C macro as in the following example instrument fragment COMPONENT d1 Detector COMPONENT d2 Detector FINALLY ni printf Detector counts dl Md d2 d n MC GETPAR d1 counts MCGEIPAR d2 counts This way McStas takes care to rename transparently the two counts OUTPUT param eters so that they are distinct and can be accessed from el
165. s in the second example it will be searched within the library and an HTML help will be created for all available components matching comp The last example will list the name and description of all McStas tools Additionally the options web manual and comp will open the McStas web site page the User Manual this document and the Component Manual all requiring 59 BROWSER to be defined Finally the help option will display the command help as usual See section for more details about the McDoc usage and header format To use the mcdoc front end the program Perl should be available 4 5 7 Translating McStas components for Vitess mcstas2vitess Any McStas component may be translated for usage with Vitess starting from Vitess version 2 3 The syntax is simply mcstas2vitess Compo comp This will create a Vitess module of the given component Let us assume the component Compo shall be translated The tool first creates a small instrument called McStas Compo instr consisting of 1 component Vitess input 2 component Compo 3 component Vitess output This file is parsed to generate the C file McStas Compo c The last step is to compile the C file and build the executable Vitess module McStas compo For both steps McStas is used as for any other instrument McStas_compo has to be moved to the directory MODULES that contains all VITESS executables Additionally a file McStas compo tcl is created that conta
166. seen needs can be satisfied Power Simple things should be simple complex things should be possible New ideas should be easy to try out and the time from thought to action should be as short as possible If you are faced with the prospect of programming for two weeks before getting any results on a new idea you will most likely drop it Ideally if you have a good idea at lunch time the simulation should be running in the afternoon Efficiency Monte Carlo simulations are computationally intensive hardware capacities are finite albeit impressive and humans are impatient Thus the system must assist in producing simulations that run as fast as possible without placing unreasonable burdens on the user in order to achieve this 1 3 The design of McStas In order to meet these ambitious goals it was decided that McStas should be based on its own meta language also known as domain specific language specially designed for simulating neutron scattering instruments Simulations are written in this language by the user and the McStas compiler automatically translates them into efficient simulation programs written in ISO C In realizing the design of McStas the task was separated into four conceptual layers 1 Graphical user interface and scripting layer presentation of the calculations graph ical or otherwise aka the tool layer 14 2 Modeling of the overall instrument geometry mainly consisting of the type and posi
167. sewhere in the instrument EXTEND FINALLY SAVE or from other components This particular example is outdated since McStas monitors will themselves output their contents 5 5 4 The SHARE section 87 oF WN FR WO IV Li I Li SHARE ni C code shared declarations variables definitions functions These should not be OUTPUT parameters The SHARE section has the same role as DECLARE except that when using more than one instance of the component it is inserted only once in the simulation code No occurrence of the items to be shared should be in the OUTPUT parameter list not to have McStas rename the identifiers This is particularly useful when using many instances of the same component for instance guide elements If the declarations were in the DECLARE section McStas would duplicate it for each instance making the simulation code longer A typical example is to have shared variables functions type and structure definitions that may be used from the component TRACE section For an example of SHARE see the samples Single crystal component The include file keyword may be used to import a shared library The SHARE section is optional and should be located before the DECLARE section 5 5 5 The INITIALIZE section INITIALIZE Zi C code initialization n This gives C code that will be executed once at the start of the simulation usually to initialize any variables declared in the DE
168. shown in figures et 451 IPSD_ collimator jtarg SOUT PGPLOT Window 1 EDDA TOF diagram letDisk out Z Axis m X vie T o5 Figure 4 4 Left Output from mcdisplay with PGPLOT backend The left mouse button starts a new neutron ray the middle button zooms and the right button resets the zoom The Q key quits the program Right The new PGPLOT time of flight option See section 4 5 3 for details For a slightly longer gentle introduction to McStas see the McStas tutorial available from Mes and as of version 2 1 built into the mcgui help menu For more technical details read on from section 4 3 4 3 Running the instrument compiler This section describes how to run the McStas compiler mcstas manually Often it will be more convenient to use the front end program mcgui section or mcrun section 4 5 2 which run the compilation and the simulations automatically Upon a command of the form 35 home fys pkwi Beta0 mestas 1 7 Beta0 examples vanadium_example x m ved NNN Traietoi Piot Reset vie Comp s kom target Unlock Exit rea Ghats A Figure 4 5 Output from mcdisplay with Matlab backend Display can be adjusted using the window buttons 1 mcstas name instr the compiler mcstas will read the instrument definition name instr written in the McStas meta language and translate it into a Monte Carlo simulation program in the programmi
169. simulation results and other results Tools Online plotting of results installs a DSA key to be used for ssh clustering and MPI see Section 4 7 Tools Dataset convert merge Opens a GUI to the mcformat tool in order to convert datasets to other formats merge scattered dataset e g from successive or grid simulations and assemble scan sets This tool does not handle raw event files Tools Shortcut keys displays the shortcut keys used for running and editing instru ments Tools Install DSA key installs a DSA key to be used for ssh clustering and MPI see Section 7 The Histogrammer In addition to these tools the Neutron site Tools Histogrammer example instrument may read McStas Vitess MCNP and Tripoli event files in or der to generate histograms of any type The Help menu has the following features through use of mcdoc and a web browser To customize the used web browser set the BROWSER environment variable If BROWSER is not set mcgui uses netscape mozilla firefox on Unix Linux and the default browser on Windows Help McStas User manual calls mcdoc manual brings up the local pdf version of this manual using a web browser 50 instr Help McStas Component manual calls mcdoc comp brings up the local pdf version of the component manual using a web browser Help Component library index displays the component documentation using the com ponent index html index file Help McStas web page calls mcdoc web
170. strument files and components should be trivial but if you experience problems feel free to contact mcstas users mcstas org or the authors 1 1 Development of Monte Carlo neutron simulation The very early implementations of the method for neutron instruments used home made computer programs see e g papers by J R D Copley D F R Mildner J M Carpenter J Cook more general packages have been designed providing models for most parts of the simulations These present existing packages are NISP See 00 ResTrax SK97 Mestas hs Vies W IDEAS and IB Instrument Builder Ibw Supplementing the Monte Carlo based methods various analytic phase space simulation methods exist including Neutron Acceptance Diagram Shading NADS Nad Their usage usually covers all types of neutron spec 11 trometers most of the time through a user friendly graphical interface without requiring programming skills The neutron ray tracing Monte Carlo method has been used widely for e g guide stud ies Sch 04 instrument optimization and design Lie05 Most of the time the conclusions and general behavior of such studies may be obtained using the classical analytic approaches but accurate estimates for the flux the resolutions and generally the optimum parameter set benefit advantageously from MC methods Recently the concept of virtual experiments i e full simulations of a complete neutron experiment has been suggested as a major asset for
171. tal speed improvement mentioned above Data New lau datafiles for macromolecular structures Rubedoxin and Perdeuterated pyrophosphatase contributed by Esko Oksanen ESS 24 3 Monte Carlo Techniques and simulation strategy This chapter explains the simulation strategy and the Monte Carlo techniques used in McStas We first explain the concept of the neutron weight factor and discuss the statistical errors in dealing with sums of neutron weights Secondly we give an expression for how the weight factor transforms under a Monte Carlo choice and specialize this to the concept of direction focusing Finally we present a way of generating random numbers with arbitrary distributions More details are available in the Appendix concerning random numbers 3 1 Neutron spectrometer simulations 3 1 1 Monte Carlo ray tracing simulations The behavior of a neutron scattering instrument can in principle be described by a complex integral over all relevant parameters like initial neutron energy and divergence scattering vector and position in the sample etc However in most relevant cases these integrals are not solvable analytically and we hence turn to Monte Carlo methods The neutron ray tracing Monte Carlo method has been used widely for guide studies Sch 04 instrument optimization and design ZLa04 Lie05 Most of the time the conclusions and general behavior of such studies may be obtained using the classical analytic appro
172. tas omit the run time code from the generated simulation program and the user must then explicitly link with the file mcstas r c as well as other shared libraries from the McStas distribution Users that need these options are encouraged to contact the authors for further help 4 3 4 Running the C compiler After the source code for the simulation program has been generated with mcstas it must be compiled with the C compiler to produce an executable Since the generated C code obeys the ISO C standard it should be easy to compile it using any ISO C or C compiler E g a typical Unix style command would be 1 cc O o name out name c lm The McStas team recommends these compiler alternatives for the Intel and AMD hardware architectures A gcc which is a very portable open source ISO C compatible c compiler available for most platforms For Linux it is usually part of your distribution for Windows the McStas distribution package includes a version of gcc in the Dev CPP sub package and for Mac OS X gcc is part of the Xcode tools package available on the installation medium B icc or the Intel c compiler is available for Linux Mac OS and Windows systems and is a commercial software product Generally simulations run with the Intel compiler are a factor of 2 faster than the identical simulation run using gcc To use icc with McStas on Linux or Mac OS X set the environment variables MCSTAS_CC icc MCSTAS_CFL
173. tase Thank you guys This is what McStas is all about Third party software included only those distributed with McStas are Strawberry Perl Windows system only perl Math Amoeba from John A R Williams J A R Williams aston ac uk perl Tk Codetext from Hans Jeuken haje toneel demon nl PGPLOT from Tim Pearson tjp astro caltech edu Windows and Mac OS X systems only perl PGPLOT from Karl Glazebrook karl astro swin edu au Windows and Mac OS X systems only PDL Perl Data Language from http pdl perl org Windows and Mac OS X systems only NXSLib from Mirko Boin boin helmholtz berlin de The McStas project has been supported by the European Union through XENNI Cool Neutrons FP4 SCANS FP5 nmi3 MCNSI FP6 McStas was supported directly from the construction project for the ISIS second target station TS2 EU see Ts Currently McStas is supported through Danish in kind work packages to ward the European Spallation Source ESS see and the European Union through nmi3 E learning and nmi3 MCNSI7 FP7 see the home pages Men 10 1 Introduction to McStas Efficient design and optimization of neutron spectrometers are formidable challenges which are efficiently treated by Monte Carlo simulation techniques When McStas ver sion 1 0 was released in October 1998 except for the NISP MCLib program Nis no existing package offered a general framework for the neutron scattering community t
174. th McStas and have meaningful names with reference to the relevant TS Source gen now contains LLB and FRM II source parameters in the component help Monitor nD contains infrastructure for handling events in Mantid NeXus files 23 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 Isotropic_Sqw various fixes including optimized memory usage Lens component support for abstract geometries via the OFF PLY input format Guide_anyshape various improvements FermiChopper fixed bug in tangent intersection Elliptic_guide_gravity support for curvature via horizontal vectorial addition to gravity Instruments Various instruments have been included allowing to estimate pulsed source average and peak brilliance ISIS_SANS2d instrument contributed by R Heenan ISIS Test_Guide_Curved test instrument for simple curved guide types HZBFLEX contributed by Klaus Habicht and Markos Skoulatos HZB SEMSANS instrument instr by Morten Sales HZB Test_Scatter_log_losses instr see above notice about Scatter logging Test_Scatter_log mvalues instr see above notice about Scatter logging Test_Scatter_log_ssw_mcnp instr see above notice about Scatter logging FZJ_BenchmarkSfin2 instr by Heinrich Frielinghaus FZJ Test instrument for the SANS_benchmark2 comp templateNMX instr templateLaue variant demonstrating the Single crys
175. the following major parts e A short list of new features introduced in this McStas release appears in chapter 2 e Chapter 3 concerns Monte Carlo techniques and simulation strategies in general e Chapter 4 includes a brief introduction to the McStas system section 4 2 as well a section 4 3 on running the compiler to produce simulations Section 4 4 explains how to run the generated simulations Running McStas on parallel computers require special attention and is discussed in section A number of front end programs are used to run the simulations and to aid in the data collection and analysis of the results These user interfaces are described in section 4 5 e The McStas meta language is described in chapter 5 This chapter also describes a set of library functions and definitions that aid in the writing of simulations See appendix B for more details e The McStas component library contains a collection of well tested as well as user contributed beam components that can be used in simulations The Mc Stas component library is documented in a separate manual and on the McStas web page Mes but a short overview of these components is given in chapter 7 of the Manual As of this release of McStas support for simulating neutron polarization is strongly improved e g by allowing nested magnetic fields tabulated magnetic fields in numerical input files and by close to full support of polarization in all components As this
176. the simulation data as a single structure variable whereas the second one will additionally plot each detector separately This also equivalently stands for IDL idl s mcstas idl s mcstas plot See section for another way of plotting simulation results using the mcplot front end When choosing the HTML format the simulation results are saved as a web page whereas the monitor data files are saved as VRML files displayed within the web page 41 s seed seed seed Set the initial seed for the random number generator This may be useful for testing to make each run use the same ran dom number sequence n count ncount count Set the number of neutron histories to simulate The default is 1 000 000 1e6 d dir Create a new directory dir and put all data files in that di dir dir rectory h Show a short help message with the options accepted avail help able formats and the names of the parameters of the instru ment i Show extensive information on the simulation and the instru info ment definition it was generated from t Makes the simulation output the state of every neutron as it trace passes through every component Requires that the t or trace option is also given to the McStas compiler mcstas when the simulation is generated no output files Disables the writing of data files output to the terminal such as detector intensities will still be written
177. tion This latter setting is only an approximation and may produce wrong results with some components 69 Figure 5 1 conventions for the orientations of the axes in simulations An instrument consists of a list of components through which the neutron ray passes one after the other The order of components is thus significant since mcstas does not automatically check which component is the next to interact with the neutron ray at a given point in the simulation Note that in case of a negative propagation time from one component to the next the neutron ray is by default absorbed as this is often an indication of unphysical conditions The instrument is given a global absolute coordinate system In addition every component in the instrument has its own local coordinate system that can be given any desired position and orientation though the position and orientation must remain fixed for the duration of a single simulation By convention the z axis points in the direction of the beam the x axis is perpendicular to the beam in the horizontal plane pointing left as seen from the source and the y axis points upwards see figure 5 1 Nothing in the McStas metalanguage enforces this convention but if every component used different conventions the user would be faced with a severe headache It is therefore necessary that this convention is followed by users implementing new components In the instrument definitions units of length e
178. tion multiple times in an instrument description Beware about variable type conversion when setting numerical parameter values as in p1 12 1000 In this example the parameter p1 will be set to 0 as the division of the two integers is indeed 0 To avoid that use explicitly floating type numbers as in p1 12 0 1000 The compiler mcstas will automatically search for a file containing a definition of the component if it has not been declared previously The definition is searched for in a file called name comp See section 4 3 2 for details on which directories are searched This facility is often used to refer to existing component definitions in standard component libraries It is also possible to write component definitions in the main file before the instrument definitions or to explicitly read definitions from other files using include not within embedded C blocks The physical position of a component is specified using an AT modifier following the component declaration 1 AT x y z RELATIVE name This places the component at position x y z in the coordinate system of the previ ously declared component name Placement may also be absolute not relative to any component by writing 1 AT x y z RELATIVE ABSOLUTE Any C expression may be used for x y and z The AT modifier is required Rotation is achieved similarly by writing 1 ROTATED phi_x phi_y phi_z RELATIVE name This will result in a coordinat
179. tion read_table lib c 129 Table Read Offset C function read table lib c 125 Table Read Offset Binary C function read_table lib c Table Rebin C function read_table lib c 723 Table_Value C function read_table lib c 723 Table Value2d C function read_table lib c 129 TAS1 110 TERM signal Time of flight spectrometer PRISMA Tools external see IDL Matlab NeXus Perl PGPLOT VRML OpenGL McStas see medisplay mcdoc mc format mcgui mcplot mcresplot mcrun mcstas mcstas2vitess TRACE McStas keyword Triple axis spectrometer TASI 110 Tripoli Units constants and conversions USR1 signal USR2 signal 44 V2K constant 128 Variance Variance reduction vec_prod C function mccode r c version McDoc keyword Virtual sources Vitess vitess lib vitess lib library 60 VRML OpenGL VS2E constant Weight statistical uncertainty transformation WHEN McStas keyword Windows file and directory names with spaces Perl distribution written by McDoc keyword 96 137
180. tion of the individual components 3 Modeling the physical processes of neutron scattering i e the calculation of the fate of a neutron that passes through the individual components of the instrument absorption scattering at a particular angle etc 4 Accurate calculation using Monte Carlo techniques of instrument properties such as resolution function from the result of ray tracing of a large number of neutrons This includes estimating the accuracy of the calculation If you don t want to read this manual in full go directly to the brief introduction in chapter 4 2 Though obviously interrelated these four layers can be treated independently and this is reflected in the overall system architecture of McStas The user will in many situations be interested in knowing the details only in some of the layers For example one user may merely look at some results prepared by others without worrying about the details of the calculation Another user may simulate a new instrument without having to reinvent the code for simulating the individual components in the instrument A third user may write an intricate simulation of a complex component e g a detailed description of a rotating velocity selector and expect other users to easily benefit from his her work and so on McStas attempts to make it possible to work at any combination of layers in isolation by separating the layers as much as possible in the design of the system and in the
181. tive time propagation we no longer ABSORB these neutrons but rather restore the incoming neutron state leaving it untouched for the following components This avoids various types of shadowing effects e g when placing parallel monitors that are not in a GROUP This is furhter in preparation for the forthcoming ASSEMBLY keyword which will work roughly like an iterative group that loops on the ASSEMBLY of components until no furhter scattering is achieved but always scatters first on the component which is closest in time to the neutron Scatter logging With this release we provide this special ensemble of instrument examples Test_Scatter_log_losses instr Test_Scatter_log_mvalues instr Test_Scatter_log_ssw_mcnp instr that together with the misc cathegory components Scatter_log_iterator comp Scatter_log_iterator_stop comp Scatter logger comp Scatter_logger_stop comp provide a powerful post processing mechanism mainly for guide systems that for instance can be used to study the non propagated i e absorbed neutron flux along the guide For more information a paper by Esben Klinkby et al will be available in one of the next issues of Journal of Physics Conference Series proceedings of the NOP amp D 2013 meeting in Ismaning Slides from Esbens talk are available here http orbit dtu dk files 57025887 prod11375088187360 NO_P_v8 pdf As of this release
182. tributable binary of iF it exists iFit contains wrapper functionality for compiling and running McStas simulations as object functions and allows to select many different optimizers including swarms and other non gradient methods Please see the iFit documentation for more information Our experience is that iF it together with McStas is a more robust optimization solution than the McStas built in Simplex solution Using the Simplex method The McStas package comes with a Simplex optimization method to find best instrument parameters in order to maximize all or some specified monitor integrated values It uses the Downhill Simplex Method in Multidimensions which is a geometric optimization method somewhat similar to genetic algorithms It is not as fast as the gradient method but is much more robust It is well suited for problems with up to about 10 20 parameters to optimize Higher dimensionalities are not guarantied to converge to a meaningful solution When using mcrun section 4 5 2 the optimization mode is set by using the optim option or a list of monitors to maximize with as many optim COMP as required The optimization accuracy criterion may be changed with the optim prec accuracy op tion From mcgui section 4 5 1 one should choose the Optimization execution mode instead of the Simulation or Trace mode Then specify the instrument parameters to optimize by indicating their variation range param min max e g Lambda
183. tropic phonons sim ple General powder sample with a single scattering vector General powder sample with N scattering vectors using a data file Can assume concentric shape i e can be used to model sample enviroment Simple sample for Small Angle Neutron Scattering hard spheres Mosaic single crystal with multiple scattering vectors using a data file Vanadium sample or other incoherent scatterer quasielastic broadening Optional Res_sample TOF_Res_sample Res_monitor TOF_Res_monitor Sample like component for resolution function calculation Sample like component for resolution function calculation in TOF instruments Monitor for resolution function calculations Monitor for resolution function calculations for TOF instru ments Table 7 3 Sample components of the McStas library 104 MCSTAS monitors Description DivPos_monitor Divergence_monitor E_monitor L_monitor Monitor Monitor_nD PSD_monitor PSD_monitor_4PI PreMonitor_nD TOFLambda_monitor TOF_monitor Divergence position monitor acceptance diagram Horizontal vertical divergence monitor 2D Energy sensitive monitor Wavelength sensitive monitor Simple single detector monitor General monitor that can output 0 1 2D signals Intensity or signal vs something and vs something Position sensitive monitor Spherical position sensitive detector This component is a PreMonitor that is to be used w
184. uments TRACE The include insertion mechanism may be used within the TRACE section in order to concatenate instruments together This way each DECLARE INITIALIZE SAVE and FINALLY C blocks as well as instrument parameters from each part are concatenated The TRACE section is made of inserted COMPONENTS from each part In principle it is then possible to write an instrument as 1 DEFINE concatenated 2 TRACE 3 4 include partl instr 5 include part2 instr 6 7 END where each inserted instrument is a valid full instrument In order to avoid some com ponents to be duplicated e g Sources from each part a special syntax in the TRACE section 1 REMOVABLE COMPONENT a 78 O OMAJ 9O CI L VW IV Li marks the component a as removable when inserted In principle inserted instruments may themselves use 4include 5 4 2 Groups and component extensions GROUP EXTEND It is sometimes desirable to slightly modify an existing component of the McStas library One would usually make a copy of the component and extend the code of its TRACE section McStas provides an easy way to change the behavior of existing components in an instrument definition without duplicating files using the EXTEND modifier EXTEND zi C code executed after the component TRACE section 7 IV lL The embedded C code is appended to the component TRACE section and all its internal variables as well
185. unning simulations on the commandline mcrun 54 4 5 3 Graphical display of simulations mcdisplay 55 4 5 4 Plotting the results of a simulation meplot 57 4 5 5 Plotting resolution functions mcresplot 4 6 Data formats Analyzing and visualizing the simulation results 61 4 6 1 McStas and PGPLOT format s s 62 462 NeXus format 2 0 s s sss 62 4 7 Using computer Grids and Clusters ss sss 63 4 7 1 Distribute mcrun simulations on grids multi SSH grid ts x poe amp Enjo aualera HR ee 4 En ugo A ke rande 4 7 2 Parallel computing MPI ss es ee ae eo Oe voki 65 4 7 3 McRun script with MPI support mpich 67 4 7 4 McStas MPI Performance 67 4 7 5 MPI and Grid Bugs and limitations 68 5 The McStas kernel and meta language 69 5 1 Notational conventions 0 0000 ee soso soso 69 5 2 Syntactical conventions ss sss TO 5 3 Writing instrument de nitions sss 73 5 3 1 The instrument definition head 73 5 3 2 The DEPENDENCY line 2 a a a a 74 Oo date RMA ee he a ae Boe SR Aes 74 shies aval had E E E E ae a 75 pee heehee a esters eck eee ee ee 75 ig a li ad a keen plna GPS oo ee oe eee E 3 75 y M TTEEE ew es Ba ae oe 77 So Hr ee
186. ust this weight according to the path of the ray If e g the reflectivity of a certain optical component is 10 and only reflected neutrons ray are considered later in the simulations the neutron weight will be multiplied by 0 10 when passing this component but every neutron is allowed to reflect in the component In contrast the totally realistic simulation of the component would require in average ten incoming neutrons for each reflected one Let the initial neutron weight be po and let us denote the weight multiplication factor in the j th component by m The resulting weight factor for the neutron ray after passage of the n components in the instrument becomes the product of all contributions n p pn Po 75 3 2 j l Each adjustment factor should be 0 lt 7 lt 1 except in special circumstances so that total flux can only decrease through the simulation see section For convenience the value of p is updated within each component during the simulation Simulation by weight adjustment is performed whenever possible This includes e Transmission through filters and windows e Transmission through Soller blade collimators and velocity selectors in the ap proximation which does not take each blade into account e Reflection from monochromator and analyzer crystals with finite reflectivity and mosaicity e Reflection from guide walls e Passage of a continuous beam through a chopper e Scattering from all types o
187. ustrate some of the things that can be done in a simulation as opposed to a real life experiment this example instrument further discriminates between the scattering off each individual analyser crystal when the neutron hits the detector The analyser com ponent is modified so that a global variable neu_color registers which crystal scatters the neutron ray The detector component is then modified to construct seven different time of flight histograms one for each crystal see the source code for the instrument for details One way to think of this is that the analyser blades paint a color on each neutron which is then observed in the detector An illustration of the instrument is shown in figure 8 8 Test results are shown in Appendix 8 4 1 115 Moderator Monitor Slit Slit Sample Collimator Slit PSD 7 blade analyser Figure 8 8 A sketch of the PRISMA instrument 8 4 1 Simple spectra from the PRISMA instrument Detector A plot from the detector in the PRISMA simulation is shown in Figure 8 9 These results were obtained with each analyser blade rotated one degree relative to the previous one The separation of the spectra of the different analyser blades is caused by different energy of scattered neutrons and different flight path length from source to detector We have not performed any quantitative analysis of the data PRISMA with RITA backend 9 7 x 10 I n
188. w Laue pattern file as issued from Crystallographica For use with Single crystal PowderN and Isotropic Sqw Data h k 1 Mult d space 2Theta F squared Powder pattern file as obtained from Lazy ICSD For use with PowderN Isotropic_Sqw and possibly Single_crystal transmission file typically for monochromator crystals and filters Data k Angs 1 Transmission 0 1 re ectivity file typically for mirrors and monochromator crys tals Data k Angs 1 Reflectivity 0 1 S q w files for IsotropicSqw component Data q fw S 4 w Table 7 8 Data files of the McStas library MCSTAS examples Description instr This directory contains example instruments accessible throught the mcgui Neutron site menu Table 7 9 Instrument example files of the McStas library 107 8 Instrument examples In this section we present a few typical instruments We then give a longer description of three selected instruments We present the McStas versions of the Risg standard triple axis spectrometer TAS1 and the ISIS time of flight spectrometer PRISMA 8 4 But first we present an example of a component test instrument the instrument to test the component V_sample 8 2 These instrument files are included in the McStas distribution in the examples directory Most of the instrument examples there in may be executed automatically throught the McStas self test procedure The list of inst
189. y Can be channeled and or focusing Rectangular tapered guide parabolic elliptic sections Polarised 3He cell ISIS Target 1 and 2 moderator models based on MCNP cal culations Doubly bent monochromator with multiple slabs a multi pipe slit for SANS Realistic detector model with gas effects A banana PSD monitor SiC multilayer sample for reflectivity simulations SNS moderator models based on MCNP calculations An array of sources described from spectrum tables Reads a PTRAC neutron events file from MCNP Writes a PTRAC neutron events file for MCNP Reads a Batch neutron events file from Tripoli 4 Writes a Batch neutron events file for Tripoli 4 Table 7 6 Contributed components of the McStas library MCSTAS share Description adapt_tree lib mcstas r monitor nd lib read table lib vitess lib Handles a simulation optimisation space for adatative impor tance sampling Used by the Source adapt component Main Run time library always included Handles multiple monitor types Used by Monitor nD Res monitor Enables to read a data table text binary to be used within an instrument or a component Enables to read write Vitess event binary files Vitess_input and Vitess_output Used by Table 7 7 Shared libraries of the McStas library See Appendix B for details 106 MCSTAS data Description lau laz trm rfl SQ

User and programmers guide to the neutron ray-tracing

Contents

Download Pdf Manuals

Related Search

Related Contents