如何管理您的安装

管理配置文件

创建配置文件

每个AiiDA安装可以有多个配置文件,每个配置文件都可以有自己的单独数据库和文件存储库来存储 可验证性图 的内容。配置文件允许您在单个AiiDA安装的情况下完全独立地运行多个项目,并且至少需要一个配置文件才能运行AiiDA。可以使用 verdi quicksetup or verdi setup, 创建一个新的配置文件,后者工作原理类似于前者,但给用户更多的配置选择。

列出配置文件

The verdi profile command line interface provides various commands to manage the profiles of an AiiDA installation. To list the currently configured profiles, use verdi profile list:

Info: configuration folder: /home/user/.virtualenvs/aiida/.aiida
* project-one
  project-two

在这个特定的例子中,有两个配置文件, project-oneproject-two 。第一个被高亮显示,用 * 符号标记,这意味着它是默认配置文件。配置文件是默认的,这意味着任何 verdi 命令都会在这个配置下执行。你可以使用 --p/--profile 选项 在每次调用的基础上改变配置文件 。要更改默认配置文件,请使用 verdi profile setdefault PROFILE

显示配置文件

每个配置文件定义多个参数,例如文件存储库在文件系统上的位置和数据库的连接参数。要显示这些参数,使用 verdi profile show:

Info: Profile: project-one
----------------------  ------------------------------------------------
aiidadb_backend         django
aiidadb_engine          postgresql_psycopg2
aiidadb_host            localhost
aiidadb_name            aiida_project_one
aiidadb_pass            correcthorsebatterystaple
aiidadb_port            5432
aiidadb_repository_uri  file:///home/user/.virtualenvs/aiida/repository/
aiidadb_user            aiida
default_user_email      user@email.com
options                 {'daemon_default_workers': 3}
profile_uuid            4c272a87d7f543b08da9fe738d88bb13
----------------------  ------------------------------------------------

默认情况下,会显示默认配置文件的参数,但是可以传递另一个配置文件的名称,例如 verdi profile show project-two 来更改。

删除配置文件

可以使用 verdi profile delete 命令删除配置文件。默认情况下,删除概要文件也将删除其文件存储库和数据库。这种行为可以使用 --skip-repository--skip-db 选项来改变。

注解

为了删除数据库,系统用户需要拥有所需的权限,但这取决于系统。在这种权限限制的情况下,删除数据库可能会失败,用户将不得不通过PostgreSQL手动执行删除。

配置您的安装

开启tab补齐

verdi 命令行界面有许多命令和参数,可以用tab补全来简化其使用。要启用tab补全,应该执行以下shell命令:

$ eval "$(_VERDI_COMPLETE=source verdi)"

将此命令放在shell或虚拟环境激活脚本中,以便在打开新shell或激活环境时自动启用tab补全。这个文件是对应特定shell的,可能是以下之一:

重要

在将这一行添加到启动脚本之后,请确保重新启动终端或源脚本,使更改生效。

配置文件选项

AiiDA为配置文件提供了各种配置选项,可以用 verdi config 命令控制。

查看当前配置文件设置的所有配置选项。

$ verdi config list
name                                   source    value
-------------------------------------  --------  ------------
autofill.user.email                    global    abc@test.com
autofill.user.first_name               global    chris
autofill.user.institution              global    epfl
autofill.user.last_name                global    sewell
caching.default_enabled                default   False
caching.disabled_for                   default
caching.enabled_for                    default
daemon.default_workers                 default   1
daemon.timeout                         profile   20
daemon.worker_process_slots            default   200
db.batch_size                          default   100000
logging.aiida_loglevel                 default   REPORT
logging.alembic_loglevel               default   WARNING
logging.circus_loglevel                default   INFO
logging.db_loglevel                    default   REPORT
logging.kiwipy_loglevel                default   WARNING
logging.paramiko_loglevel              default   WARNING
logging.plumpy_loglevel                default   WARNING
logging.sqlalchemy_loglevel            default   WARNING
rmq.task_timeout                       default   10
runner.poll.interval                   profile   50
transport.task_maximum_attempts        global    6
transport.task_retry_initial_interval  default   20
verdi.shell.auto_import                default
warnings.showdeprecations              default   True

配置选项值按照优先级的顺序从特定配置文件设置、全局设置(适用于所有配置文件)或默认值中获取。

你也可以通过前缀进行过滤:

$ verdi config list transport
name                                   source    value
-------------------------------------  --------  ------------
transport.task_maximum_attempts        global    6
transport.task_retry_initial_interval  default   20

要显示配置选项的完整信息或获取其当前值:

$ verdi config show transport.task_maximum_attempts
schema:
    default: 5
    description: Maximum number of transport task attempts before a Process is Paused.
    minimum: 1
    type: integer
values:
    default: 5
    global: 6
    profile: <NOTSET>
$ verdi config get transport.task_maximum_attempts
6

你也可以通过API获取值:

In [1]: from aiida import get_config_option
In [2]: get_config_option('transport.task_maximum_attempts')
Out[2]: 6

要在配置文件或全局级别设置一个值:

$ verdi config set transport.task_maximum_attempts 10
Success: 'transport.task_maximum_attempts' set to 10 for 'quicksetup' profile
$ verdi config set --global transport.task_maximum_attempts 20
Success: 'transport.task_maximum_attempts' set to 20 globally
$ verdi config show transport.task_maximum_attempts
schema:
    type: integer
    default: 5
    minimum: 1
    description: Maximum number of transport task attempts before a Process is Paused.
values:
    default: 5
    global: 20
    profile: 10
$ verdi config get transport.task_maximum_attempts
10

小技巧

默认情况下,通过 verdi config 设置的任何选项将应用于当前的默认配置文件。要更改配置文件,可以使用 配置选项

类似于取消设置的值:

$ verdi config unset transport.task_maximum_attempts
Success: 'transport.task_maximum_attempts' unset for 'quicksetup' profile
$ verdi config unset --global transport.task_maximum_attempts
Success: 'transport.task_maximum_attempts' unset globally
$ verdi config show transport.task_maximum_attempts
schema:
    type: integer
    default: 5
    minimum: 1
    description: Maximum number of transport task attempts before a Process is Paused.
values:
    default: 5
    global: <NOTSET>
    profile: <NOTSET>
$ verdi config get transport.task_maximum_attempts
5

重要

影响守护进程的更改(例如,logging.aiida_loglevel )只会在重新启动守护进程后生效。

分离多个实例

AiiDA实例定义为已安装的源代码加上存储配置文件和所有配置文件的配置文件夹。只需在虚拟环境中分离代码和配置,就可以在一台机器上运行多个AiiDA实例。

要分离代码,请确保将AiiDA安装到虚拟环境中,例如,使用conda或venv,如 这里 所述。无论何时激活这个特定环境,都将运行专门为它安装的特定版本的AiiDA(以及所有插件)。

这与AiiDA的配置是分开的,配置存储在配置文件夹中,该目录总是默认命名为 .aiida ,并在默认情况下存储在用户家目录中。因此,配置目录的默认路径是 ~/.aiida 。默认情况下,每个AiiDA实例(每个安装)将在这个文件夹中存储相关的配置文件。最佳实践是始终将概要文件和它们所属的代码分开。典型的方法是将配置文件夹放在虚拟环境本身中,并在激活环境时自动选择它。

AiiDA配置文件夹的位置可以用 AIIDA_PATH 环境变量控制。通过向虚拟环境的激活脚本添加以下行,我们可以自动更改配置文件夹。例如,如果虚拟环境的路径是 /home/user/.virtualenvs/aiida ,则添加以下行:

$ export AIIDA_PATH='/home/user/.virtualenvs/aiida'

如果虚拟环境已经处于活动状态,请确保重新激活它,以便使更改生效。

注解

对于 conda,创建目录结构 etc/conda/activate.d 。在conda环境的根目录下(例如: /home/user/miniconda/envs/aiida ),并将 aiida-init.sh 文件放在导出 AIIDA_PATH 的文件夹中。

您可以先用 echo $AIIDA_PATH 显示环境变量,以确认它打印的路径是正确的,再测试一切是否正常。最后,你可以通过调用 verdi profile list 来检查AiiDA是否也正确地实现了配置文件夹的新位置。这将显示配置目录的当前位置:

Info: configuration folder: /home/user/.virtualenvs/aiida/.aiida
Critical: configuration file /home/user/.virtualenvs/aiida/.aiida/config.json does not exist

如果您还没有为这个AiiDA实例设置配置文件,那么您将看到第二行。有关设置配置文件的信息,请参阅 创建配置文件

除了单个路径, AIIDA_PATH 的值也可以是一个冒号分隔的路径列表。AiiDA将遍历每个路径,并检查它们是否包含一个配置文件夹,即一个名为 .aiida 的文件夹。遇到的第一个配置目录将用作配置目录。如果没有找到配置目录,将在考虑的最后一个路径中创建一个。例如,你的主文件夹 ~/ 中的目录结构可能是这样的:

.
├── .aiida
└── project_a
    ├── .aiida
    └── subfolder

如果未设置 AIIDA_PATH 变量的值,将会使用默认路径 ~/.aiida 。但如果使用如下设置 :

$ export AIIDA_PATH='~/project_a:'

则就会使用 ~/project_a/.aiida 作为配置路径

警告

如果 ~/project_a 中没有 .aiida 目录,那么AiiDA将会创建这个文件夹。因此需要特别注意是否正确设置了 AIIDA_PATH 环境变量。

将守护进程作为系统服务

可以将守护进程设置为系统服务,以便在系统启动时自动启动。如何做到这一点,取决于操作系统。对于Ubuntu,请参考 `服务文件的模板<https://github.com/marvel-nccr/ansible-role-aiida/blob/c709088dff74d1e1ae4d8379e740aba35fb2ef97/templates/aiida-daemon%40.service>`_安装服务的说明

性能提升

AiiDA支持使用数百万个节点运行成千上万的计算和图表。但是,在这种规模下获得最佳性能可能需要对AiiDA配置进行一些调整,以平衡CPU和磁盘负载。以下是一些可以提高AiiDA性能的一般技巧:

更新您的安装

无论何时更新您的AiiDA安装,请确保您 非常仔细地遵循这些说明 ,即使只是升级补丁版本!如果不这样做,可能会使您的安装处于损坏状态,或者更糟的是,可能会损坏您的数据,并无法修复。

  1. 激活安装AiiDA的Python环境。

  2. 完成所有正在运行的进程。所有已完成的流程将被自动迁移,但不可能恢复未完成的流程。

  3. 使用 verdi daemon Stop 停止守护进程。

  4. 创建您的数据库和存储库的备份

    警告

    一旦您迁移了您的数据库,您就不能再回到 aida -core 的旧版本(除非您从备份中恢复数据库和存储库)。

  5. 更新您的 aida -core 安装。

    • 如果你已经通过 conda 安装了AiiDA,只需运行: conda update aiida-core

    • 如果您已经通过 pip 安装了AiiDA,只需运行: pip install --upgrade aiida-core

    • 如果通过git仓库 pip install -e . 安装的话,那么在升级分支之前,首先删除所有的 .pyc 文件( find . -name "*.pyc" -delete )。

  6. 运行 reentry scan 更新注册入口点的缓存。

  7. 使用 verdi -p <profile_name> database migrate 迁移数据库。根据数据库的大小和要执行的迁移数量,数据迁移可能需要时间,所以请耐心等待。

数据库迁移完成后,您将能够继续处理现有数据。

注解

如果更新涉及到 aida -core 的主版本号的变化,并知晓有向后不兼容的变化,还需要检查你是否也需要更新安装的插件包。

备份您的安装

AiiDA实例和AiiDA管理数据的完整备份需要备份以下东西:

  • .aiida 文件夹中,config.json 文件中有AiiDA环境配置的相关信息。通常该文件夹在 ~/.aiida (同时参考 配置).

  • 项目文件夹的节点相关的文件(每个profile配置有一个独立的文件夹)。通常存在于 .aiida 文件夹中。

  • PostgreSQL 数据库中可查询的元数据(每个profile配置有独立的数据)。

配置文件仓库的备份 (.aiida 文件夹)

对于 小存储库 (小于100k文件),只需备份 .aiida 文件夹,可以选择使用标准备份软件。例如,rsync 实用程序支持增量备份,备份命令可以是 rsync -avHzPx (详细的)或 rsync -aHzx

对于有多如100k个节点的 大型仓库 , 即便是增量备份工具也会耗费大量时间。AiiDA提供了一个帮助脚本,其中使用了AiiDA数据库的优势,以用来决定哪些文件在你的最新一次备份中需要加入。下面的指南解释了如何使用它:

  1. 使用命令 verdi -p PROFILENAME devel configure-backup 配置你的这次备份,其中 PROFILENAME 时你要备份的AiiDA配置文件名。这个过程会需要下面几个信息:

    • “备份的文件夹”, 也就是备份后储存配置文件的位置。默认为 .aiida 文件夹中名为 backup_PROFILENAME 的文件夹。

    • “目标文件夹”, 是储存备份后的所有相关信息文件的位置。这默认会在上面“备份文件夹” 的子目录中,但我们 强烈建议将文件备份在另外一个储存设备中 (请看下面的提示)

    该配置步骤会在“备份文件夹” 中创建两个文件:一个名为 backup_info.json 配置文件(可以手动编辑)和一个名为 start_backup.py 的脚本。

  2. 运行 “备份文件夹” 中的 start_backup.py 脚本开始备份。

    这会将所有时间晚于 oldest_object_backedup 的数据备份。它只会在一定的 periodicity 时间里进行新的备份,如果设置了备份的最后时间,将会备份到那个时间为止的数据。 (分别使用 end_date_of_backupdays_to_backup 来指定上述参数), 详细参考 这个页面

    一旦你检查并确保备份可以进行,请保证周期性的进行数据的备份(比如使用日常cron 任务)

注解

您可能希望从主目录的任何单独设置的自动备份中排除文件存储库。

数据库备份

PostgreSQL 通常把数据库信息分散存储在多个文件当中,如果直接备份的话,就不能保证恢复数据库。因此,我们强烈建议定期将数据库内容转存至单个文件(之后您可以通过喜欢的方式备份)。

以下是一些有用的建议:

  • 为了避免每次使用脚本时都要输入数据库密码,你可以在您的主目录中创建一个文件 .pgpass 包含您的数据库凭证,如 PostgreSQL文档

  • 为转储你的数据库,使用 PostgreSQL的pg_dump程序。您可以使用类似于 这个文件 的bash脚本作为起始示例。

  • 您可以使用cron将备份脚本设置为每天运行(参见 :ref:`previous section <how-to:installation:backup:repository>`中的注释)。

恢复备份

为了恢复备份,您需要:

  1. 将之前备份的存储库文件夹恢复到原来的位置(你可以在 .aiida 文件夹的 config.json 文件中查看文件库位置,或使用 verdi profile show )。

  2. 按照以下说明创建一个空数据库 database 跳过 verdi setup 设置。数据库的名称和用户名应该与原来的数据库相同(例如,如果你在原来的postgresql集群上进行恢复,你可能需要重命名或删除原来的数据库)。

  3. 将目录更改为包含使用 pg_dump 创建的数据库转储的文件夹,并使用 psql 命令加载它。

管理多个用户

目前不支持为单个AiiDA实例设置多个用户。相反,每个AiiDA用户应该在自己的计算机上以Unix/Windows帐户安装AiiDA。在此帐户下,可以配置连接到远程计算机所需的所有凭据。使用独立的帐户将确保,例如,连接到超级计算机的SSH凭据不会与其他人共享。

可以使用 AiiDA的导出和导入功能 在实例之间共享数据。可以根据需要经常共享AiiDA图(其子集)。