Home

User and programmers guide to the neutron ray-tracing

1. 43 5 4 2 Running simulations on the commandline merun 48 5 4 3 Graphical display of simulations mcdisplay 49 5 4 4 Plotting the results of a simulation mcplot 51 5 4 5 Plotting resolution functions mcresplot 52 5 4 6 Creating and viewing the library component instrument help and Mantials medoc ea esa Sopdet so SG Ee Ste eS eA 53 5 4 7 Translating McStas components for Vitess mcstas2vitess 54 5 4 8 Translating McStas results files between Matlab and Scilab formats 54 5 4 9 Translating and merging McStas results files all text formats 55 5 5 Analyzing and visualizing the simulation results 55 5 6 Using computer Grids and Clusters 2 e eee ee 57 5 6 1 Distribute mcrun scans ssh grid Unix only 58 5 6 2 Parallel computing MPI oh oe ee ee ea ee eS ES eg 59 5 6 3 McRun script with MPI support mpich 60 5 6 4 McStas MPI Performance 2 00 022s 60 5 6 5 McStas MPI Bugs and limitations 2 222 482 8 ane ee eae ee 3 61 5 6 6 Parallel computing multi threading 62 The McStas kernel and meta language 63 6 1 Notational conventions 2 e a eo oa ea e nokoa ee 64 6 2 Syntaxical conventions 2 ee ea a a aA Eea an A a a a A 65 6 3 Writing instrument definitions o aoo e e e 0 ee 67 6 3 1 The instrument definition head oaa 67 6 3 2 The DECLARE section o
2. 1 2 Scientific background a 2 penie an ee PAE ee ee ee ee G 1 2 1 The goals of McStas 0 0 0 0202000002 2a ee 1 3 The design of McStas 0 0 0 eee ee LAs OVervieW vrsi aiaa e Stat ey tets Ae do dod ae ae ea bt Ad at 2 New features in McStas 1 10 2 4 General ta 2 2 Gad tHe fells Bin Mee eR ek eh eR I as 2 2 Kernel sro awe ssid nos ho he Reo Oe AOA ee ao a aiT 2 3 Ran bimle s 3 lt 4 40 base A a aR a Gee NE ah a de od A 2 4 Components and Library 0 0000 eee ee ee 2 4 1 Newcomponents 0 2 00 0 eee ee ee eee 2 4 2 New example instruments 2 000000 0 2 5 Documentation e a 402 8 ab ddd sce ee wee ek oe eel a ed 2 65 Tools msta latios ac 3 Sira p a oe yee toe See Big ZOT NEW TOOS Haa ono fon ao be atch Bic Fh ech ang E oe ok de a Sos SEE ee eA 20 2 UnstallatiOnses 4 04 2 48 RBL Soe bok ee e a ee LS ed 2 7 Future extensions a e e a a a E a A a O a a E 3 Installing McStas 3 1 Getting MeSt s s os a 4 8 ep a a e ea a a e aa he ee See a ede Dicensiho os o a ns A eh BO eS a ie galley ooa 3 3 Installation on windows 2 0 2 2 3 4 Installation on Unix systems aoo ee 3 4 1 Configuration and installation 000 3 4 2 Specifying non standard options 020008 4 3 5 Finishing and Testing the McStas distribution 4 Monte Carlo Techniques and simulation strategy 4 1 Neutron spectrometer simulations o oo
3. A 10 For an unpolarized beam S 0 and all directions are equally probable 50 Note that in our approach we do not decide if the neutron is up or down after a given component but instead keep track of as much information for as long as possible In the following we will use P to denote the polarization vector The most important variables used are 106 Ris R 1416 rev ed EN K Scattering vector P Polarization before a component ingoing Pi Polarization perpendicular to scattering vector P1 amp x P x amp P Polarization after a component outgoing 7 Unit vector in direction of atomic spin B 1 for a ferromagnet Fy Unit cell nuclear structure factor Fy Unit cell magnetic structure factor The unit cell nuclear structure factor is defined as Fy K X exp ir d ba A 11 d where the d is the position of the d th atom within the unit cell and bg is the average of ba In the simple case of a single atom Bravais crystal one finds Fy K b The unit cell magnetic structure factor is useful when the atoms in the crystal only have spin orbital angular momentum and simple when the magnet is saturated all spins are parallel or anti parallel to one direction oq 1 It is then given as 1 A Fu K nro X exp ir d 5 9aF alt a oa A 12 d where ro He 2 818 x 10715m g 2 is the Land splitting factor and Fy K is the magnetic form factor which is the Fouri
4. COMPONENT name comp pi 1 p2 2 WHEN condition 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 pa rameters Usage examples could be to have specific monitors only sensitive to selected processes or to have components which are only present under given circonstances e g removable guide or radial collimator or to select a sample among a set of choices Riso R 1416 rev ed EN 75 In the following example an EXTEND block defines sets a condition when a scattering event is encoutered and the following monitor is then activated COMPONENT Sample V_sample AT EXTEND ht if SCATTERED flag 1 else flag 0 ht COMPONENT MyMon Monitor WHEN flag 1 AT eeh The WHEN keyword only applies to the TRACE section of instruments components Other sections INITIALIZE SAVE MCDISPLAY FINALLY are exectuted indepen dently of the condition As a side effetc 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 6 4 4 Component loops 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 me
5. e 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 e mcset_ncount n Sets the number of neutron histories to simulate to n e mcget_ncount Returns the number of neutron histories to simulate usually set by option n e mcget_run_num Returns the number of neutron histories that have been simu lated until now B 1 3 Coordinate transformations e coords_set x y z returns a Coord structure like POS_A CURRENT_COMP with x y and z members e coords_get P amp x amp y amp z copies the x y and z members of the Coord structure P into x y z variables Riso R 1416 rev ed EN 117 coords_add a b coords_sub a b coords_neg a enable to operate on coordi nates and return the resulting Coord structure rot_set_rotation Rotation t dz dy z Get transformation matrix for rotation first gz around x axis then around y and last around z t should be a Rotation 3 3 double matrix rot_mul Rotation t1 Rotation t2 Rotation t3 performs t3 1 t2 rot_copy Rotation dest Rotation src performs dest src for Rotation arrays t rot_transpose Rotation src Rotation dest performs dest src rot_apply Rotat
6. may be used for both input and output filename to represent standard input and standard output respectively Riso R 1416 rev ed EN 31 5 2 1 Code generation options By default the output files from the McStas compiler are in 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 5 4 3 The code generation options can also be controlled by using preprocessor macros in the C compiler without the need to re run the McStas compiler If the preprocessor macro MC_PORTABLE is defined the same result is obtained as with the portable option of the McStas compiler The effect of the trace option may be obtained by defining the MC_TRACE_ENABLED macro Most Unix like C compilers allow preprocessor macros to be defined using the D option eg cc DMC_TRACE_ENABLED DMC_PORTABLE Finally the verbose option will list the components and libraries beeing included in t
7. 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 I gt ni Np 4 3 where N is the number of rays hitting the detector and the vertical bar denote averaging By performing the weight transformations the statistical mean value of J is unchanged However N will in general be enhanced and this will improve the accuracy of the simu lation 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 o N VN Hence the statistical uncertainty of the observed intensity becomes o I VNp I VN 4 4 as is used in real neutron experiments where p 1 For a better approximation we return to Eq 4 3 Allowing variations in both N and p we calculate the variance of the resulting intensity assuming that the two variables are independent o I 0 N p N 0 p 4 5 Assuming as before that N follows a normal distribution we reach o N p Np Further assuming that the individual weights p follow a Gaussian distribution which in some cases is far from the truth we have N o p o X2 pi No p and reach o I
8. 88 6 7 McDoc the McStas library documentation tool 89 7 The component library Abstract 91 7 1 A short overview of the McStas component library 91 8 Instrument examples 97 8 1 A test instrument for the component Vsample 97 8 1 1 Scattering from the V sample test instrument 97 8 2 The triple axis spectrometer TAS 000 0000 008 97 8 2 1 Simulated and measured resolution of TAS 99 8 3 The time of flight spectrometer PRISMA 004 100 8 3 1 Simple spectra from the PRISMA instrument 103 A Polarization in McStas 105 AT TintrOduetiOnitcs 03 24 8 ah ee ie sh dc a ah Re hoe eB fae ol aT as 105 A 2 The Polarization Vector 2 2 aaa a 105 A 2 1 Example Magnetic fields ooa 020 200 048 107 A 3 Polarized Neutron Scattering 0 00000 e 108 A 3 1 Example Nuclear scattering 20200 109 A 3 2 Example Polarizing Monochromator and Guides 110 A 4 New McStas Components 0 0 0000 eee ee 112 Ava Polarizerse 2 ae dase Bee oa a a be amp ee ee i 112 A4 2 Detectors er oie soo ie Bh See bd a As ay BG Be 113 Riso R 1416 rev ed EN 5 A 4 3 Magnetic fields 0 0 0 0 02 eee ee ee 113 ACA A Samples o jae ek ee ee PS a tie es 114 A 5 Tests With New Components 000000 eee eee 114 Libraries and conversion constants 115 B 1 Run time calls and functions mcst
9. Meta language Output data multi format File Visualisation Matlab Compilation mcstas c compiler Visualisation Scilab N Visualisation Browser Visualisation IDL Executable binary Figure 5 1 An illustration of the structure of McStas vanadium_example instr file supplied in the examples directory of the McStas distri bution To start the graphical user interface of McStas run the command mcgui mcgui pl on Windows This will open a window with a number of menus see figure 5 2 To File Simulation Neutron site Help McDoc Instrument file lt N Undefined site Edit New Run Simulation results FZ_Juelich Read Piot Status Ok Brookhaven 6 atory 1997 2006 in 2003 2006 rights rese tests Plotters Scilat m Clustering meth Risoe PSI templateDIFF templateTAS vanadium_example Figure 5 2 The graphical user interface mcgui load an instrument select Tutorial from the Neutron site menu and open the file vanadium_example Next check that the current plotting backend setting select Choose backend from the Simulation menu corresponds to your system setup The default setting can be adjusted as explained in Chapter 3 e by editing the tools perl mcstas_config perl setup file of your installation 28 Risg R 1416 rev ed EN e by setting the MCSTAS_FORMAT environment variable Nex
10. Risoe National Laboratory Roskilde Denmark Institut Laue Langevin Grenoble France Component Slit 1 Written by Kim Lefmann and Henrik M Roennow Date June 16 1997 Version Revision 1 23 Origin Risoe Release McStas 1 6 Rectangular circular slit with optional insignificance cut D A simple rectangular or circular slit You may either specify the radius circular shape or the rectangular bounds No transmission around the slit is allowed If cutting option is used low weight neutron rays are ABSORBED Example Slit xmin 0 01 xmax 0 01 ymin 0 01 ymax 0 01 Slit radius 0 01 cut 1e 10 AP INPUT PARAMETERS radius Radius of slit in the z 0 plane centered at Origo m xmin Lower x bound m xmax Upper x bound m ymin Lower y bound m ymax Upper y bound m Optional parameters cut Lower limit for allowed weight 1 e e E e E HF E a HFK a HF a HF HF E a a KF a KF a HH F HF HF E a 0 AE FRE A OO IA RA RK Ra A a 2k 2K 3 2k 24 21 2k 24 2k 24 1 21 2 24 2k 2k 2k 2K 2k 2A 2k 2 2k 2 kkk kkk kk kk kk kk kk DEFINE COMPONENT Slit DEFINITION PARAMETERS SETTING PARAMETERS xmin 0 xmax 0 ymin 0 ymax 0 radius 0 cut 0 width 0 height 0 86 Riso R 1416 rev ed EN STATE PARAMETERS x y zZ vx vy vz t s1l s2 p INITIALIZE Ae if width gt 0 4 xmax width 2 xmin xmax if height gt 0 ymax height 2 ymin ymax if xmin 0 amp amp xma
11. 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 iy can be obtained as pliz n iy if p is a pointer to the first element Riso R 1416 rev ed EN 83 Three dimensional detectors monitors The results of a three dimensional detector monitor are written to a file using the following macro DETECTOR_OUT_3D t xlabel ylabel zlabel xvar yvar zvar Zmins max Ymin gt Ymax mins maxs M N J amp N O 0 0 amp p O O 0 amp p2 0 0 0 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 6 5 7 The FINALLY section FINALLY ht C code to execute at end of simulation ht 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 6 5 8 The MCDISPLAY section MCDISPLAY At C code to draw a sketch of the component ht This gives C code that draws a sketch of the component in the plots produced by the mcdisplay front end see section 5 4 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 seque
12. 5 4 3 Graphical display of simulations mcdisplay The front end mcdisplay mcdisplay pl on Windows is a graphical debugging tool 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 in the wrong position or to find out where neutrons are getting lost See figures 5 4 5 6 To use the mcdisplay front end with a simulation run it as follows mcdisplay sim args where sim is the name of either the instrument source sim instr or the simulation pro gram sim out generated with McStas and args are the normal command line argu ments for the simulation as explained above The h option will list valid options The drawing back end program may be selected among PGPLOT VRML Matlab and Scilab using either the pPLOTTER option or using the current MCSTAS_FORMAT environ ment variable For instance calling Riso R 1416 rev ed EN 49 mcdisplay pScilab vanadium_example out ROT 90 or csh tcsh syntax setenv MCSTAS_FORMAT Scilab mcdisplay vanadium_example out ROT 90 will output graphics using Scilab The mcdisplay front end can also be run from the mcgui front end Examples of plotter appearence for mcdisplay is shown in figures 5 4 5 6 McStas PGPLOT back end This will view the instrument from above A multi display that shows the instr
13. A 4 3 Magnetic fields Much inspiration for the components and the tests have been found in 48 e Pol_constBfield A rectangular box with a constant magnetic field in the y direction The x and z components of the spin precess with the Larmor frequency wz It is possible to define the field in terms of a wavelength so that the spin will precess 180 degrees for the given wavelength The component can be rotated to have the field along another axis e Pol_simpleBfield The first attempt at a component for handling general magnetic fields It is a concentric component where you define a start and stop component for each field but this allows other components e g monitors to be put inside the field The component overloads the propagation routines so that numerical spin propagation is done for analytical magnetic fields Riso R 1416 rev ed EN 113 NB At the moment both components does not really check the boundaries of the field on the sides but merely assumes that the field starts at the entrance plane and stops at the exit plane Also some optimization remains for the numerical component and it would be nice to support tabulated magnetic field files However the framework developed for Pol_simpleBfield is very general and should easily facilitate these changes A 4 4 Samples V_sample Modified the sample so that the scattered neutron has P 1 3P Note that this component does not handle multiple scattering so this app
14. EN 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 3 1 Moderator Sample Collimator Monitor Slit Slit Slit PSD Detector 7 blade analyser Figure 8 8 A sketch of the PRISMA instrument 8 3 1 Simple spectra from the PRISMA instrument 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 Riso R 1416 rev ed EN 103 x 10 PRISMA with RITA backend Intensity A T 1 3600 6000 6500 7000 7500 time usec Figure 8 9 Test result from PRISMA instrument using colored neutrons Each graph shows the neutrons scattered from one analyser blade 104 Riso R 1416 rev ed EN Appendix A Polarization in McStas P Christiansen Ris December 8 2006 A 1 Introduction In the current release of McStas there are components with polarization capabilities At the moment all such components should be understood as un
15. ISIS plus inspiration from the VitESS and NISP packages As this is the first release with polarisation support the methods and algorithms implemented will certainly bed developed further Hence documentation of the functionality has been placed in Appendix A to this manual Polarisation users Please give us feedback for further development Items marked by p below relate to the new polarisation support New keywords for the meta language improves support for e g description of sample enviroments A method for automatic optimisation has been implemented e g for achieving max imum flux at the sample position any quantity measured by a McStas monitor can be optimised as a function of simulation parameters e Bugfixes in many different areas 2 2 Kernel The following changes concern the Kernel i e the McStas meta language and program See the dedicated chapter in the User manual for more details 14 Riso R 1416 rev ed EN 2 3 2 4 New WHEN keyword conditional use of components COMPONENT MyComp Component WHEN condition AT New JUMP keyword possibility to iterate a given component a number of times multiple scattering or for teleportation to a given component USE WITH CAU TION Improved COPY keyword with parameter substitution Make a copy of an other com ponent instance with a few parameters changed Spin propagation algorithm When magnetic field is set on the central propagation
16. Output from mcdisplay with Matlab backend Display can be adjusted using the window buttons e The versions 1 10 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 version 1 10 x are also listed on the web and new versions may be released quite frequently when it is requested by the user community e The version 1 11 will contain important new features and an updated manual It will be released in 2007 5 2 Running the instrument compiler This section describes how to run the McStas compiler manually Often it will be more convenient to use the front end program mcgui section 5 4 1 or mcrun section 5 4 2 These front ends will compile and run the simulations automatically The compiler for the McStas instrument definition is invoked by typing a command of the form mcstas name instr This will read the instrument definition name instr which is written in the McStas meta language The compiler will translate the instrument definition into a Monte Carlo simu lation program provided in ISO 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 mcstas o code c name instr which gives the output in the file code c A single dash
17. 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 4n PSD monitor with 50 x 100 pixels and a radius of 10 m The set up is shown in figure 8 1 8 1 1 Scattering from the V sample test instrument In figure 8 2 we present the radial distribution of the scatting from an evenly illuminated 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 2 The triple axis spectrometer TAS1 With this instrument definition we have tried to create a very detailed model of the conventional cold source triple axis spectrometer TAS1 at the now closed neutron source DR3 of Riso National Laboratory Except for the cold source itself all components used Riso R 1416 rev ed EN 97 Collimator Source 4r PSD Figure 8 1 A sketch of the test instrument for the component V_sample 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 98 Riso R 1416 rev ed EN have quite realistic properties Furthermore the overall geometry of the instrument has been adapted from the detailed technical drawings of the real spectrometer The
18. and Fy Fu K R so that Fy amp gt 0 and Fy k gt Fu rk We then find Pa va A 33 Fulk va ves A 34 When Fiy amp and Fy7 amp are determined from these equations Eq A 28 and Eq A 29 can easily be used to handle any situation This solution is both used for monochromators and guides It is not clear that this solution is correct If we make a simple example with R 1 and R 0 25 then we could in principle have four solutions but let us just quote the two where Fy amp is positive since the last two are found by inserting a minus before all the solutions and this does not change the physics The two solutions are Fy K 0 75 Fu K 0 25 and Fmy k 0 75 Fy K 0 25 All solutions gives the same cross section but if the Riso R 1416 rev ed EN 111 incoming beam is polarized and only then the outgoing beam will have two different polarization values since P F y Fyy and 72 7 P Fy K are different for the two solutions It seems that one needs some additional information to choose between the two solutions NB The simplifying geometry shown in Figure A 1 only applies for the sides of the guide wall and not the top and bottom assuming that the magnetizing field is pointing up or down so there another set of equations should really be used The same physics could also be used for a polarizing powder or single crystal sample if F y amp and Fyy can be calc
19. display informations for all blocks also retu y Table_Index Table 0 2 5 read in 1st block the 3rd row 6th column elem 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 Vir tual_input for other implementation examples B 3 Monitor_nD Library This library gathers a few functions 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 Adaptative importance sampling Library This library is currently only used by the components Source_adapt and Adapt_check It performs adaptative importance sampling of neutrons for simulation efficiency optimiza 122 Riso R 1416 rev ed EN 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 Name Value Conversion from Conversion
20. it contains full documentation of all aspects of the program It covers the various ways to compile and run simulations a descrip tion of the meta language used to define simulations and some example simulations performed with the program This report documents McStas version 1 10 released December 2006 The authors are Peter Kj r Willendrup lt peter willendrup risoe dk gt Materials Research Department Ris National Laboratory Roskilde Denmark Emmanuel Farhi lt farhi ill fr gt Institut Laue Langevin Grenoble France Kim Lefmann lt kim lefmann risoe dk gt Materials Research Department Ris National Laboratory Roskilde Denmark as well as authors who left the project Peter Christiansen lt pchristi hep lu se gt Materials Research Department Ris National Laboratory Roskilde Denmark Present address University of Lund Lund Sweden Klaus Lieutenant lt Klaus Lieutenant ife no gt Institut Laue Langevin Grenoble France Present address Institute for Energy Technology Kjeller Norway Kristian Nielsen lt kristian nielsen mail tele dk gt Materials Research Department Ris National Laboratory Roskilde Denmark Presently associated with MySQL AB Sweden ISBN 87 550 3481 0 Internet ISSN 0106 2840 Pitney Bowes Management Services Denmark A S Riso National Laboratory 2006 Contents Preface and acknowledgements 1 Introduction to McStas 1 1 Development of Monte Carlo neutron simulation
21. mcstas simulation You may evaluate directly the signal and statistics fields of the structure to obtain useful informations HTML VRML XML NeXus and NeXus formats Both HTML and XML NeXus formats are available The former may be viewed using any web browser Netscape Internet Explorer Nautilus showing data sets as VRML objects while the latter may be browsed for instance using Internet Explorer Windows and Mac OS or GXMLViewer and KXMLEditor under Linux The support for NeXus in McStas is prelimminary as NeXus is not fully laid out A future version of McStas will fully support output in the final NeXus format 45 5 6 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 Riso R 1416 rev ed EN 57 simulated without interfering with other simulated neutron rays Therefore each neutron ray can be simulated independently on a set of computers McStas provides three methods in order to distribute computations on many computers e when scanning instrument parameters using mcrun multi N it is possible to distribute each scan step on a list of computers e when using an homogeneous computer cluster each simulation including scan steps may be computed in parallel using MPI using mcrun mpi Nb Nodes We highly recommand this method which shows excelle
22. options Random seed Set seed to selects between using a random seed different in each sim ulation for the random number generator or using a fixed seed to reproduce results for debugging Simulate Trace 3D Optimize selects between several modes of running the simula tion 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 indivitual neutrons through the instrument e Optimize find the optimum value of the simulation parameters in the given ranges see section 5 3 5 steps optim sets the number of simulation to run when performing a parameter scan or the number of iterations to perform in optimization mode Inspect component Trace mode will trace only neutron trajectories that reach a given component e g sample or detector First component Trace mode seletcs the first component to plot default is first in order to define a region of interest Last component Trace mode seletcs the last component to plot default is first in order to define a region of interest Start runs the simulation Cancel aborts the dialog 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 per
23. the use of existing equipment design new instrumentation and carry out virtual exper iments 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 in strument descriptions into efficient ANSI 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 manual for the McStas components it contains full documentation of all aspects of the program 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 Descriptors Neutron Instrumentation Monte Carlo Simulation Software Available on request from Information Service Department Ris National Laboratory Afdelingen for Informationsservice Forskningscenter Ris P O Box 49 DK 4000 Roskilde Denmark Phone 45 4677 4004 Telefax 45 4677 4013 Risg s research is aimed at solving concrete problems in the society Research targets are set through continuous dialogue with business the political system and researchers The effects of our research are sustainable energy supply and new technology for the health sector www risoe dk
24. 31 monochro mators 32 35 and detectors 36 38 In the case of selected neutron instrument parts one may use efficiently the so called acceptance diagram theory 14 26 39 within which the neutron beam distributions are considered to be homogeneous or gaussian However the concatenation of a high number of neutron optical elements which indeed constitute real instruments brings additional complexity by introducing strong correlations between neutron beam parameters divergence and position which is the basis of the acceptance diagram method but also wavelength and time The usual analytical methods phase space theory then reach their limit of validity in the description of the resulting fine effects In principle computing individual neutron event propagation at each instrument part using analytical and numerical models is not such a hard task The use of probablilities is common to describe microscopic physical processes Integrating all these events over the propagation path will result in an estimation of measurable quantities characterizing the neutron instrument Moreover using variance reduction e g importance sampling whenever possible will both speed up the computation and achieve a better accuracy What we just sketched is nothing else than the basis of the Monte Carlo MC method 22 Riso R 1416 rev ed EN 40 applied to neutron ray tracing instrumentation 4 1 1 Monte Carlo ray tracing simulations Math
25. 7 of the Manual A collection of example instrument definitions is described in chapter 8 of the Man ual As of this release of McStas some support for simulating neutron polarisation is included As this is the very first release with these features functionality is likely to change To reflect this the documentation is currently only available in appendix A A list of library calls that may be used in component definitions appears in appendix B and an explanation of the McStas terminology can be found in appendix C of the Manual Plans for future extensions are presented on the McStas web page 2 as well as in section 2 7 Riso R 1416 rev ed EN 13 Chapter 2 New features in McStas 1 10 This version of McStas implements both new features as well as many bug corrections especially for the Windows platform Bugs are reported and traced using the McStas Bugzilla system 3 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 garranty that the software is bullet proof but we do our best to correct bugs when they are reported 2 1 General e This release is a major step forward for McStas in terms of support for polarisation Peter Christiansen who worked at Riso March October 2006 was the main workforce behind this new functionality backed by funding from ISIS work by Rob Dalgliesh at
26. As a side effect refering this component instance for e g further positioning is not straight forward as the name is determined by McStas and does not depend completely on the user s choice eventhough the PREVIOUS keyword may still be used We thus recommand to use this naming mechanism only for components which should not be refered to in the instrument This automatic naming may be used anywhere in the TRACE section of the instrument so that all components which do not need further refering 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 CG_1 Guide_gravity 1l 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 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 COMPONENT CG_Out Arm AT 0 0 L n RELATIVE PREVIOUS 6 4 3 Conditional components One of the most usefull features of the extended McStas syntax is the conditional WHEN modifier This optional keyword comes before the AT ROTATED positioning It basically enables the component only when a given condition is true non null
27. INDEX CURRENT COMP is the number index of the current component starting from 1 e POS_A_COMP_ INDEX index is the absolute position of component index 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 1 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 POS_A_COMP_INDEX indez i where i is x y or z e POS_R_COMP_INDEX works the same as above but with relative coordinates e STORE NEUTRON index Y Z vx vy vz t S sy SZ p stores the current neu tron state in the trace history table in local coordinate system index is usually IN DEX_CURRENT_COMP This is automatically done when entering each component of an instrument e RESTORE NEUTRON indez y Z V VY VZ t S 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 UT vy UZ t S 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 e 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
28. Instrument parameters allows the setting of the values for the input parameters of the instrument The type of each instrument parameter is given in parenthesis 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 scans enter the minimum and maximum values to scan separated by a comma e g 1 10 and do not forget to set the Scanpoints to more than 1 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 Force Forces to overwrite existing data files Neutron count sets the number of neutron rays to simulate the ncount option Riso R 1416 rev ed EN 45 Gravity Activates gravitation handling Be aware that not all components support the use of gravitation Distribute mcrun scans grid activates the distribution of the scan steps over a com puter grid using an ssh mechanism See section 5 6 on parallel computing for more informations about how to define and access the grid This options is only visible if MPI ssh is available Plot results if checked the mcplot front end will be run after the simulation has finished and the plot dialog will appear see below Format The data file format can be changed the same way as in the Simulation Configuration
29. R 1416 rev ed EN 69 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 outside 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 recommand as well the usage of the WHEN and EXTEND keywords as well as other syntax extensions presented in section 6 4 below 6 3 5 The SAVE section SAVE ht C code to execute each time a temporary save is required ht 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 This section is optional 6 3 6 The FINALLY section FINALLY ht C code to execute at end of simulation ht This gives code that will be executed when the simulatio
30. Removed neutron events 67 78 113 Signal handler 33 INT signal 67 TERM signal 67 USR2 signal 67 Simulation optimization 30 Testing the distribution 15 Tools 13 24 HTML 32 IDL 33 52 53 Matlab 26 32 33 46 48 49 51 53 130 meconvert 51 mcdisplay 46 mcdoc 50 86 88 mcformat 52 55 mcgui 25 28 40 47 48 mcplot 26 33 40 42 46 48 52 mcresplot 49 mcrun 28 45 mestas2vitess 51 120 Octave 52 Perl libraries 44 47 49 PGPLOT 26 32 44 46 49 52 Scilab 26 32 33 46 48 49 51 53 VRML OpenGL 32 46 VRML openGL 33 52 Tripoli 32 Vitess 32 51 Riso R 1416 rev ed EN Riso R 1416 rev ed EN 131 Bibliographic Data Sheet Risg R 1416 rev ed EN Title and author s User and Programmers Guide to the Neutron Ray Tracing Package McStas Version 1 10 Peter Willendrup Emmanuel Farhi Klaus Lieutenant Kim Lefmann and Peter Chris tiansen ISBN ISSN ISBN 87 550 3561 2 Internet 0106 2840 Dept or group Date Materials Research Department December 2006 Groups own reg number s Project contract No Pages Tables Illustrations References 132 12 27 49 Abstract Max 2000 char The software package McStas is a tool for carrying out Monte Carlo ray tracing simulations 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
31. See http mensi risoe dk See http neutron eu net en See http ts 2 isis rl ac uk See http strider lansce lanl gov NISP Welcome html P A Seeger L L Daemen T G Thelliez and R P Hjelm Physica B 283 433 2000 J Saroun and J Kulda Physica B 234 1102 1997 See website http omega ujf cas cz restrax P Willendrup E Farhi and K Lefmann Physica B 350 735 2004 D Wechsler G Zsigmond F Streffer and F Mezei Neutron News 25 11 2000 See http www hmi de projects ess vitess W T Lee and X L Wang Neutron News 13 30 2002 See website http www sns gov ideas J R D Copley J Neut Research 1 21 1993 E Farhi T Hansen A Wildes R Ghosh and K Lefmann Appl Phys A 74 S1471 2002 C Schanzer P Boni U Filges and T Hils Nucl Instr Meth A 529 63 2004 G Zsigmond K Lieutenant and S Manoshin et al Nucl Instr Meth A 529 218 2004 K Lieutenant J Phys Condens Matter 17 S167 2005 T E Mason K N Clausen G Aeppli D F McMorrow and J K Kjems Can J Phys 73 697 702 1995 Riso R 1416 rev ed EN 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 K N Clausen D F McMorrow K Lefmann G Aeppli T E Mason A Schr der M Issikii M Nohara and H Takagi Physica B 241 243 50 55 1998 K Lefmann D F McMorrow H M R nnow K Ni
32. 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 see section 5 3 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 5 3 and section 5 3 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 mon itor detector components should use standard macros for writing data in the SAVE or FINALLY section as explained below In the following we use N p to denote the count of detected neutron events p gt gt p to denote the sum of the weights of detected neutrons and p2 p to denote the sum of the squares of the weights as explained in section 4 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 and the number of statistical events N This will result in a line such as Detector CompNamel p CompName_ERR o CompName_N N 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 n axis value as the sum of events falling into the n n 1 range i e the bins are
33. 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 ge ometry propagation of neutrons between the different components parameters data in put output etc is handled in the meta language and by the McStas compiler Complex calculations are written in C embedded in the meta language description of the compo nents 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 available 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 informations from to data files e Convenient conversion factors between relevant units etc The McStas meta language was designed to be readable
34. 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 Source like component that reads neutron events from an ascii binary virtual source file recorded by Virtual_output Detector like component that writes neutron state for use in Virtual_input Read neutron state parameters from a VITESS neutron file Write neutron state parameters to a VITESS neutron file Table 7 5 94 Miscellaneous components of the McStas library Riso R 1416 rev ed EN MCSTAS contrib Description Al_window Collimator_ROC Filter_graphite Filter_powder Guide_curved Guide_honeycomb Guide_tapering He3_cell ISIS_moderator Monochromator_2foc PSD_monitor_rad SiC SNS_source Virtual _tripoli4_input Virtual_tripoli4_output Aluminium transmission window Radial Oscillating Collimator ROC 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 geometry 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 calcu lations Doubly bent monochromator with multiple slabs A banana PSD monitor SiC mult
35. h and radius r centered at the origin e sphere_intersect amp t amp t2 x Y Z Vz Vy Uz r Similar to box_intersect but using a sphere of radius r B 1 7 Random numbers e rand01 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 1 The algorithm used to sample the normal distribution is explained in Ref 50 ch 7 e randpm1 Returns a random number distributed uniformly between 1 and 1 e randvec_target_circle amp v amp vy amp vz amp dQ aim aimy aim rf Generates a random vector Vz Vy Vz of the same length as aim aim aim which is targeted at a disk centered at aimz aim aim with radius r 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 position of the neutron is returned in dQ This routine was previously called randvec_target_sphere which still works Riso R 1416 rev ed EN 119 e randvec_target_rect_angular amp v amp vy amp vz amp dQ aim aim aim h w Rot does the same as randvec_target_circle but targetting at a rectangle with angu lar dimensions h and w in radians not in degrees as other angles The rota tion matrix Rot is the coordinate system orientation in the absolute frame usually ROT_A_CURRENT_COMP e randvec_target_
36. index displays the component documentation using the compo nent index html index file 44 Ris R 1416 rev ed EN McStas web page calls mcdoc web brings up the McStas website in a web browser Tutorial opens the McStas tutorial for a quick start Current instrument info generates a description web page of the current edited instru ment Test McStas installtion 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 Generate component index re generates locally the component index html The run dialog Run simulation Wie testinstr x Instrument source h6_test instr HTML docs Instrument parameters D floating point I integer S string Lambda D 2 36 Output to dir J force Browse Neutron count 1000000 _ gravity BEWARE Random seed joo Simulate steps 0 _ Plot results Format PGPLOT Clustering None single CPU Number of nodes 2 start Cancel Figure 5 8 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 5 3 for details It also allows to run the mcdisplay section 5 4 3 and mcplot section 5 4 4 front ends together with the simulation The meaning of the different fields is as follows
37. input parameter for a component For example the radius of a sample component or the divergence of a collimator Input parameter For a component either a definition parameter or a setting parameter These parameters are supplied by the user to define the characteristics of the particular instance of the component definition For an instrument a parameter that can be changed at simulation run time Instrument An assembly of McStas components defining a neutron spectrometer Kernel The McStas language definition and the associated compiler McStas Monte Carlo Simulation of Triple Axis Spectrometers the name of this package Pronounciation ranges from mez tas to mac stas and m c stas 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 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 Riso R 1416 rev ed EN e Setting parameter Similar to a definition parameter but with the restriction that the value of the parameter must be a number Riso R 1416 rev ed EN 125 Bibliography 10 11 12 13 14 15 16 17 18 19 126 K Lefmann and K Nielsen Neutron News 10 20 23 1999 See http www mcstas org See http neutron risoe dk McZilla
38. inserting in the built in editor e Possibility to not optimize when compiling the generated c code e Adjustment of final precision when doing parameter optimization m Mcstas Configuration options 7x Plotting options PGPLOT original McStas Use binary files faster J 3 pane view with PGPLOT trace Clustering None single CPU Editor options Advanced built in editor W Surround strings with quotes Compilation options Optimize g 02 Optimization options Precision Figure 5 7 The configuration options dialog in mcgui 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 transfered to the active directory so that users have modification rights and loaded One may then view its source Edit and use it directly for simulations trace 3D View 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 on Unix and the default browser on Windows McStas User manual calls mcdoc manual brings up the local pdf version of this manual using a web browser McStas Component manual calls mcdoc comp brings up the local pdf version of the component manual using a web browser Component library
39. 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 6 1 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 5 2 2 It is also possible to explicitly include another file using a line of the form include file 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 the McStas compiler 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 the McStas compiler into the generated simulation C program Embedded C code is written by putting it between the special symbols and as follows
40. 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 DETECTOR_OUT_OD t N p p2 Here t is a string giving a short descriptive title for the results e g Single monitor One dimensional detectors monitors The results of a one dimensional detector monitor are written using the following macro DETECTOR_OUT_1D t xlabel ylabel xvar min Tmax M amp N 0 amp pl0 amp p2 0 filename Here e is a string giving a descriptive title e g Energy monitor e zlabel is a string giving a descriptive label for the X axis in a plot e g Energy meV e ylabel is a string giving a descriptive label for the Y axis of a plot e g Intensity e rvar 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 82 Riso R 1416 rev ed EN Zmax is the upper limit for the X axis 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 amp p 0 is a pointer to the first element in the array of p values for the detector component amp p
41. own Everything else in the identification section is part of a short description of the component Riso R 1416 rev ed EN 89 90 In the 4PARAMETERS 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 parenthesis are also supported for backwards compatibility but nested parenthesis do not work well The DESCRIPTION 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 gt for links to other web pages but see also the LINK section In the generated web documentation pages the text is set in lt PRE gt lt PRE gt so that the line breaks in the source will be obeyed Any number of LINK 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 gt lt A gt pointer to some other source of information Optionally an Z INSTRUMENT_SITE section followed by a single word is used to sort instruments by origin location in the Neutron Site menu in mcgui After ZEND no more comment text is read by McDoc Riso R 1416 rev ed EN Chapter 7 The component library Abstract This chapter presents an abstract of existing components As
42. parameters to avoid name conflicts ht Riso R 1416 rev ed EN 79 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 OUTPUT PARAMETERS counts DECLARE nt int counts ht 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 di Detector COMPONENT d2 Detector FINALLY nt printf Detector counts di d d2 d n MC_GETPAR d1 counts MC_GETPAR d2 counts ht This way McStas takes care to rename transparently the two counts OUTPUT parameters so that they are distinct and can be accessed from elsewhere in the instrument EXTEND FINALLY SAVE or from other components This particular example is outdated since McStas monitors will themselves output their co
43. rev ed EN da dQ P do dQ Fy 1 2Fy K Ful K P Fri r A 28 P Fiy K Fu K 2Fiv 02 Fr r 2H P Fu A 29 NB Note that in 47 Eq 2 2 25 there is a minus in front of the second term in Eq A 28 We have not been able to understand this discrepancy which is probably due to notation Most other authors agree with the minus in front of the second term e g Squires and Francis Tasset For a beam which is initially unpolarized we find the outgoing polarization to be e n2F Ny K Fy K 2F ny Kh Fy kK T dojn Fle Ful P A 30 so that the beam is fully polarized along 7 if Fy K Fiy K What we use to characterize the polarizing monochromator in practice is not Fy and Fyy but instead the reflection probabilities R and R for the reflection of interest If we assume that the reflection probabilities are directly proportional to the cross sections with proportionality constant k i e Ry kdo dOQ P 7 and R kdo dQ P 7 then we can use Eq A 28 to determine F y K and Fuy k Ry k Fy Fru k A 31 R k Fw Fu A 32 The values of VkFy and VkFy are then between 1 and 1 and unit less like the reflection probabilities In the following we ignore k and just talk about Fy K and Fm K In principle there are four solutions for Fy K and Fy r so in the code we currently choose the values where Fy K Fu K R
44. routines also handle Larmor precession in the field p Handeling of analytical B fields p Run time Optmisation support in mcrun mcgui using Perl Amoeba se description above POSIX threading on multi core processors BEWARE performance is generally better using MPI Components and Library We here list some of the new components found in the McStas lib directory which are detailed in the Component manual also mentioned in the Component Overview of the User Manual 2 4 1 New components Monochromator_pol comp Polarising monochromator analyzer p Pol_bender comp Polarising bender p Pol_mirror comp Polarising mirror p Pol_guide_vmirror comp Guide with semi transparent polarising mirror p Pol_simpleBfield comp Numerical precession in analytical B fields p 3 Polarisation monitors MeanPolLambda_monitor comp PolLambda_monitor comp Pol_monitor comp p PSD_Detector comp Physical detector comes with many gas lookup tables Con trib Thorwald van Vuure ILL Virtual mcnp_ comp MCNP event file handeling Contrib Chama Hennane EN SIMAG and Emmanuel Farhi ILL Source_multi_surfaces comp Source comp with multiple surface areas with individ ual spectrums Contrib Ludovic Giller EPFL and Uwe Filges PSI Riso R 1416 rev ed EN 15 e multi_pipe comp Defines a grid of slits focusing device Contrib Uwe Filges PSI e Exact_radial_coll comp Radial collimator comp exact model
45. spin up 7 or spin down and the polarization can be expressed as pas A 3 ny ny where n n is the number of neutrons with spin up down For a given neutron the probability of the neutron being spin up P T is 2 14 P P t _ mt m n 2_ 1 A 4 nytt ny Nr n 2 and P 1 P t 1 P 2 The expectation value of the spin operator 6 which can be expressed by the Pauli matrices is the polarization vector P P x a x The most general form of the spin wave function x for a neutron spin 1 2 is X axy bx A 5 where x and x are eigenfunction of and the complex coefficients a and b satisfy la b 1 By calculation we find P xlGelx 2Re a b A 6 P x ylx 2Im a b A 7 P xl elx lal OP A 8 This shows the relation of the polarization vector to the neutron wave function The neutron magnetic moment operator can be expressed in terms of as fin Un A 9 which as shown above is related to the polarization vector In our simulation we represent the polarization by the vector S sz Sy Sz which is propagated through the different components so it has the correct relative orientation in each component The probability for the spin to be parallel a given direction n is then 1 S P t In E This equation from 48 is easy to understand The average spin along n is n S and the probability then follows from Eq A 4
46. the command help as usual Riso R 1416 rev ed EN 53 See section 6 7 for more details about the McDoc usage and header format To use the mcdoc front end the program Perl should be available 5 4 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 transferred 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 McStas_compo For both steps McStas is used as for any other instrument McStas_compo has to be moved to the directory gt MODULES that contains all VITESS executables Additionally a file McStas_compo tcl is created that contains 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
47. the incoherent scattering due to the random isotope distribution 3 The nuclear incoherent scattering due to the random nuclear spin orientations has polarization P 1 3P for a random nuclear spin the associated Pauli matrix will 2 3 of the time point in the direction of 6 and y which according to Eq A 17 flips the spin For Vanadium where there is only one isotope and coherent scattering is negligible we find P 1 3P There is however one catch If the probability for multiple scattering is large one has to take into account that after two scattering one has P 2 1 9P and so forth The average polarization after a thick vanadium target is therefore a sum of different contributions A 3 2 Example Polarizing Monochromator and Guides Figure A 1 Principle and geometry of a polarizing monochromator In a polarized monochromator and polarizing guides we have a ferromagnetic crystal in an external magnetic field The scattering potential is now both nuclear no internal direction and magnetic internal direction so in general the outgoing polarization can be quite complex However as illustrated in Figure A 1 the typical setup has many geometrical constraints N R 0 N P 7 P and amp x 7 x K 7 which simplifies the problem In the calculation for a centrosymmetric ferromagnetic crystal is done and inserting the constraints above one finds 49 Eq 10 96 and Eq 10 110 110 Riso R 1416
48. 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 5 4 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 Matlab Scilab and IDL formats With these formats McStas automatically writes scripts containing the data as a structure as well as in line import and plot functions for the selected language Usage examples are given in section 5 3 Thus it is not necessary to write a load routine for each format as the script is itself a program that knows how to handle the data Alternatively using mcplot with Matlab and Scilab plotters provide additional functionalities from menus and dialogs see section 5 4 4 When imported through the data generated script see section 5 3 or using mcplot see section 5 4 4 a single variable may be created into the Matlab Scilab or IDL base workspace This variable is a structure constituting a data tree containing many fields some being themselves structures Field names are the initial names from the instrument com
49. using your BROWSER setting or as text if unset The help option will display the command help as usual Riso R 1416 rev ed EN 91 MCSTAS sources Description Adapt_check ESS_moderator_long ESS_moderator_short Moderator Monitor_Optimizer Source_Maxwell 3 Source_Optimizer Source_adapt Source_div Source_simple Source_gen Optimization specifier for the Source_adapt component 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 sampling Continuous neutron source with a specified Gaussian diver gence A simple continuous circular neutron source with flat en ergy wavelength spectrum General continuous neutron source with tunable shape spec trum and divergence Table 7 1 Source and source related components of the McStas library 92 Riso R 1416 rev ed EN MCSTAS optics Description Arm Beamstop Bender Chopper Collimator_linear Collimator_radial FermiChopper Filter_gen Guide Guide_channeled Guide_gravity Guide_wavy Mirror Monochromator_curve Monochromator_
50. 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 Riso R 1416 rev ed EN 63 Z gt Figure 6 1 conventions for the orientations of the axis in simulations 6 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 differ ent components The effect of gravity is taken into account either in particular components e g Guide_gravity or more generaly when setting an execution flag g to perform gravitation computation This latter setting is only an approximation and may produce wrong results with some components 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 compo nent in the instrumen
51. 2 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 monitor are written to a file using the following macro Here DETECTOR_OUT_2D t xlabel ylabel min max Ymin Ymax M N amp N 0 0 amp pl0 0 amp p2 0 0 filename t is a string giving a descriptive title e g PSD monitor label is a string giving a descriptive label for the X axis in a plot e g X position cm ylabel is a string giving a descriptive label for the Y axis of a plot e g Y position cm ZLmin is the lower limit for the X axis Zmax is the upper limit for the X axis Ymin is the lower limit for the Y axis Ymax is the upper limit for the Y axis m is the number of elements in the detector arrays along the X axis n is the number of elements in the detector arrays along the Y axis amp N 0 0 is a pointer to the first element in the array of N values for the detector component amp p 0 0 is a pointer to the first element in the array of p values for the detector component 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
52. 28e 05 0 02656624 0 0016259803 2 6180041 0 00071623812 0 0016259603 18 933766 Figure 5 10 Output from mcresplot with PGPLOT backend Use P C and G keys to write hadrcopy files 5 4 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 l The first example generates an index html catalog file using the available components and instruments both locally and in the McStas library When called with the show or s option the library catalog of components is opened using the BROWSER environment variable e g netscape konqueror nautilus MSIE mozilla Alternatively if a component or instrument comp is specified it will be searched within the library and an HTML help will be created for all available components matching comp When using the s the help will be opened 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 The last example will list the name and action of all McStas tools same as tools option 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 BROWSER to be defined Finally the help option will display
53. 6 rev ed EN 127 43 44 45 46 47 48 49 50 128 J A Nelder and R Mead Computer Journal 7 308 313 1965 W H Press S A Teukolsky W T Vetterling and B P Flannery Numerical Recipes 2nd Edition Cambridge University Press 2002 See http www neutron anl gov nexus A Abrahamsen N B Christensen and E Lauridsen McStas simulations of the TAS1 spectrometer Student s report Niels Bohr Institute University of Copenhagen 1998 W Gavin Williams Polarized Neutrons Oxford Clarendon Press 1988 P A Seeger and L L Daemen Nucl Instr Meth 457 338 2001 S W Lovesey Theory of neutron scattering from condensed matter Oxford Clarendon Press 1984 W H Press S A Teukolsky W T Vetterling and B P Flannery Numerical Recipes in C Cambridge University Press 1986 Ris R 1416 rev ed EN Index Bugs 11 52 58 66 73 74 Can not compile 62 65 86 Code generation options 29 Comments 62 Components 12 65 Coordinate system 61 Data format 78 Data formats 32 36 40 52 53 Embedded C code 62 65 70 Environment variable BROWSER 50 88 EDITOR 40 MCSTAS 29 88 112 119 MCSTAS_CC 15 MCSTAS_CFLAGS 15 MCSTAS_FORMAT 15 26 32 46 48 52 PGPLOT_DEV 44 47 49 PGPLOT_DIR 44 47 49 Gravitation 61 Grid computing 52 54 Installing 13 15 46 Instruments 64 69 Kernel 11 60 Keyword 62 include 29 62 112 ABSOLUTE 66 AT 66 CO
54. COMPONENT CG_In Arm AT C COMPONENT CG_1 Guide_gravity 1l L n m 1 AT 0 0 0 RELATIVE PREVIOUS COMPONENT CG_2_ Position Arm AT 0 0 L n d RELATIVE PREVIOUS ROTATED 0 L n d R 180 PI 0 RELATIVE PREVIOUS COMPONENT CG_2 Guide_gravity 1l L n m 1 AT 0 0 0 RELATIVE PREVIOUS ROTATED 0 L ntd R 180 PI 0 RELATIVE PREVIOUS JUMP CG_2_Position ITERATE n COMPONENT CG_Out Arm AT 0 0 L n RELATIVE PREVIOUS Similarly to the WHEN modifier see section 6 4 3 JUMP only applies within the TRACE section of the instrument definition Other sections INITIALIZE SAVE MCDISPLAY FINALLY are exectuted independently of the jump As a side effetc 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 recommanded 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 what is going on We thus recommand the usage of JUMPs only for experienced and cautious users 6 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
55. Contrib Roland Schedler HMI e FermiChopper_ILL comp Fermi Chopper comp with optional supermirror coated blades Contrib Helmut Schober ILL e V_sample enriched with quasi elastic features Kim Lefmann 2 4 2 New example instruments e TAS frontend with reciprocal space hkl calculator Emmanuel Farhi e Example instruments for polarisation comps p e QUENS test instr Test of new quasi elastic features V_sample 2 5 Documentation e Manual and component manual slightly updated according to adding modification of components and functionality e New appendix on the polarisation features p 2 6 Tools installation 2 6 1 New tools e New merge convert tool mcformat Convert between McStas output formats and merge cluster node datasets into one dataset e TOF mode for mcdisplay Statistical chopper acceptance diagrams generated from the simulated neutron rays Currently only supported on Unix systems with PG PLOT 2 6 2 Installation e Much easier installation on Windows single executable file with all support appli cations is now available Simply click next alle the way and you are done e PGPLOT and Scilab installation help tools on Linux systems Details about the installation and the available tools are given in chapter 3 16 Riso R 1416 rev ed EN 2 7 Future extensions The following features are planned for the oncoming releases of McStas not an ordered list Increased vali
56. Downloaded from orbit dtu dk on Dec 16 2015 oS i Technical University of Denmark Mt User and programmers guide to the neutron ray tracing package McStas version 1 10 Willendrup Peter Kjzer Farhi E Lieutenant K Lefmann K Christiansen P Publication date 2006 Document Version Publisher final version usually the publisher pdf Link to publication Citation APA Willendrup P K Farhi E Lieutenant K Lefmann K amp Christiansen P 2006 User and programmers guide to the neutron ray tracing package McStas version 1 10 Denmark Forskningscenter Risoe Risoe R No 1416 rev ed DA General rights Copyright and moral rights for the publications made accessible in the public portal are retained by the authors and or other copyright owners and it is a condition of accessing publications that users recognise and abide by the legal requirements associated with these rights e Users may download and print one copy of any publication from the public portal for the purpose of private study or research e You may not further distribute the material or use it for any profit making activity or commercial gain e You may freely distribute the URL identifying the publication in the public portal If you believe that this document breaches copyright please contact us providing details and we will remove access to the work immediately and investigate your claim Riso R 1416 rev ed EN User and Pro
57. MPONENT 65 COPY 71 85 DECLARE 65 77 DEFINE COMPONENT 75 INSTRUMENT 64 Riso R 1416 rev ed EN DEFINITION PARAMETERS 75 END 67 83 EXTEND 70 85 113 FINALLY 67 81 GROUP 70 113 INITIALIZE 65 78 ITERATE 73 JUMP 73 MCDISPLAY 81 113 OUTPUT PARAMETERS 75 77 POLARISATION PARAMETERS 76 PREVIOUS 66 RELATIVE 66 ROTATED 66 SAVE 67 78 SETTING PARAMETERS 75 SHARE 77 112 STATE PARAMETERS 76 TRACE 65 78 WHEN 72 73 Library 112 adapt_tree lib 119 Components 12 29 50 51 66 88 contrib 88 92 data 93 119 misc 91 monitors 91 obsolete 88 optics 90 samples 90 share 60 62 92 112 sources 89 Instruments 93 mcstas r see Library Run time monitor_nd lib 119 read_table lib Read_Table 62 117 Run time 12 30 60 62 92 112 129 ABSORB 78 112 ALLOW_BACKPROP 78 112 DETECTOR OUT 79 MC_GETPAR 77 113 NAME_CURRENT_COMP 113 POS_A_COMP 113 POS_A CURRENT_COMP 113 PROP_DT 112 PROP_GRAV_DT 112 PROP ZO 78 112 RESTORE_NEUTRON 113 ROT_A_COMP 113 ROT_A_CURRENT_COMP 113 SCATTER 70 71 78 112 SCATTERED 71 113 STORE NEUTRON 113 Shared see Library Components share vitess lib 51 120 mcstas hosts 54 MPI 54 Neutron state and units 61 Optimization 31 37 Parallel computing 54 Parameters Definition 65 75 Instruments 31 32 45 64 Optional default value 31 64 76 Protecting see Keyword OUTPUT Scans 45 Setting 65 75
58. N P o pi 4 6 The statistical variance of the p s is estimated by o p 3 p Np N 1 The resulting variance then reads o I E oH 4 7 This is not correct in a situation where the detector counts a large fraction of the neutrons in the simulation but we will neglect that for now 24 Riso R 1416 rev ed EN For almost any positive value of N this is very well approximated by the simple expression o 1 amp De pe 4 8 As a consistency check we note that for all p equal this reduces to eq 4 4 In order to compute the intensities and uncertainties the detector components in McStas will keep track of N gt gt p I X pi and Mo gt gt p 4 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 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 transmitting the real neutron is P but we make the Monte Carlo choice of transmitting the neutron ray each time fmc 1 This must be reflected on the choice of weight multiplier 7 given by the master equation fuca P 4 9 This probability r
59. 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 Optional quasielastic broadening Table Riso R 1416 rev ed E 7 3 Sample components of the McStas library N 93 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 with one Monitor_nD in order to record some neutron parameter corre lations Time of flight vs wavelength monitor Rectangular Time of flight monitor Table 7 4 Monitor components of the McStas library MCSTAS misc Description Progress_bar Res_sample TOF_Res_sample Res_monitor TOF_Res_monitor Virtual_input Virtual_output Vitess_input Vitess_output Displays status of a running simulation May also trigger in termediate SAVE Sample like component for resolution function
60. T output and want to view it using Matlab you may use mcformat file dir d target_dir format TARGET_FORMAT to translate files into format FORMAT When given a directory the translation works recursively The conversion works only for text files Some problems may be found when translating from HTML VRML data files or from binary 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 directories which vary instrument parameters For instanmce you ran a scan but finally real ized you should have prolongated it Then simply simulate the missing bits and ap ply mcformat d scan_data format PGPLOT scan stepO stepN The resulting 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 filenames or component names match these keywords e g using a file Source psd the extracted metadata information may be wrong eventhough the data itself will be correct 5 5 Analyzing and visualizing the simulation results To analyze simulation results one uses the same tools as for analyzing experimental data i e pro
61. TAS 1 simulation was the first detailed work performed with the McStas package For further details see reference 46 At the spectrometer the channel from the cold source to the monochromator is asymmet ric since the first part of the channel is shared with other instruments In 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 definition using seven Monochromator components The mosaicity of the pyrolytic graphite crystals is nominally 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 energy 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 th
62. You do not need to write a new component definition but only add a piece of code to execute 6 6 2 Component heritage and duplication There is a heritage mechanism to create childs 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 DEFINE COMPONENT child_name COPY parent_name This single line will copy all parts of the parent into the child except for the documentation header As for normal component definitions you may add other parameters DECLARE TRACE sections Each of them will replace or extend be catenated to with the COPY EXTEND keywords see example below the corresponding parent definition In practice you could copy a component and only rewrite some of it as in the following example DEFINE COMPONENT child_name COPY parent_name SETTING PARAMETERS newparl newpar2 INITIALIZE COPY parent_name EXTEND At C code to be catenated to the parent_name INITIALIZE ht SAVE ral C code to replace the parent_name SAVE ht where two additional parameters have been defined and should be handled in the extension 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 parent1 INITIALIZE COPY parent2 EXTEND ral C code to be c
63. a C source file sim c mcstas sim instr generate an executable without MPI support sim no_mpi cc o sim no_mpi sim c execute on a single computer sim no_mpi lt instrument parameters gt 5 6 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 cpu this option may be omitted Suppose you have four machines named node1 to node4 A typical machine list file machines 1list looks like nodei node2 node3 node4 You can then spread a simulation sim instr using mcrun mcrun c mpi 4 machines machines list Ssim instr lt 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 MPI whereas a simulation compiled with MPI support can be used without MPI 5 6 4 McStas MPI Performance Theorically a computation which lasts T seconds on a single computer should lasts at least seconds when it is distributed over p computers In practice
64. a a 0 02020 000 4 1 1 Monte Carlo ray tracing simulations 4 2 The neutron weight 0 20 0 0 0 ee ee 4 2 1 Statistical errors of non integer counts 24 Riso R 1416 rev ed EN 10 10 11 13 14 14 14 15 15 15 16 16 16 16 16 17 18 18 18 19 19 19 20 21 22 22 23 23 24 4 3 Weight factor transformations during a Monte Carlo choice 25 4 3 1 Direction focusing 02 0000 2b eee ee ee 25 AA gt Adaptive sampling sei ue Gee Ca yea ce Se ee tb oh OWE ee ae a 26 Running McStas 27 5 1 Brief introduction to the graphical user interface 27 5 1 1 New releases of McStas 0 0 000002 eee eee 30 5 2 Running the instrument compiler 0 22 02 00 008 31 5 2 1 Code generation options 000000 ee eee 32 5 2 2 Specifying the location of files 0 008 32 5 2 3 Embedding the generated simulations in other programs 33 5 2 4 Running the C compiler 0 02 02 008 33 5 3 Running the simulations 2 soaa 34 5 3 1 Choosing an output data file format 35 5 3 2 Basic import and plot of results oaoa a 36 5 3 3 Interacting with a running simulation 36 5 3 4 Optimizing simulation speed 00 0000 eee 40 5 3 5 Optimizing instrument parameters sooo e a 41 5 4 Using simulation front ends 2 2 42 5 4 1 The graphical user interface mcgui
65. 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 2 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 distribution in the MCSTAS library The location of this library is detailed in section 5 2 2 All of them are believed to be reliable and some amount of systematic tests have been carried out However no absolute guaranty may 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 compatibility and they still all work as before The mcdoc front end section 5 4 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
66. al locations specified using the I option see the Running McStas chapter in the User Manual and Riso R 1416 rev ed EN 121 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 kTable file 1 initialize and read the first numerical block Table_Info Table display table informations x Table_Index Table 2 5 read the 3rd row 6th column element of the table Indexes start at zero in C Table_Value Table 1 45 1 look for value 1 45 in ist column x 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 catenated 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 y t_Table Table declare a t_Table structure array long n double y Table Table_Read_Array file dat amp n initialize and read the all numerical n Table_Info_Array Table
67. an have any type including strings arrays and function pointers However because of the use of define definition parameters suffer from the usual prob lems 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 parameters 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 define the C compiler can treat definition parameters as constants when the simulation 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 were 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 6 3 OUTPUT PARAMETERS s S23 2 This declares a list of C identifiers variables functions that are output parameters i e global for the component Output parameters a
68. anual 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 behaviour of the component the meaning and units of the input parameters etc 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 feeling 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 ZIDENTIFICATION DESCRIPTION PARAMETERS LINKS and HEND keywords to mark different sections of the documentation Keywords may be abbre viated e g as ZIDENT or I Additionally optional keys VALIDATION and BUGS may be found to list validation status and possible bugs in the component e In the ZIDENTIFICATION section author or written by for backwards compat ibility 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
69. aoa aa ee ee 68 6 3 3 The INITIALIZE section aoaaa 2 000000 eee 68 6 3 4 The TRACE section ma asa mo aa aap a ie eio A A a a ee ee 68 Ris R 1416 rev ed EN 6 3 5 The SAVE section 2 0 20000 ee 70 6 3 6 The FINALLY section 0 0 eee ee RR a 70 6 3 7 The end of the instrument definition 70 6 3 8 Code for the instrument vanadium_example instr 70 6 4 Writing instrument definitions complex arrangements 72 6 4 1 Groups and component extensions 020004 73 6 4 2 Duplication of component instances 0 000 4 74 6 4 3 Conditional components 00 0000 2 eee 75 6 4 4 Component loops 0 0 00 eee ee 76 6 5 Writing component definitions 0 e eee ee 77 6 5 1 The component definition header 0 04 78 6 5 2 The DECLARE section ooo a 79 6 5 3 The SHARE SECTIO seeria na a 8 Ah N E SO A ee Ee 4 80 6 5 4 The INITIALIZE section 08 oaoa a 81 6 5 5 The TRACE section a oa a 81 6 5 6 The SAVE section aooaa aa a 81 6 5 7 The FINALLY section oaao aa 84 6 5 8 The MCDISPLAY section 2 000 eee ee ee 84 6 5 9 The end of the component definition 86 6 5 10 A component example Slit 000 86 6 6 Extending component definitions 0 0 00 ee ee eee 87 6 6 1 Extending from the instrument definition 88 6 6 2 Component heritage and duplication 2
70. 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 p and let us denote the weight multiplication factor in the 7 th component by 7 The resulting weight factor for the neutron ray after passage of the whole instrument becomes the product of all contributions n p p a7 4 2 j 1 Each adjustement factor should be 0 lt m lt 1 except in special circumstances so that total flux can only decrease through the simulation 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 approx imation which does not take each blade into account Riso R 1416 rev ed EN 23 e Reflection from monochromator and analyser 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 of samples 4 2 1 Statistical errors of non integer counts In a typical simulation the result will consist of a count of neutrons histories
71. as r 2 0 0 000048 115 B 1 1 Neutron propagation oaoa a 115 B 1 2 Coordinate and component variable retrieval 2 116 B 1 8 Coordinate transformations 0 220200004 117 B 1 4 Mathematical routines 2 0 0 0 0000000222 ae 118 B 1 5 Output from detectors s no ia neria a 020002 eee ee ee 118 B 1 6 Ray geometry intersections 0 000004 119 Bul f Random numbersia a 4nd Gib ee de A DE ee sce 119 B 2 Reading a data file into a vector matrix Table input read_table lib 120 B 3 Monitor nD library sce eae es Goss BA ee ee a Pe eS 122 B 4 Adaptative importance sampling Library 122 B 5 Vitess import export Library 2 ove fe payee Bee ee SES Gees 123 B 6 Constants for unit conversion etc 2 e 123 The McStas terminology 124 Bibliography 126 Index and keywords 128 Riso R 1416 rev ed EN Preface and acknowledgements This document contains information on the Monte Carlo neutron ray tracing program McStas version 1 10 building on the initial release in October 1998 of version 1 0 as presented in Ref 1 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 It is a pleasure to thank Prof Kurt N Clausen PSI for his continuous support to this project a
72. at Embedded C code ht The and 4 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 time shared library is included by default equivalent to Zinclude mcstas r in the DECLARE section For an example of include see the monitors Monitor nD component 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 macros and there are no name conflicts between instrument and component instances variables Riso R 1416 rev ed EN 65 Keyword Scope Meaning ABSOLUTE I Indicates that the AT and ROTATED keywords are in the ab solute coordinate system AT I Indicates the position of a component in an instrument defini tion COPY I C copy dupli
73. atenated to the parent INITIALIZE A TRACE COPY parent3 88 Riso R 1416 rev ed EN This mechanism may lighter 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 6 7 McDoc the McStas library documentation tool McStas includes a facility called McDoc to help maintain good documentation of compo nents and instruments In the component source code comments may be written that follow a particular format understood by McDoc The McDoc facility will read these com ments and automatically produce output documentation in various forms By using the source code itself 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 Two forms of documentation can be generated One is the component entry dialog in the mcgui front end see section 5 4 1 The other is a collection of web pages documenting the components and instruments handled via the mcdoc front end see section 5 4 6 and the complete documentation for all available McStas components and instruments may be found at the McStas webpage 2 as well as in the McStas library see 7 1 All 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 m
74. ats All formats except the McStas PGPLOT may eventually support binary files which are much smaller and faster to import but are platform depen dent The simulation data file extensions are appended automatically depending on the format if the file names do not contain any Binary files are particularly reeommanded for the IDL format e g format IDL_binary and the Matlab and Scilab format when handling large detectors e g more than 50x50 bins For example vanadium_example out ROT 90 format Scilab_binary or more generally for bash Bourne shell users export MCSTAS_FORMAT Matlab vanadium_example out ROT 90 It is also possible to create and read Vitess and Tripoli4 neutron event files using compo nents e Vitess_input and Vitess_output e Tripoli_input and Tripoli_output Additionally adding the raw keyword to the FORMAT will produce raw N p p data sets instead of N p a see Section 4 2 1 The former representation is fully additive and thus enables to add results from separate simulations e g when using a computer Grid Riso R 1416 rev ed EN 35 5 3 2 Basic import and plot of results The previous example will result in a mcstas m 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 the simulation data as a single structure variable whereas the second one will additionally plot each detector se
75. binary files may be used with d option a option implicitly set XML NeXus format may be used with f and d options HTML format generates a web page may be used with f and d options Data files are saved as VRML objects openGL Virtual Reality file format for data files Simulation files are not saved properly and the HTML format should be used prefer ably Tripoli 4 neutron events file format Use Virtual_tripoli4_input Virtual_tripoli4_output components MCNP PTRAC neutron events file format Use Virtual_mcnp_input Virtual_mcnp_output components Vitess neutron events file format Use Vitess_input Vitess_output components McStas event files in text or binary format Use Virtual_input Virtual_output components Table 5 3 Riso R 1416 rev ed E Available formats supported by McStas simulations N 39 USR1 Request informations status USR2 HUP Request informations and performs an intermediate saving of all monitors status and save This triggers the execution of all SAVE sections see chapter 6 INT TERM Save and exit before end status Table 5 4 Signals supported by McStas simulations 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 simulati
76. cate an instance or a component definition with pa rameters DECLARE I C Declares C internal instrument or component variables DEFINE I C Starts an instrument or component definition INSTRUMENT each associated parameter may have default values COMPONENT DEFINITION C Defines component parameters that are constants like C de fine END I C Ends the instrument or component definition EXTEND I Extends the TRACE section of a component in an instrument definition FINALLY I C Embeds C code to execute when simulation ends also executes the SAVE section GROUP I Defines an exclusive group of components include IC Imports an instrument part a component or a piece of C code when within embedded C JUMP I Iterative loops and conditional jumps INITIALIZE L C Embeds C code to be executed when starting ITERATE I Defines iteration counter for JUMP MCDISPLAY C Embeds C code to display a geometric representation of a com ponent 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 POLARISATION C Defines neutron polarisation coordinates PREVIOUS C Refers to a previous component position orientation RELATIVE I Indicates that the AT and ROTATED keywords are relative to an other component ROTATED I Indicates the orientation of a component in an instrument def inition SAVE I C E
77. catters 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 100 Riso R 1416 rev ed EN 2T scan on 1 mm slit intensity O 45 0 0 5 2T deg Figure 8 4 TAS1 Scans of 20 in the direct beam with 1 mm slit on the sample position x 30 open open measurements 0 2 700 600F intensity A a Q i G O T De T 100 Oc 3 Figure 8 5 TAS1 Corrected 26 scan on a V sample Collimations simulations x measurements o 3 Ris R 1416 rev ed EN 0 2TA deg we simulations scaled to the same intensity Collimations open open 30 28 67 101 800 700 intensity a for Oo So Oo Oo D ao Q 200 32 32 5 33 33 5 34 34 5 35 35 5 2T deg Figure 8 6 TAS1 20 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 140 120 100 intensity fee Oo e2 O T A o T 20F 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 102 Riso R 1416 rev ed
78. ction 3 3 If you prefer the old build bat install bat procedure for Windows you should instead download the alternative mcstas 1 10 i686 unknown Win32 zip package Please note that the exe method is clearly recommended mcstas 1 10 i1686 unknown Linux tar gz Binary package for Linux systems currently built on Ubuntu 6 06 Dapper Drake Should work on most Linux setups Refer to section 3 4 mcstas 1 10 src tar gz Source code package for building McStas on at least Linux and Windows XP This package should compile on most Unix platforms with an ANSI c compiler Refer to section 3 4 Licensing The conditions on the use of McStas can be read in the files LICENSE and LICENSE LIB in the distribution Essentially McStas may be used and modified freely and copies of the McStas source code may be distributed to others New or modified component and instrument files may be shared by the user community and the core team will be happy to include user contributions in the package 18 Riso R 1416 rev ed EN 3 3 Installation on windows As of release 1 10 of McStas the preferred way to install on Microsoft Windows is using a self extracting exe file The archive includes all software needed to run McStas including perl a c compiler a vrml viewer and Scilab for data plotting Installation of all the provided support tools is needed to get a fully functional McStas The option not to install some of the tools is only inc
79. ction is optional Instrument setting parameters e g doing tests or automatic settings may be modified in this section 6 3 4 The TRACE section As asummary 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 pi 1 p2 2 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 1 2 define the values of the parameters For setting parameters arbitrary ANSI C expressions may be used while for definition parameters only constant numbers strings names of instrument parameters or names of C identifiers are allowed see section 6 5 1 for details of the difference between definition and setting parameters To assign the value of a general expression to a definition parameter 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 68 Riso R 1416 rev ed EN The McStas program takes care to rename parameters appropriately in the output so that n
80. ction to how calculations are done and then quote some results which are important for implementing the first McStas components All the potentials nuclear magnetic and electric we will be interested in can be written on the form 6 64 4 6 A 16 The first term does not affect the spin while the second term can change the spin Let us just remind here that rXt X FyXt IXl zX Xf A 17 BxX SX FyX1 IXt zX TXL So that the interaction proportional to and G results in spin flips while the interactions with conserves the spin It turns out to be smart to define a density matrix operator gt eens jal ab 1 ae where x is the neutron wave function Eq A 5 and Z is the unit matrix Using the density matrix the elastic cross section can be written as Eq 10 31 do ga TAS D PATEA AVAN ATEA Ex A 19 A A where V is the interaction potential and it is understood that the trace is to be taken with respect only to the neutron spin coordinates The outgoing polarization is given as d Ta z A Pp Tr t NO PATAVII ANE NIV KAE Ex A 20 AV 108 Ris R 1416 rev ed EN Inserting Eq A 16 in Eq A 19 and Eq A 20 results in the two master equations for polarized neutron scattering Trpd s t 6184 B a P at P G iP at x a A 21 and Trpi e6 Bia l B 6 6P a1 a amp P al P a P al amp ial x i xP i Px at 3 A 22 Based on these
81. d at the very beginning of the TRACE section As a default neutrons are defined at the origin with zero time and speed As a consequence the time spread is zero Most sources Riso R 1416 rev ed EN 73 components only set the position and velocity but do not set the time of the created neutrons You may manually set the neutron time spreading for e g Time of Flight instruments in an EXTEND code section such as COMPONENT MySource source AT EXTEND ht t randpm1 10e 6 hy This will set the time randomly between 10 and 10 u seconds 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 COMPONENT name0 comp pi 1 p2 2 AT 0 0 0 ABSOLUTE COMPONENT namel comp AT ROTATED GROUP GroupName EXTEND nt if SCATTERED printf I scatter else printf I do not scatter ht 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 be comes true the code extension will result in printing I scatter and the second component will be skipped Thus we recommand t
82. dation and testing Extend test cases to all most components One instrument pr component Prob ably not in examples Better support for heterogeneous grid computing Improvements to the NeXus data format initial support is already included Updates to mcresplot to support the Matlab and Scilab backends Compatibility issues with recent Perl releases on Windows Compatibility issues with the next release of Scilab Global changes of components relating to polarisation visualisation Visualisation of neutron spins in magnetic fields for all graphical backends Array AT specifiers for components i e COMPONENT MyComp Comp AT Xarray Yarray Zarray and AT Positions filename Gui support for array AT specifiers More complete polarisation support including numerically defined magnetic fields and advanced sample components Perl plotting alternative to PGPLOT Larger variety of sample components Riso R 1416 rev ed EN 17 Chapter 3 Installing McStas The information in this chapter is also available as a separate html ps pdf document in the install_docs folder of your McStas installation package 3 1 Getting McStas The McStas package is available in various distribution packages from the project website at http www mcstas org download 3 2 McStas 1 10 1686 Win32 exe Preferred Windows installation method self extracting executable including essen tial support tools Refer to se
83. debugged by the user for every instrument or component Efficiency is also improved by letting the compiler optimize the generated code in ways that would 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 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 ANSI C making it both efficient and portable The meta language allows the user to embed arbitrary C code in the specifications Flexib
84. definition 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 centre 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 occurencies should be changed manually into fprintf stderr To use the mcstas2vitess front end the program Perl should be available 5 4 8 Translating McStas results files between Matlab and Scilab for mats If you have been running a McStas simulation with Scilab output but finally plan to look at the results with Matlab or the contrary you may use mcconvert file m sci to simply translate one file format to the other This works only for text files of course The binary files need not be translated 54 Riso R 1416 rev ed EN 5 4 9 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 simulation with PGPLO
85. der development as the amount of testing and debugging of these components is small and there are known problems Here we shall report on what have been done so far We first describe the polarization vector and how it is related to the neutron wave function section A 2 and then the physics of simple components that we need in McStas is reviewed section A 3 In the last two sections the actual McStas polarization components are first described section A 4 and a list of test instruments in McStas is given section A 5 We rely heavily on the books 47 for the physics where the detailed calculations can be found The notation used here and in 47 is P scalar P vector P unit vector operator and vector of operators A 2 The Polarization Vector The spin of the neutron is represented by an operator for which only a single component can be measured at one time Each single measurement will give a value 1 2 but if we could make a large number of measurements on the same neutron state in each of the three axis directions and then make the average we get 8 The polarization vector P is then defined as P a A 1 so that 1 lt P lt 1 For a neutron beam which contains N neutrons each with a polarization P the beam polarization is defined as P ee A 2 Riso R 1416 rev ed EN 105 If we have one common quantization direction e g a magnetic field direction each neutron will either be
86. e design of McStas the task was separated into four conceptual layers 1 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 2 Modeling of the overall instrument geometry mainly consisting of the type and position of the individual components 3 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 4 Presentation of the calculations graphical or otherwise Riso R 1416 rev ed EN 11 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 mak
87. e 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 AlgO3 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 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 8 3 Test results and data from the real spectrometer are shown in Appendix 8 2 1 8 2 1 Simulated and measured resolution of TAS1 In order to test the McStas package on a qualitative level we have performed a very detailed c
88. e 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 meta language in which simulations are written The usage of a special meta language and an automatic compiler has several advantages 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 powerful specifica tions 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 instruments 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 instru ment 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
89. e 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 overwriting previous results an error message is given if the directory already exists Alternatively 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 The complete list of options and arguments accepted by McStas simulations appears in Tables 5 1 and 5 2 5 3 1 Choosing an output data file format Data files contain header lines with information about the simulation from which 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 5 5 It may be chosen either with format FORMAT for each simulation or glob ally by setting the MCSTAS FORMAT environment variable The available format list is obtained using the name out help option and shown in Table 5 3 McStas can presently generate many formats including the original McStas PGPLOT and the new Scilab and Matlab form
90. e 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 If no component of the group could intercept the neutron ray it is ABSORBed If you wish not to absorb these neutrons you may end each group by a large monitor or another dummy component which will eventually catch neutrons that were not caught by previous components of the group It is sometimes desirable to modify an existing component of the McStas library One would usually make a copy of the component and extend the code of its TRACE sec tion McStas provides an easy way to change the behaviour of existing components in an instrument definition without duplicating files using the EXTEND modifier after the AT ROTATED and optional GROUP EXTEND ht C code executed after the component TRACE section ay The embeded C code is appended at the end of the component TRACE section and all its internal variables as well as all the DECLARE instrument variables except instrument parameters may be used It thus behave as a plug in for the component TRACE This component instance modifier is of course optional As an example for EXTEND Sources are special components that set the neutron STATE parameters e g position time velocity and initial weight and are usually positione
91. ection and the GROUP modifier See also the SCATTERED variable below B 1 2 Coordinate and component variable retrieval 116 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 where tiS Y OT Z ROT_A_CURRENT_COMP and ROT_R_CURRENT_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 rela tive 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 Riso R 1416 rev ed EN e
92. ed C code obeys the ISO C standard so it should be easy to compile it using any ISO C or C compiler E g a typical Unix style command would be cc 0 o name out name c lm The 0 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 2 e Intel x86 PC with Linux and GCC using options gcc 03 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 06 mstack align double Riso R 1416 rev ed EN 33 e HPPA machines running HPUX with the optional ISO C compiler using the op tions Aa O0all W1l 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
93. elsen K N Clausen B Lake and G Aeppli Physica B 283 343 354 2000 See http www sns gov See http www ess europe de J R D Copley P Verkerk A A van Well and H Fredrikze Comput Phys Commun 40 337 1986 H Maier Leibnitz and T Springer Reactor Sci Technol 17 217 1963 D F R Mildner Nucl Instr Meth A290 189 1990 R A Lowde J Nucl Energy Part A Reactor Sci 11 69 1960 J R D Copley Nucl Instr Meth A510 318 2003 E Fermi J Marshall and L Marshall Phys Rev T2 193 1947 J Peters Nucl Instr Meth A540 419 2005 C D Clark E W J Mitchell D W Palmer and I H Wilson J Sci Instrum 43 1 1966 A K Freund Nucl Instr Meth 213 495 1983 V F Sears Acta Cryst A53 35 1997 G Shirane S M Shapiro and J M Tranquada Neutron Scattering with a Triple Axis Spectrometer Cambridge University Press 2002 L Alianelli J Appl Cryst 37 732 2004 V Radeka IEEE Trans Nucl Sci NS 21 51 1974 V Peskov G Charpak W Dominik and F Sauli Nucl Instr and Meth A277 547 1989 G Manzin B Guerard F A F Fraga and L M S Margato Nucl Instr Meth A535 102 2004 L D Cussen J Appl Cryst 36 1204 2003 F James Rep Prog Phys 43 1145 1980 Grimmett G R and Stirzakerand D R Probability and Random Processes 2nd Edition Clarendon Press Oxford 1992 See http www rocq inria fr scilab Riso R 141
94. ematically the Monte Carlo method is an application of the law of large numbers 40 41 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 1 1 b lim Ui f u du 4 1 eG 5g 4 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 regularly 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 refer to James 40 for a detailed review on the Monte Carlo method 4 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 detector An important way of speeding up calculations is to introduce a neutron weight factor for each simulated neutron ray and to adjust 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
95. en during the computation Indeed if you request data in a given format from a simulation you will only be able to display results using that same drawing back end Anyway the mcconvert utility may convert a McStas data file between Matlab and Scilab formats see section 5 4 8 also handling binary data sets Alternatively the mcformat utility will convert any McStas result into data format see section 5 4 9 but restricting to text data sets In this case we recommand 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 5 4 5 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 file containing the current plot that can be sent to the printer to obtain a hardcopy the C key produces color postscript Riso R 1416 rev ed EN 51 The Q key quits the program or CTRL C in the controlling terminal may be used as normal 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 PG PLOT on the local system in case of diffic
96. ent definitions which the front end will not notice automatically See section 3 for how to override default C compiler options Clear output erases all text in the window showing output of compilations and simula tions Quit exits the graphical user interface front end The Simulation menu has the following features Read old simulation prompts for the name of a file from a previous run of a McStas simulation 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 Run simulation opens the run dialog window explained further below Plot results plots using mcplot the results of the last simulation run or spawns a load dialogue to load a set of results Riso R 1416 rev ed EN 43 Configuration options Opens the choose backend dialog shown in figure 5 7 Several settings can be chosen here e Selection of the desired PGPLOT Scilab 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 PGPLOT e Clustering option None MPI Threads ssh e Choice of editor to use to when editing instrument files e Automatic quotation of strings when
97. er transform of the magnetization density normalized so that F4 0 1 and 4 is the thermal average of the ordered atomic spin In the following the Debye Weller factor exp Wg have been ignored in all cross sections A 2 1 Example Magnetic fields The magnetic moment operator of the neutron is fp n8 where Yn 2pn 3 826 is the gyromagnetic ratio spin and magnetic moment is anti parallel as for an electron A magnetic field B will exert a torque 0 ds dt 1 yn du dt on the neutron magnetic moment nxB A 13 The magnetic moment u can be related to the polarization as u ynP 2 and inserting in Eq A 13 we find P mP x B A 14 In the simple case where B 0 0 B we find the solution 47 p 18 Note that if we had used S with values S 1 to define yn we would get yn 1 913 which is also commonly used Riso R 1416 rev ed EN 107 Px t cos wzt Px 0 sin wzt Py 0 sin wyt Px 0 cos wzt Py 0 A 15 Pz t Pz 0 Y Il where wr 7 B h is the Larmor frequency The equations above was checked against the equations in the polarimetrie neutronique notes by Francis Tasset and found to be consistent There can be sign differences between different publications depending on whether they use a right handed like e g McStas or a left handed like e g NISP coordinate system A 3 Polarized Neutron Scattering First we will give a short introdu
98. esented graphics will resemble one of those shown in figures 5 4 5 6 For a slightly longer gentle introduction to McStas see the McStas tutorial available from 2 and as of version 1 10 built into the mcgui help menu For more technical Riso R 1416 rev ed EN 29 4pi lurmoator oO O S D GS E m k EJ O er d G Uo S sy IL s m ui sixy x Figure 5 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 5 4 3 for details vanadium _example PlotinstrumentaD First component Last component target neutrons to trace 1 INIA IA IA IR Figure 5 5 Output from mcdisplay with Scilab backend Display can be adjusted using the dialogbox right details read on from section 5 2 5 1 1 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 30 Risd R 1416 rev ed EN home fys pkwi Beta0 mcstas 1 7 Beta0 examples vanadium_example xim Reset vie Per 2 Tso e Exit_ P 3 source PSD_4pi Redraw A 4 1 iak Figure 5 6
99. flat Selector Slit V_selector Vitess_ChopperFermi Arm optical bench Rectangular circular beam stop A curved neutron guide shown straight in mcdisplay Disk chopper A simple analytical Soller collimator A radial Soller collimator 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 1 Doubly bent multiple crystal slabs with anisotropic Gaussian mosaic Flat Monochromator crystal with anisotropic Gaussian mosaic A velocity selector helical lamella type such as V_selector component Rectangular circular slit Velocity selector Curved Fermi chopper longer execution time than FermiChop per From the Vitess package Table 7 2 Optics components of the McStas library MCSTAS samples Description Isotropic_Sqw Phonon_simple PowderN Sans_spheres Single_crystal V_sample 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 isotropic phonons simple General powder sample with N scattering vectors using a data file
100. flat radius 0 015 dist 1 xw 0 024 yh 0 015 E0 5 dE 0 2 AT 0 0 0 RELATIVE arm Here we have a soller placed to improve beam divergence The component is placed at a distance RELATIVE to a previous component COMPONENT collimator Collimator_linear len 0 2 divergence coll_div xmin 0 02 xmax 0 02 ymin 0 03 ymax 0 03 AT 0 O 0 4 RELATIVE arm We also need something to shoot at here a sample made from vanadium an isotropic scatterer Options are available to restrict the solid angle in which neutrons are emitted no need to simulate anything that we know for sure will not gain us more insight Other options for smart targeting are available refer to component documentation for info COMPONENT target V_sample radius_i 0 008 radius_o 0 012 h 0 015 focus_r 0 pack 1 target_x 0 target_y 0 target_z 1 AT 0 0 1 RELATIVE arm Here a secondary arm or reference point placed on the sample position The ROT parameter above defines rotation of this arm and components relative to the arm COMPONENT arm2 Arm AT 0 0 0 RELATIVE target ROTATED 0 ROT 0 relative arm For data output let us place a detector This detector is not very realistic since it has a spher ical shape with a 10 m radius but has the advantage that EVERYTHING emitted from the sample w
101. formed Use the File Compile menu item in mcgui 46 Ris R 1416 rev ed EN The plot dialog This dialog only shows up when using the McStas PGPLOT plotter Other plotters have attached menus to control graphics and file exports Monitors and detectors lists all the one and two dimensional detectors in the instru ment By double clicking one plots the data in the plot window Plot plots the selected detector in the plot window Has the same effect as double clicking its name Overview plot plots all the detectors together in the plot window B amp W postscript prompts for a file name and saves the current plot as a black and white postscript file This can subsequently be printed on a postscript printer Colour postscript creates a colour postscript file of the current plot Colour GIF creates a colour GIF file of the current plot Close ends the dialog 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 Instrument template inserts the text for a simple instrument skeleton in the editor window 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 value
102. grammers Guide to the Neutron Ray Tracing Package McStas Version 1 10 Peter Willendrup Emmanuel Farhi Kim Lefmann Peter Christiansen and Klaus Lieutenant Ris National Laboratory Roskilde Denmark November 2006 Risg R 1416 rev ed EN NOD User and Programmers Guide to the Neutron Ray Tracing Package McStas Version 1 10 Peter Willendrup Emmanuel Farhi Kim Lefmann Peter Christiansen and Klaus Lieutenant ata 7000 T T T T T T T T T DMC powder di McStas powder data al i C t as 5000 Ris National Laboratory Roskilde Denmark November 2006 Abstract The software package McStas is a tool for carrying out Monte Carlo ray tracing simulations 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 ANSI 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 manual for the McStas components
103. grams such as IDL Matlab and Scilab The output files from simulations are usually simple text files containing headers and data blocks If data blocks are empty they may be accessed refering to an external file indicated in the header This file may also be a binary file except with the original McStas PGPLOT format which does not contain any header except if simulation is launched with a option but are in turn smaller in size and faster to import In order for the user to choose the data format we recommand to set it via the MC STAS_FORMAT environment variable which will also make the front end programs able to import and plot data and instrument consistently The available format list is shown in Table 5 3 Note that the neutron event counts in detectors is typically not very meaningful except as a way to measure the performance of the simulation Use the simulated intensity instead whenever analysing simulation data 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 Riso R 1416 rev ed EN 55 One dimensional histogram monitors time of flight energy write one line for each his togram bin Each line contains a number identifying the bin i e the time of flight fol lowed by three numbers the simulated intensity an estimate of the statistical error as explained in section 4 2 1 and the number of neutron event
104. he McStas self test procedure which is executed with mcrun test mcrun pl on Windows This test takes a few minutes to complete and ends with a short report on the installation itself the simulation accuracy and the plotter check You should now be able to use McStas For some examples to try see the examples directory Start mcgui mcgui pl on Windows and select one of the examples in the Neutron Sites menu Riso R 1416 rev ed EN 21 Chapter 4 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 statis tical 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 4 1 Neutron spectrometer simulations 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 spa tial and time distributions in a way which may be modeled through analytical methods for simplified neutron beam configurations This stands for individual elements such as guides 25 26 choppers 27 28 Fermi choppers 29 30 velocity selectors
105. he command mcresplot file Here file is the name of a file output from a simulation using the Res_monitor component This front end currently only works with the PGPLOT plotter but ports for Matlab and Scilab may be written in the future The front end will open a window displaying projections of the 4 dimensional resolution 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 projection 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 52 Riso R 1416 rev ed EN mev w meV w meV Q 87 Q 87 Q 87 Bragg Gaussian Half Widths File Output res Instrument simulation parameters AQ 0 3133 at Date Thu May 15 10 00 08 2003 AQ 0 3263 7 X along lt Q gt in plane None AQ 0 3838 at Y perp to X in plane Z upwards Aw 2 2128 meV Resolution matrix Q o 56 464535 0 050060985 0 14036386 77 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 l9 oy Q o 0 37970629 0 0001159542 0 00015882804 2 6180041 0 0001159542 0 01921267 4 6335128e 05 0 000711623812 0 00015882804 4 63351
106. he instrument 5 2 2 Specifying the location of files The McStas compiler needs to be able to find various files during compilation some explicitly requested by the user such as component definitions and files referenced by include 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 local lib mcstas on Unix like systems and C mcstas lib on Windows systems but it can be changed to something else see section 3 for details The location can be overridden by setting the environment variable MCSTAS setenv MCSTAS home joe mcstas for csh tcsh users or export MCSTAS home joe mcstas for bash Bourne shell users For Windows Users you should define the MCSTAS from the menu Start Settings Control Panel System Advanced Environment Variables by creat ing MCSTAS with the value C mcstas lib To make McStas search additional directories for component definitions and include files use
107. his usually also requires to setup properly the ssh connections and keys This last step is not required when running on a local SMP machine 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 MPI Basic usage To enable parallel computation compile McStas output C source file 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 in a file machines list using mpich implementation refer to MPI documentation for a complete description mpirun machinefile machines list n lt N gt sim mpi lt instrument parameters gt If you don t want to spread the simulation run it as usual sim mpi lt instrument parameters gt Riso R 1416 rev ed EN 59 If you want to disable MPI support for example if you do not have MPI installed just compile the C source file generated by mcstas without mpicc and without the DUSE_MPI flag generate
108. ilayer sample for reflectivity simulations SNS moderator models based on MCNP calculations 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 Used by Vitess_input and Vitess_output Table 7 7 Shared libraries of the McStas library See Appendix B for details Riso R 1416 rev ed EN 95 MCSTAS data Description lau laz trm rfl Sqw 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 fil ters Data k Angs 1 Transmission 0 1 reflectivity file typically for mirrors and monochromator crys tals Data k A
109. ility is thus ensured since the full power of the C language is available if needed 12 Riso R 1416 rev ed EN 1 4 Overview The McStas system documentation consists of the following major parts A short list of new features introduced in this McStas release appears in chapter 2 Chapter 3 explains how to obtain compile and install the McStas compiler associ ated files and supportive software Chapter 4 concerns Monte Carlo techniques and simulation strategies in general Chapter 5 includes a brief introduction to the McStas system section 5 1 as well a section 5 2 on running the compiler to produce simulations Section 5 3 explains how to run the generated simulations Running McStas on parallel computers require special attention and is discussed in section 5 6 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 5 4 The McStas meta language is described in chapter 6 This chapter also describes a set of library functions and definitions that aid in the writing of simulations See appendix B for more details The McStas component library contains a collection of well tested as well as user contributed beam components that can be used in simulations The McStas com ponent library is documented in a separate manual and on the McStas web page 2 but a short overview of these components is given in chapter
110. ill be picked up Notice that this component changes orientation with the ROT input parameter of the instrument COMPONENT PSD_4pi PSD_monitor_4PI radius 10 nx 101 ny 51 filename Vvanadium psd AT 0 0 0 RELATIVE target ROTATED ROT 0 0 RELATIVE arm2 END 6 4 Writing instrument definitions complex arrangements In this section we describe some additional ways to build instruments using groups code extension conditions loops and duplication of components 72 Ris R 1416 rev ed EN As a summary the complete grammar definition for component instances within the in strument TRACE section is COMPONENT name comp parameters WHEN condition AT RELATIVE reference PREVIOUS ABSOLUTE ROTATED RELATIVE reference PREVIOUS ABSOLUTE GROUP group_name EXTEND C_code JUMP reference PREVIOUS MYSELF NEXT ITERATE number_of_times WHEN condition 6 4 1 Groups and component extensions In some peculiar configurations it is neccesary to position one or more groups of compo nents nested in parallel or overlapping One example is a multiple crystal monochroma tor 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 GROUP name to all involved component declarations All components of th
111. ing 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 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 a simulation quality measurement from this data usually the integrated counts or some peak width Riso R 1416 rev ed EN 41 For instance for the prisma2 instrument we could write a function for Matlab see sec tion 5 5 for details about the Matlab data format in order to study the effects of the TT parameter function y instr_value p TT p 1 p may be a vector matrix containing many parameters syscmd mcrun prisma2 instr nle5 TT num2str TT gt PHA 22 PHA1 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 Matlab Scilab IDL and Perl PDL high level languages In this example we may wish to maximize the inst
112. instrument file can be obtained from the examples directory in the distribution or from another source The structure of McStas is illustrated in Figure 5 1 The input files instrument and component files are written in the McStas meta language and are edited either by using your favourite editor or by using the built in editor of the graphical user interface mcgui Next the instrument and component files are compiled using the McStas compiler relying on built in features from the FLEX and Bison facilities to produce a C program 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 experiments by using the data handling and visualisation tools in McStas based on Perl and Mat lab Scilab 42 or PGPLOT Further data output formats including IDL and XML are available see section 5 5 5 1 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 Riso R 1416 rev ed EN 27 Graphical User Interface Perl Visualisation PGPLOT pgperl PDL Input
113. into account One should implement d spread and mosaicity in a way similar to what is done in Single crystal Riso R 1416 rev ed EN e Pol_mirror Plane with a reflection probability for up and down There are 3 options always reflect always transmit or random select transmit reflect NB Note that at the moment the plane only reflects from one side because it uses PROP_ZO e Pol_bender Curved guide with the possibilities to insert multiple slits and have the end gap parallel to the entrance or following the guide angle It is possible to select different coatings mirror parameters for each of the four sides e Pol_guide_vmirror Straight guide with non polarizing coatings with two polariz ing super mirrors sitting in a V shape inside Note that for all the polarizing guides it is possible to define analytical functions or use tables for the up and down reflectivity descriptions A 4 2 Detectors e Pol_monitor One defines a vector m mz my mz for the monitor and mea sures the projection of the spin along this vector i e m S e PolLambda_monitor Measures the projection of the spin along the defined vector m see Pol monitor as a function of the wavelength A e MeanPolLambda_monitor Measures the average projection of the spin along the defined vector m see Pol_monitor as a function of the wavelength A NB currently the error on the mean is shown a N but it might make more sense to show the spread c
114. ion approximation handling for the whole neutron propagation within the instrument May produce wrong results if the used components do no comply with this option format FORMAT This option 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 MAL Set the value of an instrument parameter rather than having to prompt for each one Scans ranges are specified as min max Table 5 1 Options accepted by McStas simulations For options specific to MPI and parallel computing see section 5 6 Riso R 1416 rev ed EN 37 f file file file Write all data into a single file file Avoid when using binary formats a data only Do not put any headers in the data files format_data FORMAT This option 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 This option will distribute the simulation over NB_CPU node requires MPI to be installed Per formances are ideal threads NB_CPU This option will distribute the simulation over NB_CPU threads requires multi threading to be avail able Performances are low machines MACHINES Specify a list of distant machines nodes to be used for MPI and grid clus
115. ion 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 dy dz bz by bz Returns the scalar product of the two vectors ax ay az and bz by bz vec_prod amp ar Xay amp az br by bz Cx Cy Cz Sets Az dy az equal to the vector prod uct br by bz X Cr Cy z rotate amp r amp y amp z Ur Vy Vz p Az y z Set x y z to the result of rotating the vector Uz Vy vz the angle y in radians around the vector az ay az normal_vec amp n amp n amp nz x y z Computes a unit vector Ng Ny nz normal to the vector x y z solve_2nd_order t A B C Solves the 2 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 118 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 es timated statistical error The output is produced in a format that can be read by McStas front end programs DETECTOR _OUT_1D Used to output the results from a one dimensional detector Integrated intensities error etc is also reported as for DETECTOR OUT 0D DETECTOR_OUT_2D Used to output the results from a two dimentional detector Integrated intensities er
116. 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 multiline 3 x y 0 which will silently produce garbage output This must instead be written as multiline 3 double x double y 0 0 The rectangle command The rectangle command takes the following form 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 y XZ x Z yz y Z The box command The box command takes the following form box x y z xzwidth yheight zlength The command draws a box with the center at x y z and the size rwidth x yheight x zlength The circle command The circle command takes the following form circle plane Y Z r Here plane should be either xy xz or yz The command draws a circle in the specified plane with the center at x y z and the radius r Ris R 1416 rev ed EN 85 6 5 9 The end of the component definition END This marks the end of the component definition 6 5 10 A component example Slit A simple example of the component Slit is given DOO OOOO OO OO A GO RA RA I A a aK A a a ak McStas neutron ray tracing package Copyright 1997 2002 All rights reserved
117. ke 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 Forcing the random seed while spreading the computation doesn t work since every node will use identical seeds and will then generate identical pseudo random values 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 When reading external data files during the TRACE specially virtual sources all nodes might access the same data potentially producing wrong results We do not recommand using MPI when reading virtual sources Riso R 1416 rev ed EN 61 5 6 6 Parallel computing multi threading Multi threading is under experimentation It has been implemented when using mcrun c threads NB_CPU and is also available from McGUI Run Dialog The method is based on a parallel execution of threads which require mutexes in order to set rules for global shared memory accesses This introduces quite large overhead and reduces efficiency We thus do NOT recommand to use it Further developments are under way 62 Riso R 1416 rev ed EN Chapter 6 The McStas kernel and meta language Instrument definitions are written in a special McStas meta language which is translated automatically by the McStas compiler into a C program which is in turn compiled to
118. l detector Riso R 1416 rev ed EN 25 Figure 4 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 4 4 Adaptive sampling Another strategy to improve sampling in simulations is adaptive importance sampling where McStas during the simulations will determine 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 26 Riso R 1416 rev ed EN Chapter 5 Running McStas This chapter describes usage of the McStas simulation package Refer to Chapter 3 for installation instructions In case of problems regarding installation or usage the McStas mailing list 2 or the authors should be contacted Important note for Windows users It is a known problem that some of the McStas tools do not support filenames directories with spaces We are working on a more general approach to this problem which will hopefully be solved in the next release Also there are known issues for McStas with recent Perl versions for Windows We recommand to use ActiveState Perl 5 6 Note that as of McStas 1 10 all needed support tools for Windows are bundled with McStas in a single installer file To use McStas an instrument definition file describing the instrument to be simulated must be written Alternatively an example
119. lar 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 applications Using the new commandline options TOF T and tmax TMAX chopper acceptance diagrams can be generated from the statistical information from the simulated 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 the PGPLOT and the PGPerl pack ages to be installed It may be necessary to set the PGPLOT_DIR and PGPLOT_DEV envi ronment variable consult the documentation for PGPLOT on the local system in case of difficulty 50 Riso R 1416 rev ed EN Matlab and Scilab back ends_ 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 Note The Scilab plotter for Windows does not allow to rotate interactively the 3D view and you are to use the alpha and theta ch
120. luded for people who have one or more tools installed already The safe and fully tested configuration installation is to install all tools leaving all in stallation defaults untouched Specifically you may experience problems if you install to non standard locations Simply follow the guidance given by the installer pressing next all the way If you experience any problems or have some questions or ideas concerning McStas please contact peter willendup risoe dk or the McStas mailing list at neutron mc risoe dk 3 4 Installation on Unix systems Our current reference Unix class platform is Ubuntu Linux which is based on Debian GNU Linux Some testing is done on other Unix variants including Fedora Core SuSE and FreeBSD To get a fully functional McStas installation on Unix systems a few support applications are required Essentially you will need a C compiler Perl and Perl Tk as well as a plotter such as Matlab Scilab or PGPLOT In the installer package we supply a method to install PGPLOT and related perl modules see step 4 below and also a method to download and install Scilab for Linux Intel see step 5 On Debian and Ubuntu systems the needed packages to install are perl tk pdl gcc libc6 dev On Ubuntu you need to enable the universe package distribution in the file etc apt sources 1list We also recommend to install octaga vrml viewer from http www octaga com download_octaga html 3 4 1 Configuratio
121. mbedded C code to execute when saving data SETTING C Defines component parameters that are variables double int char SHARE C Declares global functions and variables to be used by all com ponents STATE C Defines neutron state coordinates TRACE I C Lists the components or embedded C code to execute during simulation WHEN I Condition for component activation and JUMP Table 6 1 Reserved McStas keywords Scope is I for instrument and C for component definitions 66 Riso R 1416 rev ed EN 6 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 component is given its own local coordinate system the position and orientation of which may be specified by its translation and rotation relative to another component An example is given in section 6 3 8 and some additional examples of instrument definitions can be found on the McStas web page 2 and in the example directory 6 3 1 The instrument definition head DEFINE INSTRUMENT name a1 d2 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 6 5 A motor position is a typical example of an instr
122. meters 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 studies 14 16 instrument optimization and design 17 18 Most of the time the conclusions and general behaviour of such studies may be obtained using the classical analytical ap Riso R 1416 rev ed EN 9 proaches 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 the main goal for 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 Ris National Laboratory simulation tools were urgently needed not only to better utilize existing instruments e g RITA 1 and RITA 2 19 21 but also to plan completely new instruments for new sources e g the Spallation Neutron Source SNS 22 and the planned European Spallation Source ESS 23 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 existi
123. mple DEFINE INSTRUMENT test d1 1 string s2 hello Here di and d2 are an 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 to study the instrument design Riso R 1416 rev ed EN 67 6 3 2 The DECLARE section DECLARE ht C declarations of global variables etc ht This gives C declarations that may be referred to in the rest of the instrument definition A typical use is to declare global variables or small functions that are used elsewhere in the in strument The Zinclude file keyword may be used to import a specific component definition or a part of an instrument Variables defined here are global and may con flict with internal McStas variables specially symbols like x y z sx sy sz vx vy vz t and 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 6 3 3 The INITIALIZE section INITIALIZE ht C initializations ht This gives code that is executed when the simulation starts This se
124. mple and a spin flipper Riso R 1416 rev ed EN Appendix B Libraries and conversion 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 include McStas keyword For instance within a component C code block usually SHARE or DECLARE include read_table lib will include the read_table lib h file and the read_table lib c unless the no runtime option is used with mcstas Similarly include read_table lib h 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 p
125. mulation will prompt for the values of any instru ment parameters such as motor positions and then run the simulation Default instrument parameter values see section 6 3 if any will be indicated and entered when hitting the Return key This way of running McStas will only give data for one spectrometer setting which is normally sufficient for e g time of flight SANS or powder instruments but not for e g reflectometers or triple axis spectrometers where a scan over various spectrom eter 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 name out help The values of instrument parameters may be specified as arguments using the syntax name val For example vanadium_example out ROT 90 34 Riso R 1416 rev ed EN 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 sequenc
126. n and installation McStas uses autoconf to detect the system configuration and creates the proper Makefiles needed for compilation On Unix like systems you should be able to compile and or install McStas using the following steps 1 Unpack the sources to somewhere convenient and change to the source directory gunzip c lt package gt tar gz tar xf cd mcstas 1 10 2 Configure McStas configure 3 Build McStas only in case of the mcstas 1 10 src tar gz package make Riso R 1416 rev ed EN 19 4 Optionally build install PGPLOT as superuser build dependencies are pdl g77 libx11 dev xserver xorg dey libxt dev on Ubuntu make install pgplot amp amp configure 5 Optionally download install Scilab as superuser only on Linux with Intel hard ware make install scilab amp amp configure 6 Install McStas as superuser make install The installation of McStas in step 6 by default installs in the usr local directory which on most systems requires superuser root privileges 3 4 2 Specifying non standard options To install in a different location than usr local use the prefix option to configure in step 2 For example configure prefix home joe will install the McStas programs in home joe bin and the library files needed by McStas in home joe lib mestas In case configure makes an incorrect guess some environment variables can be set to override the defaults e The CC envir
127. n 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 recieving a TERM or INT signal on Unix systems or with Control C causing code in FINALLY to be evaluated 6 3 7 The end of the instrument definition The end of the instrument definition must be explicitly marked using the keyword END 6 3 8 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 DEO kk akk akk ak k ak ak ak ak ak ak ak ak 3k ak k ak 3k ak ak ak ak ak ak ak ak 3K ak 3k ak k ak ak 2k ak 2K ak 3K ak 3k ak 3k 2k ak ak ak 2k ak 3k ak 3K ak 3k ak kak I 2k ak 2K ak 2K ak 3K ak kK k K k McStas neutron ray tracing package 70 Riso R 1416 rev ed EN HF HF HF HF HF HH HF HH HF HF HF HF HF HF K DE Copyright 1997 2002 All rights reserved Risoe National Laboratory Roskilde Denmark Institut Laue Langevin Grenoble France Instrument vanadium_example Aldentification Written by Kristian Nielsen and Kim Lefmann Date 1998 Origin Risoe Release McStas 1 1 Version Revision 1 6 ZINSTRUMENT_SITE Tutorial A test instrument using a vanadium cylinder 7Description This instrument shows the vanadium sample scattering anisotropy This is an effect of attenuati
128. nce 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 6699 66 99 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 2x1 gt Yio 21 T2 Y2 z2 It draws a line between the points x1 y1 21 and 2 yo 22 84 Riso R 1416 rev ed EN The dashed_line command The dashed_line command takes the following form dashed_line 71 Y1 21 42 Y2 2 N It draws a dashed line between the points x1 y1 21 and x2 y2 z2 with n equidistant spaces The multiline command The multiline command takes the following form multiline n 71 Y1 215 Ins Yn gt Zn It draws a series of lines through the n points 1 y1 21 2 Y2 22 Zn Yn Zn It thus accepts a variable number of arguments depending on the value of n This exposes one of the nasty quirks of C since no type checking
129. nd for having initiated McStas in the first place Essential support has also been given by Prof Robert McGreevy ISIS Apart from the authors of this manual also Prof Per Olof Astrand NTNU Trondheim has contrubuted to the development of the McStas system 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 at mcstas risoe dk or consult the McStas home page 2 A special bug request reporting service is available 3 If you appreciate this software please subscribe to the neutron mc risoe dk 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 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 1 10 contributors Several people outside the core developer team have been contributing to McStas 1 10 e Thorwald van Vuure ILL contributed his PSD_Detector comp component a physi cal detector model e Chama Hennae ENSIMAG worked with Emmanuel Farhi on the new Virtual_mcnp_input comp and Virtual_mcnp_output comp for handeling MCNP event files e Ludovic Giller and Uwe Filges PSI contributed Source_multi_surfaces comp a source component with multiple surface areas with individ
130. 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 6 5 10 and all component definitions can be found on the McStas web page 2 and 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 e geometric intersection time computations e mathematical functions e random number generation Riso R 1416 rev ed EN 77 e physical constants e coordinate retrieval and operations e file generation routines for monitors e data file reading 6 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 dj d2 SETTING PARAMETERS s1 52 This declares the definition and setting parameters of the component The parameters can be accessed from all sections of the component see below as well as in EXTEND sections of the instrument definition see section 6 3 Setting parameters are translated into C variables usually of type double in the generated simulation program so they are usually numbers Definition parameters are translated into define macro definitions and so c
131. ng simulation software that would fulfill 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 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 measurement techniques neutron scattering provides a large variety of spectrometers to probe structure and dynamics of all kinds of materials Unfortunately the neutron flux is often a limitation in the experiments This then moti vates instrument responsibles to improve the flux and the overall efficiency at the spec trometer positions and even to design new machines Using both analytical 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 is possible to identify clearly the purely elastic structure contribution from the quasi elastic and inelastic one dynamics What a
132. ngs 1 Reflectivity 0 1 S q w files for Isotropic Sqw component Data q o S q 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 96 Riso R 1416 rev ed EN Chapter 8 Instrument examples Here we give a short description of three selected instruments We present the McStas versions of the Ris standard triple axis spectrometer TAS1 8 2 and the ISIS time of flight spectrometer PRISMA 8 3 Before that however we present one example of a component test instrument the instrument to test the component V_sample 8 1 These instrument files are included in the McStas distribution in the examples directory All the instrument examples there in may be executed automatically throught the McStas self test procedure see section 3 5 The list of instrument examples has been extended considerably see the Neutron Site menu in mcgui See page 5 1 8 1 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 The instrument consists of a narrow source a 60 collimator
133. nitialized 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 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 Table 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 reached after reading the nNrows lines 120 Riso R 1416 rev ed EN e Table Read_Offset_Binary amp T able filename type block amp offset Nrows Neolumns 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 neotumns elements No text header should be present in the file e Table_Rebin amp 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 Table x n looks for the closest x value in the first column index 0 and ex
134. nt performances but require the user to install MPI e when using SMP machines multi processor machines McStas may distribute the simulations among CPU s using multi threading mechanism Even though most systems now support multi threading i e do not require specific installation the performances are not as good as with MPI Last but not least you may run simulations manually on a number of machines and merge them subsequently Once the distributed simulation has been completed you may merge their results using the mcformat see section 5 4 9 in order to obtain a set of files just as if it had been executed on a single machine 5 6 1 Distribute mcrun scans ssh grid Unix only This is an experimental option to distribute scan steps on a set of machines using ssh connections To use this option you will need 1 A set of unix machines of the same architecture binary compatible All machines should have the same McStas distribution installed 2 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 dsaon master node enter no passphrase and add resulting ssh id_dsa pub to ssh authorized_keys on all the slave nodes 3 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 machine
135. ntents 6 5 3 The SHARE section SHARE nt C code shared declarations variables definitions functions These should not be OUTPUT parameters ht 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 occurence 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 80 Riso R 1416 rev ed EN same component for instance guide elements If the declarations were in the DECLARE section McStas would duplicates 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 6 5 4 The INITIALIZE section INITIALIZE At C code initialization ht This gives C code that will be executed once at the start of the simulation usually to ini tialize any variables declared in the DECLARE section This section is optional Component setting parameters may be modified in this section affecting the rest of the component 6 5 5 The TRACE section TRACE At C code to compute neutron interaction
136. ntioned after the positioning GROUP and EXTEND The jump may depend on a condition COMPONENT name comp p1 1 p2 2 AT JUMP reference WHEN condition in which case the instrument TRACE will jump to the reference when condition is true The reference may be an instance name as well as PREVIOUS PREVIOUS n MY SELF NEXT and NEXT n where n is the index gap to the target 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 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 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 76 Riso R 1416 rev ed EN
137. o conflicts occur between different component definitions or between component and instrument definitions It is thus possible and usual to use a component definition multiple times in an instrument description Beware about variable type conversion when setting numerical parameter values as in pi 12 1000 In this example the parameter p1 will be set to 0 as the division of the two in tegers is indeed 0 To avoid that use explicitely floating type numbers as in p1 12 0 1000 The McStas compiler 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 5 2 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 Zinclude not within embedded C blocks The physical position of a component is specified using an AT modifier following the com ponent declaration 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 AT x y z ABSOLUTE Any C expression may be used for x y and z The AT modifier is
138. o make use of the SCATTER keyword each time a component uses the neutron scatters detects within component definitions see section 6 5 6 4 2 Duplication of component instances 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 To gether with JUMPs see below there is 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 explicitely entered in order to avoid component overlaping The syntax for instance copy is COMPONENT name COPY instance name where instance_name is the name of a preceeding 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 74 Riso R 1416 rev ed EN COMPONENT name COPY instance name parl 0 par2 1 which will override the original instance parameter values The EXTEND GROUP JUMP and WHEN keywords if defined for the copied instance will override the original setting In the case where there are many duplicated components all originating from the same instance there is a mechanism for automating copied instance names COMPONENT COPY root_name COPY instance name will catenate a unique number to root_name avoiding name conflicts
139. oices in the pop up Dialog The mcdisplay front end will then require the Perl PGPLOT and either Scilab or 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 5 4 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 thus useful to get a quick overview of the simulation results In the simplest case the front end is run simply by typing mcplot This will plot any simulation data stored in the current directory which is where simula tions store their results by default If the dir or file options have been used see section 5 3 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 VRML Matlab and Scilab using either the pPLOTTER option e g mcplot pScilab file or using the current MCSTAS_FORMAT environment variable Moreover the drawing back end program will also be set depending on the file extension see Table 5 3 It should be emphasized that mcplot may only display simulation results with the format that was chos
140. omparison of a simulation with a standard experiment from TAS1 The mea surement series constitutes a complete alignment of the spectrometer using the direct beam and scattering from V and Al2O3 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 Riso R 1416 rev ed EN 99 Focusing monochromator Analyser o 3 Detector Source Collimator Slits Sample Figure 8 3 A sketch of the TAS1 instrument 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 In contrast a simulated 26 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 Fig
141. on plot or analyze it and decide to interupt 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 interupted the ratio field of the monitored data will provide the level of achievement of the computation for instance 3 33e 05 1le 06 Intensities are then usually to be scaled accordingly by the user Additionally any system error will result in similar messages giving indication about the occurence of the error component 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 5 3 4 Optimizing simulation speed There are various ways to speed up simulations e Optimize the compilation of the instrument as explained in section 5 2 4 e Execute the simulation in parallel on a computer grid or a cluster with MPI or multi threading as explained in section 5 6 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 sec
142. on and setting parameters of a component may be given a default value Parameters with default values are called optional parame ters 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 param value For example 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 defi nitions 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 6 5 2 The DECLARE section DECLARE ral C code declarations variables definitions functions These are usually OUTPUT
143. on of the beam in the cylindrical sample Example mcrun vanadium_example instr ROT 0 Parameters INPUT PARAMETERS ROT deg Rotation angle of the PSD monitor Link The McStas User manual The McStas tutorial 0 7End FOO GOOG ooo o ooo ooo IGI GI II Ak ak kf k The line below defines the name of our instrument Here we have a single input parameter ROT FINE INSTRUMENT vanadium_example ROT 0 The DECLARE section allows us to declare variables in c syntax Here coll_div collimator divergence is set to 60 degrees DECLARE double coll_div 60 Ag Here comes the TRACE section where the actual instrument is defined TRACE The Arm class component defines reference points in 3D space Every component instance must have a unique name Here arm is used This Arm component is set to define the origin of our global coordinate system AT 0 0 0 ABSOLUTE co MPONENT arm Arm AT 0 0 0 ABSOLUTE Next we need some neutrons Let s place a neutron Riso R 1416 rev ed EN 71 source Refer to documentation of Source_flat to understand the different input parameters The source component is placed RELATIVE to the arm component meaning that modifying the position or orientation of the arm will also affect the source component and other components after that one COMPONENT source Source_
144. ond simulation part Use the Virtualinput 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 sam pling can be 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 prefered whenever possible at least in the beginning of a simulation project 40 Ris R 1416 rev ed EN 5 3 5 Optimizing instrument parameters Often the user may wish to optimize the parameters of a simulation e g find the optimal curvature of a monochromator or the best geometry of a given component 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 adviced to be cautious when interpreting the optimization results 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 Simpex Method in Multidimensions 43 44 which is a geometric optimization method somewhat similar to genetic algo
145. onment variable may be set to the name of the C compiler to use this must be an ANSI C compiler This will also be used for the automatic compilation of McStas simulations in mcgui and mcrun e CFLAGS may be set to any options needed by the compiler eg for optimization or ANSI C conformance Also used by mcgui mcrun e PERL may be set to the path of the Perl interpreter to use To use these options set the variables before running configure Eg setenv PERL pub bin perl5 configure It may be necessary to remove configure s cache of old choices first rm f config cache If you experience any problems or have some questions or ideas concerning McStas please contact peter willendup risoe dk or the McStas mailing list at neutron mc risoe dk 20 Riso R 1416 rev ed EN 3 5 Finishing and Testing the McStas distribution Once installed you may check and tune the guessed configuration stored within file e MCSTAS tools perl mcstas_config perl on Windows systems e MCSTAS tools perl mcstas_config perl on Unix Linux systems where MCSTAS is the location for the McStas library You may on Linux systems ask for a reconfiguration e g after installing MPI Matlab with the commands e g cd MCSTAS tools per1 sudo mcstas_reconfigure On Windows systems the reconfiguration is performed with the mcconfig p1l command The examples directory of the distribution contains a set of instrument examples These are used for t
146. parately This also equivalently stands for Scilab using the get_sim file function the exec call is required in order to compile the code scilab gt exec mcstas sci 1 s get_mcstas scilab gt exec mcstas sci 1 s get_mcstas plot and for IDL idl gt s mcstas idl gt s mcstas plot See section 5 4 4 for an other 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 5 3 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 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 lt user gt 1382777140 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 possible to send one of the signals listed in Table 5 4 using the kill unix command or the functionalities of your process manager e g kill USR2 13277 This will
147. ponents files transformed into valid variable names e g containing only letters digits and the character except for the first character which may only be a letter In this tree you will find the monitor names which fields contain the monitored data The usual structure is For instance in most case the simulation location is mcstas m which turns into field m mcstas 56 Riso R 1416 rev ed EN s instrument simulation comp_name file name For instance reading the data from a test instrument using Matlab format will look like matlab gt s mcstas or mcplot mcstas m from the terminal matlab gt s s Format Matlab with text headers URL http neutron risoe dk Editor farhi on pcfarhi Creator test test instr McStas 1 9 Nov 15 2005 simulation Date 1 0529e 09 File mcstas test 1x1 struct EndDate 1 0529e 09 class root matlab gt s test m_mcstas monitor1 monitor1_y_kz ans Date 1 0529e 09 File gt monitor1l y_kz type array_2d 20 10 ratio gt 1e 06 1e 06 Signal gt Min 0 Max 5 54051e 10 Mean 6 73026e 13 statistics X0 0 438302 dX 0 0201232 YO 51019 6 dY 20557 1 matlab gt eval s test m_mcstas monitor1 monitor1_y_kz matlab gt dX ans 0 0201232 The latter example accesses the data from the monitor1 y_kz file written by the monitor1 component in the test instrument during the
148. 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 unforeseen 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 specially designed for simulating neutron scattering instruments Simulations are written in this meta language by the user and the McStas compiler au tomatically translates them into efficient simulation programs written in ANSI C In realizing th
149. r_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 gt 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 5 4 Using simulation front ends McStas includes a number of front end programs 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 mcstas2vitess McStas to Vitess component translation utility mcconvert Matlab lt gt Scilab script conversion tool When used with the h flag all tools display a specific help SEE ALSO mcstas mcdoc mcplot mcrun mcgui mcresplot mcstas2vitess DOC Please visit http www mcstas org An extended set of front end programs is planned for future versions of McStas including a NeXus data format option 45 42 Ri
150. re 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 analytical corrections 24 Monte Carlo techniques provide a mean to evaluate some of these quantities The technicalities of Monte Carlo simulation techniques are explained in detail in Chapter 4 1 2 1 The goals of McStas Initially the McStas project had four main objectives that determined its design 10 Riso R 1416 rev ed EN 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
151. re 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 78 Riso R 1416 rev ed EN Using OUTPUT PARAMETERS is highly recommanded for DECLARE and internal global com ponent variables and functions in order to prevent that instances of the same component use the same variable names Moreover see section 6 5 2 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 STATE PARAMETERS 2 y Z Uz Vy Uz t 1 S2 P This declares the parameters that define the state of the incoming neutron The task of the component code is to assign new values to these parameters based on the old values and the values of the definition and setting parameters Note that s and sg are obsolete and stand for sz and sy members of the polarisation vector To access sz use POLARISATION PARAMETERS Sz Sy 5z This line is necessary only if the component handles polarisation of neutrons and thus modifies the spin vector For an instrument to handle polarisation correctly it is only required that one of the components contains this line Optional component parameters Just as for instrument parameters the definiti
152. rect amp vz amp v amp vz amp dQ aimz aim 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 DECLARE or SHARE section Tables are structures of type tTable See read_table lib h file for details t_Table structure most important members double data Use Table_Index Table i j to extract i j element long rows number of rows long columns number of columns char header the header with comments char filename file name or title double min_x minimum value of 1st column vector double max_x maximum 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 amp Table filename block reads numerical block number block 0 to catenate all data from text file filename into Table which is as well i
153. required Rotation is achieved similarly by writing ROTATED z Py 9z RELATIVE name This will result in a coordinate system that is rotated first the angle x in degrees around the x axis then 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 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 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 a y z RELATIVE PREVIOUS ROTATED x by 6 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 components 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 begining Riso
154. result in a message showing status here 33 achieved as well as the position in the instrument of the current neutron McStas pid 13277 Signal 12 detected SIGUSR2 Save simulation Simulation file file instr Breakpoint MyDetector Trace 33 37 333654 0 1000000 0 Date Wed May 7 00 00 52 2003 McStas Saving data and resume simulation continue 36 Riso R 1416 rev ed EN s seed Set the initial seed for the random number generator This may seed seed be useful for testing to make each run use the same random number sequence n count Set the number of neutron histories to simulate The default is ncount count 1 000 000 1e6 d dir Create a new directory dir and put all data files in that direc dir dir tory h Show a short help message with the options accepted available help formats and the names of the parameters of the instrument i Show extensive information on the simulation and the instru info ment definition it was generated from t This option makes the simulation output the state of every trace neutron as it passes through every component Requires that the t or trace option is also given to the McStas compiler when the simulation is generated no output files This option disables the writing of data files output to the terminal such as detector intensities will still be written 8 gravitation This option toggles the gravitat
155. rior to exectuting 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 Riso R 1416 rev ed EN 115 PROP _ZO Propagates the neutron to the z 0 plane by adjusting x y z and t accordingly from knowledge of the neutron velocity vz vy vz If the propagation time is negative the neutron ray is absorbed For components that are centered along the z axis use the _intersect functions to determine intersection time s and then a PROP_DT call PROP_DT dt Propagates the neutron through the time interval dt adjusting x y z and t accordingly from knowledge of the neutron velocity PROP_GRAV_DT dt Az Ay Az Like PROP_DT but it also includes gravity using the acceleration Ax Ay Az In addition to adjusting x y z and t also vax vy vz is modified ALLOW_BACKPROP Indicates that the next propagation routine will not re move the neutron ray even if negative propagation times are found Further propa gations 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 however Beamstop and it is mainly used by the MCDISPLAY s
156. rithms It is not as fast as the gradient method but is much more robust When using mcrun section 5 4 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 option From mcgui section 5 4 1 one should choose the Optimization execution mode instead of the Simulation or Trace mode Then speficy the instrument parameters to optimize by indicating their variation range min max e g Lambda 1 4 just like parameter scans The optimization accuracy criterion is controlled using the Precision entry box in the configuration options See Figure 5 7 Finally run the simulation The optimum set of parameters is then printed at the end of the simulation process Your 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 safier for it to indeed contain a high signal domain and be preferably symetric w r to that maximum Us
157. roach is correct If the components handled multiple scattering the polarization should be set to P 1 3 P where n is the number of scatterings A 5 Tests With New Components All the test instruments can be found in the McStas examples folder go to Neutron site tests in mcgui There are basically two kind of tests The first kind of tests shows that the polarizing component can reproduce the same results as a similar non polarizing component Test_Monochromators instr Intercomparison of Monochromator_flat and Monochro mator_pol Test_Pol_Bender_Vs_Guide_Curved instr Intercomparison of Guide_curved and Pol_bender The second type of test illustrates the polarizing capabilities of the component 114 Test_Magnetic_Constant instr Constant magnetic field Test_Magnetic_Majorana instr Linearly decreasing field with small transverse com ponent Test_Magnetic_Rotation instr Rotating magnetic field Test_Magnetic_Userdefined instr Example of how to make a user defined analytic magnetic field that can also depend on time Test_Pol_Bender instr Illustrates beam polarization with the Pol_bender Test_Pol_Set instr Tests Pol_set Test_Pol_Guide_Vmirror instr Illustrates beam polarization with the Pol_guide_vmirror Test_Pol_Mirror instr Illustrates beam polarization with the Pol_mirror Test_Pol_TripleAzis instr An example of a triple axis spectrometer with polarizing monochromators a vanadium sa
158. ror etc is also reported as for DETECTOR_OUT_OD Riso R 1416 rev ed EN 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 addi tional z axis Resulting data files are treated as 2D data but the 3rd dimension is specified in the type field 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 append the simulation parameters into file f see for instance Res_monitor Internal variable mcformat should be used as specified Please contact the authors for further information B 1 6 Ray geometry intersections e inside_rectangle amp z amp y x xw yh Return 1 if rw 2 lt x lt xw 2 AND yh 2 lt y lt yh 2 Else return 0 e box _intersect amp t1 amp t2 Y Z Ux Vy Uz dx dy dz Calculates the 0 1 or 2 intersections between the neutron path and a box of dimensions dz dy and dz centered at the origin for a neutron with the parameters Y Z Uz Vy vz The times of intersection are returned in the variables t and t2 with t lt tg 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 Y Z Ur Vy Vz T h Similar to box_intersect but using a cylinder of height
159. s lt file gt 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 4 Execute mcrun as normally appending multi or M will divide the N scanpoints across the machines in mcstas hosts localhost Each of the scan steps is executed on distant machines sending the executable with scp executing single simulations and then retrieving individual scan steps on the master machine Warning This option is considered experimental i e you are welcome to use it but be ready for trouble Note also that this is a unix only option in mcgui and mcrun it does not work on Windows 58 Riso R 1416 rev ed EN 5 6 2 Parallel computing MPI When computing N neutron rays with p computers each computer will simulate x neu trons As a result there will be p N neutrons simulated As a result McStas generates two kinds of data sets e intensity measurements internally represented by three values po p1 p2 where po p p2 are additive Therefore the final value of po is the sum of all local value of po computed on each node The same rule applies for p and po The evaluation of the intensity errors is performed using the final po p and pz arrays see Section 4 2 1 e event lists the merge of events is done by concatenation The MPI support requires to have MPICH recommanded or alternatively LAM MPI installed on a set of nodes T
160. s 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 dimentional monitors also store the error estimates and event counts as additional matrices Single point monitors output the neutron intensity the estimated error and the neutron 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 5 4 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 the 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 McStas ASCII format It contains all available information about
161. s 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 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 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 sci when using Scialb 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 5 4 4 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 sub directories 1 2 3 containing all data files output from the different simulations When the d option is not used no data files are written from the individual simu lations in order to save disk space e The mcrun test command will test your McStas installation accuracy and plot ter The h option will list valid options The mcrun front end requires a working installation of Perl to run
162. s of all the parameters for the component figure 5 9 See section 6 3 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 6 7 for how to write components to integrate well with this facility 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 To use the mcgui front end the programs Perl and Perl Tk must be properly installed on the system Additionally if the McStas PGPLOT back end is used for data format PGPLOT PgPerl and PDL will be 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 Riso R 1416 rev ed EN A7 Component definition Slit Rectangular slit Date June 16 1997 Lower x bound pmax m Upper x bound ymin m Lower y bound ymax m Upper y bound DESCRIPTION A simple rectangular slit No transmission around the slit is allowed a nn JN y RELATIVE ROTATED as a et PD CREE aay _ 9k Cancel Figure 5 9 Component parameter entry dialog 5 4 2 Running simulations on the commandline mcrun The mcrun front end mcrun pl on Windows provides a convenient command line interface for running simulations with the
163. same automatic compilation features available in the ncgui front end It also provides a facility for running a series of simulations while varying an input parameter The command mcrun sim args will compile the instrument definition sim instr if necessary into an executable simu lation sim out It will then run sim out passing the argument list args The possible arguments are the same as those accepted by the simulations themselves as described in section 5 3 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 assign ment 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 48 Ris R 1416 rev ed EN 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 simulation
164. so R 1416 rev ed EN 5 4 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 is started using simply the command mcgui The mcgui mcgui pl on Windows program may optionally be given the name of an instrument file When the front end is started a main window is opened se figure 5 2 This window displays the output from compiling and running simulations and also contains a few menus and buttons The main purpose of the front end is to edit and compile instrument definitions run the simulations and visualize the results The menus The File menu has the following features Open instrument selects the name of an instrument file to be used 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 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 Compile instrument forces a recompile of the instrument definition regardless of file dates This is for example useful to pick up changes in compon
165. t select Run simulation from the Simulation menu McStas will translate the definition into an executable program and 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 5 3 When using the Scilab or Matlab backends full 3D view 4PI PSD monitor PSD_4pi vanadium psd XO 0 214041 dX 103 684 YO 2 63483 dY 52 337 vanadium_psd vanadium psd 4PI PSD monitor 10 9 0 90 50 Lattitude deg 0 Lattitude deg 10 2 50 100 0 100 1 80 Longitude deg Longitude deg 102 9 9 1 80 Lattitude deg H i ai T 100 150 M HE i 150 100 50 0 Longitude deg Figure 5 3 Output from mcplot with PGPLOT Scilab and Matlab backends 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 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 pr
166. t 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 6 1 Nothing in the McStas metalanguage enforces this convention but if every component used different con ventions 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 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 vz 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 4 64 Riso R 1416 rev ed EN 6 2 Syntaxical conventions Comments follow the normal C syntax C style comments may also be used Keywords are not case sensitive for example DEFINE define and dEfInE are all equivalent However by convention we always write keywords in uppercase to distinguish them from identifiers and C language keywords In contrast McStas identifiers
167. tering Default is to use local SMP cluster optim Run in optimization mode to find best parameters in order to maximize all monitor integral values Param eters to be varied are given just like scans min max optim COMP Same as optim but for specified monitors This op tion may be used more than once optim prec ACCURACY Sets accuracy criteria to end parameter optimization default is 10 3 test Run McStas self test force compile Force to recompile the instrument Table 5 2 Additional options accepted by McStas simulations 38 Riso R 1416 rev ed EN McStas PGPLOT Scilab Scilab_binary Matlab Matlab_binary Octave Octave_binary IDL IDL_binary XML HTML VRML Tripoli MCNP Vitess McStas events sim SCi pro xml html wrl Original format for PGPLOT plotter may be used with f and d options Scilab format may be used with f and d options Scilab format with external binary files may be used with d option a option implicitly set Matlab format may be used with f and d options Matlab format with external binary files may be used with d option a option implicitly set Octave format may be used with f and d options Octave format with external binary files may be used with d option a option implicitly set IDL format Must be used with f option IDL format with external
168. the I switch for the McStas compiler 32 Riso R 1416 rev ed EN mcstas I home joe components I home joe neutron include name instr Multiple I options can be given as shown 5 2 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 stand alone program is not appropriate For such usage the McStas compiler 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 McStas 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 5 2 4 Running the C compiler After the source code for the simulation program has been generated with the McStas compiler it must be compiled with the C compiler to produce an executable The gener at
169. 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 com piler 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 com piler easier by in lining code and using variables in an efficient way As a result McStas simulations generally run quite fast often fast enough that further optimizations are not worthwhile Also optimizations are higly time and memory consuming during compila tion 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 6 Refer to section 5 3 4 for other optimization methods 5 3 Running the simulations Once the simulation program has been generated by the McStas compiler and an exe cutable has been obtained with the C compiler the simulation can be run in various ways The simplest way is to run it directly from the command line or shell 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 si
170. there will be overhead time due to the split and merge operations 60 Riso R 1416 rev ed EN 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 Here is a table showing some comparison between MPI and no MPI simulations The cluster is built with 2 bi xeon 2GHz machines resulting in 4 processors processors p duration T seconds notes 1 622 without MPI support 1 630 with MPI support run without MPI 1 620 with MPI support run with MPI 2 316 Overhead 6 seconds Tp 1 2 310 3 210 Overhead 3 seconds T 1 3 207 4 158 Overhead 3 seconds Tp 1 4 155 The results consistently show that there is a very small overhead when computing using MPI This overhead comes from the spread and the fusion of the computations For instance spreading a computation implies either an rsh or and ssh session to be opened on every node 5 6 5 McStas MPI Bugs and limitations Signals are not supported while simulating with MPI since asynchroneous events cannot be easily transmitted to all nodes Anyway depending on the MPI imple mentation you may force all nodes to synchronize and save data using the HUP signal kill HUP mcstasPID Some header of output files might contain minor errors The computation split does not ta
171. 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 T K2V 107 A my k vector A7 Velocity m s VS2E my 2e Velocity squared m s7 Neutron energy meV SE2V 2e mn Square root of neutron en Velocity m s ergy meV FWHM2RMS 1 1 8 log 2 Full width half maximum Root mean square standard deviation RMS2FWHM 8 log 2 Root mean square stan Full width half maxi dard deviation mum MNEUTRON 1 67492 107 kg Neutron mass my HBAR 1 05459 10784 Js Planck constant PI 3 14159265 T FLT MAX 3 40282347E 38F a big float value Riso R 1416 rev ed EN 123 Appendix 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 124 Arm A generic McStas component which defines a frame of reference for other components 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 Component Instance A named Component of a given Type inserted in an In strument description Definition parameter An
172. tracts in this row the n th element starting from 0 The first column is thus the x axis for the data It does not contain any interpolation method e Table Free amp T able free allocated memory blocks Available functions to read an array of vectors matrices in a text file are e Table Read_Array File amp n read and split file into as many blocks as necessary and return a tTable array Each block contains a single vector matrix This only works for text files The number of blocks in put into n e Table Free Array amp Table free the Table array e Table Info_Array amp Table 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 Table 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 BeO transmission as measured on IN12 Thickness 0 05 m k Angs 1 Transmission 0 1 wavevector multiply 0500 0 74441 0750 0 76727 1000 0 80680 Pree H 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 addition
173. tware 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 ANSI C The present version supports both continuous and pulsed source instruments and includes a library of standard components with in total around 100 components These enable to simulate all kinds of neutron scattering instruments diffractometers spectrometers reflectometers small angle back scattering for both continuous and pulsed sources The McStas package is written in ANSI C and is freely available for download from the McStas website 2 The package is actively being developed and supported by Ris Na tional Laboratory and the Institut Laue Langevin ILL The system is well tested and is supplied with several examples and with an extensive documentation Besides this manual a separate component manual exists 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 8 ResTrax 9 McStas 1 2 10 Vitess 11 12 and IDEAS 13 Their usage usually covers all types of neutron spec tro
174. two equations and the interaction potentials all the results presented in the following are derived in A 3 1 Example Nuclear scattering The nuclear scattering potential for a crystal is p 1 E Vn K yD exp ik Ria Ala z Piae Tia A 23 ld so that a 2 1 A a 2 exp ik Rid 5 Biala A 24 Bs exp i Ria Aja A 25 ld where I is the nuclear spin operator and the constants A and B are related to the nuclear scattering lengths bt and b as A I 1 bt Ib7 2I 1 and B b b7 2I 1 To calculate the polarization cross section and outgoing polarization we have to average over the nuclear spin which we assume is random oriented so that terms linear in three last terms in Eq A 21 disappears The scattering cross section ends up being see p 159 do dQ 1 y exp ie Ra Rya Aal 41y4a a Aal Aal zl Bal Lala 1 A 26 Ld where the first term is the coherent cross section and the second term is the site incoherent cross section Both terms are independent of P as expected for a system without a pre ferred internal direction The polarization in the final state is do oe _ P X eplir Ria Rya P Aal v saa Aa Aal S Bal faZa 1 dQ ara 12 A 27 Riso R 1416 rev ed EN 109 Comparing Eq A 26 and Eq A 27 we find that 1 The nuclear coherent polarization is the same as the initial polarization 2 The same is true for
175. ual spectrums Thank you guys This is what McStas is all about Third party software included in McStas are Riso R 1416 rev ed EN 7 e perl Math Amoeba from John A R Williams J A R Williams aston ac uk e perl Tk Codetext from Hans Jeuken haje toneel demon nl e scilab Plotlib from St phane Mottelet mottelet utc fr e and optionally PGPLOT from Tim Pearson tjp astro caltech edu The McStas project has been supported by the European Union initially through the XENNI program and the RTD Cool Neutrons program in FP4 In FP5 McStas was supported strongly through the SCANS program Currently in FP6 McStas is sup ported through the Joint Research Activity MCNSI under the Integrated Infrastructure Initiative NMI3 see the home pages 4 5 McStas is also supported directly from the construction project for the ISIS second target station TS2 see 6 8 Riso R 1416 rev ed EN Chapter 1 Introduction to McStas Efficient design and optimization of neutron spectrometers are formidable challenges Monte Carlo techniques are well matched to meet these challenges When McStas version 1 0 was released in October 1998 except for the NISP MCLib program 7 no exist ing package offered a general framework for the neutron scattering community to 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 sof
176. ulated with some other program but one would have to use the general form of Eq A 28 and Eq A 29 without the simplifying geometrical constraints for monochromators and guides A 4 New McStas Components The components written so far can be divided into four groups e Polarizers Components used to make the beam polarized e Monitors Unphysical detectors that can measure the polarization of the neutrons e Magnetic fields Components used to handle magnetic fields e Samples Samples that affects the polarization A 4 1 Polarizers Some of the most common ways of polarizing a beam have been implemented 112 e Set_pol This unphysical component can be used in two ways Either to hard code the polarization to the vector px py pz or when randomOn 0 to set the polar ization vector to a random vector on the unit sphere Monochromator_pol A monochromator that only does the n 1 reflection For each neutron it calculates the wavelength which would give Bragg reflection ABragg and it then calculates based on one mosaicity and one d spread the reflection probability given the neutrons actual A The reflection probability is a Gaussian in AX ApBrage With the peak reflectivity and polarization calculated as described in section A 3 2 NB Note that this monochromator reflects the neutrons billiard like In Monochromator_flat the mosaicity of the reflecting crystal is taken into account but the d spread is not taken
177. ule 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 4 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 within a certain solid angle interval AQ only these solid angles are used for the Monte Carlo choice of scattering direction According to Eq 4 9 the weight factor will then have to be changed by the amount 7 AQ 47 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 fina
178. ulty Matlab and Scilab back ends 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 and Scilab functions may be called from these language prompt with the same method as in section 5 3 e g matlab gt s mcplot matlab gt help mcplot scilab gt s mcplot matlab or scilab gt s mcplot mcstas m matlab or scilab gt mcplot s A full parameter scan simulation result or simply one of its scan steps may be displayed using the Scan step menu item When the nw option is specified a separate Matlab or Scilab window will appear instead of being launched in the current terminal This will then enable Java support under Matlab and Tk support under Scilab resulting in additional menus and tools To use the mcplot front end the programs Perl and either Scilab or Matlab are required 5 4 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 t
179. ument from three directions simultaneously can be shown using the multi option mcdisplay 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 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 units on the different axes may no longer be equal 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 particu
180. ument 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 example illustrates all possibilities DEFINE INSTRUMENT test d1 double d2 int i char s1 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 5 3 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 exa
181. ure 8 5 The result of a 26 scan on an AlgO3 powder sample in two axis mode is shown in Figure 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 8 3 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 illustrate 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 component is modified so that a global variable neu_color registers which crystal s
182. with component ht 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 prop agation 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 preceed the call to the PROP_ call inside the component When the neutron state is changed or detected for instance if the component 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 6 3 4 The SCATTER macro should be called with the state parameters set to the proper values for the scattering event For an example of SCATTER see the optics Guide component 6 5 6 The SAVE section SAVE ht C code to execute in order to save data ht Riso R 1416 rev ed EN 81
183. x 0 amp amp ymin 0 amp amp ymax 0 amp amp radius 0 fprintf stderr Slit s Error give geometry n NAME_CURRENT_COMP exit 1 ht TRACE Ae PROP_ZO if radius 0 amp amp x lt xmin x gt xmax y lt ymin y gt ymax radius 0 amp amp x x y y gt radius radius ABSORB else if p lt cut ABSORB else SCATTER hh MCDISPLAY Ae magnify xy if radius 0 double xw yh xw xmax xmin 2 0 yh ymax ymin 2 0 multiline 3 xmin xw double ymax 0 0 double xmin double ymax 0 0 double xmin ymaxtyh 0 0 multiline 3 xmax xw double ymax 0 0 double xmax double ymax 0 0 double xmax ymaxtyh 0 0 multiline 3 xmin xw double ymin 0 0 double xmin double ymin 0 0 double xmin ymin yh 0 0 multiline 3 xmax xw double ymin 0 0 double xmax double ymin 0 0 double xmax ymin yh 0 0 else circle xy 0 0 0 radius ht END 6 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 Riso R 1416 rev ed EN 87 6 6 1 Extending from the instrument definition If you only want to add something on top of the component existing behaviour the simplest is to work from the instrument definition TRACE section using the EXTEND modifier see section 6 4 1

User and programmers guide to the neutron ray-tracing

Contents

Download Pdf Manuals

Related Search

Related Contents