.. _input_file:

インプットファイル
==========================

.. contents:: 目次:
    :depth: 3

概要
#####################################

RAIMではインプットファイルを用いて計算条件を設定する。
ここでは、インプットファイルの記述方法および各変数の説明を行う。
なお、バージョン1.3.3から、インプットファイルの形式をYAML形式へと変更した。
それ以前のバージョンにおけるインプットファイルの説明は :ref:`namelist_input` を参照のこと。

記述方法
#####################################

YAMLはデータシリアライズ形式の一つであり、Pythonの辞書型に似た構造を持つ。
インデントを用いて階層構造を表現し、キーと値のペアでデータを記述する。
インプットファイルでは、各計算条件をキーとし、その値を設定する。
以下、インプットファイルを記述するにあたって必要なYAMLの一般的な記述のルールを示す。

- 変数名と値の間にコロン（ **:** ）を使用する（コロンの後にスペースが必要）
- 階層を表すためにインデントを使用する
- 変数名の先頭にハイフン（ **-** ）を用いて配列を表現する
- 値が文字列であってもシングルクォテーション（ **'** ）またはダブルクォーテーション（ **"** ）で囲む必要はない
- **#** 以降の文字列はコメントとして扱われる。

変数を説明した後に具体的な記述例を示す。

変数の説明
#####################################

計算条件をグループ分けし、グループ名を辞書のキーとして、詳細な条件をそのキーに対応する値として記述する。

以下、各グループの説明を行う。

control
*************************************

計算全般に関する設定を行う。
Defaultが設定されている変数は省略可能である。
このグループは省略することはできない。

.. csv-table:: controlグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_control

   変数名, 型または値, Default, 説明
   project, 文字列, project1, プロジェクト名を設定する。出力ファイルの保存先フォルダ名となる。
   proj_ow, 整数：0/1, 1, 既に同じプロジェクトが存在する場合、(1)出力ファイルを上書きするか、(0)しないかを選択する。(0)の場合、projectに日時を付与したフォルダに出力ファイルを保存する。
   sim, 整数：1/2/3, 1, シミュレーション計算において、(1)断面積計算、(2)パルス関数を畳み込まない共鳴吸収スペクトル計算、(3)パルス関数を畳み込んだ透過率計算の選択を行う。
   fit, 整数：0/1,, フィッティング計算において、(1)フィッティングを行うか、(0)行わないかを選択する。(0)は初期値の確認等に使用する。
   pulse_fit, 整数：0/1, 0, フィッティング計算において、(0)パルス関数を最適化しないモードか、(1)最適化するモードかを選択する。
   fn_xs, 文字列, xs, 計算した断面積を出力する際のファイル名のプレフィックス。後に設定するmaterialグループの物質ごとに断面積が出力される。
   fn_tr0, 文字列, tr0, パルス関数を畳み込まない共鳴吸収スペクトルを出力する際のファイル名。
   fn_trr, 文字列, trR, パルス関数を畳み込んだ共鳴吸収スペクトルを出力する際のファイル名。
   fn_fiti, 文字列, initial, フィッティング計算において、初期値で計算した共鳴吸収スペクトルを出力する際のファイル名。
   fn_fitf, 文字列, final, フィッティング計算において、フィッティング結果で計算した共鳴吸収スペクトルを出力する際のファイル名。
   format, 整数：1/2/3, 1, 出力ファイルのフォーマットを指定する。(1)CSV、(2)テキスト（スペース区切り）、(3)(1)と(2)の両方
   outdir, 文字列, output, プロジェクトフォルダの保存先フォルダ名。 :file:`raim` からの相対パスで指定する。
   matplotlib, 整数：0/1, 0, 計算終了時にmatplotlibによるグラフの表示を(1)行うか、(0)行わないかを選択する。
   show_baseline, 整数：0/1, 0, matplotlibによるグラフにベースラインを(1)表示するか、(0)表示しないかを選択する。

具体例：

.. code-block:: yaml

    control:
      project: sample_fit_tr  # project name (default "project1")
      proj_ow: 1  # overwrite project directory, No:0, Yes:1 (default 1)
      fit: 1  # 0:simulation, 1:fitting
      pulse_fit: 0  # 0:normal, 1:adjust/fix parameters of pulse function (default 0)
      fn_xs: xs_ta  # file name of cross section (default "xs")
      fn_fiti: initial_ta  # file name of initial fitting line (default "initial")
      fn_fitf: final_ta  # file name of final fitting line (default "final")
      format: 3  # 1:csv, 2:text, 3:csv and text (default 1)
      outdir: ./output  # base directory (default "./output")
      matplotlib: 1  # 0:no, 1:yes (default 0)

xs
*************************************

断面積計算を行う際の中性子エネルギーの範囲等の設定を行う。
Defaultが設定されている変数は省略可能である。
このグループは省略することはできない。

.. csv-table:: xsグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_xs

   変数名, 型または値, Default, 説明
   e_l, 実数,, 断面積計算を行う際のエネルギーの下限値[eV]
   e_h, 実数,, 断面積計算を行う際のエネルギーの上限値[eV]
   enum, 整数,,断面積計算を行う際のエネルギーの群数を設定する。正の場合は対数、負の場合は線形で等分点が与えられる。
   reuse, 整数：0/1, 0, （バージョン1.3.2から追加）0の場合、FRENDYを用いて断面積の計算を行う。1の場合、FRENDYで計算済みの断面積データファイル（ `control` の `fn_xs` で指定したファイル）を用いる。

具体例：

.. code-block:: yaml

    xs:
      e_l: 50.0  # lower limit of neutron energy [eV]
      e_h: 5000.0  # upper limit of neutron energy [eV]
      enum: 2000  # number of group (+:logscal, -:linscale)

.. note::

   reuse=1で計算を行う際に、用いる断面積データファイルでの計算条件（ `e_l` 、 `e_h` 、 `enum` の値および `material` で指定する核データファイル）と
   異なる計算条件で計算を行いたい場合には、改めて断面積の計算を行う必要があることに注意すること。

material
*************************************

試料に含まれる物質の定義を行う。
`material` キーの値は配列であり、複数の物質を定義できる。
このグループは省略することはできない。

.. csv-table:: materialグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_material

   変数名, 型または値, Default, 説明
   name, 文字列,, 物質の名前を設定する。
   elm, 配列,, 物質を構成する元素を設定する。配列の各要素において、核データ `ndata` 、 存在比 `abn` を設定する。
   elm/ndata, 文字列,, 元素の核データを設定する。
   elm/abn, 実数,, 元素の存在比を設定する。
   elm/pw,‐ ,, このキーが存在する場合、 `ndata` で指定した核データはポイントワイズデータとして読み込まれる（値は何でもよい）。
   dens, 実数,, 物質の密度を体積密度[ :math:`g/cm^{3}` ]で指定する。 `area_dens` で密度を定義する場合、省略可能。
   thickness, 実数,, 物質の厚さを[cm]で指定する。 `area_dens` で密度を定義する場合、省略可能。
   area_dens, 実数,, 物質の密度を面密度[atoms/barn]で指定する。 `dens` と `thickness` で密度を定義する場合、 `area_dens` を定義するとエラーとなる。
   teff, 実数, 300.0, 物質の温度（実効温度）を[K]で指定する。
   tsamp, 実数,, 物質の温度を[K]で指定する。
   debye, 実数,, 物質のデバイ温度を[K]で指定する。
   pw, 配列,, ポイントワイズデータで温度マップを作成する場合、配列の各要素においてポイントワイズデータファイル `file` と温度 `temp` の組を定義する。
   pw/file, 文字列,, ポイントワイズデータファイルを設定する。
   pw/temp, 実数,, ポイントワイズデータの温度を設定する。


具体例：

.. code-block:: yaml

    material:
      - name: cu  # name of material (1)
        elm:
          - ndata: data/jendl5/Cu63.res
            abn: 0.6915
          - ndata: data/jendl5/Cu65.res
            abn: 0.3085
        dens: 8.9  # density of sample [g/cm^3]
        thickness: 0.2  # thickness of sample [cm]
        tsamp: 300.0  # sample temperature [K]
        debye: 343  # debye temperature [K]
      - name: ta  # name of material (2)
        elm:
          - ndata: data/jendl5/Ta181.res
            abn: 1.0
        area_dens: 1.68e-4  # area density of sample [at/b]
        teff: 300.0  # effective temperature [K] (default 300.0)

transmission
*************************************

透過率計算を行う際の設定を行う。
Defaultが設定されている変数は省略可能である。
インプットファイルに `fitting` グループが設定されている場合、このグループは無視される。
また、 `transmission` と `capture` を同時に設定している場合、エラーメッセージが出力されて計算ができない。
また、 `control` グループにおいて `sim=1` を設定している場合はこのグループを省略できる。

.. csv-table:: transmissionグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_transmission

   変数名, 型または値, Default, 説明
   t_l, 実数,, 透過率計算を行う際のTOFの下限値[ :math:`\mu s` ]。xsグループで設定したエネルギー範囲を外れた値を設定できる。0を設定した場合、エネルギーが無限大になってしまうため、最初のTOFビンを切り詰めて計算を行う。
   t_h, 実数,, 透過率計算を行う際のTOFの上限値[ :math:`\mu s` ]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   tnum, 整数,, TOFのビン数を設定する。正の場合は対数、負の場合は線形で等分点が与えられる。
   e_l, 実数,, 透過率計算を行う際のエネルギーの下限値[eV]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   e_h, 実数,, 透過率計算を行う際のエネルギーの上限値[eV]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   enum, 整数,, エネルギーの群数を設定する。正の場合は対数、負の場合は線形で等分点が与えられる。
   L, 実数, 18.0, 飛行距離[m]を設定する。
   td, 実数, 0.0, TOFのずれ[ :math:`\mu s` ]を設定する。+方向が遅れ、-方向が進みである。
   a0, 実数, 1.0, ベースラインを表す多項式の0次の係数
   a1, 実数, 0.0, ベースラインを表す多項式の1次の係数
   a2, 実数, 0.0, ベースラインを表す多項式の2次の係数
   a3, 実数, 0.0, ベースラインを表す多項式の3次の係数
   a4, 実数, 0.0, ベースラインを表す多項式の4次の係数

.. note::

    `t_l` , `t_h` , `tnum` と `e_l` , `e_h` , `enum` はどちらか一方のみ設定すればよい。
    また、計算範囲の設定はTOFがエネルギーに優先される。
    つまり、 `t_l` , `t_h` , `tnum` が設定されている場合、 `e_l` , `e_h` , `enum` は無視される。

具体例：

.. code-block:: yaml
    transmission:
      t_l: 20.0  # lower limit of TOF [us]
      t_h: 150.0  # upper limit of TOF [us]
      tnum: -600  # number of TOF bin (+:logscal, -:linscale)
      L: 18.0  # flight path [m] (default 18.0)
      td: 1.0  # delay of TOF [us] (default 0.0)

capture
*************************************

共鳴吸収量計算を行う際の設定を行う。
Defaultが設定されている変数は省略可能である。
インプットファイルに `fitting` グループが設定されている場合、このグループは無視される。
また、 `transmission` と `capture` を同時に設定している場合、エラーメッセージが出力されて計算ができない。
また、 `control` グループにおいて `sim=1` を設定している場合はこのグループを省略できる。

.. csv-table:: captureグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_capture

   変数名, 型または値, Default, 説明
   t_l, 実数,, 共鳴吸収量計算を行う際のTOFの下限値[ :math:`\mu s` ]。xsグループで設定したエネルギー範囲を外れた値を設定できる。0を設定した場合、エネルギーが無限大になってしまうため、最初のTOFビンを切り詰めて計算を行う。
   t_h, 実数,, 共鳴吸収量計算を行う際のTOFの上限値[ :math:`\mu s` ]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   tnum, 整数,, TOFのビン数を設定する。正の場合は対数、負の場合は線形で等分点が与えられる。
   e_l, 実数,, 共鳴吸収量計算を行う際のエネルギーの下限値[eV]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   e_h, 実数,, 共鳴吸収量計算を行う際のエネルギーの上限値[eV]。xsグループで設定したエネルギー範囲を外れた値を設定できる。
   enum, 整数,, エネルギーの群数を設定する。正の場合は対数、負の場合は線形で等分点が与えられる。
   L, 実数, 18.0, 飛行距離[m]を設定する。
   td, 実数, 0.0, TOFのずれ[ :math:`\mu s` ]を設定する。+方向が遅れ、-方向が進みである。
   a0, 実数, 1.0, ベースラインを表す多項式の0次の係数
   a1, 実数, 0.0, ベースラインを表す多項式の1次の係数
   a2, 実数, 0.0, ベースラインを表す多項式の2次の係数
   a3, 実数, 0.0, ベースラインを表す多項式の3次の係数
   a4, 実数, 0.0, ベースラインを表す多項式の4次の係数
   c, 実数, 1.0, 共鳴吸収量の強度を規格化する係数

.. note::

    `t_l` , `t_h` , `tnum` と `e_l` , `e_h` , `enum` はどちらか一方のみ設定すればよい。
    また、計算範囲の設定はTOFがエネルギーに優先される。
    つまり、 `t_l` , `t_h` , `tnum` が設定されている場合、 `e_l` , `e_h` , `enum` は無視される。

具体例：

.. code-block:: yaml

    capture:
      t_l: 20.0  # lower limit of TOF [us]
      t_h: 800.0  # upper limit of TOF [us]
      tnum: -600  # number of TOF bin (+:logscal, -:linscale)
      L: 18.0  # flight path [m] (default 18.0)
      td: 1.0  # delay of TOF [us] (default 0.0)
      a0: 100  # baseline parameter a0
      c: 100000  # scale factor (default 1.0)

fitting
*************************************

スペクトルフィッティングを行う際の設定を行う。
Defaultが設定されている変数は省略可能である。
`control` グループで `fit` が定義されていない場合、このグループは無視される。

.. csv-table:: fittingグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_fitting

   変数名, 型または値, Default, 説明
   meas_file, 文字列,, 測定データのファイルパスを設定する。複数ファイルを一括でフィッティングする場合には、フォルダ内の1つのファイルを指定する。
   adjust, 文字列,, "どのパラメータをフィットするか選択する。
                     | path：飛行距離とTOFのずれ
                     | base：ベースライン
                     | dens：密度
                     | base_dens：ベースラインから密度の連続フィット
                     | temp：温度
                     | temp_map：温度（温度マップでフィットする場合）
                     | temp_pw：温度（ポイントワイズデータを利用した温度マップでフィットする場合）
                     | c：共鳴吸収量の強度の規格化係数
                     | pulse：パルス関数のパラメータ（t0、sig1、sig2、g1、g2、ratio）"
   L, 実数,, 飛行距離[m]を設定する。adjust="path"の場合、初期値となる。
   td, 実数,, TOFのずれ[ :math:`\mu s` ]を設定する。adjust="path"の場合、初期値となる。
   teff, 実数,, 実効温度[K]を設定する。adjust="temp"、"temp_map"、"temp_pw"の場合、初期値となる。それ以外の場合にはmaterialの温度が計算に使用される。
   teff_list, 配列[実数],, 温度マップを作成する際の温度点。配列で4点以上設定する必要がある。adjust="temp_map"の場合に有効。
   a0, 実数, 1.0, ベースラインを表す多項式の0次の係数。adjust="base"または"base_dens"の場合、初期値となる。
   a1, 実数, 0.0, ベースラインを表す多項式の1次の係数。adjust="base"または"base_dens"の場合、初期値となる。
   a2, 実数, 0.0, ベースラインを表す多項式の2次の係数。adjust="base"または"base_dens"の場合、初期値となる。
   a3, 実数, 0.0, ベースラインを表す多項式の3次の係数。adjust="base"または"base_dens"の場合、初期値となる。
   a4, 実数, 0.0, ベースラインを表す多項式の4次の係数。adjust="base"または"base_dens"の場合、初期値となる。
   c, 実数, 1.0, 共鳴吸収量の強度を規格化する係数。adjust="c"の場合、初期値となる。
   t0, 実数,, パルス関数のパラメータ :math:`t_{0}` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   sig1, 実数,, パルス関数のパラメータ :math:`\sigma_{1}` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   sig2, 実数,, パルス関数のパラメータ :math:`\sigma_{2}` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   g1, 実数,, パルス関数のパラメータ :math:`\gamma_{1}` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   g2, 実数,, パルス関数のパラメータ :math:`\gamma_{2}` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   ratio, 実数,, パルス関数のパラメータ :math:`R` を設定する。pulse_fit=1の場合に必要となる。adjust="pulse"の場合、初期値となる。
   fit_material, 配列[文字列],, adjust="dens"または"base_dens"の場合に、密度を求める対象となる物質を名前 `name` で指定する。対象となる物質が1つであっても配列として設定する。
   fit_range, 配列[配列[実数]],, フィッティング範囲をTOF[ :math:`\mu s` ]で指定する。下限と上限を配列で指定する。範囲が1つであっても配列として設定する。
   base, 配列[配列[実数]],, ベースラインをフィットする際のフィッティング範囲をTOF[ :math:`\mu s` ]で指定する。下限と上限を配列で指定する。範囲が1つであっても配列として設定する。
   level, 実数, 0.0, この値以下の透過率もしくは共鳴吸収量のTOF範囲をフィッティングから除外する。
   show, 整数：0/1, 0, フィッティング中にイタレーション計算の途中経過を標準出力に(1)表示するか、(0)表示しないかを選択する。

具体例：

.. code-block:: yaml

    fitting:
      meas_file: data/measurement/Tr_Ta.dat
      # initial parameters
      L: 23.7  # flight path [m]
      td: 0.0  # delay of TOF [us]
      teff: 300.0  # effective temperature [K]
      # material
      fit_material:
        - ta
      # fitting range
      fit_range:
        - [520.0, 550.0]  # lower and upper limit of fitting range (TOF [us])
        - [800.0, 860.0]  # lower and upper limit of fitting range (TOF [us])
      # mask
      level: 0.0  # masking level of transmission (Default 0.0)
      # adjusted parameter(s)
      adjust: dens  # Type of fitting parameter(s)
                    # path:L, delay, dens:density, temp:temperature
                    # pulse:pulse function, base:baseline
      show: 1

.. note::

    adjust="base"または"base_dens"においてベースラインのフィッティングを行う場合、
    a0からa4までのうち定義されている中で最大の次数のパラメータと同じ次数の多項式で計算が行われる。
    例えば、a0、a1、a2が定義されている場合、2次の多項式でベースライン計算を行う。
    すべてのパラメータが定義されていない場合、デフォルト値を係数とした4次の多項式で計算を行う。

.. note::

   配列は複数の値を括弧（ **[** と **]** ）で囲むことでも定義することができる（インライン記法）。
   例えば、 `fit_range` 変数はTOFの下限と上限の組を配列で定義し、その組を複数個設定できるため、配列の配列として定義する必要がある。
   この場合、ハイフンのみで記述すると人間には読みにくいので、上記の例の様にインライン記法を用いると良い。
   ちなみに、インライン記法を用いない場合は以下の様に記述する。

   .. code-block:: yaml

      fitting:
        fit_range:
          - - 520.0  # lower limit of fitting range (TOF [us])
            - 550.0  # upper limit of fitting range (TOF [us])
          - - 800.0  # lower limit of fitting range (TOF [us])
            - 860.0  # upper limit of fitting range (TOF [us])

pulse
*************************************

パルス関数に関する設定を行う。
Defaultが設定されている変数は省略可能である。
このグループは省略することができる。

.. csv-table:: pulseグループ変数
   :header-rows: 1
   :widths: 15, 15, 15, 55
   :name: input_pulse

   変数名, 型または値, Default, 説明
   pulse_file, 文字列, （使用しない）, パルス関数のパラメータ設定ファイルを相対パスで指定する。指定しない場合、ソースコード内に記述されているBL10の値で計算する。
   proton_file, 文字列, （使用しない）, 加速器ビームの時間構造定義ファイルを相対パスで指定する。指定しない場合、ソースコード内に記述されているダブルバンチ構造の値で計算する。

具体例：

.. code-block:: yaml

    pulse:
      pulse_file: data/pulse/BL10.dat  # parameters of pulse function (default none)
      proton_file: data/pulse/double.dat  # data of proton pulse shape (default none)