Getting started¶

我们看到，科学技术中存在知识积累的过程，现今可利用的新技术和新资源越来越多，科研工作者需要掌握的东西也越来越多，科研工作需要减轻技术负担，需要全新的工作方法。

为了解决具体计算以及知识的探索和积累问题，经过几年的摸索和开发，结合这些年出现的一些先进的软件工具，我们设计并实现了了 Labkit 框架。

Labkit 作为一个解决问题的手段，给出了计算科研工作的一套领域知识，或者实验室知识的探索，积累，和使用的合理方案。可以让科研人员专注算法。

Labkit 中，算法即计算，Labkit 能够让科研人员只需简单方便的描述算法，便可以直接提交使用超算资源进行并行化计算。并且算法和计算结果可以方便保存下来复用，实现知识的层层推动。

Labkit是一个算法设计，计算，验证，分析的框架，可以实现基础方法的探索研究；Labkit 可以方便的自由组合已有模块，自由编写扩展模块；Labkit 也是一个执行计算的框架，能够并行的高效的执行具体计算任务。

Labkit 对人和程序都简洁友好，能够让科研人员简单方便的理解使用和开发。

Labkit 的使用流程¶

系统搜索法的例子

我们用一个最简单的例子，系统搜索法。来说明 Labkit 的使用和执行流程。

系统法相当于在构象空间中均匀采样，考虑所有变量的全部组合方式。如果采样足够密集，可以获得构象空间中的全部局域极小值。该方法的优点是可靠性最高，缺点是计算量大，不可避免的面临组合爆炸问题。随着变量的增加，采样数目呈指数方式增长。因此只适用于尺度较小的体系。但是由于其简单易于说明，我们这里就拿系统法来进行阐述。

系统法的一个典型流程是，根据自由度穷举生成构型，先采用低精度方法优化去重，再一步步采用高精度方法优化去重，逐步，具体来说，例如，我们对于一个体系如 CGGG（半胱氨酸-甘氨酸-甘氨酸-甘氨酸），我们生成初始构型后，对其调用高斯依次进行 PM3 优化，HF/3-21G* 计算单点能去重并能量截取，HF/3-21G* 优化后去重并能量截取， BHandHLYP/6-31G* 优化的计算后去重和能量截取。

labkit 命令最简单教程¶

Labkit 需要运行在 Linux 集群上，并且需要 LSF 或者 Torque 队列系统。

安装¶

在 Linux 命令行下，运行以下命令下载安装 labkit。

curl -L http://files.snquantum.com/releases/labkit-INSTALL-full |bash

运行 curl -L http://files.snquantum.com/releases/molpack-INSTALL-full |bash 下载安装 molpack 计算包，即可进行分子研究相关的计算。ms.map.gaussian 是调用高斯，输入 xyz文件和参数，计算得到一个新的 xyz 和 out 文件的这样一个函数。

新建任务¶

描写输入¶

目录结构如下，初始构型放在 start 目录下：

.
├── start          # 初始结构集合
├── ...       # 计算中间过程
└── recipe.yml    # 算法描述

Recipe 文件采用 yaml 语法，其组成单元是列表和字典。列表是形如数组的[1,2,3] 这样的结构, yaml 中列表每一项用 - 号表示。而字典是形如 { 'key1': value1, 'key2': value2 } 的键值对，yaml 中用：号表示。Labkit 解析 Recipe 中的 yaml 的基本规则是：

 rule:         # :分割的是字典, 没有参数的键值会被忽略, 可以用来起名字
   - list:     # -开头的是列表
       - 列表就是任务, 每一个列表会自动执行
       - 第二项会接续执行
     dict: 字典如果是一个模块名, 则调用它, 如果是个大写开头的名字忽略.

算法描述中 # 开头的是注释。此外 Labkit 还追加了 def 定义变量等高级功能，这点在下面说明中可以很自然的理解其规则，我们写出 Recipe 文件：

Start:    
  - def CGGG: Load: { folder: init}    # def关键字加大写字母定义和赋值变量。获取变量。

def SYS:           
  - [CGGG]         # - 开头的是列表项，列表将会顺序执行
  - ms.map.gaussian: { method: pm3 opt }   # 小写字母模块名称: { 参数名: 参数, ...} 的方式调用模块，map 中的模块会自动发送到集群上面批量执行
  - ms.map.gaussian: { method: HF/3-21G* }  # 继续下一步计算
  - ms.findhf: {}     # 去重，去除优化到统一结构的冗余构型
  - ms.energy_cut: { energy: 20}  # 截取一定能量范围内的构型，单位 kcal/mol
  - ms.map.gaussian: { method: HF/3-21G* opt } 
  - ms.findhf: {}    
  - ms.energy_cut: { energy: 10}  
  - ms.map.gaussian: { method: BHandHLYP/6-31G*, xxx}  
  - ms.findhf: {}    
  - ms.energy_cut: { energy: 5}      # 列表经过运算之后，返回最后一步运算的结果，即指向文件夹的指针，这里即是最后一步运算目录的绝对路径。最后，返回的结果将保存在变量 SYS 中。

Result:  # 在这里提取最终需要的结果。
  - SYS

这个算法 recipe 描述了：先加载在init的目录下的结构集合，然后对其调用高斯依次进行 PM3 优化，HF/3-21G* 单点能去重，HF/3-21G* 优化, BHandHLYP/6-31G* 优化的计算，并进行相应的去重和能量截取。

目前版本支持串行和并行的计算流程，使用 ls_sub 提交。而如上的函数等功能在下一个版本提供。目前版本可使用 sh 和 sh_map 模块调用 shell 命令，如下指示了一个分子结构的从结构生成到计算去重的算法流程：

# 1.1 生成原始结构
- sh: { cmd: template_generate G }
- sh: { cmd: input_file_creat G }

# 1.2 生成dftb 初始文件
- sh_map: {cmd: single_file.sh }       #计算高斯单点能
- sh: { cmd: out-dftb }

# 2.1 dftb优化，优化一次不够，至少三次
- sh_map: {cmd: single_dftb_opt.sh }

# 2.2 重新优化dftb错误文件
- sh: { cmd: "mkdir result_good; mv *.out result_good; mv result_good/*err* .; ls *.out > list; mout-xyz list; ls *.xyz > list; mxyz-dftbin list; rm *.out *.xyz; rename _err.txt .txt *_err.txt; rm *err*" }
- sh_map: {cmd: single_dftb_opt.sh }

- sh: { cmd: "mv *.out result_good; mv result_good/*err* .; ls *.out > list; mout-xyz list; ls *.xyz > list; mxyz-dftbin list; rm *.out *.xyz; rename _err.txt .txt *_err.txt; rm *err*" }
- sh_map: {cmd: single_dftb_opt.sh }

- sh: { cmd: "mv *.out result_good; mv result_good/*err* .; ls *.out > list; mout-xyz list; ls *.xyz > list; mxyz-dftbin list; rm *.out *.xyz; rename _err.txt .txt *_err.txt; rm *err*" }
- sh_map: {cmd: single_dftb_opt.sh }

- sh: { cmd: "rm *err*; mv result_good/*.out ." }


# 2.2 处理
- sh: { cmd: "ls *.out > list.txt; findhf" }
- sh: { cmd: out-orca_ddn }


#  3. orca 优化
- sh_map: {cmd: single_orca.sh }
- sh: { cmd: "rm *err*; cp *.out ../" }

提交计算¶

运行以下命令提交计算。以下命令参数使用 2 个节点每个节点 28 核进行计算。

ls_sub smallopa 2 28 ./pbs_example

得到结果¶

labkit 会自动提交计算，等待计算完成后，目录内将会得到计算结果。最后会得到计算结果的文件夹，以及计算过程中调用到的所有模块的参数。

解释¶

理解以下概念和过程，可以理解 labkit 的工作原理。

算法描述：recipe.yml 文件使用 yaml 语言，用列表和字典的方式描述算法。描绘清楚模块函数的调用流程。

自动并行： yaml 描述中的集合操作类函数，会在集群上面并行执行。