deploy: b2f84bd

_sources/pypolymlp.md

@@ -36,7 +36,8 @@ in the distribution from GitHub or PyPI.
    supercells. The dataset must be stored in a phono3py-yaml-like file, e.g.,
    `phono3py_params.yaml`. Use {ref}`--cf3 <cf3_option>` and {ref}`--sp
    <sp_option>` option simultaneously.
-4. Develop MLPs. At this step `phono3py.pmlp` is saved.
+4. Develop MLPs. By default, 90 and 10 percents of the dataset are used for the
+   training and test, respectively. At this step `phono3py.pmlp` is saved.
 5. Generate displacements in supercells either systematic or random displacements.
 6. Evaluate MLPs for forces of the supercells generated in step 5.
 7. Calculate force constants from displacement-force dataset from steps 5 and 6.
@@ -244,7 +245,7 @@ Having `phono3py_params.yaml`, phono3py is executed with `--pypolymlp` option,
  | |_) | | | | (_) | | | | (_) |__) | |_) | |_| |
  | .__/|_| |_|\___/|_| |_|\___/____/| .__/ \__, |
  |_|                                |_|    |___/
-                       3.5.0-dev22+g575c4107
+                                           3.5.0
 
 -------------------------[time 2024-09-19 15:33:23]-------------------------
 Compiled with OpenMP support (max 10 threads).
@@ -327,3 +328,40 @@ displacements are generated. These displacements are then inverted, resulting in
 an additional 200 supercells. In total, 400 supercells are created. The forces
 for these supercells are then evaluated. Finally, the force constants are
 calculated using symfc.
+
+## Parameters for developing MLPs
+
+A few parameters can be specified using the `--mlp-params` option for the
+development of MLPs. The parameters are provided as a string, e.g.,
+
+```bash
+% phono3py-load phono3py_params.yaml --pypolymlp --mlp-params="ntrain=80, ntest=20"
+```
+
+Parameters are separated by commas for configuration. A brief explanation of the
+available parameters can be found in the docstring of `PypolymlpParams` that is
+found by
+
+```python
+In [1]: from phonopy.interface.pypolymlp import PypolymlpParams
+
+In [2]: help(PypolymlpParams)
+```
+
+`ntrain` and `ntest` are implemented in phono3py, while the remaining parameters
+are directly passed to pypolymlp. Optimizing pypolymlp parameters can be
+difficult, both in terms of achieving accuracy and managing the computational
+resources required. The current default parameters are likely suitable for
+systems up to ternary compounds. For binary systems, the calculations can
+generally be run on standard laptop computers, but for ternary systems, around
+40 GB of memory or more may be necessary.
+
+For parameter adjustments, it is recommended to consult the
+[pypolymlp](https://github.com/sekocha/pypolymlp) documentation and review the
+ relevant research papers.
+
+### `ntrain` and `ntest`
+
+This method provides a straightforward dataset split: the first `ntrain`
+supercells from the list are used for training, while the last `ntest`
+supercells are reserved for testing.

pypolymlp.html

@@ -331,6 +331,10 @@ <h2> Contents </h2>
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#steps-4-6-force-constants-calculation-random-displacements-in-step-5">Steps 4-6: Force constants calculation (random displacements in step 5)</a></li>
 </ul>
 </li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#parameters-for-developing-mlps">Parameters for developing MLPs</a><ul class="nav section-nav flex-column">
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ntrain-and-ntest"><code class="docutils literal notranslate"><span class="pre">ntrain</span></code> and <code class="docutils literal notranslate"><span class="pre">ntest</span></code></a></li>
+</ul>
+</li>
 </ul>
             </nav>
         </div>
@@ -374,7 +378,8 @@ <h2>Workflow<a class="headerlink" href="#workflow" title="Link to this heading">
 <li><p>Prepare dataset composed of displacements, forces, and energies in
 supercells. The dataset must be stored in a phono3py-yaml-like file, e.g.,
 <code class="docutils literal notranslate"><span class="pre">phono3py_params.yaml</span></code>. Use <a class="reference internal" href="command-options.html#cf3-option"><span class="std std-ref">–cf3</span></a> and <a class="reference internal" href="command-options.html#sp-option"><span class="std std-ref">–sp</span></a> option simultaneously.</p></li>
-<li><p>Develop MLPs. At this step <code class="docutils literal notranslate"><span class="pre">phono3py.pmlp</span></code> is saved.</p></li>
+<li><p>Develop MLPs. By default, 90 and 10 percents of the dataset are used for the
+training and test, respectively. At this step <code class="docutils literal notranslate"><span class="pre">phono3py.pmlp</span></code> is saved.</p></li>
 <li><p>Generate displacements in supercells either systematic or random displacements.</p></li>
 <li><p>Evaluate MLPs for forces of the supercells generated in step 5.</p></li>
 <li><p>Calculate force constants from displacement-force dataset from steps 5 and 6.</p></li>
@@ -567,7 +572,7 @@ <h3>Steps 4-6: Force constants calculation (random displacements in step 5)<a cl
  <span class="o">|</span> <span class="o">|</span><span class="n">_</span><span class="p">)</span> <span class="o">|</span> <span class="o">|</span> <span class="o">|</span> <span class="o">|</span> <span class="p">(</span><span class="n">_</span><span class="p">)</span> <span class="o">|</span> <span class="o">|</span> <span class="o">|</span> <span class="o">|</span> <span class="p">(</span><span class="n">_</span><span class="p">)</span> <span class="o">|</span><span class="n">__</span><span class="p">)</span> <span class="o">|</span> <span class="o">|</span><span class="n">_</span><span class="p">)</span> <span class="o">|</span> <span class="o">|</span><span class="n">_</span><span class="o">|</span> <span class="o">|</span>
  <span class="o">|</span> <span class="o">.</span><span class="n">__</span><span class="o">/|</span><span class="n">_</span><span class="o">|</span> <span class="o">|</span><span class="n">_</span><span class="o">|</span>\<span class="n">___</span><span class="o">/|</span><span class="n">_</span><span class="o">|</span> <span class="o">|</span><span class="n">_</span><span class="o">|</span>\<span class="n">___</span><span class="o">/</span><span class="n">____</span><span class="o">/|</span> <span class="o">.</span><span class="n">__</span><span class="o">/</span> \<span class="n">__</span><span class="p">,</span> <span class="o">|</span>
  <span class="o">|</span><span class="n">_</span><span class="o">|</span>                                <span class="o">|</span><span class="n">_</span><span class="o">|</span>    <span class="o">|</span><span class="n">___</span><span class="o">/</span>
-                       <span class="mf">3.5.0</span><span class="o">-</span><span class="n">dev22</span><span class="o">+</span><span class="n">g575c4107</span>
+                                           <span class="mf">3.5.0</span>
 
 <span class="o">-------------------------</span><span class="p">[</span><span class="n">time</span> <span class="mi">2024</span><span class="o">-</span><span class="mi">09</span><span class="o">-</span><span class="mi">19</span> <span class="mi">15</span><span class="p">:</span><span class="mi">33</span><span class="p">:</span><span class="mi">23</span><span class="p">]</span><span class="o">-------------------------</span>
 <span class="n">Compiled</span> <span class="k">with</span> <span class="n">OpenMP</span> <span class="n">support</span> <span class="p">(</span><span class="nb">max</span> <span class="mi">10</span> <span class="n">threads</span><span class="p">)</span><span class="o">.</span>
@@ -651,6 +656,38 @@ <h3>Steps 4-6: Force constants calculation (random displacements in step 5)<a cl
 calculated using symfc.</p>
 </section>
 </section>
+<section id="parameters-for-developing-mlps">
+<h2>Parameters for developing MLPs<a class="headerlink" href="#parameters-for-developing-mlps" title="Link to this heading">#</a></h2>
+<p>A few parameters can be specified using the <code class="docutils literal notranslate"><span class="pre">--mlp-params</span></code> option for the
+development of MLPs. The parameters are provided as a string, e.g.,</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>%<span class="w"> </span>phono3py-load<span class="w"> </span>phono3py_params.yaml<span class="w"> </span>--pypolymlp<span class="w"> </span>--mlp-params<span class="o">=</span><span class="s2">&quot;ntrain=80, ntest=20&quot;</span>
+</pre></div>
+</div>
+<p>Parameters are separated by commas for configuration. A brief explanation of the
+available parameters can be found in the docstring of <code class="docutils literal notranslate"><span class="pre">PypolymlpParams</span></code> that is
+found by</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">In</span> <span class="p">[</span><span class="mi">1</span><span class="p">]:</span> <span class="kn">from</span> <span class="nn">phonopy.interface.pypolymlp</span> <span class="kn">import</span> <span class="n">PypolymlpParams</span>
+
+<span class="n">In</span> <span class="p">[</span><span class="mi">2</span><span class="p">]:</span> <span class="n">help</span><span class="p">(</span><span class="n">PypolymlpParams</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">ntrain</span></code> and <code class="docutils literal notranslate"><span class="pre">ntest</span></code> are implemented in phono3py, while the remaining parameters
+are directly passed to pypolymlp. Optimizing pypolymlp parameters can be
+difficult, both in terms of achieving accuracy and managing the computational
+resources required. The current default parameters are likely suitable for
+systems up to ternary compounds. For binary systems, the calculations can
+generally be run on standard laptop computers, but for ternary systems, around
+40 GB of memory or more may be necessary.</p>
+<p>For parameter adjustments, it is recommended to consult the
+<a class="reference external" href="https://github.com/sekocha/pypolymlp">pypolymlp</a> documentation and review the
+relevant research papers.</p>
+<section id="ntrain-and-ntest">
+<h3><code class="docutils literal notranslate"><span class="pre">ntrain</span></code> and <code class="docutils literal notranslate"><span class="pre">ntest</span></code><a class="headerlink" href="#ntrain-and-ntest" title="Link to this heading">#</a></h3>
+<p>This method provides a straightforward dataset split: the first <code class="docutils literal notranslate"><span class="pre">ntrain</span></code>
+supercells from the list are used for training, while the last <code class="docutils literal notranslate"><span class="pre">ntest</span></code>
+supercells are reserved for testing.</p>
+</section>
+</section>
 </section>
 
 
@@ -705,6 +742,10 @@ <h3>Steps 4-6: Force constants calculation (random displacements in step 5)<a cl
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#steps-4-6-force-constants-calculation-random-displacements-in-step-5">Steps 4-6: Force constants calculation (random displacements in step 5)</a></li>
 </ul>
 </li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#parameters-for-developing-mlps">Parameters for developing MLPs</a><ul class="nav section-nav flex-column">
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ntrain-and-ntest"><code class="docutils literal notranslate"><span class="pre">ntrain</span></code> and <code class="docutils literal notranslate"><span class="pre">ntest</span></code></a></li>
+</ul>
+</li>
 </ul>
   </nav></div>