optimade-maker

从各种格式的结构数据（例如CIF文件的存档）创建OPTIMADE API的工具。

此存储库包含src/optimade-maker Python包和相应的CLI工具optimake，这些工具旨在实现这一目标。功能包括

• 定义配置文件格式（optimade.yaml），用于注释要用于OPTIMADE生态系统的数据存档；
• 使用现有的解析器（例如，ASE用于结构）将原始数据转换为相应的OPTIMADE类型；
• 将注释的数据存档转换为中间JSONLines文件格式，该格式可以导入数据库并用于提供完整的OPTIMADE API。
• 作为OPTIMADE API（使用optimade-python-tools参考服务器实现）提供注释的数据存档或JSONLines文件。

用法

请参阅 ./examples 了解更完整的支持格式和相应的 optimade.yaml 配置文件。

使用 optimade.yaml 进行注释

为了注释您的结构数据以便于 optimade-maker 使用，数据归档需要附带一个 optimade.yaml 配置文件。以下是一个简单的示例，它是一个 cif 文件的 zip 归档（structures.zip），以及一个可选的属性文件（data.csv）。

config_version: 0.1.0
database_description: Simple database

entries:
  - entry_type: structures
    entry_paths:
      - file: structures.zip
        matches:
          - cifs/*/*.cif
    # (optional) property file and definitions:
    property_paths:
      - file: data.csv
    property_definitions:
      - name: energy
        title: Total energy per atom
        description: The total energy per atom as computed by DFT
        unit: eV/atom
        type: float

结构 id 和属性文件

optimade-maker 将根据归档中的完整路径为每个结构分配一个 id，遵循一个简单的确定性规则：从所有归档路径的集合中，移除最大公共路径前缀和后缀（包括文件扩展名）。例如：

structures.zip/cifs/set1/101.cif
structures.zip/cifs/set2/102.cif

生成 ["set1/101", "set2/102"]。

属性文件需要引用这些 id 或归档中的完整路径，以便与结构相关联。例如，一个可能的属性 csv 文件可以是：

id,energy
set1/101,2.5
structures.zip/cifs/set2/102.cif,3.2

安装和运行 optimake

使用以下命令安装：

pip install optimade-maker

这将使 optimake CLI 工具可用。

对于包含数据归档和 optimade.yaml 文件（如 /examples 中的）的文件夹，运行

• optimake convert . 仅将条目转换为 JSONL 格式（见下文）。
• optimake serve . 以启动 OPTIMADE API（如果需要，这也首先转换条目）；

有关更多信息，请参阅 optimake --help。

optimade-maker JSONLines 格式

如上所述，optimade-maker 通过 OPTIMADE API 的中间 JSONLines 文件表示形式工作（另请参阅规范中的相应问题）。此文件应提供足够的元数据来启动具有许多不同条目类型的 OPTIMADE API。格式如下：

• 第一行必须是一个字典，其键为 x-optimade，包含元数据子字典（例如，OPTIMADE API 版本）。
• 第二行包含 info/structures 端点。
• 如果存在，第三行包含 info/references 端点。
• 然后每一行都包含来自相应单个结构/参考端点的条目。

{"x-optimade": {"meta": {"api_version": "1.1.0"}}}
{"type": "info", "id": "structures", "properties": {...}}
{"type": "info", "id": "references", "properties": {...}}
{"type": "structures", "id": "1234", "attributes": {...}}
{"type": "structures", "id": "1235", "attributes": {...}}
{"type": "references", "id": "sfdas", "attributes": {...}}

注意：在 OPTIMADE v1.2.0 的 info/ 端点将包括 type 和 id。

相关链接

• 路线图和会议记录
• OPTIMADE 序列化格式说明
• 流程图

贡献者

初始原型于 2023 年 6 月 12 日至 16 日在瑞士保罗·谢勒研究所创建。

作者（按字母顺序排列）

• Kristjan Eimre
• Matthew Evans
• Giovanni Pizzi
• Gian-Marco Rignanese
• Jusong Yu
• Xing Wang