There are 3 modules to handle trajectories: spin_reset to set spin and 'color', of the trajectories, read_in to read the trajectories from a file and writeout to write the trajectories. The latter one is an alternative to creating the neutron trajectories by the module 'source'.
The module spin_reset (folder 'trajectories') is meant to reset the quantization direction of the spin at any point of the instrument. The quantization direction is set in the source module. If the beamline is bent, this direction is not the same any more relative to the beamline. Example: If one sets the quantization direction to the x-direction (beam direction) in the source and has a curved guide of 5°, these directions will deviate by 5° after the curved guide. But some modules require certain quantization directions relative to the surface. If the module spin_reset is used after the curved guide, the quantization direction can now be set along the beamline again, i.e. into the new x-direction.
A second option has been added to the module spin_reset: the colour marking certain trajectories can be reset.
The property 'colour' of the neutron trajectories is used in many modules to mark trajectories in order to distinguish them later on,
e.g. by monitoring or evaluating only trajectories of a certain colour.
Examples are:
source : mark the moderator that the trajectory comes from
chopper: mark the window that the trajectory passes
guide : count the number of reflections
sample (environment): distinguish between different scattering events
As one might investigate more than one of these effects in an instrument, it is necessary to reset the colour.
If you give '1' as 'number of colours', all trajectories will set to colour 1.
If you give 'N' colours, trajectory i (i>=1) will get colour (i mod N),
i.e. the first will get colour 1, the second colour 2, ... the Nthe number 'N', the (N+1)th again colour 1, and so on.
| Parameter Unit |
Description |
Range or Values |
Command Option |
| degree of polarization [%] |
percentage of polarisation: 0% unpolarized, 100% all spins point into the same direction | [0,100] | -P |
| polarisation direction X Y Z | X-, Y and Z-component of the polarisation direction, the norm of the vector should be 1 | [0,1] | -X -Y -Z |
| number of colours |
if zero, nothing happens if greater zero, the colour of the trajectories will be reset (to a value between 1 and this number) (for details see text above) |
>=0 | -c |
The module read_in can read the data of the output file or data sets written by writeout or a corresponding module in another simulation program.
It can read data of the same 5 formats: VITESS, McStas, MCPL, MCNP6, both as ASCII and binary data.
In any case it expects complete data sets, i.e. data sets with a reduced number of paramters as enabled in writeout for the VITESS format (see above) cannot be read.
Up to 3 files can be read. If nore than 1 file is used, their weights have to be set accordingly.
The weight should be proportional to the (started) number of trajectories and their sum should give 1.
The input file(s) can be also be read N times to start a longer simulation. Note that this gives a faked improvement of the resolution.
In this case the weights of the trajectories are divided by N to give the same total beam intensity.
For MCNP data, a normalization is foreseen to get correct absolute intensities.
In contrast to writeout, there is only one filter realized - by color (of the neutrons/trajectories), which only works for VITESS.
read_in is supposed to be used as the first module in a simulations thereby replacing a source module.
As it will often be the first module in the simulation of the second (or third) part on an instrument,
there is the option to give the file 'instrument.inf' of the first (two) part(s) of the instrument, so that a complete and correct 'instrument.inf' file for the whole simulation can be obtained.
Note that the name must be different from 'instrument.inf' to prevent overwriting.
read_in and writeout will replace input file and output file from VITESS 4.0 on.
The same information as described above is expected by read_in - except for the weight in MCNP format, where neutron counts are assumed. This can be normalised to [n/s] by the corresponding input parameter (see the following tables).
| Parameter Unit |
Description |
Range or Values |
Command Option |
| data format | Format in which the input was written | "VITESS" "McStas" "MCPL" "MCNP6" |
-f |
| storage format |
Format in which trajectories were written into the input file: in scientific/exponential form (e.g. 5.4321E03) or usual float format (5432.1) or binary form |
"exp" "float" "binary" |
-F | ASCII input file 1, 2, 3 |
Names of the input files containing the neutron trajectories for MCPL format only input file 1 is handled |
- | -A -B -D |
| Weight of the trajectories in file 1, 2, 3 |
If there is only one input file, then this should get the weight 1.0. If 2 input files resulting from simulation with 1 Mio. and 3 Mio. trajectories are combined, then 0.25 for the 1st and 0.75 for the 2nd would be the proper choice to get the correct flux |
0.0 - 1.0 | -a -b -c |
| repetition |
(optional) The trajectories will be written 'repetition' times to yield 'repetition' times as many neutrons for the simulations. The weight of each trajectory will be reduced by the same factor. |
>= 1 (int) default: 1 |
-R |
| Intensity factor [1/s] |
The weight of each neutron trajectory from the target-moderator simulation will be multiplied by this factor to yield correct absolute source flux values. This factor F = Ip,src/ NMCNP-Events can be calculated as the ratio of time averaged proton current to the number of protons simulated. |
>0 typical 1.0e8 default: 1.0 |
-I |
| Surface ID | Only for MCNP6: If a surface ID is given, only neutrons passing through this surface are read from the input file(s). | ≥-1 default: -1 (all neutrons) |
-s |
| read in color | (optional) Only trajectories of the given color are read. Color -1 means: all trajectories are read |
>= -1 (int) default: -1 |
-C |
| instrument input file | Specifies the instrument file of the previous part of the simulation. | any | --I |
| raytracing file | File containing IDs of the trajectories to ray-traced. The output of a writeout module can be used for example. | any | -r |
| kind of raytracing | defines if raytracing takes places and in which way - see help file called 'Raytracing'. | 'no' 'write trace files' 'only trace trajectories' |
-k |
The module writeout can be inserted between two other VITESS modules or put to the end of the instrument.
It records the output of the preceding module by writing data sets of trajectories (or 'neutrons' or 'events') into an ASCII or binary file.
The data can be written in 5 different formats: VITESS, McStas, MCPL and MCNP6.
For ASCII output, the separator (space or tab) and the data format (float or exponential) has to be specified.
It is possible to write all data sets, but there are also different options to select the trajectories that are written to this file
(see table Parameters for Module 'writeout').
In any case, all trajectories are written unchanged to the pipe for the following module, so the simulation is not disturbed by using this module.
There is the possibility to disable the module, i.e. suppress writing the output.
For VITESS, there is also the option to select the written parameters (see table Parameters for Module 'writeout').
Note that the output file needs something like 0.1 kByte per trajectory and may therefore become very large.
| Parameter Unit |
Description |
Range or Values |
Command Option |
| ASCII output file | Name of the output file containing the neutron trajectories | - | -A |
| Active? | "no": no output is written "yes": output file is written |
"no" "yes" |
-a |
| Header | "no": no header is written "yes": first 2 or 3 lines contain information, mainly about the content of the columns |
"no" "yes" |
-a |
| data format | The format in which the output file will be written | "VITESS" "McStas" "MCPL" "MCNP6" |
-f |
| storage format |
Data format in which float numbers are written to the output file "exp": exponential (scientific) representation, "float": floating point representation, "binary": binary format |
"exp" "float" "binary" |
-F |
| separator |
Character used to separate the numbers in a VITESS output file MCNP6 and McStas data are separated by 'space' |
"Space" "Tabulator" |
-S |
| Intensity factor [n/s] |
The weight of each neutron trajectory is divided by this factor to yield the counts in the MCNP simulation. The factor is: F = Isrc/ NMCNP-Events |
>0 typical 1.0e8 default: 1.0 |
-I |
| Surface ID | Only for MCNP6: this number is written as surface ID to the output file. If no number is given, 0 is written. | default: 0 | -s |
| Simulation name | Only for MCNP6: title of the simulation. this is written to the header of the output file. | default: 0 | -T |
| SSW reference file | Specifies the name of the SSW reference file to determine the file format | -r | |
| Columns | Choice of output parameters for VITESS format | - | -c |
| writeout color | (optional) Only trajectories of the given color are written to the output file. Color -1 means: all trajectories are written |
>= -1 (int) default: -1 |
-C |
| filter lambda min/max [Å] |
(optional) Only neutrons within the given wavelength range are read | >0 | -l -L |
| filter Y pos. min/max [cm] |
(optional) Only neutrons within the given horizontal space range are read | any | -y -Y |
| filter Z pos. min/max [cm] |
(optional) Only neutrons within the given vertical space range are read | any | -z -Z |
| filter hor. div. min/max [] |
(optional) Only neutrons within the given horizontal divergence range are read | any | -e -d |
| filter vert. div. min/max [] |
(optional) Only neutrons within the given vertical divergence range are read | any | -E -D |
| filter div. min/max [] |
(optional) Only neutrons within the given total divergence range are read | >=0 | -g -G |
To read and write data in MCPL format, the utiliy mcpl by Thomas Kittelmann is used (see MCPL-Homepage) which stores the trajectories in binary format. The interface does not allow options like using several input files, ASCII format, etc.
The following information is written for each trajectory (or neutron) in VITESS format:
column
1 ID of the trajectory. (e.g. AA000123456)
2 tracing information (T: tracing, N: no tracing)
3 'color' of the trajectory (reserved for the user's demands)
4 time of flight [ms]
5 neutron wavelength [Å]
6 intensity (or weight) [n/s] (represented by the trajectory)
7 - 9 x-,y-,z-coordinate of the position [cm] (with respect to the coordinate system provided by the module preceding writeout)
10 -12 x-,y-,z-coordinate of the flight dir. (direction cosinus)
13 -15 x-,y-,z-coordinate of the spin
column
1 intensity (or weight) [n/s] (represented by the trajectory)
2 - 4 x-,y-,z-coordinate of the position [m] (with respect to the coordinate system provided by the module preceding writeout)
5 - 7 x-,y-,z-coordinate of the speed [m/s]
8 time of flight [s]
9 -11 x-,y-,z-coordinate of the polarization
column
1 history [-] not used, 0 written
2 ID [-] not used, 0 written
3 weight [n/s] (represented by the trajectory)
4 neutron energy [MeV]
5 time of flight [shakes=1e-8s]
6 - 8 x-,y-,z-coordinate of the position [cm] (with respect to the coordinate system provided by the module preceding writeout)
9 -11 x-,y-,z-coordinate of the flight dir. (direction cosinus)
12 unused [-] not used, 0 written