如何共享数据#

AiiDA 提供两种与他人共享数据的途径：归档文件和 REST API。

共享 AiiDA 档案#

您使用 AiiDA 进行了计算，您希望分享您的 AiiDA provenance graph，例如，使您的科学研究具有可重复性。

由于 AiiDA 会记录每一个计算结果的 provenance，所以这一步很容易：告诉 AiiDA 你希望可重现的**最终结果，AiiDA 就会使用遍历规则自动包含整个 provenance。

参见

导出单个 node#

假设您研究的关键结果包含在三个 AiiDA node 中，PK 分别为 12 、 123 、 1234 。导出这些结果和它们的 provenance 就很容易：

$ verdi archive create my-calculations.aiida --nodes 12 123 1234

像往常一样，您可以使用任何标识符(标签、PK 或 UUID)来指定要导出的 node。

生成的存档文件 my-calculations.aiida 包含与导出的 node 相关的所有信息。默认遍历规则确保包含指定的任何 node 的完整 provenance 信息，对大多数情况来说足够了。有关修改遍历规则的方法，请参见 verdi archive create --help 。

小技巧

要在导出前查看导出的内容，可以使用 --test-run 选项：

$ verdi archive create --test-run my-calculations.aiida

当你的同事指向 AiiDA 存档内的数据时，请记住使用 UUID ，因为 UUID 保证是普遍唯一的(而 PK 不是)。

输出大量 nodes#

如果要导出的结果数量较多，例如在高通量研究中，可使用 QueryBuilder 将相应的 nodes 添加到 my-results 组中(见如何分组 nodes )。然后导出组：

$ verdi archive create my-calculations.aiida --groups my-results

或者，用以下方法导出整个个人资料：

$ verdi archive create my-calculations.aiida --all

发布 AiiDA 存档文件#

AiiDA档案文件可以发布在任何研究数据储存库，例如 Materials Cloud Archive、 Zenodo 或 Open Science Framework。在 Materials Cloud Archive 上发布 AiiDA 归档文件时，你还会获得一个交互式 EXPLORE 部分，允许同行直接在浏览器中浏览 AiiDA provenance graph。

检查档案#

为了快速查看存档文件，而不将其 import 添加到 AiiDA 配置文件中，请使用 verdi archive info ：

$ verdi archive info --detailed test.aiida
metadata:
    export_version: main_0001
    aiida_version: 2.0.0
    key_format: sha256
    compression: 6
    ctime: '2022-03-06T23:50:57.964429'
    creation_parameters:
        entities_starting_set:
        node:
        - 6af3f8a0-cf0d-4427-8472-f8907acfc87a
        include_authinfos: false
        include_comments: true
        include_logs: true
        graph_traversal_rules:
        input_calc_forward: false
        input_calc_backward: true
        create_forward: true
        create_backward: true
        return_forward: true
        return_backward: false
        input_work_forward: false
        input_work_backward: true
        call_calc_forward: true
        call_calc_backward: true
        call_work_forward: true
        call_work_backward: true
entities:
    Users:
        count: 1
        emails:
        - aiida@epfl.ch
    Computers:
        count: 2
        labels:
        - computer1
        - computer2
    Nodes:
        count: 53
        node_types:
        - data.core.array.trajectory.TrajectoryData.
        - data.core.cif.CifData.
        - data.core.code.Code.
        - data.core.dict.Dict.
        - data.core.folder.FolderData.
        - data.core.remote.RemoteData.
        - data.core.singlefile.SinglefileData.
        - data.core.structure.StructureData.
        - process.calculation.calcfunction.CalcFunctionNode.
        - process.calculation.calcjob.CalcJobNode.
        process_types:
        - aiida.calculations:codtools.ciffilter
        - aiida.calculations:quantumespresso.pw
    Groups:
        count: 0
        type_strings: []
    Comments:
        count: 0
    Logs:
        count: 0
    Links:
        count: 59
repository:
    objects:
        count: 71

您还可以使用 Python API 以配置文件的形式检查归档文件，请参见如何检查档案。

Import 创建档案#

使用 verdi archive import 将 import AiiDA 档案加入你目前的 AiiDA 档案。 verdi archive import 接受 URL，例如：

$ verdi archive import "https://archive.materialscloud.org/record/file?file_id=2a59c9e7-9752-47a8-8f0e-79bcdb06842c&filename=SSSP_1.1_PBE_efficiency.aiida&record_id=23"

在 import 期间，AiiDA 将根据 UUID(以及 User 条目的电子邮件比较)避免标识符碰撞和 node 重复。默认情况下，现有实体将根据最新更改进行更新。Node 额外内容和注释具有特殊模式，用于确定如何 import 它们–更多详情，请参阅 verdi archive import --help 。

要在 importing 之前查看 imported 的内容，可以使用 --test-run 选项：

$ verdi archive import --test-run my-calculations.aiida

小技巧

AiiDA 存档格式随着时间的推移而演变，但你仍然可以 import 存档用以前的 AiiDA 版本创建。如果在 import 期间检测到过期的存档版本，存档文件将自动迁移到最新版本(在临时文件夹内)，并重新尝试 import。

您还可以使用 verdi archive migrate 从现有存档文件创建更新存档文件(或就地更新)。

通过 REST API 提供数据#

AiiDA REST API 允许通过 HTTP(S) 查询 AiiDA 数据库，并以 JSON format 返回结果。

备注

截至 2020 年 10 月，AiiDA REST API 仅支持 GET methods (reading); in particular, it does not yet support workflow management. This feature is, however, part of the AiiDA roadmap。

备注

为确保在提供 orm.ArrayData one always obtains a valid JSON compliant with the ECMA-262 standard 服务时，任何 np.nan 、 np.inf 和/或 -np.inf 条目都将被 None 代替，而在通过 API 调用获取数组时， None 将显示为 null 。

启动 REST API#

开始通过 REST API 从默认 AiiDA 配置文件提供数据：

$ verdi restapi
 * REST API running on http://127.0.0.1:5000/api/v4
 * Serving Flask app "aiida.restapi.run_api" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

REST API 现在运行在本地计算机的 5000 端口上。

与所有 verdi 命令一样，您可以通过 -p PROFILE 选项选择不同的 AiiDA 配置文件：

verdi -p <another_profile> restapi

备注

REST API 历史版本：

aiida-core >= 1.0.0b6: v4 .简化端点；仅保留 /nodes 、 /processes 、 /calcjobs 、 /groups 、 /computers 和 /servers 。
aiida-core >= 1.0.0b3, <1.0.0b6: v3 .开发版本，从未与稳定版本一起发布。
aiida-core <1.0.0b3: v2 。第一个应用程序接口版本，逐步添加新的端点。

查询 REST API#

查询 REST API 的 URL 包括

默认为*基础 URL*：

http://127.0.0.1:5000/api/v4

查询基本 URL 会返回所有可用端点的列表。
定义请求的资源的路径，可选择在其后加上一个更具体的终点。例如：：
```
/nodes
/nodes/page/2
/nodes/projectable_properties
/nodes/<uuid>
/nodes/<uuid>/links/outgoing
```
如果没有附加端点，API 将返回该资源的对象列表。要请求资源的特定对象，请附加其 UUID 。

备注

像往常一样，只要 UUID 是唯一的，就可以使用部分 UUID。

要通过 PK 进行查询，您需要使用 id 过滤器(见下文)。这也适用于 User ，因为它没有 UUID(而是使用电子邮件)。
(可选) 查询字符串 ，用于对结果进行筛选、排序和分页。例如：：
```
?limit=20&offset=35
?id=200
?node_type=like="data%"
```

以下是一些可供尝试的例子：

http://127.0.0.1:5000/api/v4/users/
http://127.0.0.1:5000/api/v4/computers?scheduler_type="slurm"
http://127.0.0.1:5000/api/v4/nodes/?id>45&node_type=like="data%"

小技巧

交互式 EXPLORE sections on Materials Cloud 全部由 AiiDA REST API 支持，你可以使用网络浏览器或 curl 等工具查询底层 API：

$ curl https://aiida-dev.materialscloud.org/2dstructures/api/v4/users

有关端点、查询字符串和响应格式的大量用户文档，请参见 AiiDA REST API reference 。

Added in version 2.1.0.

可以允许请求声明运行配置文件的特定配置文件。这样就可以使用单一的 REST API 来提供所有配置文件的内容。配置文件切换功能默认是禁用的，但可以通过配置启用：

verdi config set rest_api.profile_switching True

例如，重启 REST API 后，它将接受 profile 查询参数：

http://127.0.0.1:5000/api/v4/computers?profile=some-profile-name

如果已加载指定的配置文件，REST API 的功能与未启用配置文件切换时完全相同。如果指定了另一个配置文件，REST API 会在执行请求前首先切换配置文件。

备注

如果在请求中指定了配置文件参数，而 REST API 未启用配置文件切换功能，则会返回 400 响应。

部署 REST API 服务器#

verdi restapi command runs the REST API through the werkzeug python-based HTTP server. In order to deploy production instances of the REST API for serving your data to others, we recommend using a fully fledged web server, such as Apache 或 NGINX，然后通过 web server gateway interface (WSGI) 运行 REST API python 应用程序。

备注

一个 Apache/NGINX 服务器可以承载多个 REST API 实例，例如，提供来自不同 AiiDA 配置文件的数据。

AiiDA 配置文件 myprofile 的 myprofile-rest.wsgi 脚本如下：

# wsgi script for AiiDA profile 'myprofile'
from aiida.manage.configuration import load_profile
from aiida.restapi.run_api import configure_api

load_profile('myprofile')

api = configure_api()
application = api.app

备注

有关所有可用配置选项，请参阅 configure_api() 文档。

下面，我们将介绍如何在 Ubuntu 上使用 Apache 运行此 wsgi 应用程序。

安装并启用 mod_wsgi WSGI module 模块：

$ sudo apt install libapache2-mod-wsgi-py3
$ sudo a2enmod wsgi

将 WSGI 脚本放到服务器上的一个文件夹中，例如 /home/ubuntu/wsgi/myprofile-rest.wsgi 。

使用类似于以下的虚拟主机配置，配置 apache 以运行 WSGI 应用程序：

# Apache virtual host configuration file for AiiDA REST API
# Copy to /etc/apache2/sites-enabled/aiida-rest.conf

<VirtualHost *:80>

    LogLevel debug

    # Let the app do authorization
    WSGIPassAuthorization On

    # Require privileges on the wsgi directory
    <Directory "/home/ubuntu/wsgi">
        Require all granted
    </Directory>

    # BEGIN SECTION for "myprofile" AiiDA profile
    # Use 5 threads and "aiida" virtual python environment
    WSGIDaemonProcess rest-myprofile \
        user=ubuntu group=ubuntu \
        threads=5 \
        python-home=/home/ubuntu/.virtualenvs/aiida \
        display-name=aiida-rest-myprofile

    # REST API will be served on <host>/myprofile/api/v4
    WSGIScriptAlias /myprofile /home/ubuntu/wsgi/myprofile-rest.wsgi
    <Location /myprofile>
        WSGIProcessGroup myprofile
    </Location>
    # END SECTION for "myprofile" AiiDA profile


</VirtualHost>

将此 aiida-rest.conf 文件放到 /etc/apache2/sites-enabled 中

重新启动 apache： sudo service apache2 restart .

现在您应该可以通过 localhost/myprofile/api/v4 (端口 80)访问 REST API。