[ Identification | Description | Input parameters | Output parameters | Links ]

# The `Isotropic_Sqw` Component

Isotropic sample handling multiple scattering and absorption for a general S(q,w) (coherent and/or incoherent/self)

## Identification

- Author: Virginie Hugouvieux, E. Farhi
- Origin: ILL
- Date: August 2003
- Version: 1.90
- Modification history:
  - E. Farhi, Jul 2005: made it work, concentric mode, multiple use
  - E. Farhi, Mar 2007: improved implementation, correct small bugs
  - E. Farhi, Oct 2008: added any shape sample geometry

## Description

    An isotropic sample handling multiple scattering and including as input the
    dynamic structure factor of the chosen sample (e.g. from Molecular
    Dynamics). Handles elastic/inelastic, coherent and incoherent scattering -
    depending on the input S(q,w) - with multiple scattering and absorption.
    Only the norm of q is handled (not the vector), and thus suitable for
    liquids, gazes, amorphous and powder samples.

    If incoherent/self S(q,w) file is specified as empty (0 or "") then the
    scattering is constant isotropic (Vanadium like).
    In case you only have one S(q,w) data containing both coherent and
    incoherent contributions you should e.g. use 'Sqw_coh' and set 'sigma_coh'
    to the total scattering cross section.
    The implementation assumes that the S(q,w) data is normalized, i.e. S(q)
    goes to 1 for large q. If this is not the case, the component can do that
    when 'auto_norm=-1'. Alternatively, the S(q,w) data will be multiplied by
    'auto_norm' for positive values.

    Focusing on the relevant [q,w] data range corresponding to the instrument
    setting may improve computation accuracy and prevent some neutrons
    to be removed when energy transfer is higher than actual neutron energy.
    An automatic such process may be activated when 'auto_qw=1'.
    On the other hand, if the input S(q,w) data is too restricted in q, the
    scattering conditions will be limited, leading to incomplete result.
    Best conditions are to get the widest S(q,w) data and use 'auto_qw=1'.
    Additionally, for single order scattering (order=1), you may restrict the
    vertical spreading of the scattering area using d_phi parameter.

    An important option to enhance statistics is to set 'p_interact' to, say,
    30 percent (0.3) in order to force a fraction of the beam to scatter. This
    will result on a larger number of scattered events, retaining intensity.

    If you use this component and produce valuable scientific results, please
    cite authors with references bellow (in Links).

    Sample shape:
    Sample shape may be a cylinder, a sphere, a box or any other shape
      box/plate:       xwidth x yheight x zdepth (thickness=0)
      hollow box/plate:xwidth x yheight x zdepth and thickness>0
      cylinder:        radius x yheight (thickness=0)
      hollow cylinder: radius x yheight and thickness>0
      sphere:          radius (yheight=0 thickness=0)
      hollow sphere:   radius and thickness>0 (yheight=0)
      any shape:       geometry=OFF file

      The complex geometry option handles any closed non-convex polyhedra.
      It computes the intersection points of the neutron ray with the object
      transparently, so that it can be used like a regular sample object.
      It supports the OFF and NOFF file format but not COFF (colored faces).
      Such files may be generated from XYZ data using qhull/powercrust, and
      viewed with geomview
      The default size of the object depends of the OFF file data, but its
      bounding box may be resized using xwidth,yheight and zdepth.

    Concentric components:
    This component has the ability to contain other components when used in
    hollow cylinder geometry (namely sample environment, e.g. cryostat and
    furnace structure). Such component 'shells' should be split into input and
    output side surrounding the 'inside' components. First part must then use
    'concentric=1' flag to enter the inside part. The component itself must be
    repeated to mark the end of the concentric zone. The number of concentric
    shells and number of components inside is not limited.

    COMPONENT S_in = Isotropic_Sqw(Sqw_coh="Al.laz", concentric=1, ...)
    AT (0,0,0) RELATIVE sample_position

    COMPONENT something_inside ... // e.g. the sample itself or other materials

    COMPONENT S_out = COPY(S_in)(concentric=0)
    AT (0,0,0) RELATIVE sample_position

    Sqw file format:
    File format for S(Q,w) (coherent and incoherent) should contain 3 numerical
    blocks, defining q axis values (vector), then energy axis values (vector),
    then a matrix with one line per q axis value, containing Sqw values for
    each energy axis value. Comments (starting with '#') and non numerical lines
    are ignored and used to separate blocks. Sampling must be regular.

    Example:
    # q axis values
    # vector of m values in Angstroem-1
    0.001000 .... 3.591000
    # w axis values
    # vector of n values in meV
    0.001391 ... 1.681391
    # sqw values (one line per q axis value)
    # matrix of S(q,w) values (m rows x n values), one line per q value,
    9.721422  10.599145 ... 0.000000
    10.054191 11.025244 ... 0.000000
    ...
    0.000000            ... 3.860253

    See for instance file He4_liq_coh.sqw. Such files may be obtained from e.g. INX,
    Nathan, Lamp and IDA softwares, as well as Molecular Dynamics.

    Powder file format:
    Files for coherent elastic powder scattering may also be used.
    Format specification follows the same principle as in the PowderN
    component, with parameters:

        powder_format=Crystallographica
    or  powder_format=Fullprof
    or  powder_format=Lazy
    or  powder_format={j,d,F2,DW,Delta_d/d,1/2d,q,F} (column indexes 1:n)

    or column indexes (starting from 1) given as comments in the file header
    (e.g. '#column_j 4'). Refer to the PowderN component for more details.
    Delta_d/d and Debye-Waller factor may be specified for all lines with the
    'powder_Dd' and 'powder_DW' parameters.

    Additionally a special [q,Sq] format is also defined with:
      powder_format=qSq
    for which column 1 is 'q' and column 2 is 'S(q)'.

    Examples:
    1- Vanadium-like incoherent elastic scattering
      Isotropic_Sqw(radius=0.005, yheight=0.01, V_rho=1/13.827,
        sigma_abs=5.08, sigma_inc=4.935, sigma_coh=0)

    2- liq-4He parameters
      Isotropic_Sqw(..., Sqw_coh="He4_liq_coh.sqw", T=10, p_interact=0.3)

    3- powder sample
     Isotropic_Sqw(..., Sqw_coh="Al.laz", save_sqw=1)

    %BUGS:
    When used in concentric mode, multiple bouncing scattering
    (traversing the hollow part) is not taken into account.
    When adapting the (q,w) range automatically, the guess may be wrong for highly
    polychromatic beam.

    %VALIDATION
    For Vanadium incoherent scattering mode, V_sample, PowderN, Single_crystal
    and Isotropic_Sqw produce equivalent results, eventhough the two later are
    more accurate (geometry, multiple scattering). Isotropic_Sqw gives same
    powder patterns as PowderN, with an intensity within 20 %.

## Input parameters

Parameters in boldface are required; the others are optional.

Name | Unit | Description | Default
--- | --- | --- | ---
powder_format | no quotes | name or definition of column indexes in file | Undefined
Sqw_coh | str | Name of the file containing the values of Q, w and S(Q,w) Coherent part; Q in Angs-1, E in meV, S(q,w) in meV-1. Use 0, NULL or "" to disable. | 0
Sqw_inc | str | Name of the file containing the values of Q, w and S(Q,w). Incoherent (self) part. Use 0, NULL or "" to scatter isotropically (V-like). | 0
geometry | str | Name of an Object File Format (OFF) file for complex geometry. The OFF file may be generated from XYZ coordinates using qhull/powercrust | 0
radius | m | Outer radius of sample in (x,z) plane. cylinder/sphere. | 0
thickness | m | Thickness of hollow sample Negative value extends the hollow volume outside of the box/cylinder. | 0
xwidth | m | width for a box sample shape | 0
yheight | m | Height of sample in vertical direction for box/cylinder shapes | 0
zdepth | m | depth for a box sample shape | 0
qmin | Angs-1 | Minimum Q value to use in S(q,w). | 0
qmax | Angs-1 | Maximum Q value to use in S(q,w). | 0
wmin | meV | Minimum Energy value to use in S(q,w). | 0
wmax | meV | Maximum Energy value to use in S(q,w). | 0
auto_qw | 1 | When set to 1, the [q,w] range will automatically be tuned to optimal setting whenever required (recommended). | 0
threshold | 1 | Value under which S(Q,w) is not accounted for. to set according to the S(Q,w) values, i.e. not too low. | 1e-10
order | 1 | Limit multiple scattering up to given order | 0
T | K | Temperature of sample, detailed balance | 0
verbose | 1 | Verbosity level (0:silent, 1:normal, 2:verbose, 3:debug). | 1
d_phi | deg | scattering vertical angular spreading (usually the height of the next component/detector). Use 0 for full space. This is only relevant for single scattering (order=1). | 0
concentric | 1 | Indicate that this component has a hollow geometry and may contain other components. It should then be duplicated after the inside part (only for box, cylinder, sphere) [1] See description for an example. | 0
V_rho | AA-3 | Density of atoms (nb atoms/unit cell V_0). | 0
sigma_abs | barns | Absorption cross-section at 2200 m/s. Use -1 to unactivate. | 0
sigma_coh | barns | Coherent Scattering cross-section. Use -1 to unactivate. | 0
sigma_inc | barns | Incoherent Scattering cross-section. Use -1 to unactivate. | 0
save_sqw | 1 | When set to 1, saves S(q), S(w) and S(q,w) as monitors. | 0
powder_Dd | 1 | global Delta_d/d spreading, or 0 if ideal. | 0
powder_DW | 1 | global Debey-Waller factor, if not in |F2| or 1. | 0
powder_Vc | AA^3 | volume of the unit cell | 0
density | g/cm^3 | density of material. V_rho=density/weight/1e24*N_A | 0
weight | g/mol | atomic/molecular weight of material | 0
p_interact | 1 | Force a given fraction of the beam to scatter, keeping intensity right, to enhance small signals (-1 unactivate). | -1
auto_norm | 1 | Normalize S(q,w) when -1. Use raw data when 0 (default), multiply S(q,w) when auto_norm>0. | 0
powder_barns | 1 | 0 when |F2| data in powder file are fm^2, 1 when in barns (barns=1 for laz, barns=0 for lau type files). | 1

## Output parameters

Name | Unit | Description | Default
--- | --- | --- | ---
VarSqw | - | .type interaction type of event 'c' (coherent), 't' (transmitted) 'i' (incoherent) 'v' (isotropic incoherent, Vanadium-like). |
columns |  |  |
offdata |  |  |

## Links

- Source code for `Isotropic_Sqw.comp`.
- E. Farhi, V. Hugouvieux, M.R. Johnson, and W. Kob, Journal of Computational Physics 228 (2009) 5251-5261 "Virtual experiments: Combining realistic neutron scattering instrument and sample simulations"
- Hugouvieux V, Farhi E, Johnson MR, Physica B, 350 (2004) 151 "Virtual neutron scattering experiments"
- Hugouvieux V, PhD, University of Montpellier II, France (2004).
- Cross sections for single elements: http://www.ncnr.nist.gov/resources/n-lengths/
- Cross sections for compounds: http://www.ncnr.nist.gov/resources/sldcalc.html
- Example data file He4_liq_coh.sqw
- The PowderN component.
- Web Elements http://www.webelements.com/
- The test/example instrument Test_Isotropic_Sqw.instr.
- Geomview and Object File Format (OFF) <http|://www.geomview.org>
- Powercrust/qhull <http://www.cs.utexas.edu/users/amenta/powercrust>

[ Identification | Description | Input parameters | Output parameters | Links ]