.. highlight:: none

[sampling.solver], [mlref.solver] セクション
----------------------------------------------------

配位 (原子配置など) からエネルギーを計算するソルバーの設定を行います.
``sampling.solver`` はモンテカルロサンプリング中のエネルギー計算に,
``mlref.solver`` は機械学習モデルの訓練データ作成に使われます.

現在, ソルバーは大きく分けて次の2種類あります.

- 第一原理ソルバー

   - 原子配置から DFT エネルギーを計算するソルバーです.

   - 実際には VASP など, 外部の第一原理計算ソフトウェアを利用します.

      - 収束条件など, ソフトウェア固有のパラメータなどはそれぞれの入力ファイルから読み取ります.

      - それぞれのソフトウェア固有の注意事項（入力ファイル名など）は :ref:`solver_specific_notes` を参照してください.

   - 原子の存在する座標や原子種などは ``[config]`` セクションで指定します.

- Potts 模型ソルバー

   - 超立方格子上のスピン配位 (:math:`\{\sigma_i\}`, :math:`\sigma_i = 0, 1, \dots, Q-1`) のエネルギー :math:`E = -\sum_{ij} \delta_{\sigma_i, \sigma_j} \quad (\sigma_i = 0, 1, \dots, Q-1)` を計算するソルバーです.

   - 超立方格子の次元および格子点の数, スピンの取りうる値 :math:`Q` は ``[config]`` セクションで指定します.

   - アルゴリズムのテストおよびチュートリアルを目的としたソルバーです.


ソルバーの種類 (VASP, QE, ...)、ソルバーへのパス、不変な入力ファイルのあるディレクトリなど（第一原理計算）ソルバーのパラメータを指定します.
以下のようなファイルフォーマットをしています.

  :: 
  
    [sampling.solver]
    type = 'vasp'
    path = './vasp'
    base_input_dir = './baseinput'
    perturb = 0.1
    run_scheme = 'mpi_spawn_ready'

入力形式
^^^^^^^^^^^^
``keyword = value`` の形式でキーワードとその値を指定します.
また, #をつけることでコメントを入力することができます(それ以降の文字は無視されます).

キーワード
^^^^^^^^^^

-  ``type``

   **形式 :** str型

   **説明 :**
   ソルバーの種類を指定します. 大文字小文字の区別はありません.

   -  ``OpenMX``

      - OpenMXを利用します.

   -  ``QE``

      - Quantum Espressoを利用します.

   -  ``VASP``

      - VASPを利用します.

   -  ``aenet``

      - aenetを利用します.

   -  ``aenetPyLammps``

      - LAMMPS を経由してaenetを利用します.

   -  ``nequip``

      - NequIPを利用します.

   -  ``allegro``

      - Allegroを利用します.

   -  ``mlip_3``

      - MLIP-3を利用します.

   -  ``user``
   
      - ユーザー定義のソルバーを利用します.

   -  ``potts``

      - Potts 模型ソルバーを利用します.
      - 主にアルゴリズムのテストおよびチュートリアルを目的としたソルバーです.

   ``type = "potts"`` の場合には以下のパラメータは利用しません.

-  ``path``

   **形式 :** str型

   **説明 :**
   ソルバーへのパスを指定します.

-  ``base_input_dir``

   **形式 :** str型 or str型のリスト

   **説明 :** 
   ベースとなる入力ファイルへのパスを指定します.
   リスト形式で複数設定した場合は、各々の入力を使った計算が順番に実行されます. 2番目以降の計算では、前の計算の最終ステップでの構造が初期座標として用いられ, 最後の計算のエネルギーが使用されます. 例えば、1つ目の入力ファイルで精度を犠牲にして高速な構造最適化を行い、2番目以降の入力ファイルで高精度な設定で構造最適化を行うといったことが可能にります. あるいは、格子ベクトルの緩和を行う場合に、設定した平面波カットオフに基づいて計算メッシュをリセットするために同じ入力の計算を複数回実行するといったことも可能です.

-  ``perturb``

   **形式 :** float型

   **説明 :**
   対称性が良い構造を入力にしてしまうと、構造最適化が鞍点で止まってしまいがちである。これを避けるため、各原子をこのパラメータに比例するようにランダムに変位させたものを初期構造とする。0.0あるいはfalseに設定することも可能. デフォルト値 = 0.0.

-  ``ignore_species``

   **形式 :** list型

   **説明 :**
   ``aenet`` などのニューラルネットワークモデルで「無視」する原子種を指定します. 常に占有率が1のものについては、ニューラルネットワークモデルの訓練および評価時に存在を無視した方が、計算効率が高くなります.

-  ``run_scheme`` (``sampling.solver`` のみ)

   **形式 :** str型

   **説明 :**
   ソルバーを起動する方法を指定します.
   詳細は :ref:`solver_specific_notes` を参照してください。       

-  ``parallel_level`` (``type = "QE"`` のみ)

   **形式 :** 辞書型

   **説明 :** 
   `Parallelization levels <https://www.quantum-espresso.org/Doc/user_guide/node18.html>`_ について、各level の並列数を指定します。
   長い形式のコマンドラインオプションから ``-`` を抜いたもの、すなわち、
   ``nimage``, ``npools``, ``nband``, ``ntg``, ``ndiag`` をキーとして、各level の分割数を値とする辞書として指定します。
   指定した要素のみ、実際のコマンドラインオプションとして ``pw.x`` に渡されます。

-  ``function`` (``type = "user"`` のみ)

   **形式 :** str型

   **説明 :** 
   ユーザー定義のソルバー関数を指定します.

   - ソルバー関数は ``pymatgen.core.Structure`` を受け取って ``float`` を返す関数である必要があります.

   - ``.`` で区切られたパッケージ名を含む場合は、パッケージは自動でインポートされます.

      - 例えば ``function = "mypackage.mymodule.myfunction"`` と指定した場合、 ``mypackage.mymodule`` がインポートされ、 ``myfunction`` が呼び出されます.
      - インポートされるパッケージはカレントディレクトリからも探索されます.