\(\renewcommand\AA{\unicode{x212B}}\)

Abins v1

Credits

Author:

Adam Jackson, Krzysztof Dymkowski

Contributors:

Sanghamitra Mukhopadhyay, Elliot Oram, Leonardo Bernasconi, Leandro Liborio

Summary

Calculates inelastic neutron scattering against 1-D ω axis.

See Also

Abins2D

Properties

Name	Direction	Type	Default	Description
VibrationalOrPhononFile	Input	string	Mandatory	File with the data from a vibrational or phonon calculation. Allowed values: [‘phonon’, ‘out’, ‘outmol’, ‘log’, ‘xml’, ‘yaml’, ‘castep_bin’, ‘hdf5’, ‘json’]
AbInitioProgram	Input	string	CASTEP	An ab initio program which was used for vibrational or phonon calculation. Allowed values: [‘CASTEP’, ‘CRYSTAL’, ‘DMOL3’, ‘FORCECONSTANTS’, ‘GAUSSIAN’, ‘JSON’, ‘VASP’]
OutputWorkspace	Output	Workspace	Mandatory	Name to give the output workspace.
TemperatureInKelvin	Input	number	10	Temperature in K for which dynamical structure factor S should be calculated.
Atoms	Input	str list		List of atoms to use to calculate partial S.If left blank, workspaces with S for all types of atoms will be calculated. Element symbols will be interpreted as a sum of all atoms of that element in the cell. ‘atomN’ or ‘atom_N’ (where N is a positive integer) will be interpreted as individual atoms, indexing from 1 following the order of the input data.
SumContributions	Input	boolean	False	Sum the partial dynamical structure factors into a single workspace.
SaveAscii	Input	boolean	False	Write workspaces to .ascii files after computing them.
ScaleByCrossSection	Input	string	Incoherent	Scale the partial dynamical structure factors by the scattering cross section. Allowed values: [‘Total’, ‘Incoherent’, ‘Coherent’]
QuantumOrderEventsNumber	Input	string	1	Number of quantum order effects included in the calculation (1 -> FUNDAMENTALS, 2-> first overtone + FUNDAMENTALS + 2nd order combinations. Allowed values: [‘1’, ‘2’]
Autoconvolution	Input	boolean	False	Estimate higher quantum orders by convolution with fundamental spectrum.
EnergyUnits	Input	string	cm-1	Energy units for output workspace and experimental file. Allowed values: [‘cm-1’, ‘meV’]
BinWidthInWavenumber	Input	number	1	Width of bins used during rebinning.
SampleForm	Input	string	Powder	Form of the sample: Powder. Allowed values: [‘Powder’]
ExperimentalFile	Input	string		File with the experimental inelastic spectrum to compare. Allowed values: [‘raw’, ‘dat’]
Scale	Input	number	1	Scale the intensity by the given factor. Default is no scaling.
Instrument	Input	string	TOSCA	Name of an instrument for which analysis should be performed. Allowed values: [‘TOSCA’, ‘Lagrange’]
Setting	Input	string		Setting choice for this instrument (e.g. monochromator). Allowed values: [‘’, ‘All detectors (TOSCA)’, ‘Backward (TOSCA)’, ‘Cu(220) (Lagrange)’, ‘Cu(331) (Lagrange)’, ‘Forward (TOSCA)’, ‘Si(111) (Lagrange)’, ‘Si(311) (Lagrange)’]

Description

Abins is a plugin for Mantid which allows scientists to compare experimental and theoretical inelastic neutron scattering spectra (INS).

Abins requires data from existing lattice dynamics calculations to determine the phonon mode frequencies and displacements. These are used to compute INS intensities; higher-order phonons may be approximated as combinations of fundamental modes. Several file formats are supported for frequency and displacement data at given \(\mathbf{q}\)-points. Alternatively, force-constants data can be provided and a fine \(\mathbf{q}\)-point mesh will be sampled automatically. Supported codes include CASTEP (.phonon), CRYSTAL (.out), DMOL3 (.outmol), GAUSSIAN (.log), PHONOPY (.yaml), VASP (.xml) as well as some pre-processed JSON (.json) formats. For more information about the files, features and quirks of these codes see Abins Data Formats.

The user may also provide an experimental file with measured dynamical structure factor S in order to directly compare theoretical and experimental spectra. Abins produces one dimensional INS spectrum that can be compared against TOSCA, IN1-LAGRANGE and similar instruments; a semi-empirical powder averaging model accounts for q- and energy-dependent intensity behaviour in this system. The user-input temperature value is included in a Debye-Waller term, recreating the intensity fall-off with increasing wavelength. More information about the implemented working equations can be found here.

After successful analysis a user obtains a Mantid Workspace Group which stores theoretical spectra (and, optionally, experimental data). Currently a user can produce theoretical spectra for given atoms (e.g. ‘atom_1’, the first atom listed in the input data) or types of atom (for example for benzene two element symbols: C, H) and for each quantum event (up to tenth order). Total theoretical spectra can also be generated, summing over all considered quantum events for that atom or element. The user can also produce a total spectrum for the whole considered system. The dynamical structure factor S is calculated for all atoms in the system and results are cached, so if no settings have been changed then subsequent runs of Abins can quickly create more Mantid Workspaces without re-calculating any spectra.

Abins is in constant development and suggestions for improvements are very welcome. For any such contributions please contact Dr. Sanghamitra Mukhopadhyay. If you are developing or modifying Abins, see the Abins: Implementation details notes which outline some of the key conventions, practices and pitfalls.

If Abins is used as part of your data analysis routines, please cite the relevant reference [1].

Usage

Note

To run these usage examples please first download the usage data, and add these to your path. In Mantid this is done using Manage User Directories.

Example - loading CASTEP phonon data:

benzene_wrk = Abins(AbInitioProgram="CASTEP", VibrationalOrPhononFile="benzene.phonon",
                    QuantumOrderEventsNumber="1")


for name in benzene_wrk.getNames():
    print(name)

Output:

benzene_wrk_C_total
benzene_wrk_C
benzene_wrk_H_total
benzene_wrk_H

Example - loading CRYSTAL phonon data:

wrk=Abins(AbInitioProgram="CRYSTAL", VibrationalOrPhononFile="b3lyp.out", QuantumOrderEventsNumber="1")

for name in wrk.getNames():
    print(name)

Output:

wrk_C_total
wrk_C
wrk_H_total
wrk_H
wrk_N_total
wrk_N
wrk_Na_total
wrk_Na
wrk_O_total
wrk_O

Example - calling AbINS with more arguments:

wrk_verbose=Abins(AbInitioProgram="CASTEP", VibrationalOrPhononFile="benzene.phonon",
                  ExperimentalFile="benzene_experimental.dat",
                  TemperatureInKelvin=10, BinWidthInWavenumber=1.0, SampleForm="Powder", Instrument="TOSCA",
                  Atoms="H, atom1, atom2", SumContributions=True, QuantumOrderEventsNumber="1", ScaleByCrossSection="Incoherent")

for name in wrk_verbose.getNames():
    print(name)

Output:

experimental_wrk
wrk_verbose_total
wrk_verbose_H_total
wrk_verbose_H
wrk_verbose_atom_1_total
wrk_verbose_atom_1
wrk_verbose_atom_2_total
wrk_verbose_atom_2

Categories: AlgorithmIndex | Simulation

Source

Python: Abins.py

References

[1]

11. Dymkowski, S. F. Parker, F. Fernandez-Alonso and S. Mukhopadhyay, “AbINS: The modern software for INS interpretation” , Physica B, doi:10.1016/j.physb.2018.02.034 (2018).