update doc

MaterSim · Aug 17, 2024 · 084a827 · 084a827
1 parent 2672a75
commit 084a827
Show file tree

Hide file tree

Showing 51 changed files with 331 additions and 96 deletions.
diff --git a/doc/Usage.rst b/doc/Usage.rst
@@ -378,24 +378,42 @@ with a list of numbers. For example,
 .. code-block:: Python
 
     >>> my_crystal = pyxtal()
-    >>> my_crystal.from_random(3, 99, ['Ba','Ti','O'], [1,1,3])
+    >>> my_crystal.from_random(3, 99, ['Ba','Ti','O'], [1,1,3], random_state=10)
     >>> my_crystal
-    ------Random Crystal------
-    Composition: Ba1 Ti1 O3
+    
+    ------Crystal from random------
     Dimension: 3
-    Group: P4mm (99)
-    Volume factor: 1.0
-    tetragonal lattice:   5.1029   5.1029   4.3018  90.0000  90.0000  90.0000
+    Composition: Ba1Ti1O3
+    Group: P 4 m m (99)
+      4.0080,   4.0080,   9.3650,  90.0000,  90.0000,  90.0000, tetragonal
     Wyckoff sites:
-    	Ba @ [0.5000 0.5000 0.3612], Wyckoff letter:  1b, Site symmetry: 4 m m
-    	Ti @ [0.5000 0.5000 0.8701], Wyckoff letter:  1b, Site symmetry: 4 m m
-    	 O @ [0.5000 0.0000 0.0823], Wyckoff letter:  2c, Site symmetry: 2 mm .
-    	 O @ [0.5000 0.5000 0.8177], Wyckoff letter:  1b, Site symmetry: 4 m m
+    	Ba @ [ 0.5000  0.5000  0.7043], WP [1b] Site [4mm]
+    	Ti @ [ 0.0000  0.0000  0.2199], WP [1a] Site [4mm]
+    	 O @ [ 0.5000  0.0000  0.3652], WP [2c] Site [2mm.]
+    	 O @ [ 0.0000  0.0000  0.6833], WP [1a] Site [4mm]
 
 would create a random :math:`BaTiO_3` crystal. If the generation is successful, the value
 of ``my_crystal.valid`` will be set to ``True``;
 otherwise, it will be ``False``.
 
+Keep in mind that the you can pass an integer value to `random_state` to ensure the reproducibility.
+This feature would be useful for many different purposes. 
+
+If you want to generate many random structures with a fixed random number generator, we recommend the following scripts by setting up a random number generator via `np.random.default_rng`:
+
+.. code-block:: Python
+
+from pyxtal import pyxtal
+import numpy as np
+rng = np.random.default_rng(0)
+
+xtals = []
+for i in range(10):
+    xtal = pyxtal()
+    xtal.from_random(3, 99, ['Ba','Ti','O'], [1,1,3], random_state=rng)
+    xtals.append(xtal)
+
+Similar setup can be applied to other modules as well.
 
 Random 3D molecular crystals
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/doc/modules.rst b/doc/modules.rst
@@ -0,0 +1,7 @@
+pyxtal
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   pyxtal
diff --git a/doc/pyxtal.XRD.rst b/doc/pyxtal.XRD.rst
@@ -2,6 +2,6 @@ pyxtal.XRD module
 =================
 
 .. automodule:: pyxtal.XRD
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.block_crystal.rst b/doc/pyxtal.block_crystal.rst
@@ -2,6 +2,6 @@ pyxtal.block\_crystal module
 ============================
 
 .. automodule:: pyxtal.block_crystal
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.constants.rst b/doc/pyxtal.constants.rst
@@ -0,0 +1,7 @@
+pyxtal.constants module
+=======================
+
+.. automodule:: pyxtal.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.crystal.rst b/doc/pyxtal.crystal.rst
@@ -2,6 +2,6 @@ pyxtal.crystal module
 =====================
 
 .. automodule:: pyxtal.crystal
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.database.cifs.rst b/doc/pyxtal.database.cifs.rst
@@ -0,0 +1,7 @@
+pyxtal.database.cifs package
+============================
+
+.. automodule:: pyxtal.database.cifs
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.database.collection.rst b/doc/pyxtal.database.collection.rst
@@ -2,6 +2,6 @@ pyxtal.database.collection module
 =================================
 
 .. automodule:: pyxtal.database.collection
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.database.element.rst b/doc/pyxtal.database.element.rst
@@ -2,6 +2,6 @@ pyxtal.database.element module
 ==============================
 
 .. automodule:: pyxtal.database.element
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.database.rst b/doc/pyxtal.database.rst
@@ -2,14 +2,23 @@ pyxtal.database package
 =======================
 
 .. automodule:: pyxtal.database
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pyxtal.database.cifs
 
 Submodules
 ----------
 
 .. toctree::
+   :maxdepth: 4
 
    pyxtal.database.collection
    pyxtal.database.element
diff --git a/doc/pyxtal.db.rst b/doc/pyxtal.db.rst
@@ -0,0 +1,7 @@
+pyxtal.db module
+================
+
+.. automodule:: pyxtal.db
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.descriptor.rst b/doc/pyxtal.descriptor.rst
@@ -2,6 +2,6 @@ pyxtal.descriptor module
 ========================
 
 .. automodule:: pyxtal.descriptor
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.elasticity.rst b/doc/pyxtal.elasticity.rst
@@ -0,0 +1,7 @@
+pyxtal.elasticity module
+========================
+
+.. automodule:: pyxtal.elasticity
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.LJ.rst b/doc/pyxtal.interface.LJ.rst
@@ -0,0 +1,7 @@
+pyxtal.interface.LJ module
+==========================
+
+.. automodule:: pyxtal.interface.LJ
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.ani.rst b/doc/pyxtal.interface.ani.rst
@@ -0,0 +1,7 @@
+pyxtal.interface.ani module
+===========================
+
+.. automodule:: pyxtal.interface.ani
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.charmm.rst b/doc/pyxtal.interface.charmm.rst
@@ -0,0 +1,7 @@
+pyxtal.interface.charmm module
+==============================
+
+.. automodule:: pyxtal.interface.charmm
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.dftb.rst b/doc/pyxtal.interface.dftb.rst
@@ -0,0 +1,7 @@
+pyxtal.interface.dftb module
+============================
+
+.. automodule:: pyxtal.interface.dftb
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.gulp.rst b/doc/pyxtal.interface.gulp.rst
@@ -2,6 +2,6 @@ pyxtal.interface.gulp module
 ============================
 
 .. automodule:: pyxtal.interface.gulp
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.lammpslib.rst b/doc/pyxtal.interface.lammpslib.rst
@@ -2,6 +2,6 @@ pyxtal.interface.lammpslib module
 =================================
 
 .. automodule:: pyxtal.interface.lammpslib
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.rst b/doc/pyxtal.interface.rst
@@ -2,14 +2,21 @@ pyxtal.interface package
 ========================
 
 .. automodule:: pyxtal.interface
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Submodules
 ----------
 
 .. toctree::
+   :maxdepth: 4
 
-   pyxtal.interface.vasp
+   pyxtal.interface.LJ
+   pyxtal.interface.ani
+   pyxtal.interface.charmm
+   pyxtal.interface.dftb
    pyxtal.interface.gulp
+   pyxtal.interface.lammpslib
+   pyxtal.interface.vasp
+   pyxtal.interface.vasprun
diff --git a/doc/pyxtal.interface.vasp.rst b/doc/pyxtal.interface.vasp.rst
@@ -2,6 +2,6 @@ pyxtal.interface.vasp module
 ============================
 
 .. automodule:: pyxtal.interface.vasp
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.interface.vasprun.rst b/doc/pyxtal.interface.vasprun.rst
@@ -0,0 +1,7 @@
+pyxtal.interface.vasprun module
+===============================
+
+.. automodule:: pyxtal.interface.vasprun
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.io.rst b/doc/pyxtal.io.rst
@@ -2,6 +2,6 @@ pyxtal.io module
 ================
 
 .. automodule:: pyxtal.io
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.lattice.rst b/doc/pyxtal.lattice.rst
@@ -1,7 +1,7 @@
 pyxtal.lattice module
-======================
+=====================
 
 .. automodule:: pyxtal.lattice
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.molecular_crystal.rst b/doc/pyxtal.molecular_crystal.rst
@@ -2,6 +2,6 @@ pyxtal.molecular\_crystal module
 ================================
 
 .. automodule:: pyxtal.molecular_crystal
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.molecule.rst b/doc/pyxtal.molecule.rst
@@ -2,6 +2,6 @@ pyxtal.molecule module
 ======================
 
 .. automodule:: pyxtal.molecule
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.msg.rst b/doc/pyxtal.msg.rst
@@ -0,0 +1,7 @@
+pyxtal.msg module
+=================
+
+.. automodule:: pyxtal.msg
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.operations.rst b/doc/pyxtal.operations.rst
@@ -2,6 +2,6 @@ pyxtal.operations module
 ========================
 
 .. automodule:: pyxtal.operations
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.DFS.rst b/doc/pyxtal.optimize.DFS.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.DFS module
+==========================
+
+.. automodule:: pyxtal.optimize.DFS
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.QRS.rst b/doc/pyxtal.optimize.QRS.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.QRS module
+==========================
+
+.. automodule:: pyxtal.optimize.QRS
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.WFS.rst b/doc/pyxtal.optimize.WFS.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.WFS module
+==========================
+
+.. automodule:: pyxtal.optimize.WFS
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.base.rst b/doc/pyxtal.optimize.base.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.base module
+===========================
+
+.. automodule:: pyxtal.optimize.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.basin_hopping.rst b/doc/pyxtal.optimize.basin_hopping.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.basin\_hopping module
+=====================================
+
+.. automodule:: pyxtal.optimize.basin_hopping
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.benchmark.rst b/doc/pyxtal.optimize.benchmark.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.benchmark module
+================================
+
+.. automodule:: pyxtal.optimize.benchmark
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/pyxtal.optimize.common.rst b/doc/pyxtal.optimize.common.rst
@@ -0,0 +1,7 @@
+pyxtal.optimize.common module
+=============================
+
+.. automodule:: pyxtal.optimize.common
+   :members:
+   :undoc-members:
+   :show-inheritance: