Update docs

openkim · Oct 7, 2022 · 9d9b0bf · 9d9b0bf
1 parent fc27b27
commit 9d9b0bf
Show file tree

Hide file tree

Showing 9 changed files with 118 additions and 140 deletions.
diff --git a/docs/source/auto_examples/auto_examples_jupyter.zip b/docs/source/auto_examples/auto_examples_jupyter.zip
diff --git a/docs/source/auto_examples/auto_examples_python.zip b/docs/source/auto_examples/auto_examples_python.zip
diff --git a/docs/source/auto_examples/example_kim_SW_Si.ipynb b/docs/source/auto_examples/example_kim_SW_Si.ipynb
@@ -22,7 +22,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Before getting started to train the SW model, let's first install the SW model::\n\n   $ kim-api-collections-management install user SW_StillingerWeber_1985_Si__MO_405512056662_006\n\n.. seealso::\n   This installs the model and its driver into the ``User Collection``. See\n   `install_model` for more information about installing KIM models.\n\nWe are going to create potentials for diamond silicon, and fit the potentials to a\ntraining set of energies and forces consisting of compressed and stretched diamond\nsilicon structures, as well as configurations drawn from molecular dynamics trajectories\nat different temperatures.\nDownload the training set :download:`Si_training_set.tar.gz\n<https://raw.githubusercontent.com/openkim/kliff/master/examples/Si_training_set.tar.gz>`.\n(It will be automatically downloaded if not present.)\nThe data is stored in # **extended xyz** format, and see `doc.dataset` for more\ninformation of this format.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>The ``Si_training_set`` is just a toy data set for the purpose to demonstrate how to\n   use KLIFF to train potentials. It should not be used to train any potential for real\n   simulations.</p></div>\n\nLet's first import the modules that will be used in this example.\n\n"
+        "Before getting started to train the SW model, let's first make sure it is installed.\n\nIf you haven't already, follow `installation` to install ``kim-api`` and\n``kimpy``, and ``openkim-models``.\n\nThen do ``$ kim-api-collections-management list``, and make sure\n``SW_StillingerWeber_1985_Si__MO_405512056662_006`` is listed in one of the\ncollections.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>If you see ``SW_StillingerWeber_1985_Si__MO_405512056662_005`` (note the last\n   three digits), you need to change ``model = KIMModel(model_name=\"SW_StillingerWeber_1985_Si__MO_405512056662_006\")``\n   to the corresponding model name in your installation.</p></div>\n\n\nWe are going to create potentials for diamond silicon, and fit the potentials to a\ntraining set of energies and forces consisting of compressed and stretched diamond\nsilicon structures, as well as configurations drawn from molecular dynamics trajectories\nat different temperatures.\nDownload the training set :download:`Si_training_set.tar.gz\n<https://raw.githubusercontent.com/openkim/kliff/master/examples/Si_training_set.tar.gz>`.\n(It will be automatically downloaded if not present.)\nThe data is stored in # **extended xyz** format, and see `doc.dataset` for more\ninformation of this format.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>The ``Si_training_set`` is just a toy data set for the purpose to demonstrate how to\n   use KLIFF to train potentials. It should not be used to train any potential for real\n   simulations.</p></div>\n\nLet's first import the modules that will be used in this example.\n\n"
       ]
     },
     {
@@ -168,7 +168,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.9.12"
+      "version": "3.10.6"
     }
   },
   "nbformat": 4,

diff --git a/docs/source/auto_examples/example_kim_SW_Si.py b/docs/source/auto_examples/example_kim_SW_Si.py
@@ -10,13 +10,20 @@
 
 
 ##########################################################################################
-# Before getting started to train the SW model, let's first install the SW model::
+# Before getting started to train the SW model, let's first make sure it is installed.
 #
-#    $ kim-api-collections-management install user SW_StillingerWeber_1985_Si__MO_405512056662_006
+# If you haven't already, follow :ref:`installation` to install ``kim-api`` and
+# ``kimpy``, and ``openkim-models``.
+#
+# Then do ``$ kim-api-collections-management list``, and make sure
+# ``SW_StillingerWeber_1985_Si__MO_405512056662_006`` is listed in one of the
+# collections.
+#
+# .. note::
+#    If you see ``SW_StillingerWeber_1985_Si__MO_405512056662_005`` (note the last
+#    three digits), you need to change ``model = KIMModel(model_name="SW_StillingerWeber_1985_Si__MO_405512056662_006")``
+#    to the corresponding model name in your installation.
 #
-# .. seealso::
-#    This installs the model and its driver into the ``User Collection``. See
-#    :ref:`install_model` for more information about installing KIM models.
 #
 # We are going to create potentials for diamond silicon, and fit the potentials to a
 # training set of energies and forces consisting of compressed and stretched diamond

diff --git a/docs/source/auto_examples/example_kim_SW_Si.py.md5 b/docs/source/auto_examples/example_kim_SW_Si.py.md5
@@ -1 +1 @@
-aa103f8edc37ca96254be2e86d1426f3
+947c895af491358253f7829e0e4762ee
diff --git a/docs/source/auto_examples/example_kim_SW_Si.rst b/docs/source/auto_examples/example_kim_SW_Si.rst
@@ -26,15 +26,22 @@ Train a Stillinger-Weber potential
 In this tutorial, we train a Stillinger-Weber (SW) potential for silicon that is archived
 on OpenKIM_.
 
-.. GENERATED FROM PYTHON SOURCE LINES 13-37
+.. GENERATED FROM PYTHON SOURCE LINES 13-44
 
-Before getting started to train the SW model, let's first install the SW model::
+Before getting started to train the SW model, let's first make sure it is installed.
 
-   $ kim-api-collections-management install user SW_StillingerWeber_1985_Si__MO_405512056662_006
+If you haven't already, follow :ref:`installation` to install ``kim-api`` and
+``kimpy``, and ``openkim-models``.
+
+Then do ``$ kim-api-collections-management list``, and make sure
+``SW_StillingerWeber_1985_Si__MO_405512056662_006`` is listed in one of the
+collections.
+
+.. note::
+   If you see ``SW_StillingerWeber_1985_Si__MO_405512056662_005`` (note the last
+   three digits), you need to change ``model = KIMModel(model_name="SW_StillingerWeber_1985_Si__MO_405512056662_006")``
+   to the corresponding model name in your installation.
 
-.. seealso::
-   This installs the model and its driver into the ``User Collection``. See
-   :ref:`install_model` for more information about installing KIM models.
 
 We are going to create potentials for diamond silicon, and fit the potentials to a
 training set of energies and forces consisting of compressed and stretched diamond
@@ -53,7 +60,7 @@ information of this format.
 
 Let's first import the modules that will be used in this example.
 
-.. GENERATED FROM PYTHON SOURCE LINES 37-45
+.. GENERATED FROM PYTHON SOURCE LINES 44-52
 
 .. code-block:: default
 
@@ -72,15 +79,15 @@ Let's first import the modules that will be used in this example.
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 46-51
+.. GENERATED FROM PYTHON SOURCE LINES 53-58
 
 Model
 -----
 
 We first create a KIM model for the SW potential, and print out all the available
 parameters that can be optimized (we call this ``model parameters``).
 
-.. GENERATED FROM PYTHON SOURCE LINES 51-56
+.. GENERATED FROM PYTHON SOURCE LINES 58-63
 
 .. code-block:: default
 
@@ -95,8 +102,6 @@ parameters that can be optimized (we call this ``model parameters``).
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
     #================================================================================
@@ -147,7 +152,7 @@ parameters that can be optimized (we call this ``model parameters``).
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 57-71
+.. GENERATED FROM PYTHON SOURCE LINES 64-78
 
 The output is generated by the last line, and it tells us the ``name``, ``value``,
 ``size``, ``data type`` and a ``description`` of each parameter.
@@ -164,7 +169,7 @@ The output is generated by the last line, and it tells us the ``name``, ``value`
 Now that we know what parameters are available for fitting, we can optimize all or a
 subset of them to reproduce the training set.
 
-.. GENERATED FROM PYTHON SOURCE LINES 71-78
+.. GENERATED FROM PYTHON SOURCE LINES 78-85
 
 .. code-block:: default
 
@@ -181,8 +186,6 @@ subset of them to reproduce the training set.
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
     #================================================================================
@@ -209,7 +212,7 @@ subset of them to reproduce the training set.
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 79-115
+.. GENERATED FROM PYTHON SOURCE LINES 86-122
 
 Here, we tell KLIFF to fit four parameters ``B``, ``gamma``, ``sigma``, and ``A`` of the
 SW model. The information for each fitting parameter should be provided as a list of
@@ -248,7 +251,7 @@ corresponding to each configuration using :class:`~kliff.dataset.weight.Weight`.
 this example, we set ``energy_weight`` to ``1.0`` and ``forces_weight`` to ``0.1``.
 For the silicon training set, we can read and process the files by:
 
-.. GENERATED FROM PYTHON SOURCE LINES 115-122
+.. GENERATED FROM PYTHON SOURCE LINES 122-129
 
 .. code-block:: default
 
@@ -265,16 +268,14 @@ For the silicon training set, we can read and process the files by:
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
-    2022-04-28 11:03:34.898 | INFO     | kliff.dataset.dataset:_read:397 - 1000 configurations read from /Users/mjwen/Applications/kliff/examples/Si_training_set
+    2022-10-06 23:44:01.093 | INFO     | kliff.dataset.dataset:_read:398 - 1000 configurations read from /Users/mjwen.admin/Packages/kliff/examples/Si_training_set
 
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 123-139
+.. GENERATED FROM PYTHON SOURCE LINES 130-146
 
 The ``configs`` in the last line is a list of :class:`~kliff.dataset.Configuration`.
 Each configuration is an internal representation of a processed **extended xyz** file,
@@ -293,7 +294,7 @@ parameters stored in the model so that the up-to-date parameters are used the ne
 the model is evaluated to compute the energy and forces. The calculator can be created
 by:
 
-.. GENERATED FROM PYTHON SOURCE LINES 139-144
+.. GENERATED FROM PYTHON SOURCE LINES 146-151
 
 .. code-block:: default
 
@@ -308,16 +309,14 @@ by:
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
-    2022-04-28 11:03:38.460 | INFO     | kliff.calculators.calculator:create:107 - Create calculator for 1000 configurations.
+    2022-10-06 23:44:01.499 | INFO     | kliff.calculators.calculator:create:107 - Create calculator for 1000 configurations.
 
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 145-160
+.. GENERATED FROM PYTHON SOURCE LINES 152-167
 
 where ``calc.create(configs)`` does some initializations for each
 configuration in the training set, such as creating the neighbor list.
@@ -335,7 +334,7 @@ following code snippet, we create a loss of energy and forces and use ``2`` proc
 to calculate the loss. The ``L-BFGS-B`` minimization algorithm is applied to minimize
 the loss, and the minimization is allowed to run for a max number of 100 iterations.
 
-.. GENERATED FROM PYTHON SOURCE LINES 160-166
+.. GENERATED FROM PYTHON SOURCE LINES 167-173
 
 .. code-block:: default
 
@@ -351,35 +350,33 @@ the loss, and the minimization is allowed to run for a max number of 100 iterati
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
-    2022-04-28 11:03:38.462 | INFO     | kliff.loss:minimize:290 - Start minimization using method: L-BFGS-B.
-    2022-04-28 11:03:38.462 | INFO     | kliff.loss:_scipy_optimize:406 - Running in multiprocessing mode with 2 processes.
-    2022-04-28 11:05:36.267 | INFO     | kliff.loss:minimize:292 - Finish minimization using method: L-BFGS-B.
+    2022-10-06 23:44:01.500 | INFO     | kliff.loss:minimize:290 - Start minimization using method: L-BFGS-B.
+    2022-10-06 23:44:01.501 | INFO     | kliff.loss:_scipy_optimize:406 - Running in multiprocessing mode with 2 processes.
+    2022-10-06 23:44:36.663 | INFO     | kliff.loss:minimize:292 - Finish minimization using method: L-BFGS-B.
 
-          fun: 0.6940780132834561
+          fun: 0.6940780132865667
      hess_inv: <3x3 LbfgsInvHessProduct with dtype=float64>
-          jac: array([-3.65263345e-06,  1.88971060e-04,  3.90798507e-06])
-      message: 'CONVERGENCE: REL_REDUCTION_OF_F_<=_FACTR*EPSMCH'
-         nfev: 180
-          nit: 36
-         njev: 45
+          jac: array([ 8.88178346e-07, -3.50830474e-06,  7.77156122e-08])
+      message: 'CONVERGENCE: NORM_OF_PROJECTED_GRADIENT_<=_PGTOL'
+         nfev: 184
+          nit: 37
+         njev: 46
        status: 0
       success: True
-            x: array([14.93863664,  0.58740288,  2.20146242])
+            x: array([14.93863457,  0.58740273,  2.20146129])
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 167-171
+.. GENERATED FROM PYTHON SOURCE LINES 174-178
 
 The minimization stops after running for 27 steps.  After the minimization, we'd better
 save the model, which can be loaded later for the purpose to do a retraining or
 evaluations. If satisfied with the fitted model, you can also write it as a KIM model
 that can be used with LAMMPS_, GULP_, ASE_, etc. via the kim-api_.
 
-.. GENERATED FROM PYTHON SOURCE LINES 171-178
+.. GENERATED FROM PYTHON SOURCE LINES 178-185
 
 .. code-block:: default
 
@@ -396,8 +393,6 @@ that can be used with LAMMPS_, GULP_, ASE_, etc. via the kim-api_.
 
 .. rst-class:: sphx-glr-script-out
 
- Out:
-
  .. code-block:: none
 
     #================================================================================
@@ -407,24 +402,24 @@ that can be used with LAMMPS_, GULP_, ASE_, etc. via the kim-api_.
     #================================================================================
 
     A 1
-      1.4938636641779590e+01   1.0000000000000000e+00   2.0000000000000000e+01 
+      1.4938634567965085e+01   1.0000000000000000e+00   2.0000000000000000e+01 
 
     B 1
-      5.8740288227791959e-01 
+      5.8740272891468026e-01 
 
     sigma 1
       2.0951000000000000e+00 fix 
 
     gamma 1
-      2.2014624192566941e+00 
+      2.2014612879744848e+00 
 
 
-    2022-04-28 11:05:36.291 | INFO     | kliff.models.kim:write_kim_model:695 - KLIFF trained model write to `/Users/mjwen/Applications/kliff/examples/SW_StillingerWeber_1985_Si__MO_405512056662_006_kliff_trained`
+    2022-10-06 23:44:36.670 | INFO     | kliff.models.kim:write_kim_model:695 - KLIFF trained model write to `/Users/mjwen.admin/Packages/kliff/examples/SW_StillingerWeber_1985_Si__MO_405512056662_006_kliff_trained`
 
 
 
 
-.. GENERATED FROM PYTHON SOURCE LINES 179-197
+.. GENERATED FROM PYTHON SOURCE LINES 186-204
 
 The first line of the above code generates the output.  A comparison with the original
 parameters before carrying out the minimization shows that we recover the original
@@ -448,28 +443,23 @@ parameters quite reasonably. The second line saves the fitted model to a file na
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** ( 2 minutes  4.046 seconds)
+   **Total running time of the script:** ( 0 minutes  36.524 seconds)
 
 
 .. _sphx_glr_download_auto_examples_example_kim_SW_Si.py:
 
+.. only:: html
 
-.. only :: html
-
- .. container:: sphx-glr-footer
-    :class: sphx-glr-footer-example
-
-
-
-  .. container:: sphx-glr-download sphx-glr-download-python
+  .. container:: sphx-glr-footer sphx-glr-footer-example
 
-     :download:`Download Python source code: example_kim_SW_Si.py <example_kim_SW_Si.py>`
 
+    .. container:: sphx-glr-download sphx-glr-download-python
 
+      :download:`Download Python source code: example_kim_SW_Si.py <example_kim_SW_Si.py>`
 
-  .. container:: sphx-glr-download sphx-glr-download-jupyter
+    .. container:: sphx-glr-download sphx-glr-download-jupyter
 
-     :download:`Download Jupyter notebook: example_kim_SW_Si.ipynb <example_kim_SW_Si.ipynb>`
+      :download:`Download Jupyter notebook: example_kim_SW_Si.ipynb <example_kim_SW_Si.ipynb>`
 
 
 .. only:: html

diff --git a/docs/source/auto_examples/example_kim_SW_Si_codeobj.pickle b/docs/source/auto_examples/example_kim_SW_Si_codeobj.pickle