User guide
On this page a short manual is presented that should allow users to get started with XMI-MSIM. Although the screenshots were obtained on a Mac, they should be representative for Windows and Linux as well. Significant divergences will be indicated. The following guide assumes that the user has already installed XMI-MSIM, according to the Installation instructions.
For Mac users: assuming you dragged the app into the Applications folder, use Finder or Spotlight to launch XMI-MSIM.
For Windows users: an entry should have been added to the Start menu. Navigate towards it in Programs and click on XMI-MSIM.
For Linux users: an entry should have been added to the Education section of your Start menu. Since this may very considerably depending on the Linux flavour that is being used, this may not be obvious at first. Alternatively, fire up a terminal and type:
xmimsim-gui
Your desktop should now be embellished with a window resembling the one in the following screenshot.
XMI-MSIM may also be started on most platforms by double clicking XMI-MSIM input-files and output-files in your platform's file manager, thereby loading the file's contents.
The main view of the XMI-MSIM consists of three pages that each serve a well-defined purpose. The first page is used to generate inputfiles, based on a number of parameters that are defined by the user. The second page allows for the execution of these files, while the third and last page is designed to visualise the results and help in their interpretation. The purpose of the following sections is to provide an in-depth guide on how to operate these pages.
The first page consists of a number of frames, each designed to manipulate a particular part of the parameters that govern a simulation.
The General section contains 4 parameters:
- Outputfile: clicking the Save button will pop up a file chooser dialog, allowing you to select the name of the outputfile that will contain the results of the simulation
- Number of photons per discrete line: the excitation spectrum as it is used by the simulation is assumed to consist of a number of discrete energies with each a given intensity (see Excitation for more information). This parameter will determine how many photons are to be simulated per discrete line. The calculation time is directly proportional to this value
- Number of interactions per trajectory: this parameter will determine the maximum number of interactions a photon can experience during its trajectory. It is not recommended to set this value to higher than 4, since the contribution of increasingly higher order interactions to the spectrum decreases fast. The calculation time is directly proportional to this value
- Comments: use this textbox to write down some notes you think are useful.
This interface allows you to define the system that will make up your sample and possibly its environment. XMI-MSIM assumes that the system is defined as a stack of parallel layers, each defined by its composition, thickness and density. Adding layers can be accomplished by simply clicking the Add button. A dialog will pop up as seen in the following screenshot:
The different elements that make up the layer are added by clicking on the Add button. A small dialog will emerge, enabling you to define a compound or a single element, with its corresponding weight fraction. In the following screenshot, I used CuSO4 with a weight fraction of 50 % to start with.
You may wonder at exactly which chemical formulas are accepted by the interface. Well the answer is: anything that is accepted by xraylib's CompoundParser function. This includes formulas with (nested) brackets such as: Ca10(PO4)6(OH)2 (apatite). Invalid formulas will lead to the Ok button being greyed out and the Compound text box gaining a red background.
After clicking ok, you should see something resembling the following screenshot:
You will notice that the compound has been parsed and separated into its constituent elements, with weight fractions according to the mass fractions of the elements.
In this example I added an additional 50 % of U3O8 to the composition and picked the values 2.5 g/cm3 and 1 cm for density and thickness, respectively, leading to a weights sum of 100 %. It is considered good practice to have the weights sum equal to 100 %. This can be accomplished by either adding/editing/removing compounds and elements from the list, or by clicking the Normalize button, which will scale all weight fractions in order to have their sum equal to 100 %. Your dialog should match with this screenshot:
When satisfied with the layer characteristics, press Ok.
X-ray fluorescence are quite often performed under atmospheric conditions. If so, it is of crucial importance to add the atmosphere to the system for several reasons:
- The atmosphere attenuates the beam and the X-ray fluorescence
- The intensity of the Rayleigh and Compton scatter peaks is greatly influenced by the atmosphere
- The photons from the beam as well as the fluorescence and the scattered photons will lead to the production of Ar-K fluorescence, a common artefact in X-ray fluorescence spectra. In some rare cases, one may even detect Xe fluorescence.
To add such a layer, click again on Add button. In the Modify layer dialog, add the composition, density and thickness of the air layer. This is shown in the next screenshot:
Clicking the Ok button should lead the following situation in the Composition section:
However, the ordering of the layers in the table is wrong: XMI-MSIM assumes that the layers are ordered according to distance from the X-ray source. This means that the first layer is closest to the source and all subsequent layers are positioned at increasingly greater distances from the source. This can be easily remedied by selecting a layer and then moving it around using the Top, Up, Down and Bottom buttons. The following screenshot shows the corrected order of the layers:
An important parameter in this table is the Reference layer. Using the toggle button, you select which layer corresponds to the one that is considered to be the first layer of the actual sample. In most cases, this will indicate the first non-atmospheric layer. The Reference layer is also the layer that is used to calculate the Sample-source distance in the Geometry section.
Layers can be removed by selecting them and then clicking the Remove button. Existing layers may be modified by either double-clicking the layer of interest or by selecting the layer, followed by clicking the Edit button.
Keep in mind that the number of elements influences the computational time greatly, especially when dealing with high Z-elements that may produce L- and M-lines.
Scrolling down a little on the Input parameters page reveals the Geometry section as shown in the next screenshot:
This sections covers the position and orientation of the system of layers, detector and slits. In order to fully appreciate the geometry parameters, it is important that I first describe the coordinate system that these position coordinates and directions are connected to (picture will be added later...):
- The coordinate system is right-handed Cartesian
- The z-axis is aligned with the beam direction and points from the source towards the sample.
- The y-axis defines, along with the z-axis, the horizontal plane
- The x-axis emerges out from the plane formed by the y- and z-axes
Now with this covered, let's have a look at the different Geometry parameters:
- Sample-source distance: the distance between the source and the Reference layer in the system of layers as defined in the Composition section
- Sample orientation vector: the normal vector that determines the orientation of the stack of layers that define the sample and its environment. The z component must be strictly positive
- Detector window position: the position of the detector window. This is seen as the point where the photons are actually detected and terminated by the detector. Keep this in mind when defining a collimator
- Detector window normal vector: the normal vector of the detector window. Should be directed towards the sample (unless you have a very good reason not to do so)
- Active detector area: this corresponds to the area of the detector window that is capable of letting through detectable photons. Should be provided by the manufacturer of your detector
- Collimator height: XMI-MSIM allows for the definition of a conical detector-collimator whose properties are determined by this parameter and the Collimator diameter. Setting either to zero corresponds to a situation without collimator. This height parameter is seen as the height of the cone, measured from the detector window to the opening of the collimator, along the detector window normal vector
- Collimator diameter: diameter of the opening of the conical detector collimator. The base of the collimator corresponds to the Active detector area
- Source-slits distance: XMI-MSIM defines a set of virtual slits, whose purpose is to define the size of the beam at a given point, based on the distance between these slits and the X-ray source, as well as the Slits size, defined by the next parameter. I recommend to have the Source-slits distance correspond to the Sample-source distance, since this way the beam, upon hitting the Reference layer, will have exactly the dimensions specified by Slits size (if using a point source!)
- Slits size: see previous parameter. Refers to the dimensions of the beam at the Source-slits distance. This parameter will be ignored when dealing with a Gaussian source (see Excitation section)
Next, there is the Excitation section, which is used to define the X-ray beam that irradiates the sample. The corresponding excitation spectrum is assumed to consist of a number of discrete energies, each with a horizontally and vertically polarized intensity, as well as a number of parameters that define the type and the aperture of the source. At runtime, the code will use the Number of photons per discrete line parameter to determine how many photons will be simulated per discrete energy. Adding, editing and removing discrete energies is handled through the buttons in the Excitation section. For example, we can change the settings of the default value by clicking the Edit button. The dialog contains the fields necessary to define a particular energy:
- Energy: the energy of this particular part of the excitation spectrum, expressed in keV
- Horizontally and vertically polarized intensities: the number of photons that are polarized in the horizontal and vertical planes, respectively. A completely unpolarized beam has identical horizontal and vertical intensities (such as those produced by X-ray tubes), while synchrotron beams will have very, very low vertically polarized intensities. For information on how to convert the total number of photons given the degree of polarization to the horizontal and vertical polarized intenties, consult Part 5 in our series of papers on Monte-Carlo simulations
- Source size x and y: If both these values are equal to zero, then the source is assumed to be a point source, and the divergence of the beam is completely determined by the Source-slits distance and Slits size parameters of the Geometry section. Otherwise the source is considered a Gaussian source, in which case the photon starting position is chosen according to Gaussian distributions in the x and y planes, determined by the Source size x and Source size y parameters
- Source divergence x and y: If these values are non-zero, AND the source is Gaussian, then the Source-slits distance takes on a new role as it becomes the distance between the actual focus and the source position. In this way a convergent beam can be defined, emitted by a Gaussian source at the origin. For the specific case of focusing on the sample the Sample-source distance should be set to the Source-slits distance.
In this particular case, I have changed the energy to 20.0 keV, and made the beam unpolarized by equalizing both intensities, as shown in the following screen shot. The source remains a point source.
The two following sections deal with absorbers, first absorbers that are optionally placed in the excitation path (for example a sheet of Al or Cu), and next the absorbers that are optionally placed in the detector path. This means that the former will reduce the intensity of the incoming beam, while the latter will reduce the intensity of the photons that hits the detector. It is important to realize that these absorbers are only used here for their attenuating properties, they are not considered as objects in the simulations so they cannot contribute fluorescence lines to the eventual spectrum! Adding, editing and removing absorbers is performed through an interface identical to the one seen in the Composition section, but without the Reference layer toggle button. New inputfiles will always have a Be detector absorber added, corresponding to the detector window commonly found in ED-XRF detectors.
The last section deals with the settings of the detector and its associated electronics, as can be seein in the following screenshot:
- Detector type: every detector comes with its own detector response function, which can be influenced by several detector and electronics parameters. XMI-MSIM offers some predefined detector response functions that its authors have found to be reasonably well for two detector types: Si(Li) and Si Drift Detectors. Generally speaking, our policy is to encourage users to implement their own detector response functions in the
xmi_detector_convolutesubroutine ofsrc/xmi_detector_f.F90in the source code - Live time: the actual measurement time of the simulated experiment, taking into account dead time
- Detector gain: the width of one channel of the spectrum, expressed in keV/channel
- Detector zero: the energy of the first channel in the spectrum (channel number zero)
- Detector Fano factor: measure of the dispersion of a probability distribution of the fluctuation of an electric charge in the detector. Very much detector type dependent
- Detector electronic noise): the result of random fluctuations in thermally generated leakage currents within the detector itself and in the early stages of the amplifier components. Contributes to the Gaussian broadening
- Pulse width: the time that is necessary for the electronics to process one incoming photon. This value will be used only if the user enables the pulse pile-up simulation in the Simulation controls. Although this parameter is connected to several detector and electronics parameters, typically the value is obtained after trial and error
- Max convolution energy: the maximum energy that will be considered when applying the detector response function. Make sure this value is 10-20 % higher than the highest expected energy in the spectrum
- Crystal composition: the composition of the detector crystal. Adding, editing and removing absorbers is performed through an interface identical to the one seen in the Composition section, but without the Reference layer toggle button. Will be used to calculate the detector transmission and the escape peak ratios
Once an acceptable inputfile is detected by the application, the Save and Save as buttons will become activated. If the file has not been saved before, clicking either of these buttons will launch a dialog allowing you to choose a filename for the input-file.
If the file was saved before, then clicking Save will result in the file contents will be overwritten with the new file contents.
Keep in mind that XMI-MSIM input-files have the xmsi extension (blue logo), while the output-files the xmso extension (red logo).
In order to start a simulation, the Input parameters page must contain a valid input-file description. This can be obtained by either preparing a new input-file based on the instructions in a previous section (and saving it!), or by opening an existing input-file by double clicking an XMI-MSIM input-file in your file manager or opening an input-file through the Open interface of XMI-MSIM.
Either way, the Simulation controls page should look as shown in the following screenshot:
