aiida_eos

创建AiiDA插件的Python包的演示。目标是创建一个用于https://aiida-qe-demo.readthedocs.io/en/latest/6_write_your_own_workflow.html中演示的状态方程工作流程的插件包。

此存储库中的每个提交都对应教程中的一个步骤。

注意，可以使用https://github.com/aiidateam/aiida-plugin-cutter来自动化这些步骤中的大部分，但在这里我们将手动解释包的各个方面。

初始创建

第一步是在GitHub上创建一个新的存储库。我们将称之为aiida_eos。存储库应包含一个README.md和一个.gitignore文件。

与存储库交互

我们将使用Visual Studio Code与存储库交互。这是一个免费、开源、跨平台的IDE，具有与GitHub的良好集成和许多有用的扩展。

创建包元数据

第一步是创建包元数据。这是通过在存储库根目录中创建一个pyproject.toml文件来完成的。它可以被pip用于安装包，并被其他工具用于构建包：[https://pip.pythonlang.cn/en/stable/reference/build-system/pyproject-toml/](https://pip.pythonlang.cn/en/stable/reference/build-system/pyproject-toml/)

我们将使用flit来构建包。这是一个简单的工具，旨在从pyproject.toml文件中构建Python包。

我们可以通过运行以下命令初始化pyproject.toml文件

flit init

这还会生成一个许可文件，这对于允许他人使用您的包至关重要。

创建包并安装它

我们使用单个文件创建初始包： src/aiida_eos/__init__.py。此文件应包含描述包的文档字符串和一个 __version__ 变量。

我们现在想以可编辑模式安装此包。这意味着我们可以修改包，并且更改将立即对Python可用。

首先，我们创建一个虚拟环境并激活它

python -m venv .venv
source .venv/bin/activate

虚拟环境是隔离Python环境的一种方式。

现在我们可以以可编辑模式安装该包

python -m pip install --upgrade pip
pip install -e .

现在我们可以将包导入Python

>>> import aiida_eos
>>> aiida_eos.__version__
'0.0.1'

使用 pre-commit 添加格式化和代码检查

我们将使用pre-commit自动格式化和检查代码。这将确保代码格式一致，并符合风格指南。

我们可以使用以下命令初始化pre-commit配置文件：

pre-commit sample-config > .pre-commit-config.yaml
pre-commit autoupdate
pre-commit install

我们将向配置文件添加几个额外的钩子

• black：Python代码格式化工具
• flake8：Python代码检查工具
• isort：用于排序Python导入的工具

添加测试

我们将使用pytest来运行包的测试。为了安装pytest，我们将将其添加到pyproject.toml文件中的optional-dependencies部分。这是因为我们只需要pytest来运行测试，而不是使用包。

现在我们可以安装包，包括可选依赖项

pip install -e ".[test]"

现在我们可以向包中添加一个测试。我们将添加一个检查包是否可以导入的测试。这是通过添加一个tests目录，并在其中添加一个test_import.py文件来实现的。

现在我们可以运行测试

pytest

要检查测试覆盖率，我们可以运行

pytest --cov=aiida_eos

使用 tox

tox CLI工具是一个可选的方式来自动化设置虚拟环境，然后在其中运行测试。请参阅pyproject.toml部分以获取配置信息。然后，您只需运行tox来运行测试，或者运行tox -e py39以使用特定的Python版本。请参阅tox-conda以了解如何使用conda与tox结合使用。

添加 GitHub Actions

我们可以使用GitHub Actions来自动在每个提交上运行测试。这是通过添加一个.github/workflows/test.yml文件来实现的。

添加 rescale calcfunction

我们将向包中添加一个rescale calcfunction。这是一个简单的函数，它接受一个结构，并通过给定的因子对其进行缩放。

请注意，到目前为止，我们还没有添加任何AiiDA特定的代码。现在，我们要添加一个AiiDA特定的calcfunction，我们需要将aiida-core依赖项添加到pyproject.toml文件中，以及添加ase以进行结构操作。

如果使用tox，我们可以使用以下命令重新生成虚拟环境：

tox -r

类型注解

我们还将注意到我们添加了函数的类型注解。这是一个好习惯，可以提供静态类型推断，并允许我们使用像mypy这样的工具来检查类型注解。

测试 calcfunction

现在我们可以为rescale calcfunction添加一个测试。实际上，如果我们使用测试驱动开发，我们首先编写测试，然后编写使测试通过的代码！

由于calcfunction需要将数据存储到AiiDa配置文件中，我们需要为测试创建一个配置文件。我们可以通过使用pgtest软件包来创建一个临时的本地PostgreSQL数据库集群，这允许我们创建一个临时的AiiDa配置文件，并将其添加到pyproject.toml测试依赖中。

为此，我们首先需要一个运行中的PostgreSQL服务器来连接。有几种方式可以实现，例如使用Docker镜像，或在macOS上通过Homebrew安装，或在Ubuntu上通过PostgreSQL apt仓库安装。

要创建测试配置文件，我们可以在tests目录中添加一个conftest.py文件。然后在其中注册AiiDa的pytest fixtures。您可以通过运行pytest --fixtures（或tox -- --fixtures）来查看所有可用的fixtures。我们最初需要的是aiida_profile_clean fixture，它创建一个临时配置文件，并在测试结束时将其销毁。

现在我们可以为rescale calcfunction添加一个通过测试。

在GitHub Actions上设置PostgreSQL

我们还需要在test.yml文件中指定一个服务来启动我们的GitHub Actions的PostgreSQL服务器。这实际上使用了PostgreSQL Docker镜像，它会在运行测试之前启动。

添加方程状态工作流程

我们现在将添加实际的工作流程。

我们在pyproject.toml文件中添加一个project.entry-points."aiida.workflows"部分，以将EquationOfState工作流程注册为入口点，以便AiiDA可以访问。在重新安装包（pip install --no-deps -e ".[test]"）后，我们现在可以使用verdi plugin list aiida.workflows eos.base命令来查看已注册的工作流程。

在运行工作流程之前，我们需要设置一些更多资源，我们可以通过在conftest.py文件中添加pytest fixtures来实现。

我们还需要针对实际的pw.x可执行文件进行测试。一种方法是通过conda安装quantum-espresso软件包，这将把pw.x可执行文件安装到conda环境的bin目录中。我们正在开发的其他方法是aiida-testing。

发布软件包

一旦软件包运行正常，创建一个版本标签和一个CHANGELOG.md来跟踪更改是一个好主意。

现在我们可以将软件包发布到PyPI。首先在PyPI上创建一个账户，然后创建一个API令牌。

您可以使用本地的flit publish来发布软件包，或者使用GitHub Actions：将令牌添加到GitHub仓库设置中的PYPI_KEY秘密。然后我们添加一个发布工作流程，它在每次新版本发布时运行。

一旦发布到PyPI（或发布之前），您可以向AiiDA插件注册表提交一个PR，以便其他人可以找到您的插件。