PhysicsDepartment, TechnicalUniversityofDenmark ... · PDF filePhysicsDepartment,...

Click here to load reader

  • date post

    04-Aug-2018
  • Category

    Documents

  • view

    212
  • download

    0

Embed Size (px)

Transcript of PhysicsDepartment, TechnicalUniversityofDenmark ... · PDF filePhysicsDepartment,...

  • User and programmers guide

    to the neutron ray-tracing package McStas,

    version 2.0

    P Willendrup, E Farhi, E Knudsen, U Filges, K Lefmann

    Physics Department,

    Technical University of Denmark, 2800 Kongens Lyngby, Denmark

    November, 2012

    nMcStas

  • Abstract

    The software package McStas is a tool for carrying out Monte Carlo ray-tracingsimulations of neutron scattering instruments with high complexity and precision.The simulations can compute all aspects of the performance of instruments and canthus be used to optimize the use of existing equipment, design new instrumentation,and carry out virtual experiments for e.g. training, experimental planning or dataanalysis. McStas is based on a unique design where an automatic compilation processtranslates high-level textual instrument descriptions into efficient ANSI-C code. Thisdesign makes it simple to set up typical simulations and also gives essentially unlimitedfreedom to handle more unusual cases.

    This report constitutes the reference manual for McStas, and, together with themanual for the McStas components, it contains documentation of most aspects ofthe 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 simulationsperformed with the program.

    This report documents McStas version 2.0, released November, 2012

    The authors are:

    Peter Kjr Willendrup Physics Department, Technical University of Denmark, Kongens Lyngby, Den-mark

    Emmanuel Farhi Institut Laue-Langevin, Grenoble, France

    Erik Knudsen Physics Department, Technical University of Denmark, Kongens Lyngby, Den-mark

    Kim Lefmann Niels Bohr Institute, University of Copenhagen, Denmark

    as well as authors who left the project:

    Peter Christiansen Materials Research Department, Ris National Laboratory, Roskilde, DenmarkPresent address: University of Lund, Lund, SwedenKlaus Lieutenant Institut Laue-Langevin, Grenoble, FrancePresent address: Helmotlz Zentrum Berlin, GermanyKristian Nielsen Materials Research Department, Ris National Laboratory, Roskilde, DenmarkPresently associated with: MySQL AB, Sweden

    ISBN 9788755036796ISSN 01062840

    Information Service Department Ris DTU 2012

  • Contents

    Preface and acknowledgements 7

    1 Introduction to McStas 9

    1.1 Development of Monte Carlo neutron simulation . . . . . . . . . . . . . . . 9

    1.2 Scientific background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

    1.2.1 The goals of McStas . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    1.3 The design of McStas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

    1.4 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

    2 New features in McStas 2.0 15

    2.1 Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    2.2 Run-time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    2.3 Components and Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    2.3.1 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    2.3.2 New example instruments and Data files . . . . . . . . . . . . . . . . 16

    2.4 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    2.5 Tools, installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    2.5.1 New tool features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    2.5.2 Platform support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    2.5.3 Various . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    2.5.4 Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

    2.6 Future extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

    3 Installing McStas 19

    3.1 Getting McStas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

    3.2 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.3 Installation on windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.4 Installation on Unix systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

    3.4.1 Debian class systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

    3.4.2 Other Linux/Unix systems . . . . . . . . . . . . . . . . . . . . . . . 21

    3.4.3 Configuration and installation . . . . . . . . . . . . . . . . . . . . . . 22

    3.4.4 Specifying non-standard options . . . . . . . . . . . . . . . . . . . . 22

    3.5 Finishing and Testing the McStas distribution . . . . . . . . . . . . . . . . . 23

    DTU 3

  • 4 Monte Carlo Techniques and simulation strategy 25

    4.1 Neutron spectrometer simulations . . . . . . . . . . . . . . . . . . . . . . . . 25

    4.1.1 Monte Carlo ray tracing simulations . . . . . . . . . . . . . . . . . . 25

    4.2 The neutron weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

    4.2.1 Statistical errors of non-integer counts . . . . . . . . . . . . . . . . . 26

    4.3 Weight factor transformations during a Monte Carlo choice . . . . . . . . . 28

    4.3.1 Direction focusing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.4 Adaptive and Stratified sampling . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.5 Accuracy of Monte Carlo simulations . . . . . . . . . . . . . . . . . . . . . . 29

    5 Running McStas 31

    5.1 Brief introduction to the graphical user interface . . . . . . . . . . . . . . . 32

    5.1.1 New releases of McStas . . . . . . . . . . . . . . . . . . . . . . . . . 35

    5.2 Running the instrument compiler . . . . . . . . . . . . . . . . . . . . . . . . 35

    5.2.1 Code generation options . . . . . . . . . . . . . . . . . . . . . . . . . 36

    5.2.2 Specifying the location of files . . . . . . . . . . . . . . . . . . . . . . 36

    5.2.3 Embedding the generated simulations in other programs . . . . . . . 37

    5.2.4 Running the C compiler . . . . . . . . . . . . . . . . . . . . . . . . . 37

    5.3 Running the simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

    5.3.1 Choosing an output data file format . . . . . . . . . . . . . . . . . . 40

    5.3.2 Basic import and plot of results . . . . . . . . . . . . . . . . . . . . . 40

    5.3.3 Interacting with a running simulation . . . . . . . . . . . . . . . . . 41

    5.3.4 Optimizing simulation speed . . . . . . . . . . . . . . . . . . . . . . 44

    5.3.5 Optimizing instrument parameters . . . . . . . . . . . . . . . . . . . 45

    5.4 Using simulation front-ends . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

    5.4.1 The graphical user interface (mcgui) . . . . . . . . . . . . . . . . . . 48

    5.4.2 Running simulations on the commandline (mcrun) . . . . . . . . . . 53

    5.4.3 Graphical display of simulations (mcdisplay) . . . . . . . . . . . . . 55

    5.4.4 Plotting the results of a simulation (mcplot) . . . . . . . . . . . . . . 57

    5.4.5 Plotting resolution functions (mcresplot) . . . . . . . . . . . . . . . . 58

    5.4.6 Creating and viewing the library, component/instrument help andManuals (mcdoc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

    5.4.7 Translating McStas components for Vitess (mcstas2vitess) . . . . . . 59

    5.4.8 Translating McStas results files between Matlab and Scilab formats 60

    5.4.9 Translating and merging McStas results files (all text formats) . . . 60

    5.5 Data formats - Analyzing and visualizing the simulation results . . . . . . . 61

    5.5.1 McStas and PGPLOT format . . . . . . . . . . . . . . . . . . . . . . 61

    5.5.2 Matlab, Scilab and IDL formats . . . . . . . . . . . . . . . . . . . . 62

    5.5.3 HTML/VRML and XML formats . . . . . . . . . . . . . . . . . . . . 63

    5.5.4 NeXus format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

    5.6 Using computer Grids and Clusters . . . . . . . . . . . . . . . . . . . . . . . 64

    5.6.1 Distribute mcrun simulations on grids, multi-cores and clusters (SSHgrid) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

    5.6.2 Parallel computing (MPI) . . . . . . . . . . . . . . . . . . . . . . . . 66

    5.6.3 McRun script with MPI support (mpich) . . . . . . . . . . . . . . . 67

    5.6.4 McStas/MPI Performance . . . . . . . . . . . . . . . . . . . . . . . . 68

    4 DTU

  • 5.6.5 MPI and Grid Bugs and limitations . . . . . . . . . . . . . . . . . . 69

    6 The McStas kernel and meta-language 70

    6.1 Notational conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

    6.2 Syntactical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

    6.3 Writing instrument definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 74

    6.3.1 The instrument definition head . . . . . . . . . . . . . . . . . . . . . 74

    6.3.2 The DECLARE section . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

    6.3.3 The INITIALIZE section . . . . . . . . . . . . . . . . . . . . . . . . . 75

    6.3.4 The NEXUS extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

    6.3.5 The TRACE section . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

    6.3.6 The SAVE section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

    6.3.7 The FINALLY section . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

    6.3.8 The end of the instrument definition . . . . . . . . . . . . . . . . . . 78

    6.3.9 Code for the instrument vanadium example.instr . . . . . . .