gedent

gedent 是计算化学工作流程的输入生成器。它力求尽可能简单和通用，同时局限于量子化学研究领域。

gedent 代表 gerador de entradas，这是输入生成器在葡萄牙语中的翻译。🇧🇷

gedent 旨在为诸如 XTB、orca、ADF、Gaussian、NWChem 等类似的化学软件套件提供配置和模板的范例。虽然它旨在支持此类软件，并且考虑到这种用例而设计，但它是一个模板 CLI 与用户定义的配置相结合，因此如果您发现它有其他用途，请随时提出支持您需求的特性请求。

它好吗？

是的。

安装

要求

在安装 gedent 之前，请确保您已满足以下先决条件

• Rust（版本 1.65.0 或更高版本）
• Cargo，Rust 软件包管理器

如果 Rust 和 Cargo 尚未安装，您可以使用以下单行命令方便地设置它们

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装

要安装 gedent，我们将从源代码构建它，通过克隆 GitHub 仓库并运行 cargo build

git clone https://github.com/caprilesport/gedent.git
cd gedent
cargo build --release

构建后，二进制文件将位于 target/release/gedent，要使其在系统范围内可用，您可以将它链接到您的 $PATH 中的某个位置，例如

sudo ln -s $PWD/target/release/gedent /usr/local/bin

安装后，剩下的唯一事情就是将 templates 和 presets 目录，以及 gedent.toml 文件复制到您的系统配置目录。

Linux 和 Mac

mkdir ~/.config/gedent
cp -r ./templates ~/.config/gedent/
cp -r ./presets ~/.config/gedent/
cp ./gedent.toml ~/.config/gedent

配置

gedent 支持每个项目的配置文件。如果在当前目录或其父目录中没有找到配置文件（gedent.toml），则该工具默认使用 Linux 上的 ~/.config/gedent 中的配置。

如果您只想为当前文件夹（或其中任何子文件夹）中的配置修改参数，可以使用以下方法克隆当前使用的配置文件：

gedent init

将用户定义的配置文件与 TERA 模板 的强大功能相结合，可以生成丰富的输入生成系统。

以下是一个 gedent 的示例配置：

[gedent]
default_extension = "gjf"

[parameters]
charge = 1
mult = 1
solvation = true
solvent = "dmso"
random_field = "any valid toml data"
other_named_key = [100, 38, 29]

[gedent] 块包含默认设置，而 [parameters] 部分允许通过模板访问用户定义的配置。

gedent 提供了一个默认配置文件，其中包含程序中提供的模板的示例默认值。

模板基础

在 gedent 中，模板在生成输入方面发挥着核心作用。template 子命令便于模板管理。

入门指南

有关模板功能的全面指南，请参阅 Tera 模板文档。它基于 Jinja2 和 Django 模板语言，所以如果您熟悉这些语言之一，您会感到非常舒适。

创建新模板

要创建新模板，您可以在 presets 目录中添加一个基本模板，然后调用 gedent

gedent template new "new_template_name"

如果没有提供预设名称，则会弹出一个模糊对话框，帮助您为新模板选择预设。然后，该模板将在您的默认编辑器中打开以供修改。

gedent 随带一些流行的化学软件的默认模板预设，但鼓励用户创建自定义基本预设。目前，我们提供以下基本模板预设（如果您的软件不受支持，请 提交一个 pull-request）：

• orca
• ADF
• Gaussian
• NWChem

模板元数据

模板支持使用 --@ 分隔符的元数据标题。目前，唯一支持的元数据是 extension 指令，用于设置默认文件扩展名。未来的版本计划支持每个模板包含多个 XYZ 文件。

示例模板元数据

--@
extension = "inp"
--@

元数据使用 TOML 语法。

模板渲染

gedent 使用 .xyz 格式渲染模板，并且如果需要，用户可以利用 openbabel 进行格式转换。生成输入文件非常简单

gedent gen `name_of_template` example.xyz

支持通配符，允许使用类似 gedent gen orca/opt *.xyz 的命令。使用 gedent template list 查看所有可用的模板。

分子对象

gedent 将 XYZ 文件解析为 Molecule 对象，该对象包含以下字段： filename、description 和 atoms。在已经内置的 tera 函数 和 过滤器 的基础上，还提供了两个接收 Molecule 的额外函数，分别是 print_molecule 和 split_molecule。

示例 Molecule 对象字段

filename: example
description: Sample XYZ file
atoms: ["O  0.0  0.0  0.0", "H  0.0  1.0  0.0", "H  1.0  0.0  0.0"]

工作流程示例

Orca 优化

让我们通过一个使用 gedent 生成用于优化水分子的输入文件的示例来进行分析。

1. 创建新模板

   gedent template new opt orca
   

   此命令基于 orca 预设生成一个名为 opt 的新模板，并在您的默认编辑器中打开文件。

2. 编辑模板： 在您的编辑器中打开生成的模板，修改它以适应优化场景。例如

   --@
   extension = "inp"
   --@
   ! {{ functional }} {{ basis_set }}
   ! Opt freq
   
   %pal
    nprocs {{ nprocs }}
   end
   
   %maxcore {{ memory }}
   
   *xyz {{ charge }} {{ mult }}
   {{ print_molecule(molecule = Molecule) }}
   *
   

3. 审查配置： 确保配置参数符合要求。使用以下方法检查配置：

   gedent config print
   

   这将打印出类似以下内容

   charge = 1
   basis_set = "def2svp"
   functional = "BP86"
   functional_class = "GGA"
   memory = 3000
   mult = 1
   nprocs = 8
   solvation = false
   solvent = "water"
   start_hessian = false
   

4. 调整配置： 如果需要，使用以下方法修改配置：

   gedent config set
   

5. 生成优化输入

   gedent gen opt h2o.xyz
   

   这将根据模板和指定的 XYZ 坐标生成优化输入。

   这将产生

   ! BP86 def2svp
   ! Opt freq D3BJ
   
   %pal
    nprocs 8
   end
   
   %maxcore 3000
   
   *xyz 0 1
   O       -0.981036882      0.000000000     -2.282900972
   H       -0.981036882      0.759337000     -1.686857972
   H       -0.981036882     -0.759337000     -1.686857972
   *
   

示例模板

要了解如何使用 gedent 创建输入，请探索 模板目录 或 预设 中提供的模板。这些示例作为创建您自定义模板的宝贵参考。

交互式帮助

为了快速访问命令摘要和选项，请使用 --help 标志。例如

gedent --help
gedent template --help
gedent gen --help

贡献

欢迎为 gedent 贡献！如果您发现了一个错误，有一个功能请求或想贡献代码，请 创建一个问题 或 提交一个 pull request。

致谢

gedent 是基于以下出色的 crates 构建的

• TERA
• Dialoguer

许可证

gedent 在 MIT 许可证 下发布。