17. Glossary of Parameters

Each Analysis window is different since each requires different parameters to be configured before it can be run. However, all of them have the same structure (example window below), consisting of these parts:

trajectory box shows the path to the NetCDF file format trajectory that this analysis will be performed on.
Parameters are a group of options, all of which are explored in the following sections. These are the options which vary from analysis to analysis. The only parameters that exist on every analysis are Frames and Output files.
Buttons are situated at the bottom of each analysis and consist of these options:
- Help opens the source code documentation for the relevant class in an MDANSE window.
- Save opens a file browser that allows you to save the current analysis with the set options into a python script which can be run from the command line. More information about scripts in MDANSE scripts.
- Run starts the analysis and prompts you whether you want to close the window. The status of the analysis can be found in the Jobs panel, though there is a known bug where successful analyses do not show up.

../_images/10000001000003220000021BA346CFB73717C1BE.png

17.1. Frames

This parameter is always situated at the top of the analysis window, right below the trajectory box. It allows you to configure which frames in the trajectory are to be analysed. It consists of these three boxes:

First frame

Format: int Default: 0 Description: the frame from which the analysis will begin, the first frame taken into account.

Last frame

Format: int Default: the last frame in the trajectory Description: the frame until which the analysis proceeds. The last frame taken into account.

Frame step

Format: int Default: 1 Description: determines the periodicity of which steps are used and which are skipped. 1 means that all frames are read, 2 means every other is read, etc.

17.2. Q shells

Reciprocal vectors are used in MDANSE for the analysis related to scattering experiments such as dynamic coherent structure or elastic incoherent structure factor analysis. The Q vectors generator supported by MDANSE always generates Q vectors on Q-shells, each shell containing a set of Q vectors whose norm match the Q shell value within a given tolerance (typically given in a separate input labeled width.)

The following inputs can be used to define the number of Q shells and the average length of the Q vectors in each shell:

from

Format: float

Default: 0

Description: The lowest value of $|Q|$ to be used in Q-vector generation.

to

Format: float

Default: 10

Description: The highest value of $|Q|$ to be used in Q-vector generation.

by step of

Format: float

Default: 1

Description: The step by which $|Q|$ in incremented when changing from one Q-shell to the next one. Please keep in mind that the width input parameter should be adjusted as well when chaning the step.

The unit of the Q-vector length in MDANSE is $\text{nm}^{-1}$ .

17.3. Output files

../_images/100000010000030400000042DC1FC2D755A00B07.png

This is one of the two parameters that are present in each analysis, the other being Frames. It usually appears at the bottom of an analysis window (Analysis), right above the buttons. It consists of these three parts:

output files

Format: str

Default: mmtk_trajectory_directory_path\<trajectory_filename>_<analysis_acronym>

Here, mmtk_trajectory_directory_path is the path to the directory where the NetCDF file that is being used for analysis is located. The <trajectory_filename> is the name of the NetCDF file. <trajectory_filename> is the shortened name of the analysis, e.g. disf for dynamic incoherent structure factor. How this translates into practice can be seen in the picture above.

Further, if the above path already exists, (n) will be appended to the end of the file name, where n is the lowest number for which a file doesn’t exist. This way, no overwriting occurs.

Description: determines the location where the analysis results will be stored. Browse button can be used to find the location using a file browser.

Browse button opens a system file browser window, allowing the navigation of the filesystem.
output formats

Format: drop-down

Default: HDF5 (for analysis), NetCDF (for trajectory conversion)

Description: specifies the Input and output files in which the analysis results are saved. HDF5 file format, NetCDF file format, DAT file format, or cominbations of those can be selected. The name of these files is given in the ‘Basename’ string.

17.4. Creating selections

There are the following Selections in MDANSE, each of which provides a variety of ways to alter the analysis:

Axis Selection/Reference Basis
Atom Selection
Atom Transmutation
Atom Charges
Q Vectors (explored separately in the next section)

The ones relevant to the analysis are present in its window, but some can also be performed from Molecular Viewer. By default, there are no Selections saved in MDANSE; they all have to be created manually. Each selection is unique to a trajectory MMTK NetCDF file, but all selections are stored in the same folder, $APPDATA/mdanse. Therefore, if a selection is to be reuse, it is important to give selections unique names even when creating the same selection for multiple trajectories. To help with that, all existing saved selection can be viewed in the User Definition Viewer which can be accessed from the toolbar. To save a selection, type a name in the field next to the Save button, and then click on the button. This will save the selection without closing the window.

17.4.1. Axis Selection/Reference Basis

Inside an analysis window, Axis Selection looks like this:

../_images/10000001000003090000003B6471CB689476B467.png

The drop-down menu is used to choose one of the existing definitions. Only the definitions with the format matching the analysis, i.e. those with the same number of selected atoms as the analysis expects, will appear. New ones can be created by clicking on the New definition button, which will open the window below. The details of the currently selected definition can be viewed in the User Definition Viewer by clicking on the View selected definition.

../_images/100000010000024A000002509C35D54A8D72A4C8.png

When this window is opened from an analysis window, the ‘Number of atoms’ field at the top will be set to the number of atoms that must be selected for the selection to work in the analysis from whose window it was opened. The field will also not be editable. Thus, when the New definition button is clicked in Angular Correlation analysis, the field will be set to 2, because that is how many it requires.

The number of atoms indicates how many atoms from one molecule must be selected. To select an atom, click on the + button in the ‘Molecules’ list to show which atoms that molecule contains, and then double-click the atom. That will cause the chosen atom to appear in the ‘Selected atoms’ list, and its details in the box below. An atom can be removed from selection by clicking on it in the ‘Selected atoms’ list and hitting the Delete key on the keyboard.

../_images/100000010000024A0000024F4D31AD6A44D2DC96.png

Axis selection is available for Angular Correlation and Order Parameter analyses, which both require 2 atoms to be selected, and the Spatial Density analysis, which requires 3 atoms.

17.4.1.1. Output contribution per axis

../_images/10000001000003220000027563B8CBFF70E2089C.png

This is an option that is always and only available in analyses that use Axis Selection/Reference Basis. It is a checkbox and is by default unchecked. This represents that the analysis is performed normally, ie. the calculated value is averaged over the selected axes. If this box is checked, another output is generated by the analysis in which the values calculated for each axis are saved separately. This can then be plotted on a 3D graph.

17.4.2. Atom Selection

Atom Selection allows you to select any set of atoms and/or other particles. These selected particles are then the ones that are made the target of the analysis. There is no limit to which particles can be included in a selection, or to how many selections can be used simultaneously. There can even be none; Atom Selection is entirely optional.

Inside an analysis window, Atom Selection appears thusly:

../_images/100000010000030800000047DA737593A6C8ED75.png

The green button adds a line for another selection, allowing you to choose one more selection to apply to that analysis:

../_images/100000010000030200000070CC785E9ACCB53208.png

The line can be removed by clicking on the red button. The drop-down menu and the View selected definition button work the way they do in Axis Selection <link>. The Set new selection button opens the following window:

../_images/100000010000024B00000251035B45CB484FE36D.png

The Filter by field contains different ways to access the various particles in the loaded trajectory. Clicking on a filter will make all the relevant particles appear in the top right box:

../_images/10000001000002480000024FA666A56C2A7CF8F5.png

Clicking on the particles/groups in that window will highlight them and make them appear in the Selection box. Together with the buttons for logical operations, it is possible to make complex selections, like so:

../_images/100000010000024900000255AD8D31ECFB0A37B1.png

The large box below the Selection box should show information about your selection, but it is broken for complex selections. The box at the very bottom, next to the Save button, is used for naming the selection. Each selection must be named with a unique name. The Save button saves the selection for the loaded trajectory, but it will not close the Atom Selection window. Once selection has been saved, it should appear in the drop-down menu in the analysis window.

Atom selection is available for all the analyses for which Atom Transmutation is available, as well as all Trajectory analyses, General AutoCorrelation Function, Molecular Trace, Root Mean Square Fluctuation, Radius of Gyration, Solvent Accessible Surface, and Spatial Density.

17.4.3. Atom Transmutation

Atom Transmutation can be used to simulate the effect of isotopic substitution. By default, in the converted trajectory each chemical element corresponds to the weighted sum (using the natural abundances) of all its possible isotopes. You can use this option to force a given atom to be a particular isotope.

This selection appears very similar to Atom Selection inside an analysis window (as in figure below) and so can be operated the same way. In fact, it requires an Atom Selection to function. That is because Atom Transmutation gets applied to an Atom Selection.

../_images/10000001000003070000007D5FB1F7297C409C62.png

To use Atom Transmutation, simply select an Atom Selection in the grey drop-down menu on the left, and then choose the element into which the atoms in that Atom Selection will be transmuted from the white drop-down menu next to the red button. For example, the below Atom Transmutation will transmute all sodium ions into potassium ions:

../_images/10000001000002FC00000077E7EBAA5ADD00FF40.png

This parameter is available for the following analyses: Coordination Number, Current Correlation Function, Density Of States, Density Profile, Dynamic Coherent Structure Factor, Dynamic Incoherent Structure Factor, Eccentricity, Elastic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, General Auto Correlation Function, Mean Square Displacement, Neutron Dynamic Total Structure Factor, Order Parameter, Pair Distribution Function, Position Auto Correlation Function, Root Mean Square Deviation, Static Structure Factor, Velocity Auto Correlation Function, X-Ray Static Structure Factor.

17.4.4. Atom Charges

This selection works inside an analysis window exactly the same as Axis Selection/Reference Basis. The only difference is the window that opens when Set new selection button is clicked. The Partial Charges window appears as below, and allows you to edit the charges at each atom inside the system. To do that, simply click on a field in the charge column and type in a number. The change will be confirmed once you hit enter or click outside the field. Once all changes have been made, name the selection using the box at the bottom, then click the Save button, and finally close the window.

../_images/100000010000024900000250A7ED210266718E94.png

This parameter is only available for the Dipole AutoCorrelation Function analysis.

17.5. Q vectors

Similar to the selections above but specific to Scattering Plugins, Q vectors give the opportunity to change how the analysis is performed. Each window has a part like this:

../_images/10000001000003050000003F7D1CF6AF37C53021.png

This section must be filled for analysis to be able to run. Like for other selections, there are no definitions by default. Therefore, one has to be created by clicking on the New definition button. This will open a window like in one of the following subsections, which show how Q Vectors are defined for each type of Q Vector. There are many types, and it is up to you to choose which is the best for a given experiment.

Once a definition of choice exists, it can be selected from the drop-down menu. The View selected definition opens the User Definition viewer <link> at the currently selected definition.

17.5.1. Spherical Lattice Vectors

Generates a set of hkl vectors compatible with the simulation box and groups them in shells going from the minimum and maximum values provided by the user with the given step (the values have to be given in nm^-1). The maximum number of vectors in each shell must also be given. Increasing the number of vectors will improve the statistics of your result, but the calculation will also take longer. Note also that for the lowest values of |Q|, the number of hkl vectors available may be much smaller than this maximum number of vectors. The width defines the accepted tolerance for a shell, so often the value for the width will be the same as the step value. But it is also possible to give a much smaller width in order to ensure a “high Q resolution” around well-defined |Q| values.

This will be the usual choice whenever you want to compute the dynamical coherent structure factor on an isotropic sample (a liquid or a crystalline powder).

../_images/1000000100000312000002131D552DD432567B3E.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.

Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.2. Circular Lattice Vectors

Similar to Spherical Lattice Vectors, but in this case the vectors are generated only in a plane perpendicular to the two axes given.

../_images/1000000100000313000002B80FE3D39AE365B8F3.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
axis 1
- x-component
  
  Format: int Default: 1 Description: the x-components of the first axis used to specify the plane.
- y-component
  
  Format: int Default: 0 Description: the y-components of the first axis used to specify the plane.
- z-component
  
  Format: int Default: 0 Description: the z-components of the first axis used to specify the plane.
axis 2
- x-component
  
  Format: int Default: 0 Description: the x-components of the second axis used to specify the plane.
- y-component
  
  Format: int Default: 1 Description: the y-components of the second axis used to specify the plane.
- z-component
  
  Format: int Default: 0 Description: the z-components of the second axis used to specify the plane.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.3. Linear Lattice Vectors

Similar to Spherical Lattice Vectors and CircularLattice Vectors, but now the vectors are generated only along a specific direction determined by the axis given.

../_images/100000010000030F0000025C4113EA5B9835A7B9.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
axis
- x-component
  
  Format: int Default: 1 Description: the x-components of the specified axis.
- y-component
  
  Format: int Default: 0 Description: the y-components of the specified axis.
- z-component
  
  Format: int Default: 0 Description: the z-components of the specified axis.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.4. Miller Indices Lattice Vectors

Similar to spherical_lattice, as it generates integer hkl vectors, but provides extra flexibility in selecting the hkl values. For example, it can be used to generate only h00 vectors.

../_images/100000010000031100000260CCD5B8A592078403.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
h (and the same goes for k and l fields)
- from
  
  Format: int Default: 0 Description: the minimum value used to construct the range of h vectors.
- to
  
  Format: int Default: 0 Description: the maximum value used to construct the range of h vectors.
- by step of
  
  Format: int Default: 1 Description: the step used to construct the range of h vectors. If it is 1, every integer between from and to is placed into the range, if it is 2, every other, etc.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.5. Spherical Vectors

Similar to Spherical Lattice Vectors, but the generated hkl are not integers. This means that these vectors should never be used to compute any coherent property! But you can use them if you are only interested in single particle properties, as the dynamic incoherent or the elastic incoherent structure factor. They have the advantage that there are no limitations in the available values, so you will be able to generate always as many vectors as you want, including at low |Q|.

However, if you are interested in computing and comparing/combining both the dynamic coherent and incoherent structure factors, it is preferable that you generate a single set of vectors using the Spherical_lattice option and use the same set for both calculations.

../_images/10000001000003130000021078646D692A64AF83.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.6. Circular Vectors

Similar to Spherical Vectors, but in this case the vectors are generated only in a plane perpendicular to the two axes given.

../_images/1000000100000312000002D77678DDABC09BFDCA.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
axis 1
- x-component
  
  Format: int Default: 1 Description: the x-components of the first axis used to specify the plane.
- y-component
  
  Format: int Default: 0 Description: the y-components of the first axis used to specify the plane.
- z-component
  
  Format: int Default: 0 Description: the z-components of the first axis used to specify the plane.
axis 2
- x-component
  
  Format: int Default: 0 Description: the x-components of the second axis used to specify the plane.
- y-component
  
  Format: int Default: 1 Description: the y-components of the second axis used to specify the plane.
- z-component
  
  Format: int Default: 0 Description: the z-components of the second axis used to specify the plane.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.7. Linear Vectors

Similar to Spherical Vectors and Circular Vectors, but now the vectors are generated only along a specific direction determined by the axis given.

../_images/1000000100000312000002623129F3A7253B13AD.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
Q shells
n vectors

Format: int Default: 50 Description: the number of hkl vectors in each shell. Higher values result in higher accuracy but at the cost of longer computational time.
width

Format: float Default: 1.0 Description: the accepted tolerance of each shell. It is often identical to by step of.
axis
- x-component
  
  Format: int Default: 1 Description: the x-components of the specified axis.
- y-component
  
  Format: int Default: 0 Description: the y-components of the specified axis.
- z-component
  
  Format: int Default: 0 Description: the z-components of the specified axis.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.8. Grid Vectors

Generates hkl vectors in the given range. They are grouped together according to the given qstep.

../_images/1000000100000312000002168C1C6AF89094EC7A.png

seed

Format: int Default: 0 Description: the RNG seed used to generate the vectors. This will ensure that the same random numbers are generated when the same seed is used, therefore making the calculation more reproducible.
hrange (and the same goes for krange and lrange fields)
- from
  
  Format: int Default: 0 Description: the minimum value used to construct the range of h vectors.
- to
  
  Format: int Default: 0 Description: the maximum value used to construct the range of h vectors.
- by step of
  
  Format: int Default: 1 Description: the step used to construct the range of h vectors. If it is 1, every integer between from and to is placed into the range, if it is 2, every other, etc.
qstep

Format: float Default: 0.01 Description: determines how the hkl vectors are grouped.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.5.9. Approximated Dispersion Vectors

Generates Q vectors along the line joining the 2 Q-points given as input.

../_images/1000000100000315000001D1BF3B69F011009E2F.png

generator

Format: drop-down Default: circular_lattice Description: the selection of which type of Q Vectors is being defined.
Q start (nm^-1) – the first of the two Q points (the same goes for the second one)
- x-component
  
  Format: int Default: 1 Description: the x-component of this Q point.
- y-component
  
  Format: int Default: 0 Description: the y-component of this Q point.
- z-component
  
  Format: int Default: 0 Description: the z-component of this Q point.
Q step (nm^-1)

Format: float Default: 0.1 Description: the increment by which Q is increased when tracing the line between the two points.
Generate button generates the hkl vectors based on the specifications above. It must be clicked before the vectors can be saved.
Name

Format: str Default: None Description: this is the empty box at the bottom of the window. It allows you to name the generated vectors. This must be set before the vectors can be saved.
Save button saves the generated vectors. It does not close the Q Vectors window.

17.6. Group coordinates

../_images/1000000100000323000002D1329469D922AFA541.png

Most of the analyses provide the Group coordinates option. The default value is atom, indicating that the calculation will be done using the atomic positions of all the atoms currently selected. But you can use this option to “merge” all the atoms belonging to a given group into a single position, which will be used then in the calculation. For example, this can be used to compute the mean square displacement of the molecular centres. Naturally, the availability of the different group options (group, residue, chain, molecule) will depend on the nature of your system and how MDANSE interpreted during the conversion step.

This parameter is available in the following analyses: Center Of Masses Trajectory, Density Of States, Dynamic Incoherent Structure Factor, Elastic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, General AutoCorrelation Function, Mean Square Displacement, Order Parameter, Rigid Body Trajectory, Root Mean Square Deviation, Root Mean Square Fluctuation, Velocity Auto Correlation Function.

17.7. Instrument resolution

This option is available in all the analyses performing a time Fourier Transform, e.g. for the calculation of the density of states or the dynamic structure factor. The following resolution shapes are supported in MDANSE at the moment:

Gaussian

The following formula is used for the calculation of the Gaussian function:

$G(\omega;\sigma,\mu) = \frac{\sqrt{2\pi}}{\sigma} e^{\frac{(\omega-\mu)^{2}}{-2\sigma^{2}}}$

The corresponding MDANSE input is:

('gaussian', {'mu': 0.0, 'sigma': 1.0})
Lorentzian

The following formula is used for the calculation of the Lorentzian function:

$L(\omega;\sigma,\mu) = \frac{2\sigma}{(\omega-\mu)^{2} + \sigma^{2}}$

The corresponding MDANSE input is:

('lorentzian', {'mu': 0.0, 'sigma': 1.0})
Pseudo-Voigt

The Pseudo-Voigt profile is expressed as a combination of Lorentzian and Gaussian functions:

$V_p(\omega) = \eta L(\omega,\sigma_L,\mu_L) + (1 - \eta) G(\omega,\sigma_G,\mu_G)$

The corresponding MDANSE input is:

('pseudo-voigt', {'eta': 0.5, 'mu_lorentzian': 0.0, 'sigma_lorentzian': 1.0, 'mu_gaussian': 0.0, 'sigma_gaussian': 1.0})
square

Square profile is a constant for points that are separated from $\mu$ by a distance less than $\sigma$ , and 0 otherwise:

$R(\omega) = \begin{cases} \frac{\pi}{\sigma} & if \ |\omega - \mu| \leq \sigma, \\ 0 & if \ |\omega - \mu| > \sigma. \end{cases}$

The corresponding MDANSE input is:

('square', {'mu': 0.0, 'sigma': 1.0})
triangular

Triangular profile drops linearly on either side of the $\mu$ argument and reaches 0 at the distance $\sigma$ from $\mu$ :

$R(\omega) = \begin{cases} \frac{2\pi}{\sigma^{2}} (\sigma - |\omega - \mu|) & if \ |\omega - \mu| \leq \sigma, \\ 0 & if \ |\omega - \mu| > \sigma. \end{cases}$

The corresponding MDANSE input is:

('triangular', {'mu': 0.0, 'sigma': 1.0})
ideal

The ideal resolution is expressed as a Dirac function:

$D(\omega) = \begin{cases} 1 & if \ \omega = 0, \\ 0 & if \ \omega \neq 0. \end{cases}$

The corresponding MDANSE input is:

('ideal', {})

You can choose the shape of the resolution (default is Gaussian), the centre position (default is at $\mu=0$ ) and the parameter defining the width of the function in frequency space ( $\sigma$ ). Since MDANSE uses frequency units, and most neutron scientists work with meV energy units, you can follow the simple conversion for the Gaussian function:

$\sigma (\text{FWHM}=1\text{meV}) \approx 0.65 \text{ps}^{\text{-1}},$

which means that $\sigma=0.65$ will correspond to a 1 meV resolution. The conversion factor is derived here:

(17.1) ${\sigma\approx\frac{\mathit{FWHM}{\lbrack\text{meV}\rbrack}}{2.35}\times 1.519\frac{\lbrack\text{ps}^{\text{-1}}\rbrack}{\lbrack\text{meV}\rbrack}\approx 0.065\text{ps}^{\text{-1}}},$

where the 2.35 is the $2\sqrt{2\log2}$ factor connecting the FWHM with the $\sigma$ parameter of the Gaussian function.

The selected resolution function (window function) in the frequency units is first inverse Fourier-transformed to produce its equivalent in time units

(17.2) $w(t) = \mathscr{F}(w(\omega) )$

The time-dependent function (e.g. velocity autocorrelation function for the DOS, or the intermediate scattering function fot the $S(Q,\omega)$ ) calculated in the analysis is then multiplied by the window function and Fourier-transformed to produce a spectrum in energy units.

(17.3) $I(\omega) = \frac{1}{2 \pi} \mathscr{F}(f(t)w(t))$

Therefore, apart from simulating the effect of the instrumental resolution in an experiment, the purpose of the instrument resolution is to smooth the function computed directly in time before performing its Fourier Transform into frequency space, in order to avoid numerical artefacts when FT noisy data.

This parameter is available for the following analyses: Current Correlation Function, Density of States, Dynamic Coherent Structure Factor, Dynamic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, Neutron Dynamic Total Structure Factor, Structure Factor From Scattering Function.

17.8. Interpolation order

Analyses that require atomic velocity data have an option to interpolate this data from atomic positions. By default, no interpolation is performed and instead MDANSE attempts to use the velocities stored int the NetCDF trajectory. Of course, depending on the way your simulation was set up, it is possible that the atoms velocities were not even stored in the output. It is still possible to derive the velocities of atoms from their positions at known time intervals, which is the subject of this section.

If an interpolation order is selected, MDANSE performs a numerical differentiation of the positional data. There are options to differentiate using 1^st to 5^th order.

Order 1

The first time-derivative of each point r(t_i) is calculated as

(17.4) ${\overset{.}{r}{\left( t_{i} \right) = \frac{r{\left( t_{i + 1} \right) - r}\left( t_{i} \right)}{\mathit{\Delta t}}}},$

where $\mathit{\Delta t}$ is the time step.
Order N = {2, 3, 4, 5}

MDANSE calculates the first time-derivative of each point r(t_i) (r = x,y,z) using the Nth-order polynomial, interpolating the N+1 points across r(t_i), where r(t_i) belongs to this set. Please see Ref [Ref36] for more information.

Interpolation order is available for the following analyses: Current Correlation Function, Density of States, Temperature, Velocity Auto Correlation Function. However, please note that due to the nature of the Current Correlation Function analysis, the interpolation there is more complicated, the details of which can be found in its section.

17.9. Normalize

../_images/100000010000031F00000248D8781028790CCDA5.png

This parameter provides the option to normalise the results of the analysis. By default, no normalisation is performed.

At the moment the normalisation is performed by dividing the number array by its first element. For the time correlation analysis the normalisation means that the correlation curve is divided by the value at $t=0$ , and the normalised function $f(t)$ will, as a result, fullfil the criterion $f(0)=1$ .

$f_{norm}(t) = \frac{f(t)}{f(t)\rvert_{t=0}}$

Normalisation is available for the following analyses: Current Correlation Function, General Auto Correlation Function, Position Auto Correlation Function, Velocity Auto Correlation Function.

17.10. Project coordinates

Use this option to use only the projection of the atom coordinates on a particular axis or plane. Note that the reference axis are the orthonormal X, Y, Z axes, which in most cases correspond to the usual axes of the simulation box. But if you have done a simulation using a non-orthorombic box, remember that the projection is done using the orthonormal X, Y, Z spatial axes as a reference, and not with the a, b, c “crystal unit cell” ones.

This parameter is available for the following analyses: Density of States, Dynamic Incoherent Structure Factor, Elastic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, Mean Square Displacement, Position Auto Correlation Function, Velocity Auto Correlation Function.

17.11. Weights

Most of the analyses include a weights option. The default value depends on the nature of the analysis. In many cases, it is set to ‘equal’, indicating that all atoms in the system contribute with the same weight to the computation of this property. But in scattering analysis, the default is b_coh for coherent and b²_inc for incoherent analyses. In any case, if needed the user can select any other numerical property from the MDANSE database to be used as weighting factor.

The weights apply to the chemical elements present in the system and are used to compute the total property. A particular analysis will compute the desired property P either for all the different elements identified in the system (in the case of a single particle analysis, such as the mean square displacement, the velocity autocorrelation function or the dynamic incoherent structure factor) or for all the possible pairs of different elements (in the case of a collective analysis such as the partial distribution function or the dynamic coherent structure factor). The partials P_i or P_ij are saved together with the total result, which is calculated as:

(17.5) ${P_{\mathit{total}} = \frac{\sum\limits_{i}{c_{i}w_{i}P}_{i}}{\sum\limits_{i}{c_{i}w_{i}}}}\\ \text{or}\\ {P_{\mathit{total}} = \frac{\sum\limits_{\mathit{ij}}{c_{i}{c_{j}w}_{i}w_{j}P}_{i}}{\sum\limits_{\mathit{ij}}{c_{i}c_{j} w_{i} w_{j} }}},$

where the sum runs over the number of different chemical elements, c_i is the number concentration of element i and w_i its weight.

This parameter is available in the following analyses: Current Correlation Function, Density of States, Density Profile, Dynamic Coherent Structure Factor, Dynamic Incoherent Structure Factor, Eccentricity, Elastic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, General Auto Correlation Function, Mean Square Displacement, Pair Distribution Function, Radius of Gyration, Rigid Body Trajectory, Root Mean Square Deviation, Static Structure Factor, Velocity Auto Correlation Function.

17.12. Running mode

This parameter allows for the configuration of the number of processors used to perform the analysis. By default, only one processor is used, but if more are configured, MDANSE performs the analysis using parallel processing, speeding it up.

Running mode is available for most analyses: all Dynamics analyses, all Trajectory analyses, all Thermodynamics analyses, Area Per Molecule, Coordination Number, Current Correlation Function, Density Profile, Dipole Auto Correlation Function, Dynamic Coherent Structure Factor, Dynamic Incoherent Structure Factor, Eccentricity, Elastic Incoherent Structure Factor, Gaussian Dynamic Incoherent Structure Factor, McStas Virtual Instrument, Molecular Trace, Neutron Dynamic Total Structure Factor, Order Parameter, Pair Distribution Function, Radius of Gyration, Rigid Body Trajectory, Root Mean Square Deviation, Root Mean Square Fluctuation, Spatial Density, Static Structure Factor, Voronoi, X-Ray Static Structure Factor.