Merge pull request #27 from stanfordbshan/dev

HTMACat-kit 1.0.3 更新内容
materialssimulation · Apr 18, 2023 · 30f4d9d · 30f4d9d
2 parents 8ebab80 + 2a94e51
commit 30f4d9d
Show file tree

Hide file tree

Showing 173 changed files with 37,468 additions and 3,169 deletions.
diff --git a/.github/workflows/auto_gen_whl.yml b/.github/workflows/auto_gen_whl.yml
@@ -1,6 +1,16 @@
-name: Python package
+name: publish HtmaCat-kit to release
 
 on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'The branch to run the workflow on'
+        required: false
+        default: 'master'
+        type: choice
+        options:
+          - 'master'
+          - 'dev'
   push:
     branches:
       - master
@@ -16,12 +26,13 @@ jobs:
     runs-on: ubuntu-latest
     permissions: write-all
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.inputs.branch || github.ref }}
       - name: Publish Python Package
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.8
-          publish-package: true
 
       - name: Build wheel and source distribution
         run: |
@@ -44,6 +55,19 @@ jobs:
           file: src/dist/*.whl
           tag: v${{env.app_version}}
           release_name: v${{env.app_version}}
-          overwrite: true
+          overwrite: false
           file_glob: true
           body: ${{github.event.head_commit.message}}
+
+      - name: Replace the install link and Update Readme
+        run: |
+          link=$(curl --silent "https://api.github.com/repos/${{ github.repository }}/releases/latest" | \
+            jq -r '.assets[].browser_download_url' | head -n1)
+          sed -i 's~https://github.com/[^/]*/[^/]*/releases/download/[^/]*/HTMACat-[^"]*~'"$link"'~g' README.md
+
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v9
+        with:
+          add: 'README.md'
+          message: 'Updated wheel link in README'
+          push: true
diff --git a/.gitignore b/.gitignore
@@ -103,4 +103,5 @@ venv.bak/
 
 # custom
 example/backup*
-example/zjwang*
+example/zjwang*
+.idea/
diff --git a/README.md b/README.md
@@ -1,89 +1,111 @@
 # HTMACat
 
-# Introduction
-
-A high-throughput modeling, calculation, and analysis framework for catalytic reaction processes, it provides key tools for high-throughput design and screening of catalytic materials. The software mainly includes functional modules such as surface structure analysis and information extraction, catalytic surface and various adsorption model construction, automatic construction of primitive reaction processes, automatic extraction of computational data and automatic extraction and construction of descriptors.The software can perform the following computational workflows: adsorption energy calculation and analysis workflow, primitive reaction calculation and analysis workflow, high throughput calculation and automated analysis of adsorption energy and reaction potential of catalytic primitive reaction processes, etc.
-
-# Installation Guide
-
-
-## 1.  Environment
-Python 3.6-3.9; ASE 3.22.1; CatKit 0.5.4; 1.20.0 <= Numpy <= 1.23.5 
+# 1. Introduction
+
+A high-throughput modeling, calculation, and analysis framework for catalytic reaction processes, it provides key tools
+for high-throughput design and screening of catalytic materials. The software mainly includes functional modules such as
+surface structure analysis and information extraction, catalytic surface and various adsorption model construction,
+automatic construction of primitive reaction processes, automatic extraction of computational data and automatic
+extraction and construction of descriptors.The software can perform the following computational workflows: adsorption
+energy calculation and analysis workflow, primitive reaction calculation and analysis workflow, high throughput
+calculation and automated analysis of adsorption energy and reaction potential of catalytic primitive reaction
+processes, etc.
+
+# 2. Installation Guide
+
+## 2.1 Environment
+
+```requirements.txt
+Python >= 3.6, <=3.9
+ASE >= 3.22.1
+CatKit == 0.5.4
+numpy >= 1.20.0, <= 1.23.5
+rdkit
+typer
+```
 
-If you haven‘t installed **Python3.x** yet, [download](https://www.python.org) the specified version of package and install it.
+If you haven't installed **Python3.x** yet, [download](https://www.python.org) the specified version of package and
+install it.
 
 ## 2.  Installation
-### 1) Automatic installation
-
-download the install script:[install_wheel.bat](https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/install_wheel.bat) or [install_wheel.sh](https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/install_wheel.sh)
-```shell
-./install_wheel.bat # Windows 
-./install_wheel.sh # linux
-```
-### 2) Manual installation
 
 ```shell
-# windows
-pip install ase numpy==1.23.5 scikit-learn
-pip install https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/requires_wheel/FireWorks-2.0.3-py3-none-any.whl
-pip install https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/requires_wheel/CatKit-0.5.4-py3-none-any.requires_wheel
-for /f "tokens=1,* delims=:" %%A in ('curl -ks https://api.github.com/repos/stanfordbshan/HTMACat-kit/releases/latest ^| find "browser_download_url"') do (
-    pip install -U %%B
-)
-
-#linux
 pip install ase numpy==1.23.5 scikit-learn
 pip install https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/requires_wheel/FireWorks-2.0.3-py3-none-any.whl
 pip install https://raw.githubusercontent.com/stanfordbshan/HTMACat-kit/master/requires_wheel/CatKit-0.5.4-py3-none-any.whl
-pip install --upgrade $(curl -s https://api.github.com/repos/stanfordbshan/HTMACat-kit/releases/latest | grep "browser_download_url.*\.whl" | cut -d : -f 2,3 | tr -d \")
-```
+pip install -U https://github.com/stanfordbshan/HTMACat-kit/releases/download/v1.0.2/HTMACat-1.0.2-py3-none-any.whl
 
-# Getting started
-
-1. **High-throughput single adsorption modeling**
-
-    (1) Prepare the input files: *StrucInfo *and *Model*
-
-    "StrucInfo" file Contains the carrier of lattice type and the crystal parameters, the format is as follows:
-
-    ```shell
-    Pt fcc 3.97 111 # Element Lattice_type Lattice_parameter Crystal_plane
-    ```
-    The four parameters above are the bulk phase element, lattice type, lattice parameter and crystal plane. In addition, by adding more rows, more systems can be constructed continuously.  
-    "Model" file contains the surface doping and adsorption modeling parameters, the format is as follows:
-
-    ```shell
-    Cu # Doping elements
-    b1 # Doping type
-    SML C(=O)O # Adsorption species (SMILES of formic acid)
-    1 2 # Adsorption type
-    ```
-    Where the first line of the file is the doping element and the second line is the doping type, 0 corresponds to no doping, 1, 2 and 3 correspond to surface layers doped with 1, 2 and 3 atoms, respectively, and 1L and b1 represent surface layer substitution and bulk equivalent proportional substitution. The third and fourth lines respectively represent the adsorbate species and the adsorption types. <b>Please note that the adsorbates should be declared by their SMILES expressions if the third line starts with 'SML'!</b> If no 'SML' at the beginning of this line, the species are represented in their chemical formula. <b>To avoid ambiguity, it is recommended that SMILES be used when declaring complex species.</b> Users can modify the corresponding parameters to achieve customized modeling according to their research needs.
-
-    (2) run script
-
-    Running command "ads" can automate the enumeration and construction of all possible configurations, and ultimately output structure files in the VASP format, like Pt_Cu_111_1_NH_0.vasp  
-    Furthermore, for the adsorption models on doped surfaces, we use the get_binding_adatom function to determine the types of surface atoms that the adsorbate binds to in the preliminary configurations. We only select configurations where the adsorbate is bound to a surface atom that contains a dopant atom, in order to reduce the number of final output structures.
-2. **High-throughput co-adsorption modeling**
-
-    (1) Prepare the input files: *StrucInfo *and *Model*
-
-    The two input files for the co-adsorption model construction module are still StrucInfo and Model, and StrucInfo has the same file format as the single adsorption model construction module. However, the Model files for the two differ. The format of the Model file for the co-adsorption modeling module is as follows:
-
-    ```shell
-    Cu # Doping elements
-    3 # Doping type
-    SML N [O];[NH2] [OH];[N] [N];[N] [O];[N] [N]=O # Co-adsorption species
-    1 1;1 1;1 1;1 1;1 1 # Adsorption type
-    ```
-    The first line represents the dopant element, the second line represents the dopant type, the third and fourth lines respectively represent the co-adsorbate species (also in SMILES format) and the co-adsorption type. Different co-adsorption combinations are separated by ";".
-
-    (2) run script
+```
 
-    Running command "coads" can automate the enumeration and construction of all possible configurations, and ultimately output structure files in the VASP format, like Pt_Cu_111_2_N_H_0.vasp.
-3. **Automated construction of reaction transition state calculation process**
-4. **Automated extraction of calculation results**
-5. **Automated extraction of descriptors**
+# 3. Getting started
+
+## 3.1 High-throughput adsorption modeling
+
+### 1) Prepare the input files
+
+`config.yaml` should be prepared in your working folder.
+`Config.yaml` file Contains two parts: 
+- `StuctInfo` parts 
+- `Model` parts
+
+The format of the whole `config.yaml` is as follows:
+   ```yaml
+   StrucInfo:
+    element: Au
+    lattype: fcc
+    latcont: 4.16
+    facet: ['111','100']
+    dope:
+      Cu: [3]
+
+   Model:
+    SML: False
+    ads:
+      - ['NH3',1]
+      - ['NO', 2]
+    coads: 
+      - ['NH3','O',1,1]
+   ```
+
+`StuctInfo` parts contains the information about substrate, including:
+
+- `element`: bulk phase element
+- `lattype`: lattice type
+- `latcont`: lattice parameter
+- `facet`: crystal plane, hould be a *list*, start with `[`, separate with `,` and end with `]`, facet index
+  should
+  be a str start with `'` end with `'`, like `'100'`,`'111'`
+- `dope`: dope of the substrate, the formate is `dope element : [dope type1, dope type2]`
+  before `:` is the doped element, after the `:` is the dope type, the dope type can be chosen as follows：
+  `0` corresponds to no doping, `1`, `2` and `3`correspond to surface layers doped with `1`, `2` and `3` atoms,
+  respectively.
+  `1L` and `b1` represent surface layer substitution and bulk equivalent proportional substitution.
+
+`Model` parts contains the adsorption modeling parameters, including:
+
+- `SML`: whether using *Smiles* toe represent the adsorption species
+- `ads`: using `- [ adsorbate formular , adsorption sites type]` to represent one adsorption status, where
+  adsorption formular should be a str start with `'` end with `'`. Different adsorption status should start with
+  new line, adsorption sites type can be chosen from `1` or `2`.
+- `coads`: using `- [ads1, ads2, ads1 sites, ads2 sites]`, *ads1* and *ads2* is two adsorbate species formular,
+  *ads1 sites* and *ads2 sites* is adsorption sites type, can be chosen from `1` and `2`.
+
+**To avoid ambiguity, it is recommended that SMILES be used when declaring complex species.** Users can modify the
+corresponding parameters to achieve customized modeling according to their research needs.
+
+### 2) run script
+
+Running command `htmat ads` can automate the enumeration and construction of all possible configurations, and ultimately
+output structure files in the VASP format, like Au_Cu_111_1_NH_0.vasp, 
+Furthermore, for the adsorption models on doped surfaces, we use the `get_binding_adatom` function to determine the
+types of surface atoms that the adsorbate binds to in the preliminary configurations. We only select configurations
+where the adsorbate is bound to a surface atom that contains a dopant atom, in order to reduce the number of final
+output structures.
+
+
+## 3.2 Automated construction of reaction transition state calculation process
+## 3.3 Automated extraction of calculation results
+## 3.4 Automated extraction of descriptors
 
 ‍
 
@@ -97,4 +119,4 @@ pip install --upgrade $(curl -s https://api.github.com/repos/stanfordbshan/HTMAC
 
 # Links
 
-* Materials Design and Nano-Manufacturing Center@HUST:http://www.materialssimulation.com/
+* Materials Design and Nano-Manufacturing Center@HUST:http://www.materialssimulation.com/
diff --git a/doc/面向催化反应的高通量建模与分析软件.pdf b/doc/面向催化反应的高通量建模与分析软件.pdf
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/Examples.html b/docs/Examples.html
@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Examples &mdash; HTMACat-kit 1.0.2 documentation</title>
+      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+        <script src="_static/jquery.js"></script>
+        <script src="_static/underscore.js"></script>
+        <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
+        <script src="_static/doctools.js"></script>
+    <script src="_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="The description of Example" href="Examples_docs/description.html" />
+    <link rel="prev" title="Usage" href="Usage.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+
+
+
+          <a href="index.html" class="icon icon-home">
+            HTMACat-kit
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="Get_start.html"><strong>Get_start</strong></a></li>
+<li class="toctree-l1"><a class="reference internal" href="Usage.html"><strong>Usage</strong></a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#"><strong>Examples</strong></a><ul>
+<li class="toctree-l2"><a class="reference internal" href="Examples_docs/description.html">The description of Example</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="HTMACat.html">HTMACat package</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="index.html">HTMACat-kit</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
+      <li class="breadcrumb-item active"><strong>Examples</strong></li>
+      <li class="wy-breadcrumbs-aside">
+            <a href="_sources/Examples.rst.txt" rel="nofollow"> View page source</a>
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <section id="examples">
+<h1><strong>Examples</strong><a class="headerlink" href="#examples" title="Permalink to this heading"></a></h1>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="Examples_docs/description.html">The description of Example</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="Examples_docs/description.html#introduction">Introduction</a></li>
+<li class="toctree-l2"><a class="reference internal" href="Examples_docs/description.html#inputs">Inputs</a></li>
+<li class="toctree-l2"><a class="reference internal" href="Examples_docs/description.html#results">Results</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</section>
+
+
+           </div>
+          </div>
+          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+        <a href="Usage.html" class="btn btn-neutral float-left" title="Usage" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
+        <a href="Examples_docs/description.html" class="btn btn-neutral float-right" title="The description of Example" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+    </div>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2023, Jiaqiang Yang; Feifeng Wu; Bin Shan.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>
diff --git a/docs/Examples.rst b/docs/Examples.rst
@@ -0,0 +1,7 @@
+**Examples**
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   Examples_docs/description.rst