The MP_SQOM tool calculates the scattering functions of simulated (MD, phasefield etc.) crystalline systems, plots their maps and saves the corresponding numerical values (ASCII) and graphics (.PS, .PNG) for further use.

1/ INPUT

A number of initial settings is read from the accompanying .PAR file from several name lists. Typical input values are displayed below together with brief explanations following the exclamation mark:

&MP_GEN
 J_VERB = 1       ! (0/1) verbose command line output
 J_PROC = 0       ! requested number of OpenMP parallel processes, 0 = automatic
                  ! maximum (eg. 12 for a 12 core Xeon processor)

&MP_OUT
 J_WEIGHT = 2     ! 1 = uniform weighting, 2 = neutron b_coh; 3 = Xray form-factors
 J_LOGSC = 1      ! 1 = logarithmic scale for plots (0=linear)
 J_TXT = 0        ! 1 = accompany .PS output by recording map intensities to .TXT file
                  ! (always linear scale, speckle filter applied if active)
 J_GRID = 0       ! 1 = display grid overlay on PG_PLOT graphs
 PG_OUT = ‘vcps’  ! set device for color map output: PNG, TPNG, CPS, VCPS, NULL
                  ! (cf. PG_PLOT notes)

&MP_SQOM
 N_INT = 0        ! integration width in time (number of snapshots, 0 = automatic
                  ! choice NFILE/2)
 S_TRIG = 0       ! trigger level of the speckle filter (0 = OFF, 2 = log_2 ratio
                  ! between neighbours)
 J_ONEPH = 0      ! FT start mode, 0 = NUFFT (usual), 1 = one-phonon mode (very slow,
                  ! use for verification only), runtime toggle 0/1 available
 J_QSQ = 0        ! 0 = plot S(Q,ω)/Q^2 (recommended for better clarity of color
                  ! maps); 1 = keep the natural Q^2 trend of S(Q,ω)

A self-explaining dialogue guides through the specifications of the input data files. Data converted by both the CELL and the BULK input methods are eligible as input to MP_SQOM.

The actual data type and further information is retrieved from the header of the first data file in an input sequence. The user has to ensure that all the subsequent data files in the sequence are consistent with this information and that they are contiguous in time whenever energy-resolved outcome (S(Q,ω)) is the goal. In case of doubt the contents of the data files (header, individual atom data) can be verified using the MP_INSP tool.

2/ LATTICE SUMS AND TIME INTEGRALS

The Fourier sum over all atoms in the simulation box is calculated using the FINUFFT implementation of the non-uniform FFT (NUFFT) technique, which offers calculation speeds comparable to FFT over regular lattices. The calculation automatically assumes periodic continuation of the box and evaluates the sum only at space frequencies commensurable with the box size to avoid truncation effects. The BULK data case with an explicitly declared absence of periodicity (N_ROW = 1 1 1) forms an exception and has to be handled as an aperiodic object. In such a case the Q-space range of the maps is specified in inverse Angstroms rather than in number of Brillouin zones and a window function (Hann) in real space is activated automatically to damp the truncation oscillations. This implies a factor of 2 loss in Q-resolution but permits to handle real space objects without any constraints, neither on their internal structure nor on the form of the simulation box.

Whenever energy-resolved maps are to be produced, MP_SQOM will calculate Fourier transform of a time-sequence of S(Q) snapshot maps. As the MD dumps are effectuated with a constant time step, this can be effectuated by conventional FFT, using a window function (Hann) to damp the truncation effects. The automatic choice is to take an integral over half the length of the time series and, after multiplication by the complex conjugate of the central frame transform, to accumulate a sliding sum such integrals over the other half. This choice can be modified within the “burried” options (cf. option 10 below). As a consequence the frequency resolution will correspond to the reciprocal of 1/4 of the total time series length (1/2 coming from the integration range choice and 1/2 coming from its further reduction by the window function).

3/ PLOTTING

MP_SQOM is intended to provide a self-explaining command line dialogue guiding the user through the different stages of the plotting exercise. Some patience and trial-and-error learning are unavoidable.

At the beginning MP_SQOM will produce a total scattering map for the specified input data sequence and Q-range, which is intended for experimenting with the adequate intensity scale (color range) and for a preliminary exploration of the response topology. The total scattering function S(Q) is an integral of S(Q,ω) over all energy/frequency spectrum. Hence, if for whatever reason the map exhibits a too weak presence of diffuse scattering, it doesn’t make much sense to continue towards plotting energy-resolved S(Q,ω) maps. Rather the volume of the input data has to be questioned (simulation box size, number of snapshot files).

When indicating the map centre in Q-space, it is possible to include the vertical component to produce a map which is above or below the nominal equatorial plane, eg. after having chosen the (hk0) option the input of 2 2 0 will produce a (h k 0) map with the corresponding centre while 2 2 .5 will produce the (h k .5) map (i.e. lifted by 0 0 .5).

All the plotting options are displayed in a way-point menu (upon exiting from the total scattering mode by setting c_min, c_max = 0 0)

Choose a plot option (PS/TXT file output is OFF):

 0  EXIT
 1  explore total scattering     (-1 edit atom masks)
 2  explore E=const maps         (-2 edit atom masks)
 3  make a stack of E=const maps (-3 reset atom masks)
 4  explore E(Q) maps            (-4 edit atom masks)
 5  make a stack of E(Q) maps    (-5 reset atom masks)
 6  change the HKL plane, range and centre (BZ)
                                 (-6 change the real space range)
 7  toggle the NU_FFT mode to ONE_PHONON (go on via 6)
 8  toggle the PS/TXT output ON (mind the TXT switch in PAR)
 9  toggle the S(Q)/Q^2 scaling to S(Q)
10  options: change the time integration window width, weighting etc.

Principal functionalities of MP_SQOM

  • total scattering S(Q) maps, calculated as sum of modulus squared of the diffracted wave amplitudes with Xray, neutron or unit amplitudes (specified in the .PAR file, can be switched under option 9 in the general switch board); this an automatic introductory option for each new plotting session, upon exit from it it the choice of all the other options is available

  • energy resolved E = const momentum space maps and their sequences (options 2 and 3 in the general switch board)

  • energy resolved Q-E momentum-energy space maps and their sequences (options 3 and 4 in the general switch board)

  • contributions of chosen atom types can be masked out by specifying negative option numbers opening a subsequent dialogue; however, it is necessary to keep in mind that we are dealing with coherent scattering, where the amplitudes and not the intensities that are additive: all atoms interfere with all other atoms! hence masking certain atoms gives only hints, which are to be interpreted with a lot of caution

  • each plot provides a dialogue to adjust the intensity range of the map, for all usual situations the logarithmic scale is the right choice

All the plots can be produced with a choice of unit, neutron and Xray weights. The values of neutron coherent scattering lengths (bcoh) and the parameters to calculate the Xray atom factors (with their Q-dependence) are read from the files neutron_xs.txt and xray_ff.txt placed in the /usr/local/mp_tools/ref directory (normally created by the installation script). When searching these files, MP_SQOM identifies atoms by their label (1st column of the ATOMS list in the .PAR file) and by their ionisation state (given in the last column of the same list). If for whatever reason different values are to be used, place an edited copy of these files under the same name into your working directory (it may be reduced to contain only the pertinent atoms) - MP_SQOM starts its search there.

4/ OUTPUT

Automatic graphics file output (.PS or .PNG format) upon exiting from an active plot can be activated via the no. 7 toggle; this can be accompanied by a text file (.TXT) output of the corresponding intensity table if activated int .PAR file. In each case the existence of former output files is tested and a counter is incremented in order not to overwrite them; the .TXT file numbering follows the graphics one without test. The .LOG files keeping a brief history record are opened on a daily basis, their filenames contain the respective date.

NOTE:

It is unavoidable that the resulting S(Q) and S(Q,ω) maps contain a grainy structure ressembling “noise”. In fact this effect goes back to coherent imaging (speckles) of the microscopic (atom) structure of the MD model systems. This can be handled symptomatically (smoothed) by the built-in speckle filter (cf. S_TRIG in the .PAR file) or by any available image postprocessing tools. It should be kept in mind that the application of any smoothing and noise filtering techniques can generate artefacts and that their results are always accompanied by some loss of detail in the image.

On the other hand the grainy structure of the bitmap colorplots can get further amplified by the rudimentary bit sampling technique implemented in the PGPLOT library. Therefore whenever an appealing output from supercells providing large pixel densities is the goal, it is preferable to use a large high resolution screen (4k), select a screenplot size as large as possible (P_SIZE=12 among the parameter list under the option 10), save the maps or their screenshots in the PNG (or JPEG) format and only subsequently generate reduced size PDF, PNG or JPEG images by using more sophisticated image viewing software (the OS X Preview does the job).