VITESS 3 – Virtual Instrumentation Tool for the European Spallation Source

VITESS is a software widely used for simulation of neutron scattering experiments. Although originally motivated by instrument design for the European Spallation Source, all major neutron sources are available. Existing as well as future instruments on reactor or spallation sources can be designed and optimized, or simulated in a virtual experiment to prepare a measurement, including basic data evaluation. This note gives an overview of the VITESS software concept and usage. New developments are presented, including a 3D visualization of instruments and neutron trajectories, a numerical optimization routine and a parallelization tool allowing to split VITESS simulations on a computer cluster.


Introduction
Simulation of neutron scattering instruments is important for the development of new beamlines or update of existing instruments by enabling tests of new ideas and optimization of instrument components prior to construction. It can further be useful to conduct a virtual experiment to prepare a planned measurement, analyzing data obtained by a simulation of the instrument in the foreseen configuration including an adequate description of the sample and detector output. Therefore several software programs have been developed to perform such simulations, many of which are dedicated to a certain type of instruments. The Virtual Instrumentation Tool for the European Spallation Source (VITESS) [1,2] is one of the most widely used of these programs due to its general applicability and easy handling. Despite its name, all major reactor and spallation neutron sources are provided. A detailed implementation of processes involving polarized neutrons [3] is a particular strength of VITESS compared to most other programs, the most common of which are McStas [4] (which recently added a comparable treatment of polarized neutrons [5]), RESTRAX [6], NISP [7] and IDEAS [8]. VITESS is continuously validated by comparison with simulations from aforementioned other programs as well as against data from real experiments [9][10][11][12].
VITESS is an open source software available on the VITESS website [13] for Windows, Linux und Macintosh. It is mainly developed at the Helmholtz-Zentrum Berlin (formerly Hahn-Meitner-Institut) in Germany but also includes contributions made by advanced users from other facilities.
In the following, the concepts upon which the VITESS simulation package is build are described in section 2, before the latest developments regarding physical models and software features are introduced in sections 3 and 4.
2. Software concept and program layout VITESS uses a Monte Carlo ray-tracing technique in which neutrons are modeled as trajectories travelling from a source through an instrument onto a sample in which they are scattered and thereafter measured in a detector. They are assigned with a weight which corresponds to the intensity of the particular phase space element and makes sure that the flux normalisation throughout the instrument is always correct independent of the number of generated trajectories. This weight is modified at each interaction with an instrument componenent. Each component is represented by a module coming as a stand-alone executable in the software package. These modules run independently of each other, with each single module reading in neutrons from the previous one and passing them on to the next one. A whole instrument is simulated by running several modules sequentially in a pipe. This is done in packages of 10000 neutrons such that in a simulation with larger statistics as usual, all modules can run simultaneously. The properties of generated neutron trajectories can be examined by monitors at any point in the instrument, or written to a file to be read in again later by a new simulation continuing the instrument.
VITESS contains a graphical user interface (GUI) from which an instrument can easily be build by assembling the needed modules and which allows to perform complex simulations without knowledge of any scripting language. A VITESS simulation can however also be run either directly from the command line or via a shell, python, perl or tcl script to which an instrument description can be exported from the GUI. This can also be used to run VITESS on a computer cluster, and since release 3.1, a framework is provided to split the simulation on a cluster into several instances to save simulation time.
Different kind of neutrons can be studied separately by ray-tracing, which is done by selecting the neutrons of interest in a first run of the simulation and save them into a file, followed by a second simulation in which only those neutrons are processed. Monitor outputs like phase space diagrams or wavelength spectra are written as ASCII files which can be viewed directly from the GUI or analyzed with a preferred external software. A visualization of the neutron paths through the instrument is possible since release 3.0 and is described in more detail in section 4.1.
The effect of gravity is included in all components apart from the bender module, but can be switched off if the user sees this fit for a particular purpose.
VITESS provides tools to assist the users in performing a simulation by e.g. creating input files or calculating chopper phases. Documentation of all tools and modules as well as of the most important features can be accessed by a help button directly from the GUI, while short descriptions of each parameter of a module can be viewed by clicking on the parameter name. Running a simulation creates a log file in which the pipe command, the module parameters as well as the flux at the end of each module are documented for error diagnostics or later reference.

Improved modelling of physics processes
In VITESS 3, the description of physics processes or resulting behavior like emitted source spectra or reflectivity curves has been improved in several modules. This section summarizes the software development connected to a more realistic modelling, while improvements in the program's usage are described in section 4.

Neutron sources
The description of several sources has been updated, including e.g. new source characteristics of the FRMII reactor in Munich, Germany, and a new source module describing the CSNS spallation source in Dongguan, China. For the spallation neutron sources SNS and ESS, a choice between different moderator descriptions is now available.

Reflectometer sample
The reflectometer sample module was updated to include both the incoherent and offspecular scattering. The incoherent scattering probability p is calculated taking into account the inverse of the mean free path in the sample material µ provided by the user and the randomly chosen penetration depth of the trajectory in the corresponding sample x: p = 1−e −µx . The offspecular reflectivity mode can be used by providing a lookup table, which contains the reflectivity R(k z,i , k z,f ) as a function of the incoming wave vector k z,i = 2π/λ · sinθ i and the outgoing wave vector k z,f = 2π/λ · sinθ f .

Supermirror reflectivity and attenuation models
In VITESS 3, improved models describing the reflectivity of neutrons at supermirror coated plates as well as in case of no reflection their attenuation in the substrate material are implemented.
Before VITESS 3, the reflectivity of supermirrors was modelled as a linear decrease from R 0 at the critical angle θ C corresponding to a mirror coating m= 1 to a reflectivity value of R m at θ m = mθ C , followed by an instantaneous drop to zero for θ > θ m in the sm ensemble module, which describes an arbitrary configuration of flat supermirror plates. Parameters R m , θ C and θ m had to be given by the user. Reflectivity files used in the modules guide and bender allowed for a slower decrease broadened by a factor W =0: with a = Rm−R 0 mQ C −Q C and Q C = 4π/λ · sinθ C . The linear reflectivity decrease is however a simplification of the behavior seen in measurements of reflectivity curves of supermirror plates, therefore this model has now been extended by an additional term: where W , a, b and m 2 are linear functions of the mirror coating m 1 , which is now the only input parameter required. Parameters of the new models have been found by fits to experimental data performed by H. Jacobsen for McStas, and implemented in VITESS within comparison of simulation results in [12].
In the tool Generate Mirror Files, this new model is used in VITESS version 3.0 or newer if quadratic Swiss Neutronics description is chosen. In the sm ensemble module it is default from VITESS version 3.1 onwards, in which R 0 is also set to R 0 = 0.99 instead of formerly R 0 = 1. The reflectivity curves obtained with equation 2 for 1Å neutrons are shown in figure 1(a) for m-values between 2 and 6. In the sm ensemble module, neutrons that are not reflected can be transmitted with probability where µ (µ ic ) is the wavelength dependent (independent) part of the macroscopic attenuation and d ′ the pathlength of the neutron trajectory in the mirror, taking refraction into account. An improved description of the attenuation in sapphire is obtained by using instead of (3), where the constant c was again found by fitting this model to experimental data in contex of the McStas study [12]. Since the aforementioned study uses a mirror on sapphire substrate, an additional fit of the attenuation for silicon to data extracted from [14] has been performed for VITESS. The obtained attenuation is shown in figure 1(b) for three different wavelengths.
The old description of equation 3 can still be used by choosing neither silicon nor sapphire as mirror substrate (option "other").
3.4. Neutron detection 3.4.1. Detector geometry and output file The upgraded detector module implemented in VITESS 3.1 allows for more flexible geometries: instead of a 2D flat detector surface, a 3D volume detector can be build including several detection layers and a possibly non-perfect resolution in all three dimension. The overall shape of a detector module can either be "flat" (now meaning cubic) or cylindrical. A flat detector can now also be simulated with a substructure of detector tubes. The tube length is equal to either the detector height or width, and a tube geometry can be chosen with either circular or rectangular tube cross-sections. The different amount of detection material depending on the neutron position with respect to the center of a circular tube is taken into account. Space between circular tubes as well as tube walls are treated as vacuum, i.e. no detection is possible in these regions but also no unwanted scattering is simulated 2 . Layers can be shifted with respect to each other by half the tube diameter in order to minimize dead detector regions, as illustrated in the central picture of figure 2(a). The tube option is only available for an overall flat geometry.
In an overall cylindrical geometry, the cylinder axis can now be oriented along all three coordinate axes. Furthermore, the new const. phi option allows the pixel size in the dimension along the cylinder axis to be variable such that a constant angular width is covered by each pixel.
Several detector modules can be combined in an array to build any complex shape. Figure 2(b) shows an example consisting of two cylindrical and two flat detector modules.
An event mode detector output is written if a file name is given as Output filename. It contains a list of detected neutrons with their respective detected position and time as well as neutron weight and color.

Detection efficiency and resolution
The efficiency of neutron detection in the detector module of VITESS version 3.1 can be calculated from the total cross-section σ of neutron scattering with the chosen active detector material, a linear approximation of which has been extracted from cross-section tables from the National Nuclear Data Center [15] for 3 He, 10 B and 6 Li. For BF 3 or 3 He gas, the gas pressure and temperature have to be given as input parameters 2 Scattering from e.g. detector housing is not implemented in the detector module. However, background from a material layer between sample and detection material can be modelled by using the sample environment module.     from which the particle density N is calculated. For layers of solid material containing 10 B or 6 Li, the particle density has to be given directly. The probability of a neutron interaction with the detector material is then calculated as where L is the detector thickness in the direction along the neutron trajectory and l a random number between zero and L following a constant probability density distribution, determining the path length of the neutron in the detector before scattering. Compared to sampling the depth l directly from an exponential decay, this approach follows the VITESS philosophy of generating possible outcomes with the same probability and adjusting the weight accordingly to ensure that the tails of the probability distributions are sufficiently populated. Every neutron trajectory is split into N rep neutrons detected at different possible path lengths l in the detector material, with the number of repetitions N rep given as input parameter by the user. The normalization factor L/N rep can be interpreted as a length segment in which the interaction probability is constant, hence the calculated efficiency is more accurate for large N rep >1. Finally, the detection probability can be modified by the wavelength independent input parameter ǫ mod which can represent e.g. losses due to secondary particle detection after neutron scattering in a solid 10 B or 6 Li converter layer. Alternatively, by not choosing a defined detection material ("other "), the efficiency modifyer ǫ mod can be used as a mean detection efficiency of neutrons traversing the detector perpendicular to the detector surface. In this case the detection probability is wavelength independent.
As a third alternative, the detection efficiency can be set by the user via an input file containing the efficiencies for different neutron wavelengths. The probability of neutron detection is then independent of the path through the detector and the exact detector geometry.
The new module further uses 3D pixelization allowing the cloud of charge carriers to be detected in the wrong pixel by the new input parameters hor. resolution, vert. resolution and resolution in x. If one of these parameters in set to a value =0, the respective coordinate of the neutron position is changed to a Gaussian random number centered around the true position with width resolution. Shifting the output position to the closest pixel center is performed after this Gaussian smear. In case of a tube detector, a non-zero resolution is only allowed in the dimension along the tube axes.

New or improved program features 4.1. Visualization of instruments and neutron trajectories
A visualization of the instrument including neutron trajectories can be called from the GUI by the new Trajectories button. A prerequisite is an X3D viewer like the recommended instantreality. The visualization of the instrument ODIN at IFE, Norway as obtained with the instantreality viewer is shown in figure 3 as example.
The information about the location and type of interaction of neutron trajectories used for their visualisation can also be utilized to monitor the intensity loss and thus radiation along the instrument, e.g. in a neutron guide. This constitutes the first step towards a background estimation via an interface to a program that models the interaction of radiation and high energy particles with matter.

Numerical Optimization
The combination of VITESS simulations with an optimization routine is done such that the latter is the main program and calls the simulation in a subroutine. All files necessary to run a VITESS optimization can be found in the directory vitess/OPTIMIZATION, a 7-step recipe is available in vitess/Concepts/Optimization.pdf. Three optimization algorithms to choose from are currently implemented: two gradient methods and a metropolis algorithm. The gradient method opt grad determines gradients in the figure of merit by varying a parameter in variation steps defined by the user. This step size should be small enough to get a good estimate of the gradient, but large enough to avoid a false result dominated by statistical fluctuations. The adapted gradient method opt grad mc is modified in order to be more robust against statistical fluctuations in Monte Carlo simulations: a parameter is changed only if variation in both directions indicate the same gradient, and the step size is varied during the optimization. The metropolis algorithm searches the parameter space in a step size set by the user, accepting a new parameter value always if the figure of merit is improved, and if it is worse with a probability according to a kind of Boltzmann factor with a user-defined standard deviation of the measurement as temperature equivalent. Compared to gradient methods, the metropolis algorithm is less prone to deliver a local optimum, but more simulation steps are needed. The default mapping between optimization parameters p opt and simulation parameters p sim is a direct assignment: p opt = p sim . Other relations can be set by writing a dedicated function; this procedure is planned to be made more user-friendly in future VITESS versions.
The figure of merit is designed flexible: It is calculated from a signal file containing neutron intensity values I sign,i , like e.g. a monitor file recording neutrons with a certain divergence at the sample position, as

Parallel processing
Until VITESS version 3.1, parallel processing was only possible via so-called helper threads using several cores of the same computer [16]. With the most recent VITESS release, simulations can be split into several instances on a computer cluster by calling vitess/TOOLS/gridrun. The simulation is then divided into several pipes with less statistics, each of which is sent to the cluster by either SGE or ssh. A work directory is created in which all input files are copied, as well as subdirectories for each pipe in which the simulation results are stored. After completion of all simulations, the output files can be merged and the subdirectories are deleted.

Further improvements
New generic monitors monitor1D and monitor2D can be used to view any neutron parameter, and combine any two parameters in the latter. Furthermore, two filter parameters can freely be chosen and combined with a logical AND or OR. The monitor1D can create up to three monitor output files per module (to which the same filter settings are applied). These new generic monitor modules are planned to replace the sum of old monitor modules, but all are available for a transition period in VITESS 3. In the old one-dimensional monitor modules, the option all files [yes/no] has even been added which allows to create a separate monitor output file for each color present in the neutron beam. The use of color has been changed such that the value 0 is the default color value and -1 stands for all colors. A new brilliance monitor mon brilliance is available that writes the brilliance instead of the intensity. It can also monitor the brilliance transfer if a reference file is given, and calculates the average and peak brilliance which can be written into a flux file (but can also be found in the logfile).
A new guide module called guide ideal was written to describe guides with a perfect elliptic shape without the use of segmentation. The location of reflection points of neutron trajectories off the guide walls is calculated analytically. The module runs significantly faster compared to the regular guide module with a fine segmentation.
Creating a sm ensemble input file is made easier by the new tool Generate Extraction System in which position and orientation of supermirror plates can be given in a user-friendly, intuitive way. Although written with a bi-spectral extraction system in mind that consists of several stacked and bended mirror plates, this tool can be used for any configuration of supermirrors.
In the monochromator module monochr analyzer, a transition mode has been added so the transmitted neutron beam can be analyzed alternatively to the reflected neutrons.
The module writeout has been expanded such that trajectories can now be written in McStas format, and supplemented by a new module read in that can read trajectories from both VITESS and McStas output files.
Handling of the graphical user interface has further been improved: It is now possible to import an instrument description from a file containing the pipe command, to give modules a short descriptive name that appears in the module list to ease distinguishing between similar instrument components, and to select between different programs (gnuplot, shell) with which monitor files are viewed directly from the GUI.
Note that only the most important program improvements could be mentionen here; a complete list can be found in the release notes separately available for every VITESS release. Detailed descriptions of new and old features are further available in the documentation within the VITESS software package.

Summary
The software package VITESS is an important tool for the simulation of neutron scattering instruments. It is easy to use due to its graphical user interface, the flexible modular design as well as user-friendly components and tools. The program is under constant development and has made large progress in releases 3.0 und 3.1. New sources have been added and existing moderator descriptions updated, the reflectometer sample can simulate off-specular scattering and incoherent background, and more accurate reflectivity and attenuation models are used in neutron guides and supermirror plates. The detector module has been updated such that it allows more flexible geometries including an array of several detector banks, the detection efficiency can be calculated from the scattering cross-section of a chosen material and resolution effects can be taken into account. Visualization of the simulated instrument including neutron trajectories is now possible. A numerical optimization routine is provided to optimize instruments with respect to a flexibly designed figure of merit. Furthermore, parallel processing on a computer cluster is enabled to save simulation time. Several smaller improvements and new features further ensure VITESS staying a state-of-the-art program contributing to the development of cutting-edge neutron instrument design.