update docs

docs/build/html/_sources/expeditions/ads.rst.txt

@@ -0,0 +1,106 @@
+Explore Adsorbate Configurations
+--------------------------------
+In this section, we demonstrate how to define an expedition to find low-energy adsorbate 
+configurations in `exp.yaml`. Here, we define an expedition called **exp** and all 
+results would be save in the directory **exp** under where we run the `explore` 
+command, and a log file `ads.out` in **exp** can be found as well.
+
+This expedition is very similiar to the MD-based one but differ in the system 
+definition.
+
+systems
+_______
+We define a system that contains a p(3x3) 4-layer Pt(111) surface. The generator 
+would enumerate possible O adsorption configurations using a graph-theory approach. 
+Here, structures with O on hollow site (`site: 3` indicates site with 3 coordination 
+number) would be created. (see article [1])
+
+[1] Deshpande, S.; Maxson, T.; Greeley, J. 
+    Graph Theory Approach to Determine Configurations of Multidentate and High Coverage Adsorbates for Heterogeneous Catalysis. 
+    npj Comput. Mater. 2020, 6, 79.
+
+.. code-block:: yaml
+
+    surface:
+      prefix: Pt111
+      generator:
+        method: adsorbate
+        substrate: ./surfaces.xyz
+        composition:
+          - species: O
+            action: add
+            distance_to_site: 1.5
+            site: 3 # site preference, coordination number is 3
+        graph:
+          # - graph
+          pbc_grid: [2, 2, 0]
+          graph_radius: 2
+          # - neigh
+          covalent_ratio: 1.1
+          skin: 0.25
+          adsorbate_elements: ["O"]
+          coordination_numbers: [3]
+          site_radius: 3
+          check_site_unique: true
+      composition: {"O": 1, "Pt": 36}
+      constraint: "1:18"
+      kpts: [4, 4, 1]
+
+create
+______
+Each generated structures would be minimised. The **driver** can be set according 
+to :ref:`driver examples`. Important parameters are **traj_period** and **steps**,
+which determine how many structure would be collected for later analysis. Their usage
+is the same as the MD-based expedition.
+
+collect
+_______
+This is the same as the MD-based one.
+
+select
+______
+This is similiar to the MD-based one. A convergence selection is usually applied to 
+split collected structures into two groups for later selection. The converged ones 
+are usually stable adsorption configurations that can be used to generate convex hull. 
+Meanwhile, the structures from minimisation trajectories can be used for training since 
+they cover the configuration space that productions may come across.
+
+
+.. code-block:: yaml
+
+    explorations:
+      exp:
+        systems: ["surface"]
+        create:
+          driver:
+            backend: external
+            task: min
+            init:
+              dump_period: 8
+            run:
+              steps: 12
+        collect:
+          traj_period: 2
+        select: # list of selection procedures
+          - method: convergence
+            fmax: 0.05 # eV/AA
+          - method: deviation # selection based on model deviation
+            criteria:
+              max_devi_e: [0.01, 0.25]
+              max_devi_f: [0.05, 0.25]
+          - method: descriptor
+            random_seed: 1112
+            descriptor:
+              name: soap
+              species: ["C", "H", "O", "Pt"]
+              rcut : 6.0
+              nmax : 12
+              lmax : 8
+              sigma : 0.3
+              average : inner
+              periodic : true
+            criteria:
+              method: cur
+              zeta: -1
+              strategy: descent
+            number: [4, 0.2]

docs/build/html/_sources/expeditions/evo.rst.txt

@@ -0,0 +1,104 @@
+Explore with Global Optimisation
+--------------------------------
+In this section, we demonstrate how to define an expedition using global optimisation 
+in `exp.yaml`. Here, we define an expedition called **exp** and all results would 
+be save in the directory **exp** under where we run the `explore` command, and 
+a log file `evo.out` in **exp** can be found as well.
+
+The global optimisation method used here is the genetic-algorithm search.
+
+systems
+_______
+Since we use global optimisation to explore structures, the initial structures are 
+usually generated randomly. Thus, the systems must be defined with a generator.
+For example, `Cu4` is a system that contains bulks with 4 Cu atoms and random lattice 
+constants. The definition using `structure` keyword is normally not allowed since it 
+contains invariant initial structures.
+
+.. code-block:: yaml
+
+    Cu4:
+      prefix: Cu4
+      generator:
+        type: bulk
+        composition: {"Cu": 4}
+        covalent_ratio: 0.5
+        volume: 40
+        cell: []
+        region:
+          phi: [35, 145]
+          chi: [35, 145]
+          psi: [35, 145]
+          a: [3, 50]
+          b: [3, 50]
+          c: [3, 50]
+      composition: {"Cu": 4}
+      kpts: 30
+
+create
+______
+As most global optimisation methods are complex, we need to set **task** to the 
+corresponding configuration file. In specific, it uses genetic-algorithm search. 
+Moreover, these computations take much time and we set **scheduler** to dispatch 
+these tasks to the queue.
+
+collect
+_______
+The computation results usually consist a large number of minimisation trajectories. 
+We would like to select low-energy minima and their trajectories that propbably cover 
+most area of the potential energy surface. (see article [1]) 
+
+**boltz** would select converged minima (fmax < 0.05 eV/AA) based on their Boltzmann 
+propbabilities. Only these minima's trajectories would be considered. Here, 256 
+minima are selected for each explored system.
+
+**traj_period** (that is 10) controls the selection interval of the trajectory 
+(e.g. frame 0,10,20 for a 20-step trajectory). 
+
+[1] Bernstein, N.; Csányi, G.; Deringer, V. L. 
+    De Novo Exploration and Self-Guided Learning of Potential-Energy Surfaces. 
+    npj Comput. Mater. 2019, 5, 99.
+
+select
+______
+The selection contains a convergence selector, which would split all structures into 
+two groups: converged ones and others. The consecutive selections would be performed 
+on these two groups, respectively. For example, if we collected 1000 structures, 
+there are 400 converged and 600 rest. The following descriptor selection would select 
+256 from 400 and 256 from 600. The number of candidates to label would be 512 (256+256) 
+for each system then.
+
+.. code-block:: yaml
+
+    explorations:
+      exp:
+        systems: ["Cu4", "Cu8", "Cu12", "Cu24"]
+        create:
+          task: ./ga.yaml
+          scheduler: ./scheduler.yaml
+        collect:
+          traj_period: 10 # every 10*dyn_dump_period steps plus last step
+          boltz:
+            random_seed: 1112
+            fmax: 0.05 # eV/AA
+            boltzmann: 3 # eV
+            number: [256, 0.2] # 128 from 1000 (20*50)
+        select: # list of selection procedures
+          - method: convergence
+            fmax: 0.05
+          - method: descriptor
+            random_seed: 1112
+            descriptor:
+              name: soap
+              species: ["Cu"]
+              rcut : 6.0
+              nmax : 12
+              lmax : 8
+              sigma : 0.3
+              average : inner
+              periodic : true
+            criteria:
+              method: cur
+              zeta: -1
+              strategy: descent
+            number: [256, 1.0]

docs/build/html/_sources/expeditions/index.rst.txt

@@ -1,10 +1,36 @@
 Expeditions
 ===========
-
 This section introduces expeditions implemented in GDPy. In general, each expedition
 includes four stages, namely create, collect, select, and label. As usual, we offer 
 a unified input file to access different explorations by setting the **method** 
-and its corresponding **create** procedure.
+and its corresponding **create** procedure. Expeditions can be combined with any 
+potential formulation that can be recognised in `pot.yaml` (see :ref:`potential examples`). 
+
+See Expedition_Examples_ in the GDPy repository for prepared input files.
+
+.. _Expedition_Examples: https://github.com/hsulab/GDPy/tree/main/examples/expedition
+
+The related command is 
+
+.. code-block:: shell
+
+    # gdp -h for more info
+    $ gdp -h
+
+    # run explorations defined in exp.yaml with potential as pot.yaml and
+    #   with selected candidates labelled by ref.yaml
+    $ gdp -p ./pot.yaml -r ./ref.yaml explore ./exp.yaml
+
+.. important:: 
+    If a scheduler is defined in `pot.yaml`, the `create` step would be submitted to
+    the queue and the expedition would stop. When running the `explore` command 
+    again, the expedition would check whether the current step (e.g. `create`) is 
+    finished and move on to the next if the current is finished.
+
+.. important:: 
+    If `-r ref.yaml` is not provided, the expedition would stop at the `select` 
+    step and prompt `Reference worker is not set properly.`. Thus, the selected 
+    candidates would not be labelled by reference (e.g. DFT).
 
 The code structure is
 
@@ -17,12 +43,12 @@ The code structure is
             select()   # select structures
             label()    # label candidates
 
-The input file structure is 
+The input file (`exp.yaml`) structure is 
 
 .. code-block:: yaml
 
-    database: ./set
-    method: MD # options are md, evo, ads, rxn
+    database: ./set # where labelled structures are stored
+    method: md # options are md, evo, ads, rxn
     systems:
         ... # a dict of system definitions
     explorations:
@@ -38,30 +64,58 @@ The input file structure is
                 ...
         ...
 
-The related command is 
+Define a System
+---------------
+In the **systems** section, we need to specify what particular systems would be 
+explored. There are several parameters need to define:
 
-.. code-block:: shell
+- prefix:      Use to distinguish systems when creating directories if needed.
+- composition: System chemical composition.
+- kpts:        System-depandent for DFT calculation.
+- constraint:  Fix some atoms during the exploration.
 
-    # gdp -h for more info
-    $ gdp -h
+More importantly, there are two ways to create initial structures.
 
-    # run explorations defined in exp.yaml with potential as pot.yaml and
-    #   with selected candidates labelled by ref.yaml
-    $ gdp -p ./pot.yaml -r ./ref.yaml explore ./exp.yaml
+The first one using structures from a file. The example below reads structures with 8
+Cu atoms as initial structures to explore.
 
-Define a System
----------------
+.. code-block:: yaml
+
+    sysName:
+        prefix: sysPrefix
+        structure: ./frames.xyz
+        composition: {"Cu": 8}
+        kpts: 30 # kspacing
+        constraint: "1:4"
 
+The second one defining a generator to create some. The example below creates
+2 (`size`) structures that have 9 water molecules randomly placed above a Pt substrate.
 
+.. code-block:: yaml
 
+    sysName:
+        prefix: sysPrefix
+        generator:
+            method: random
+            type: surface
+            composition: {"H2O": 9}
+            covalent_ratio: 0.8
+            substrate: ./substrates.xyz
+            surfdis: [1.5, 6.5]
+        size: 2
+        composition: {"H": 9, "O": 18, "Pt": 16}
+        kpts: [2,2,1] # kmesh
+        constraint: "1:4"
 
 List of Expeditions
 -------------------
+The **method** should be set to access different expedition strategies (e.g. 
+md, evo, ads and rxn).
 
 .. toctree::
    :maxdepth: 2
 
    md.rst
-   population.rst
-   adsorbate.rst
-   reaction.rst
+   evo.rst
+   ads.rst
+   rxn.rst