CfgRefDoc

NCrystal cfg-parameters reference documentation

Reference documentation of all cfg-string variables, generated with NCrystal release v3.9.0.

Base parameters

atomdb

Type: string
Default value: ""
Description: Modify atomic definitions if supported (in practice this is unlikely to be supported by anything except NCMAT data). The string must follow a syntax identical to that used in @ATOMDB sections of NCMAT file (cf. https://github.com/mctools/ncrystal/wiki/NCMAT-format), with a few exceptions explained here: First of all, colons (':') are interpreted as whitespace characters, which might occasionally be useful (e.g. on the command line). Next, '@' characters play the role of line separators. Finally, when used with an NCMAT file that already includes an internal @ATOMDB section, the effect will essentially be to combine the two sections by appending the atomdb lines from this cfg parameter to the lines already present in the input data. The exception is the case where the cfg parameter contains an initial line with the single word "nodefaults" the effect of which will always be the same as if it was placed on the very first line in the @ATOMDB section (i.e. NCrystal's internal database of elements and isotopes will be ignored).

dcutoff

Type: floating point number
Allowed input units: Aa [default], nm, mm, cm, m
Default value: 0
Description: Crystal planes with d-spacing below this value will be ignored. The special value of 0 implies an automatic selection of this threshold. Note that for backwards compatibility -1 is treated as 0 (for now).

dcutoffup

Type: floating point number
Allowed input units: Aa [default], nm, mm, cm, m
Default value: inf
Description: Crystal planes with d-spacing above this value will be ignored.

infofactory

Type: string
Default value: ""
Description: This parameter can be used by experts to bypass the usual factory selection logic for material Info objects. A factory can be selected by providing its name, or excluded by prefixing the name with "!". Multiple entries must be separated by an "@" sign (obviously at most one non-excluded entry can appear).

temp

Type: floating point number
Allowed input units: K [default], C, F
Default value: -1
Description: Temperature of material in Kelvin. The special value of -1.0 implies 293.15K unless input data is only valid at a specific temperature, in which case that temperature is used instead.

Basic parameters related to scattering processes

coh_elas

Type: boolean
Default value: 1
Description: If enabled, coherent elastic components will be included for solid materials. In the case of crystalline materials this is essentially Bragg diffraction.

incoh_elas

Type: boolean
Default value: 1
Description: If enabled, incoherent elastic scattering components will be included for solid materials.

inelas

Type: string
Default value: "auto"
Description: Influence choice of inelastic scattering models. The default value of "auto" leaves the choice to the code, and values of "none", "0", "false", or "sterile", all disable inelastic scattering. The standard scatter plugin currently supports additional values: "external", "dyninfo", "vdosdebye", and "freegas", and internally the "auto" mode will simply select the first possible of those in the listed order (falling back to "none" when nothing is possible). Note that "external" is only currently supported by .nxs files. The "dyninfo" mode will simply base modelling on whatever dynamic information is available for each element in the input data. The "vdosdebye" and "freegas" modes overrides this, and force those models for all elements if possible (thus "inelas=freegas;elas=0" can be used to force a pure free-gas scattering model). The "external" mode implies usage of an externally provided cross-section curve with an isotropic-elastic scattering model.

sans

Type: boolean
Default value: 1
Description: Control presence of SANS models. Note that this parameter is primarily added to support future developments.

scatfactory

Type: string
Default value: ""
Description: This parameter can be used by experts to bypass the usual factory selection logic for Scatter objects. A factory can be selected by providing its name, or excluded by prefixing the name with "!". Multiple entries must be separated by an "@" sign (obviously at most one non-excluded entry can appear).

vdoslux

Type: integer
Default value: 3
Description: Setting affecting "luxury" level when expanding phonon spectrums (VDOS) into scattering kernels. This primarily impacts the granularity of the kernel and the upper neutron energy (Emax) beyond which free-gas extrapolation is used, with implication for memory usage and initialisation time. Allowed values are: 0 (Extremely crude, 100x50 grid, Emax=0.5eV, 0.1MB, 0.02s init), 1 (Crude, 200x100 grid, Emax=1eV, 0.5MB, 0.02s init), 2 (Decent, 400x200 grid, Emax=3eV, 2MB, 0.08s init), 3 (Good, 800x400 grid, Emax=5eV, 8MB, 0.2s init), 4 (Very good, 1600x800 grid, Emax=8eV, 30MB, 0.8s init), 5 (Overkill, 3200x1600 grid, Emax=12eV, 125MB, 5s init). Note that when no actual VDOS input curve is available and one is approximated from a Debye temperature, the vdoslux level actually used will be 3 less than the one specified in this parameter (but at least 0).

bkgd (pseudo parameter)

Type: pseudo
Description: Obsolete parameter which can be used to disable all physics processes except bragg diffraction. It only accepts "bkgd=0" or "bkgd=none", and is equivalent to "inelas=0;incoh_elas=0;sans=0".

bragg (pseudo parameter)

Type: pseudo
Description: This is simply an alias for the "coh_elas" parameter (although the name does not strictly make sense for non-crystalline solids).

comp (pseudo parameter)

Type: pseudo
Description: Convenience parameter which can be used to disable everything except the specified components. Note that this crucially does not re-enable the listed components if they have already been disabled. Components are listed as a comma separated list, and recognised component names are: "elas", "incoh_elas", "coh_elas", "bragg", "inelas", and "sans".

elas (pseudo parameter)

Type: pseudo
Description: Convenience parameter which can be used to assign values to all of the "coh_elas", "incoh_elas", and "sans" parameters at once. Thus, "elas=0" is a convenient way of disabling elastic scattering processes and is equivalent to "coh_elas=0;incoh_elas=0;sans=0".

Advanced parameters related to scattering processes (single crystals)

dir1

Type: crystal axis orientation
Description: Primary orientation axis of a single crystal. This is specified by indicating the direction of given axis in both the crystal (c1,c2,c2) and lab frames (l1,l2,l3), using the format "@crys:c1,c2,c3@lab:l1,l2,l3". The direction in the crystal frame can alternatively be provided in HKL space (indicating the normal of a given HKL plane), by using "@crys_hkl:" instead of "@crys:": "dir1=@crys_hkl:c1,c2,c3@lab:l1,l2,l3". When this parameter is set, the parameters mos and dir2 must also be provided.

dir2

Type: crystal axis orientation
Description: Secondary orientation axis of a single crystal. This is specified using the same syntax as for the dir1 parameter. In general the opening angle between the dir1 and dir2 vectors must be nonzero and identical in the crystal and lab frames, but a discrepancy up to the value of the dirtol parameter is allowed. In any case, the components of the dir2 vectors parallel to the dir1 vectors are ignored. When this parameter is set, the parameters mos and dir1 must also be provided.

dirtol

Type: floating point number
Allowed input units: rad [default], deg, arcmin, arcsec
Default value: 0.0001
Description: Tolerance parameter for the secondary direction of the single crystal orientation (see the dir2 parameter description for more information). A value of 180deg can be used to easily set up a single crystal monochromator where one is only interested in the primary direction. When this parameter is set, the parameters mos, dir1, and dir2 must also be provided.

lcaxis

Type: vector (3D)
Description: Symmetry axis of anisotropic layered crystals with a layout similar to pyrolytic graphite (PG). The axis must be provided in direct lattice coordinates using a format like "0,0,1". Specifying this parameter along with an orientation (see dir1 and dir2 parameters) will result in the appropriate anisotropic single crystal scatter model being used for Bragg diffraction.

lcmode

Type: integer
Default value: 0
Description: Choose which modelling is used for layered crystals like PG (ignored unless the lcaxis, dir1, and dir2 parameters are set). The default value 0 enables the recommended model, which is both fast and accurate. A positive value N triggers a very slow but simple reference model, in which N crystallite orientations are sampled internally (the model is accurate only when N is very high). A negative value -N triggers a different (and multi-thread unsafe!) model in which each crossSection call triggers a new selection of N randomly oriented crystallites.

mos

Type: floating point number
Allowed input units: rad [default], deg, arcmin, arcsec
Description: Mosaic FWHM spread in mosaic single crystals. When this parameter is set, the parameters dir1 and dir2 must also be provided.

mosprec

Type: floating point number
Default value: 0.001
Description: Approximate relative numerical precision in implementation of mosaic model in single crystals.

sccutoff

Type: floating point number
Allowed input units: Aa [default], nm, mm, cm, m
Default value: 0.4
Description: Single-crystal modelling cutoff. Crystal planes with d-spacing below this value will be approximated as having infinite mosaicity (as in a powder). A value of 0 naturally disables this approximation entirely.

ucnmode

Type: string
Default value: ""
Description: Modify how UCN (ultra cold neutron) production is handled in inelastic models. The value "refine" simply improves the modelling by replacing the usual scattering kernel treatment near the kinematic endpoint, where the neutron ends with less than 300neV, with a different model. The values "only" and "remove" performs the same split of the modelling, but then leaves out either all non-UCN or all UCN processes, respectively, from the inelastic cross sections. Finally, the threshold value of 300neV can be modified by appending the desired value to the first keyword, separated by a ":" character. The default unit is eV, but meV and neV are supported as well, so "ucnmode=refine:200neV", "ucnmode=remove:2e-7eV", "ucnmode=remove:2e-7", and "ucnmode=only:0.0002meV" all specify the same threshold. In addition to simply refining the UCN model, the primary intended purpose of the ucnmode parameter is to allow one to split out the UCN process from the rest, in order to perform biased Monte Carlo simulations of UCN production in moderators.

Parameters related to absorption processes

absnfactory

Type: string
Default value: ""
Description: This parameter can be used by experts to bypass the usual factory selection logic for Absorption objects. A factory can be selected by providing its name, or excluded by prefixing the name with "!". Multiple entries must be separated by an "@" sign (obviously at most one non-excluded entry can appear).

Special parameters

density

Type: special
Allowed input units: gcm3 kgm3 perAa3 x
Description: Modify the density state, which can be a scale factor (specified with the unit "x"), or an absolute value (using units "gcm3" for g/cm^3, "kgm3" for kg/m^3, or "perAa3" for atoms/angstrom^3). When an absolute value is specified, that value is simply used. However, when a scale factor is specified (e.g. density=1.2x), then the previous value is instead scaled by that value. Thus, appending ";density=1.2x" to a cfg-string will always increase the resulting material density by 20%. If unspecified, the density state will be "1x" (i.e. material densities are left as they are). Note that since it could easily lead to undesired behaviour, scale factor density assignments are not allowed for usage when cfg strings are embedded in input data (but absolute density values are always allowed).

phasechoice

Type: special
Description: Specific material sub-phases can be selected by assigning an index value to this pseudo-parameter. More precisely, the parameter picks out child phases in LOADED materials, not at the configuration level. This is an important distinction since a single entry at the cfg-level might actually result in multiple phases being loaded. As an example, one would typically expect that loading a file called "my_sans_sample.ncmat" would result in a multiphase material with two phases. Specifying "my_sans_sample.ncmat;phasechoice=0" would then pick out one of these phases, and "my_sans_sample.ncmat;phasechoice=1" the other. When multi-phase materials are defined recursively with some child-phases themselves being multi-phased, the phasechoice parameter can be specified more than once to navigate deeper into the sub-phase tree.