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

Abins2D v1

Credits

Author:

Adam Jackson

Summary

Calculates inelastic neutron scattering over 2D (q,ω) space.

See Also

Abins

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’]

Instrument

Input

string

Ideal2D

Name of an instrument for which analysis should be performed. Allowed values: [‘Ideal2D’, ‘PANTHER’, ‘MAPS’, ‘MARI’, ‘MERLIN’]

Chopper

Input

string

Chopper package. Allowed values: [‘’, ‘A’, ‘G’, ‘R’, ‘S’]

IncidentEnergy

Input

string

4100

Incident energy in EnergyUnits

ChopperFrequency

Input

string

Chopper frequency in Hz

Description

Abins2D is a plugin for Mantid which allows scientists to generate theoretical inelastic neutron scattering spectra (INS) in 2-D \((|\mathbf{q}|,\omega)\) space, accounting for the limitations of real-world measurements.

The intensity is calculated in the “almost-isotropic” incoherent powder-averaging approximation, as used in the 1-D Abins algorithm. Different 2-D INS instruments may be selected, along with instrument parameters (incident energy, chopper settings) that determine the accessible \((|\mathbf{q}|,\omega)\) region and energy resolution. More information about the implemented working equations can be found here.

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: CASTEP (.phonon), CRYSTAL (.out), GAUSSIAN (.log), DMOL3 (.outmol) or VASP (.xml). For VASP XML inputs, it is also permitted to use a “selective dynamics” in which some atoms are frozen. In this case, data is only available for the moving atoms and contributions from the other atoms are omitted from the calculated spectrum. This may be a suitable model for systems where the frozen atoms form a rigid substrate (e.g. a noble metal surface) for an adsorbed molecule of lightweight atoms. It is not recommended where there is significant vibrational coupling between frozen and moving atoms, or where substrate modes would occupy a similar frequency range to the adsorbate.

Alternatively, force-constants data can be provided and a fine \(\mathbf{q}\)-point mesh will be sampled automatically. In this case the supported formats are CASTEP (.castep_bin generated with phonon_write_force_constants = True) and Phonopy (phonopy.yaml file generated with INCLUDE_ALL = .TRUE.) It is also permitted to use a phonopy YAML file which does not contain the force constants, if force constants are stored in a FORCE_CONSTANTS or force_constants.hdf5 file in the same directory. This is less convenient but may result in significantly faster loading if the force constant matrix is large.

After a successful run, results are written to a Mantid Workspace Group; by default this is divided by element and quantum order. The user can also request contributions from individual 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).

Abins2D is under active development; please direct feature requests and bug reports to Dr. Sanghamitra Mukhopadhyay and Dr. Adam Jackson. If you are developing or modifying Abins(2D), 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:

A minimal example, relying heavily on default parameters:

benzene_wrk = Abins2D(AbInitioProgram="CASTEP", VibrationalOrPhononFile="benzene.phonon")


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

Output: (note that only the fundamental excitations are included)

benzene_wrk_C_total
benzene_wrk_C
benzene_wrk_H_total
benzene_wrk_H

Example - using more arguments:

In practice we would usually select an instrument, incident energy, and enable all available quantum orders (2 + autoconvolution). Setting “Total” cross-section applies the “incoherent approximation”; although Abins only (so far) calculates the incoherent contribution, coherent weights can be added for a slight improvement to the predicted spectrum. (If the spectrum is dominated by coherent scattering, this approximation may not be the appropriate tool.)

wrk_verbose=Abins2D(AbInitioProgram="CASTEP", VibrationalOrPhononFile="benzene.phonon",
                    TemperatureInKelvin=10, Instrument="MAPS",
                    Atoms="H, atom1, atom2", SumContributions=True,
                    QuantumOrderEventsNumber="2", Autoconvolution=True,
                    ScaleByCrossSection="Total")

print(f"Created {wrk_verbose.size()} workspaces")
print(f"including {wrk_verbose[12].name()}")

Output:

Created 34 workspaces
including wrk_verbose_atom_1_total

Categories: AlgorithmIndex | Simulation

Source

Python: Abins2D.py

References