命令行界面#

AiiDA 的命令行界面工具称为 verdi 。本节将解释适用于所有 verdi 命令的基本概念。

小技巧

verdi command line interface can also be explored as a text-based user interface <https://en.wikipedia.org/wiki/Text-based_user_interface>`_(TUI)。它要求 ``aiida-core` 与 tui 额外安装(如 pip install aiida-core[tui] )。然后可以使用 verdi tui 启动 TUI。

参数#

verdi 命令的参数有两种：

参数：位置参数，例如 verdi process kill 123 中的 123
选项：用标志(如 -f 或 --flag )表示，后面可能跟一个值。例如 verdi process list --limit 10 或 verdi process -h 。

多值选项#

某些 verdi 命令提供的选项可以有多个值。这样可以避免重复，例如写入：：

verdi archive create -N 10 11 12 -- archive.aiida

而不是更冗长的：……：

verdi archive create -N 10 -N 11 -N 12 archive.aiida

注意使用所谓的 endopts``标记 ``-- ，这是标记 -N 选项结束并将其与 archive.aiida 参数区分开所必需的。

帮助字符串#

在任何 verdi(子)命令后加上 --help 选项，即可获得如何使用该命令的帮助。例如， verdi process kill --help 显示：：

Usage: verdi process kill [OPTIONS] [PROCESSES]...

    Kill running processes.

Options:
    -t, --timeout FLOAT  Time in seconds to wait for a response before timing
                         out.  [default: 5.0]
    --wait / --no-wait   Wait for the action to be completed otherwise return as
                         soon as it's scheduled.
    -h, --help           Show this message and exit.

所有帮助字符串都由三部分组成：

描述如何调用命令的 Usage: 行
命令功能说明
可用选项列表

Usage: 行对命令参数信息进行了编码，例如

[OPTIONS] ：该命令有一个(或多个)选项
PROCESSES ：该命令要求进程作为位置参数
[PROCESSES] ：该命令将进程作为可选位置参数
[PROCESSES]... ：该命令将一个或多个进程作为可选位置参数

在帮助字符串中，多值选项后跟 ... ，相应命令的 Usage: 行将包含 ‘endopts’ 标记。例如:

Usage: verdi archive create [OPTIONS] [--] OUTPUT_FILE

    Export various entities, such as Codes, Computers, Groups and Nodes, to an
    archive file for backup or sharing purposes.

Options:
    -X, --codes CODE...             one or multiple codes identified by their
                                    ID, UUID or label
    -Y, --computers COMPUTER...     one or multiple computers identified by
                                    their ID, UUID or label
    -G, --groups GROUP...           one or multiple groups identified by their
                                    ID, UUID or name
    -N, --nodes NODE...             one or multiple nodes identified by their ID
                                    or UUID
    ...

简介#

AiiDA 支持每个安装多个配置文件，其中一个被标记为默认配置文件，除非要求使用另一个配置文件。使用: 显示当前默认配置文件：

verdi profile list

要使用不同的配置文件，请在任何 verdi 命令中加入 -p/--profile 选项，例如：：

verdi -p <profile> process list

请注意，指定的配置文件将用于此命令，且仅用于此命令。要永久更改默认配置文件，请使用 verdi profile setdefault 。

动词性#

所有 verdi 命令都有 -v/--verbosity 选项，可以控制命令打印输出的冗长程度。该选项的值称为日志级别，所有日志级别较低的信息都将被抑制。按日志级别递增的顺序，有效值为 NOTSET 、 DEBUG 、 INFO 、 REPORT 、 WARNING 、 ERROR 和 CRITICAL 。例如，如果日志级别设置为 ERROR ，则只会显示级别为 ERROR 和 CRITICAL 的报文。这些日志级别值的选择直接来自 Python``s built-in logging module <https://docs.python.org/3/library/logging.html>`_ 。 ``REPORT 级别是由 AiiDA 定义和添加的日志级别，位于 INFO 和 WARNING 级别之间，是默认日志级别。

动词选项不区分大小写，即 --verbosity debug 和 --verbosity DEBUG 完全相同。该选项可以在任何子命令级传递，例如

verdi process list --verbosity debug

与

verdi --verbosity debug process list

如果多次指定该选项，则只考虑最后一个值。

备注

--verbosity 选项只能覆盖 aiida 和 verdi 记录仪的记录级别。要控制其他记录仪的记录级别，请使用 verdi config set (参见 this section )。

标识符#

当使用 AiiDA 实体时，你需要一种在命令行中*引用它们的方法。AiiDA 中的任何实体都可以通过三个标识符来处理：

``Primary Key`` (PK)：一个整数，例如 723 ，用于在数据库中标识您的实体(自动分配)
de9afb72 (uuid)：一个字符串，例如 ce81c420-7751-48f6-af8e-eb7c6a30cec3 ，在全球范围内标识您的实体(自动分配)
标签：人类可读字符串，如 test_calculation (手动分配)。

备注

PK 易于键入，只要不超出数据库范围即可使用。不过，在与他人共享数据时，一定要使用 UUID。

任何需要将标识符作为参数的 verdi 命令都将接受 PK、UUID 和标签。

几乎在所有情况下，这都能正常工作。由于命令行参数是以字符串形式传递的，AiiDA 需要根据其内容推断标识符的类型，这在边缘情况下可能会失败(详见实施标识符决议 )。你可以采取以下预防措施来避免这种边缘情况：

PK：无需采取预防措施
UUID：完整的 UUID 无需采取任何预防措施。部分 UUID 应至少包括一个非数字字符或破折号
标签：在标识符末尾添加感叹号 !，以便强制解释为标签

实施标识符决议#

推导标识符类型的逻辑如下：

尝试将标识符解释为 PK(整数)
如果失败，请尝试将标识符解释为 UUID(完整或部分标识符)
如果失败，则将标识符解释为标签

下面的例子说明了这种逻辑可能出现的边缘情况：

PK	UUID	标签
10	12dfb104-7b2b-4bca-adc0-1e4fd4ffcc88	组
11	deadbeef-62ba-444f-976d-31d925dac557	10
12	3df34a1e-5215-4e1a-b626-7f75b9586ef5	deadbeef

如果试图通过部分 UUID 12 来识别第一个实体，则会通过 PK 来匹配第三个实体
如果试图通过标签 10 来识别第二个实体，则会通过 PK 来匹配第一个实体
试图通过标签 deadbeef 识别第三个实体时，会根据第二个实体的部分 UUID deadbeef 与之匹配

部分 UUID 和 PK 之间的歧义总是可以通过加入 UUID 的更长子串来解决，最终使标识符不再是有效的 PK。

如果标签也是有效 PK 或(部分)UUID，则需要不同的解决方案。针对这种情况， verdi 保留了一个特殊字符，即感叹号 !, that can be appended to the identifier. Before any type guessing is done, AiiDA checks for the presence of this marker and, if found, will interpret the identifier as a label. I.e. to solve ambiguity examples mentioned above, one would pass 10! 和 deadbeef! 。