.. _sec-supermirror:

[ Super Mirror ] section
==================================================

The reflection of low energy neutron by super mirror is defined by this section. 
We assume the following empirical formula to describe the reflectivity of the super mirrors. 

.. math::

   R =
   \left\{
   \begin{array}{ll}
   R_0 & \mathrm{if}\;\; Q \le Q_c \\
   \frac{1}{2} R_0 \left( 1 - \tanh\left[
   (Q - mQ_c)/W
   \right] \right)
   \left( 1 - \alpha (Q - Q_c) \right)
   & \mathrm{if}\;\; Q > Q_c
   \end{array}
   \right.

where :math:`Q` is the scattering vector (in :math:`\mathrm{\AA^{-1}}`) defined by 

.. math::

   Q = \left|\mathbf{k}_i - \mathbf{k}_f\right|
     = \frac{4\pi \sin \theta}{\lambda}

The value of m is a parameter determined by the mirror material, the bilayer sequence and the number of bilayers. 
:math:`Q_c` is the critical scattering wave vector for a single layer of the mirror material. At higher values of :math:`Q`, the reflectivity starts falling linearly with a slope :math:`\alpha` until a cutoff at :math:`Q = mQ_c`.
The width of the cutoff is denoted :math:`W`.

These parameters are defined as

.. code-block:: text

  [ Super Mirror ]
    r-in          r-out   mm    r0    qc      am    wm
    {2001-2020}   3001    3     0.99  0.0217  3.0   0.003
    2500          3500    3     0.99  0.0217  3.0   0.003
    2600          3600    3     0.99  0.0217  3.0   0.003
    ...           ...     ...   ...   ...     ...   ...
    ...           ...     ...   ...   ...     ...   ...

The reflection surface is defined by the surface between r-in and r-out. 
You can use the format ( { 2 - 5 } 8 9 ), and you can use the lattice and universe style as ( 6 < 10[1 0 0] < u=3 ) in these definitions. 
The remaining parameters in above expression denote :math:`m` by ``mm``, :math:`R_0` by ``r0``, :math:`Q_c` by ``qc`` in :math:`\mathrm{\AA^{-1}}`, :math:`\alpha` by ``am`` in :math:`\mathrm{\AA}`, and :math:`W` by ``wm`` in :math:`\mathrm{\AA^{-1}}`.

We restrict this function only to neutrons for the case that its energy is less than 10 eV or :math:`\sin\theta` is greater than 0.001, the latter is due to roughness of the surface. 

By setting the **mm** parameter (m-value) to a negative value, the user-defined mirror function can be activated. In this case, the reflectivity is determined by the usr_mirror function written in ``src/usrmirror.f90`` . This function receives the following arguments in order (variable names in the program are shown in parentheses):

.. code-block:: text

  Q (qin), mm (smm), r0 (sr0), qc (sqc), am (sam), wm (swm), file(32) (fname)

Since parameters other than Q are passed directly from the values specified in the input file, they can be repurposed for other custom objectives. If an external file is required as input data for the reflectivity calculation, specify the filename using **file(32)** in the [Parameters] section.

A sample program is provided in ``src/usrmirror.f90`` as a default user-defined mirror function, which calculates reflectivity by interpolating values from an external database. In this sample code, the absolute value of **mm** (truncated to an integer if a real number is provided) is treated as the **ID number** of the coating. The program searches for a matching ID within the reflectivity data file specified by **file(32)** and determines the reflectivity through interpolation.

Four types of interpolation are available: q-linear/R-linear, q-linear/R-log, q-log/R-linear, and q-log/R-log. Please prepare the reflectivity data file using experimental data or neutron reflectivity simulation results in the following format and specify it via **file(32)** .

Data format is as follows:

- 1st line: **nset** (int)  
  Total number of datasets.

- Subsequent lines: Data for each dataset.

**<Dataset 1>**

- 1st line: **id** (int), **q-type** (int), **nq** (int), **qmin** (double), **qmax** (double)

  - **id**  
    Identification ID number of the dataset (corresponds to mm).

  - **q-type**  
    Interpolation method and input format.

    ::

      = 1   q-linear / R-linear interpolation (Input: R only)
      = 2   q-linear / R-log interpolation (Input: R only)
      = 3   q-log / R-linear interpolation (Input: R only)
      = 4   q-log / R-log interpolation (Input: R only)
      = 11  q-linear / R-linear interpolation (Input: pair of q & R)
      = 12  q-linear / R-log interpolation (Input: pair of q & R)
      = 13  q-log / R-linear interpolation (Input: pair of q & R)
      = 14  q-log / R-log interpolation (Input: pair of q & R)

  - **nq**  
    Number of data points for R.

  - **qmin**  
    Minimum value of q [Å\ :sup:`-1`] (valid for q-type = 1–4)

  - **qmax**  
    Maximum value of q [Å\ :sup:`-1`] (valid for q-type = 1–4)

- 2nd line and subsequent:

  - If q-type = 1, 2, 3, or 4 (Input: R only)

    ::

      R(1)
      R(2)
      ...
      R(nq)

  - If q-type = 11, 12, 13, or 14 (Input: pairs of q & R)  
    The data must be arranged in ascending order with respect to q.

    ::

      q(1), R(1)
      q(2), R(2)
      ...
      q(nq), R(nq)

- Dataset delimiter

  ::

    (blank line)
    (blank line)

  Add two blank lines between datasets as delimiters.

**<Dataset 2>**

- 1st line: id, q-type, nq, qmin, qmax  
  (same format as Dataset 1)

::

  (blank line)
  (blank line)

Specific sample input files utilizing this user-defined mirror function are stored in  
``sample/misc/usrmirror``. Please refer to them for more details.