Ctrl+K

如何管理您的安装#

管理简介#

创建简介#

每个AiiDA安装都可以有多个配置文件，每个配置文件都有自己独立的数据库和文件库来存储 provenance graph 的内容。预案让你只需安装一个 AiiDA 就能完全独立地运行多个项目，运行 AiiDA 至少需要一个预案。可以使用 verdi quicksetup 或 verdi setup 创建一个新的配置文件，其工作原理与前者类似，但给予用户更多的控制权。

Listing profiles#

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-one 和 project-two。第一个配置文件高亮显示并标有 * 符号，这意味着它是默认配置文件。默认配置文件的含义很简单，即任何 verdi 命令都将在该配置文件下执行。可以使用 --p/--profile 选项来执行 change the profile on a per-call basis。要更改默认配置文件，请使用 verdi profile setdefault PROFILE。

显示简介#

每个配置文件都定义了各种参数，如文件系统中文件存储库的位置和数据库的连接参数。要显示这些参数，请使用 verdi profile show：

Report: Profile: a-import-sqla
PROFILE_UUID: fede89dae42b4df3bf46ab27e2b500ca
default_user_email: user@email.com
process_control:
    backend: rabbitmq
    config:
        broker_host: 127.0.0.1
        broker_password: guest
        broker_port: 5672
        broker_protocol: amqp
        broker_username: guest
        broker_virtual_host: ''
storage:
    backend: core.psql_dos
    config:
        database_engine: postgresql_psycopg2
        database_hostname: localhost
        database_name: name
        database_password: abc
        database_port: 5432
        database_username: username
        repository_uri: file:///path/to/repository

默认情况下，会显示默认配置文件的参数，但也可以通过另一个配置文件的名称(如 verdi profile show project-two)来更改。

删除个人资料#

可以使用 verdi profile delete 命令删除配置文件。默认情况下，删除配置文件也会删除其文件库和数据库。可以使用 --skip-repository 和 --skip-db 选项更改这一行为。

备注

要删除数据库，系统用户需要拥有所需的权限，但这并不总是有保证的，这取决于系统。在这种情况下，数据库删除可能会失败，用户必须通过 PostgreSQL 手动执行删除操作。

配置安装#

激活选项卡补全功能#

verdi 命令行界面有许多命令和参数，可以用制表符完成，以简化使用。要启用制表符完成功能，应执行以下 shell 命令(取决于您使用的 shell)：

为 verdi 启用以下支持的 shell 之一的制表符完成功能

eval "$(_VERDI_COMPLETE=bash_source verdi)"

eval "$(_VERDI_COMPLETE=zsh_source verdi)"

eval (env _VERDI_COMPLETE=fish_source verdi)

将此命令放在 shell 或虚拟环境激活脚本中，可在打开新 shell 或激活环境时自动启用制表符补全。该文件与 shell 有关，但很可能是以下文件之一：

  • shell 的启动文件(.bashrc、.zsh……)，如果 aiida 是在整个系统中安装的

  • 虚拟环境的 activators

  • 为您的 conda 环境提供一个 startup file

重要

将该行添加到启动脚本后，确保重启终端或源代码脚本，以使更改生效。

配置配置文件选项#

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

您也可以通过*应用程序接口检索该值：

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 设置的任何选项都将应用于当前默认配置文件。要更改配置文件，可以使用 profile option。

类似地，取消设置值：

$ 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)只有在重启守护进程后才会生效。

参见

How-to configure caching

控制警告#

AiiDA 可能会因为各种原因发出警告，例如，当使用了代码的废弃部分时发出警告。这些警告默认是开启的，因为它们为用户提供了 important 信息。例如，可以使用 warnings.showdeprecations 配置选项关闭这些警告：

verdi config set warnings.showdeprecations false

小技巧

上述命令更改了当前配置文件的选项。不过，在加载配置文件之前会发出某些警告，例如当某些模块被 imported 时。要同时消除这些警告，可全局应用该选项：

verdi config set warnings.showdeprecations false --global

除了配置选项，AiiDA 也提供了专用的环境变量 AIIDA_WARN_v{version} 用于弃用警告。这里的 {version} 是版本号，例如 AIIDA_WARN_v3。即使关闭了 warnings.showdeprecations，也可以使用此环境变量启用弃用警告。这对于临时启用单个命令的弃用警告非常有用，例如

AIIDA_WARN_v3=1 verdi run script.py

隔离多个实例#

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

为了隔离代码，请确保将 AiiDA 安装到虚拟环境中，例如使用 conda 或 venv，如 here 所述。每当你激活这个特定的环境，你将运行你专门为它安装的特定版本的 AiiDA (和所有插件)。

这与 AiiDA 的配置是分开的，AiiDA 的配置保存在配置目录中，配置目录总是命名为 .aiida，默认保存在主目录中。因此，配置目录的默认路径是 ~/.aiida。默认情况下，每个 AiiDA 实例(每个安装)都会在这个文件夹中存储相关的配置文件。最好的做法是将配置文件与所属代码分开。典型的方法是将配置文件夹放在虚拟环境中，并在环境激活时自动选择。

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

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

如果虚拟环境已经激活，确保重新激活虚拟环境，以使更改生效。

备注

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

你可以先用 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 实例设置配置文件时才会看到。有关设置配置文件的信息，请参阅 creating profiles。

除了单一路径，313120F` 的值也可以是以冒号分隔的路径列表。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，这里有 a template for the service file 和 ansible instructions to install the service。

调整性能#

AiiDA 支持使用数百万个 node 运行数十万次计算和图形。然而，要在这种规模下获得最佳性能，需要调整 AiiDA 配置，以平衡 CPU 和磁盘负载。

下面，我们分享一些评估和调整 AiiDA 性能的实用技巧。更多详细信息，请参阅 topic on performance。

基准 workflow engine 性能

下载 benchmark script 并在 AiiDA 环境中运行。

sph@citadel:~/$ python performance_benchmark_base.py -n 100
    Success: Created and configured temporary `Computer` benchmark-e73b8647 for localhost.
    Success: Created temporary `Code` bash for localhost.
    Running 100 calculations.  [####################################]  100%
    Success: All calculations finished successfully.
    Elapsed time: 24.90 seconds.
    Cleaning up...
    12/19/2022 10:57:43 AM <12625> aiida.delete: [REPORT] 400 Node(s) marked for deletion
    12/19/2022 10:57:43 AM <12625> aiida.delete: [REPORT] Starting node deletion...
    12/19/2022 10:57:43 AM <12625> aiida.delete: [REPORT] Deletion of nodes completed.
    Success: Deleted all calculations.
    Success: Deleted the created code bash@benchmark-e73b8647.
    Success: Deleted the created computer benchmark-e73b8647.
    Performance: 0.25 s / process

上述输出在 AMD Ryzen 5 3600 6 核处理器(3.6 GHz，4.2 GHz 涡轮增压)上生成，使用 AiiDA v2.2.0，RabbitMQ 和 PostgreSQL 在同一台机器上运行。在这里，100 个 ArithmeticAddCalculation 进程在 ~25 秒内完成，相当于每个进程 0.25 秒。

如果观察到运行时间明显增加，您可能需要检查是否有任何相关组件(CPU、磁盘、postgresql、rabbitmq)出现拥塞。

增加守护进程工作者的数量

默认情况下，AiiDA 守护进程只使用单个 Worker，即单个操作系统进程。如果 verdi daemon status 显示守护进程工作者的 CPU 使用率一直很高，可以使用 verdi daemon incr X 添加 X 并行守护进程工作者。

请记住，您的计算机上还需要运行其他进程(如 rabbitmq、PostgreSQL 数据库……)，因此在达到 CPU 核心数之前，最好停止增加 Worker 的数量。

要使更改永久有效，请设置 :：

verdi config set daemon.default_workers 4
增加守护进程工作者插槽数量

每个守护进程处理程序一次只能接受有限数量的任务。如果 verdi daemon status 经常警告说守护进程程序员可用槽位的使用比例过高，可以增加每个守护进程程序员处理的任务数(从而增加每个程序员的工作量)。将其增加到 1000 通常会有效。

设置相应的配置变量并重启守护进程 :：

verdi config set daemon.worker_process_slots 1000
防止操作系统索引文件库。

许多 Linux 发行版都包含 locate 命令，用于快速查找文件和文件夹，并运行每日 cron 作业 updatedb.mlocate 创建相应的索引。一个大型文件库可能需要很长时间才能建立索引，甚至需要硬盘不断建立索引。

为了将版本库文件夹排除在索引之外，请将其路径添加到 /etc/updatedb.conf 配置文件的 PRUNEPATH 变量中(使用 sudo)。

将 Postgresql 数据库移到快速磁盘(固态硬盘)上，最好是大分区。

  1. 停止 AiiDA 守护进程和 back up your database。

  2. 找到 postgres 安装的数据目录(例如 /var/lib/postgresql/9.6/main、/scratch/postgres/9.6/main……)。

    最好的方法是成为 postgres UNIX 用户，并输入 postgres shell：：

    psql
SHOW data_directory;
\q

    如果无法进入 postgres shell，请尝试在文件 /etc/postgresql/9.6/main/postgresql.conf 或类似文件中查找 data_directory 变量。

  3. 停止 postgres 数据库服务：：

    service postgresql stop

  4. 将 postgres data_directory 中的所有文件和文件夹复制到新位置：：

    cp -a SOURCE_DIRECTORY DESTINATION_DIRECTORY

.. note:: Flag ``-a`` will create a directory within ``DESTINATION_DIRECTORY``, e.g.::

cp -a OLD_DIR/main/ NEW_DIR/

creates ``NEW_DIR/main``.
It will also keep the file permissions (necessary).

The file permissions of the new and old directory need to be identical (including subdirectories).
In particular, the owner and group should be both ``postgres`` (except for symbolic links in ``server.crt`` and ``server.key`` that may or may not be present).

.. note::

    If the permissions of these links need to be changed, use the ``-h`` option of ``chown`` to avoid changing the permissions of the destination of the links.
    In case you have changed the permission of the links destination by mistake, they should typically be (beware that this might depend on your actual distribution!)::

    -rw-r--r-- 1 root root 989 Mar  1  2012 /etc/ssl/certs/ssl-cert-snakeoil.pem
    -rw-r----- 1 root ssl-cert 1704 Mar  1  2012 /etc/ssl/private/ssl-cert-snakeoil.key

  5. 将 postgres 配置文件中的 data_directory 变量(如 /etc/postgresql/9.6/main/postgresql.conf)指向新目录。

  6. 重启数据库守护进程：：

    service postgresql start

最后，检查数据目录是否已更改：：

psql
SHOW data_directory;
\q

并尝试用新数据库进行简单的 AiiDA 查询。如果一切顺利，就可以删除旧数据库的位置。

如果您仍然遇到性能问题，以下提示可以帮助您找出性能瓶颈。

分析 RabbitMQ 消息速率

如果你观察到 AiiDA engine 性能缓慢，RabbitMQ management plugin 提供了一个直观的仪表板，让你监控信息速率，检查 AiiDA engine 的运行情况。

通过以下方式启用管理插件：：

sudo rabbitmq-plugins enable rabbitmq_management

然后，导航到 http://localhost:15672/，用 guest/guest 登录。

更新安装#

无论何时更新你的AiiDA安装，请务必仔细**这些说明，即使只是升级补丁版本！如果不这样做，可能会使你的安装处于损坏状态，更有甚者可能会损坏你的数据，可能无法挽回。

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

  2. 结束所有正在运行的进程。

    所有已完成的进程都将自动迁移，但无法恢复未完成的进程。

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

  4. Create a backup of your database and repository.

    警告

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

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

    • 如果通过 conda 安装了 AiiDA，只需运行：conda update aiida-core.

    • 如果您通过 pip 安装了 AiiDA，只需运行：pip install --upgrade aiida-core.

    • 如果使用 pip install -e . 从 git 代码库安装，请先删除所有 .pyc 文件(find . -name \``*.pyc\ -delete``)，然后再使用 git pull 更新分支。

  6. 使用 verdi -p <profile_name> storage migrate 迁移数据库。

    根据数据库的大小和需要执行迁移的次数，数据迁移可能需要一定的时间，请耐心等待。

数据库迁移完成后，您可以继续使用现有数据。

备注

如果更新涉及主要版本号 aiida-core 的更改，则应考虑向后不兼容的更改，并检查是否还需要更新已安装的插件包。

从 0.x.* 更新到 1.*#

从 1.* 更新到 2.*#

请参阅 Changelog 以获取更改列表。

Backing up your data#

General information#

The most convenient way to back up the data of a single AiiDA profile is to use

$ verdi --profile <profile_name> storage backup /path/to/destination

This command automatically manages a subfolder structure of previous backups, and new backups are done in an efficient way (using rsync hard-link functionality to the previous backup). The command backs up everything that’s needed to restore the profile later:

  • the AiiDA configuration file .aiida/config.json, from which other profiles are removed (see verdi status for exact location);

  • all the data of the backed up profile (which depends on the storage backend).

The specific procedure of the command and whether it even is implemented depends on the storage backend.

备注

The verdi storage backup command is implemented in a way to be as safe as possible to use when AiiDA is running, meaning that it will most likely produce an uncorrupted backup even when data is being modified. However, the exact conditions depend on the specific storage backend and to err on the safe side, only perform a backup when the profile is not in use.

Storage backend specific information#

Alternatively to the CLI command, one can also manually create a backup. This requires a backup of the configuration file .aiida/config.json and the storage backend. The panels below provide instructions for storage backends provided by aiida-core. To determine what storage backend a profile uses, call verdi profile show.

小技巧

创建备份前，建议运行 verdi storage maintain。这将优化存储，从而大大减少创建备份所需的时间。要获得最佳效果，请运行 verdi storage maintain --full。请注意，这要求配置文件未被任何其他进程使用。

psql_dos 存储后端是 AiiDA 的默认后端。它将数据存储在 PostgreSQL 数据库和本地文件系统的文件库中。要完全备份一个配置文件的数据，你应该备份相关的数据库和文件库。

PostgreSQL数据库

要导出整个数据库，建议使用 pg_dump 实用程序：

pg_dump -h <database_hostname> -p <database_port> -d <database_name> -U <database_username> -W > aiida_backup.psql

-W 标志将确保提示输入数据库密码。括号中的参数应替换为为配置文件配置的值。您可以从 verdi profile show 命令返回的 storage.config 中获取这些值。

小技巧

为了避免每次使用脚本时都要输入数据库密码，可以在主目录中创建一个包含数据库凭据的文件 .pgpass，如 in the PostgreSQL documentation 所述。

文件存放处

文件存储库是本地文件系统上的一个目录。创建备份的最有效方法是使用 rsync 实用程序。verdi profile show 命令返回的 storage.config.repository_uri 密钥中显示了存储库的路径。要创建备份，只需运行

rsync -arvz <storage.config.repository_uri> /some/path/aiida_backup

Restoring data from a backup#

Restoring a backed up AiiDA profile requires:

  • restoring the profile information in the AiiDA config.json file. Simply copy the`profiles` entry from the backed up config.json`to the one of the running AiiDA instance (see `verdi status for exact location). Some information (e.g. the database parameters) might need to be updated.

  • restoring the data of of the backed up profile according to the config.json entry. Like the backup procedure, this is dependent on the storage backend used by the profile.

The panels below provide instructions for storage backends provided by aiida-core. To determine what storage backend a profile uses, call verdi profile show. To test if the restoration worked, run verdi -p <profile-name> status to verify that AiiDA can successfully connect to the data storage.

To restore the backed up data for a profile using the core.psql_dos backend, you should restore the associated database and file repository.

PostgreSQL数据库

To restore the PostgreSQL database from the db.psql file that was backed up, first you should create an empty database following the instructions described in database skipping the verdi setup phase. The backed up data can then be imported by calling:

psql -h <db_hostname> -p <db_port> - U <db_user> -d <db_name> -W < db.psql

where the parameters need to match with the corresponding AiiDA config.json profile entry.

文件存放处

To restore the file repository, simply copy the directory that was backed up to the location indicated in AiiDA config.json (or the storage.config.repository_uri key returned by the verdi profile show command). Like the backing up process, we recommend using rsync for this:

rsync -arvz /path/to/backup/container <storage.config.repository_uri>

管理多个用户#

AiiDA目前不支持多个用户同时运行同一个AiiDA配置文件。虽然AiiDA会用创建node的 User 标记它(默认用户在配置文件中指定)，但目前内部并没有使用这些信息。特别是，目前没有权限系统来限制特定用户可以执行的操作。

典型的设置包括每个用户在他们的操作系统账户上单独安装 AiiDA。数据可通过 AiiDA’s export and import functionality 在私人 AiiDA 配置文件之间共享。

请注意，虽然 AiiDA 实例的配置文件包含访问凭证(例如 postgresql 数据库或 rabbitmq 服务)，但 AiiDA 不会在数据库或文件存储库中存储敏感数据，AiiDA 导出档案也不会包含此类数据。

On this page
Edit on GitHub
显示源代码