Pymatflow用户手册

Pymatflow是一个第一性原理模拟的工作流自动化管理软件,有两种工作模式。其一是终端命令行模式,目的是减少用户进行DFT模拟所需要的输入文件准备和结果后处理时间,让用户在服务器集群上通过一行命令就可以提交任务和进行结果的提取。其二是使用Pymatflow提供的API进行高通量计算,这部分的使用需要用户具有一定的编程能力。目前支持的计算程序有AbinitQuantum ESPRESSOCP2KSIESTAVASP

由于个人精力有限,本手册内容并不完善,目前主要对命令行工具matflowpostflowstructflow的使用方式进行了初步介绍,以方便用户试用。

安装Pymatflow

~$ pip install pymatflow

目前推荐的方式是在服务器中使用pip安装已发布的pymatflow。

如果自己不是系统管理员,没有root权限:

~$ pip install pymatflow --user

并保证~/.local/bin在环境变量PATH之中。

pymatflow支持本地与远程服务器交互操作,但是需要做一定配置,后续做补充。

使用须知

首先用户使用本软件需要对结果自行负责,Pymatflow不保证结果的正确性。需要用户具有一定的背景知识,能够鉴别计算任务的合理性。

  1. 结构文件

可以通过--cif--xsd--xsf或者--xyz三个参数之一传递结构文件路径给matflow或者postflow。用户需要注意的是这四个参数一次只能设置一个。如果是进行过渡态计算,则通过--images参数输入结构。

  1. 赝势文件

matflow提供了--pot选项供用户选择赝势文件,有三种设置方式。第一种是指定一个文件夹,该文件夹中需要包含所有的赝势文件,并且建议用户在该文件夹中仅存放赝势文件,因为目前matflow会将所有该文件夹下的内容都拷贝到当前路径。其二是默认形式,即不需要指定--pot选项,但用户需要保证所有赝势文件都在当前路径下。第三种方式是--pot auto,此时matflow会自动会你准备好赝势文件。

对于第三种方式,我们需要对服务器进行一下配置,将赝势库都准备在用户家目录下面。各个程序的赝势存放位置分别是:~/.pot-vasp~/.pot-qe~/.pot-siesta~/.pot-abinit。需要注意的是目前对CP2K的支持不需要指定赝势,默认只会使用DZVP-MOLOPT-SR-GTH基组和GTH-PBE类型的赝势。

  1. 高对称点路径

在对晶体材料的体相进行研究时,常会用到倒空间这个强有力的工具。在使用Pymatflow的过程中,所有涉及倒空间高对称点路径的任务都以一个规范的形式进行管理。你可以通过--kpath-manual或者--kpath-filematflow传入高对称点路径。

使用--kpath-manual时,需要在其后按照一定格式手动输入路径:

--kpath-manual '0.000000 0.000000 0.000000 GAMMA 15' '0.500000 0.000000 0.000000 X |' '0.000000 0.500000 0.000000 Y 15' '0.000000 0.000000 0.000000 GAMMA 15' '0.000000 0.000000 0.500000 Z |' '0.500000 0.500000 0.500000 R 15' '0.000000 0.000000 0.000000 GAMMA 15' '0.000000 0.500000 0.500000 T |' '0.500000 0.000000 0.500000 U 15' '0.000000 0.000000 0.000000 GAMMA 15' '0.500000 0.500000 0.000000 V 15'

上面的参数给出的高对称点路径是:\(\Gamma-X|Y-\Gamma-Z|R-\Gamma-T|U-\Gamma-V\)

Notes:

  • 如果一个K点的最后一个符号 为一个整数,那么它将通过该整数个点连接到下一个K点。

  • 如果一个K点的最后一个符号为|,那么它与后面的K点处于断开状态。

  • kx, ky, kz是倒空间K点坐标的分数坐标。

此外,用户可以将高对称点路径信息准备在文件中,然后将文件路径通过--kpath-file传递给Pymatflow。文件格式如下:

11
0.000000 0.000000 0.000000 #GAMMA 15
0.500000 0.000000 0.000000 #X |
0.000000 0.500000 0.000000 #Y 15
0.000000 0.000000 0.000000 #GAMMA 15
0.000000 0.000000 0.500000 #Z |
0.500000 0.500000 0.500000 #R 15
0.000000 0.000000 0.000000 #GAMMA 15
0.000000 0.500000 0.500000 #T |
0.500000 0.000000 0.500000 #U 15
0.000000 0.000000 0.000000 #GAMMA 15
0.500000 0.500000 0.000000 #V 15

文件的第一行制定了文件后面给出的行数。

每一行对应于kpath数据结构中的一个元素:

  • 行中前三个元素对应于K点的x、y和z坐标

  • 行中第四个元素对应于K点的符号(需要是大写)

  • 行中第五个元素对应于K点与其后K点的连接关系,意义和上述kpath数据结构中一致

用户往往需要通过--kpath-file参数向Pymatflow的命令行工具(如matflowpostflowstructflow)指定包含有高对称K点的文件路径。要注意这里同样坐标必须是分数坐标。注意--kpath-manual的优先级高于--kpath-file

  1. 环境变量

用户需要为Pymatflow指定所用程序的环境变量,比如将下列内容加入到你的~/.bashrc中:

export PMF_VASP_STD=/path/to/your/vasp_std
export PMF_VASP_NCL=/path/to/your/vasp_ncl
export PMF_VASP_GAM=/path/to/your/vasp_gam
export PMF_CP2K=/path/to/your/cp2k.[popt|psmp...]
export CP2K_DATA_DIR=/path/to/your/cp2k/data

然后通过下面的命令使其立即生效:

~$ source ~/.bashrc

matflow简介

matflow提供了计算任务的自动化生成和提交功能。使用方式归结为一句话就是”主命令+子命令+可选参数”。主命令当然就是matflow了,至于子命令,目前一共有5个,即:

  • abinit

  • qe

  • cp2k

  • siesta

  • vasp

使用时也就代表了命令使用到的计算器。用户可以通过matflow -h查看使用帮助。如果想要具体了解某一个计算器提供的可选参数和使用帮助需要加上子命令选项,比如命令matflow vasp -h可以查看vasp对应的帮助文档。下面我们通过一个例子来看如何在服务器上使用matflow来辅助第一性原理计算。

另外为了减少输入,用户可以使用mflow代替matflow

matflow命令工具使用示例

这里以一个简单的优化LiH立方晶胞参数的例子,展示如何使用Pymatflow来加速计算的准备工作。

首先,准备好LiH的晶体结构文件lih.cif。然后在对应路径运行一下命令:

~$ matflow vasp -r 2  --cif lih.cif --encut 300 --ibrion 2 --isif 2 --kpoints-mp 3 3 3 0 0 0 -d lih-cubic

即可在指定的lih-cubic文件夹中自动生成输入文件,并提交任务到服务器中,要注意的是这里默认提交的是PBS类型的任务。目前支持的服务器只有吕梁天河二号和PBS集群,或者以单机模式运行。具体使用参见--server参数的帮助文档。至于结果的提取由postflow工具提供。目前matflow对vasp支持的计算类型包括: 静态计算(scf、nscf、bands)、结构优化、立方晶胞参数优化、六方晶胞参数优化、四方晶胞参数优化、结合VTST进行过渡态计算、VASP自带声子谱计算、结合Phonopy进行声子谱计算。

postflow简介

postflow对Pymatflow的后处理进行了部分封装,目前还未完全成熟。可能有部分选项无法使用。这里展示一下通常的使用流程。比如对上述的LiH晶胞参数优化任务的后处理,只需要运行命令:

~$ postflow vasp -r 2 -d lih-cubic

就可以进行结果的提取,生成的文件统一在lih-cubic/post-processing目录下。

目前Pymatflow的后处理功能主要还是由API提供,但是往postflow移植的工作正在进行中,后续会完善。

structflow简介

structflow主要提供了常见的结构文件转换,以及进行固定原子结构优化等功能,其中结构文件转换得益于ASE项目的ase.io的帮助。这部分内容会在后续的文章中进行介绍

使用Pymatflow命令行的通式

matflow之VASP计算器

VASP静态计算

~$ matflow vasp -r 0 --cif YOUR_STRUCTURE.cif -d DIRECTORY --encut VALUE --ediff VALUE --kpath-file KPATH_FILE_PATH --kpoints-mp VALUE

参数-r 0表示静态计算,其行为是scf、nscf、bands一起进行计算。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。后处理命令如下:

~$ postflow vasp -r 0 -d DIRECOTRY --kpath-file KPATH_FILE_PATH --kpoints-mp VALUE

VASP结构优化

~$ matflow vasp -r 1 --cif YOUR_STRUCTURE.cif -d DIRECTORY --encut VALUE --ediff VALUE --ediffg VALUE    --ibirion VALUE --isif VALUE --kpoints-mp VALUE

参数-r 1表示进行结构优化。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。后处理命令如下:

VASP晶胞参数优化

~$ matflow vasp -r [2|3|4] --cif YOUR_STRUCTURE.cif -d DIRECTORY --encut VALUE --ediff VALUE --kpoints-mp VALUE

参数-r 2是进行cubic晶胞的cell参数的优化,-r 3进行hexagonal晶胞的cell参数的优化,-r 4进行tetragonal晶胞的cell参数的优化。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。后处理命令如下:

~$ postflow vasp -r [2|3|4] -d DIRECOTRY

VASP过渡态计算(VTST)

~$ matflow vasp -r 5 --images INITIAL.cif FINAL.cif -d DIRECTORY --encut VALUE --ediff VALUE --kpoints-mp VALUE

参数-r 5代表进行过渡态计算。其中--images用于指定初始和终态结构。

VASP声子谱计算(内置IBRION=[5, 6, 7, 8])

~$ matflow vasp -r 6 --cif YOUR_STRUCTURE.cif -d DIRECTORY --encut VALUE --ediff VALUE --kpoints-mp VALUE --ibirion [5|6|7|8] --supercell-n VALUE

参数-r  6是利用vasp内置的算法进行声子谱计算,需要设置--ibrion5|6|7|8之一。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。后处理命令如下:

~$ postflow vasp -r 6 --cif YOUR_STRUCTURE.cif -d DIRECTORY --kpath-file KPATH_FILE_PATH

VASP声子谱计算(Phonopy)

~$ matflow vasp -r 7 --cif YOUR_STRUCTURE.cif -d DIRECTORY --encut VALUE --ediff VALUE --kpoints-mp VALUE --supercell-n VALUE

matflow之QE计算器

QE几何结构优化(relax)

~$ matflow qe -r 1 --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE

QE几何结构优化(vc-relax)

~$ matflow qe -r 2 --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE

QE晶胞参数优化

~$ matflow qe -r [3|4|5] --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE

参数-r 3是进行cubic晶胞的cell参数的优化,-r 4进行hexagonal晶胞的cell参数的优化,-r 5进行tetragonal晶胞的cell参数的优化。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。后处理命令如下:

QE声子谱计算(DFPT)

~$ matflow qe -r 0 --static scf --cif YOUR_STRUCTURE -d DIRECTORY --ecutwfc VALUE --kpionts-mp VALUE
~$ # after the above task terminates
~$ matflow qe -r 7 --cif -d DIRECTORY --nq VALUE --tr2-ph VALUE

QE声子谱计算(Phonopy)

~$ matflow qe -r 8 --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE --supercell-n VALUE

matflow之CP2K计算器

CP2K结构优化(GEO_OPT)

~$ matflow cp2k -r 1 --cif YOUR_STRUCTURE.cif -d DIRECTORY --cutoff VALUE --kpoints-scheme VALUE

CP2K结构优化(CELL_OPT)

~$ matflow cp2k -r 2 --cif YOUR_STRUCUTRE.cif -d DIRECTORY --cutoff VALUE --kpoints-scheme VALUE

CP2K声子谱计算(phonopy)

~$ matflow cp2k -r 7 --cif YOUR_STRUCTURE.cif -d DIRECTORY --cutoff VALUE --kpoints-scheme VALUE --supercell-n VALUE

CP2K振动分析(VIBRATIONAL_ANALYSIS)

~$ matflow cp2k -r 8 --cif YOUR_STRUCTURE.cif -d DIRECTORY --cutoff VALUE --kpoints-scheme VALUE

CP2K晶胞参数优化

~$ matflow cp2k -r [3|4|5] --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE

参数-r 3是进行cubic晶胞的cell参数的优化,-r 4进行hexagonal晶胞的cell参数的优化,-r 5进行tetragonal晶胞的cell参数的优化。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。

matflow之SIESTA计算器

SIESTA 结构优化

~$ matflow siesta -r 1 --cif YOUR_STRUCTURE.cif -d DIRECTORY --meshcutoff VALUE --kpoints-mp VALUE

SIESTA 晶胞参数优化

~$ matflow siesta -r [2|3|4] --cif YOUR_STRUCTURE.cif -d DIRECTORY --ecutwfc VALUE --kpoints-mp VALUE

参数-r 2是进行cubic晶胞的cell参数的优化,-r 3进行hexagonal晶胞的cell参数的优化,-r 4进行tetragonal晶胞的cell参数的优化。其中需要注意-d参数不能指定为当前路径,否者命令会抛出警告并退出。

SIESTA 声子谱计算(phonopy)

~$ matflow siesta -r 5 --cif YOUR_STRUCTURE.cif -d DIRECTORY --meshcutoff VALUE --kpoints-mp VALUE --supercell-n VALUE

特定类型计算

Pymatflow提供部分特定类型计算任务,文档暂无。

structflow工具

结构格式转换

structflow支持cif、xsf、xsd、cube等结构文件的相互转换。例如,下面的命令会将cif格式的结构文件转换为xsd格式。

~$ sflow convert -i INPUT_STRUCTURE.cif -o OUTPUT_STRUCTURE.xsd

构建Supercell

~$ sflow supercell -i INPUT_STRUCTURE.cif -o OUTPUT_STRUCTURE.cif -n N1 N2 N3

删除晶体结构中的指定元素

~$ sflow remove -i INPUT_STRUCTURE.cif -o OUTPUT_STRUCTURE.cif –elements ELEMENTS_TO_REMOVE

指定移除晶体结构中原子

~$ sflow remove -i INPUT_STRUCTURE.cif -o OUTPUT_STRUCTURE.cif –atoms ATOMS_TO_REMOVE

更改晶体结构中原子的位置

~$ sflow move -i INPUT_STRUCTURE.cif -o OUTPUT_STRUCTURE.cif –atoms ATOMS_TO_REMOVE –disp LENGTH –direction DIRECTION

服务器交互实用工具

  • thq.py

  • thpull.py

  • thcancel.py

  • thcmd.py

  • threport.py

  • sz-cmd.py

  • sz-del.py

  • sz-q.py

  • sz-pull.py

这些工具是本地与远程服务器交互的工具,具体使用需要参数配置,后续补充。

API

文档暂无

官方微信公众平台

Pymatflow官方微信公众号”开源科学计算”目前已经开始试运营。欢迎订阅查看更多关于Pymatflow的最新 信息和使用教程。

_images/qrcode_for_open_source_scientific_computation.jpg

未来

首先欢迎有兴趣的朋友可以一起参与开发。也欢迎用户对程序的使用提出建议,或者提交功能需求。

问题反馈

本文档所有权归属Pymatflow项目。对项目有任何问题反馈,请发送邮件至

📫 pymatflow@163.com