Spglib

License Status

用于查找和处理晶体对称性的 C 语言库

Spglib

Spglib 的功能是什么？

将晶体结构输入 spglib 函数以获取对称性信息。spg_get_dataset 是返回最丰富空间群信息的函数。该函数以 C 结构体 SpglibDataset 的形式返回结果。由于我们不知道要返回的对称操作的数量，内存空间是动态分配的，这意味着我们必须通过 spg_free_dataset 释放它们。为了容忍晶体结构的微小畸变，在调用对称性搜索函数时必须指定该参数。以下页面展示了详细信息。

#include <assert.h>
#include "spglib.h"

int main(void) {
    SpglibDataset *dataset;
    // Wurtzite structure (P6_3mc)
    double lattice[3][3] = {
        {3.111, -1.5555, 0}, {0, 2.6942050311733885, 0}, {0, 0, 4.988}};
    double position[4][3] = {
        {1.0 / 3, 2.0 / 3, 0.0},
        {2.0 / 3, 1.0 / 3, 0.5},
        {1.0 / 3, 2.0 / 3, 0.6181},
        {2.0 / 3, 1.0 / 3, 0.1181},
    };
    int types[4] = {1, 1, 2, 2};
    int num_atom = 4;
    double symprec = 1e-5;

    // SplibDataset has to be freed after use.
    dataset = spg_get_dataset(lattice, position, types, num_atom, symprec);

    // Obtain data in SpglibDataset.
    // The space group number 186 corresponds to the wurtzite-type (P6_3mc).
    // See https://web.archive.org/web/20250505150336/https://www.cryst.ehu.es/cgi-bin/cryst/programs/nph-table
    assert(dataset->spacegroup_number == 186);

    // Deallocate SpglibDataset, otherwise induce memory leak.
    spg_free_dataset(dataset);
}

要求

C 标准：自 2.1.0 版本起，Spglib 明确强制执行最低 C11

如何使用 Spglib

我们目前仅官方支持 spglib 的 conda 和 pip 打包，并计划在不久的将来扩展到 FedoraProject。我们正在寻找额外的贡献者，以便在其他 linux 发行版上进行打包。对于尚未官方支持的系统，请参阅手动编译的说明

spglib 的主要接口是 C api，但我们还官方支持 Fortran 和 Python 接口。有关如何使用此库的最小示例，请查看提供的示例

如何安装 python 库

Spglib 在 PyPi 上可用，因此可以按以下方式安装：

$ pip install spglib

或者，您可以安装捆绑了 C 和 Fortran 库的 conda 软件包

$ conda install -c conda-forge spglib

此 Python 库将默认使用检测到的系统安装的 Spglib 库，在 Linux 上通过 LD_LIBRARY_PATH 指定，或在 MacOS 上通过 DYLD_LIBRARY_PATH 指定，否则默认使用捆绑版本。

有关更多详细信息以及如何从源代码构建 Python 项目，请参阅 Python 文档。

如何手动编译

最小配置、构建和安装说明如下：

$ cmake . -B ./build
$ cmake --build ./build
$ cmake --install ./build

有关配置选项以及如何链接项目的更多详细信息，请参阅 cmake 文档。使用 spglib 的最小示例项目可在 example 中找到。

如何运行测试

C 库测试已集成在 CMake 项目中，并默认启用。要执行这些测试，请使用指向构建目录的适当路径运行以下命令

$ ctest --test-dir ./build

此外，还有覆盖更多使用场景的 python 测试。有关更多详细信息，请参阅 python 文件夹中的 README

如何引用 Spglib

如果您在研究中使用 spglib，请考虑引用以下工作：

Atsushi Togo, Kohei Shinohara and Isao Tanaka, Spglib: a software library for crystal symmetry search, Sci. Technol. Adv. Mater., Meth. 4, 2384822-2384836 (2024) (open access)

@article{spglib,
  author = {Atsushi Togo, Kohei Shinohara and Isao Tanaka},
  title = {Spglib: a software library for crystal symmetry search},
  journal = {Sci. Technol. Adv. Mater., Meth.},
  volume = {4},
  number = {1},
  pages = {2384822--2384836},
  year = {2024},
  doi = {10.1080/27660400.2024.2384822},
  url = {https://doi.org/10.1080/27660400.2024.2384822},
}

如果您使用函数在 spglib 中搜索磁对称操作，请也考虑引用以下工作：

Kohei Shinohara, Atsushi Togo, and Isao Tanaka, Algorithms for magnetic symmetry operation search and identification of magnetic space group from magnetic crystal structure, Acta Cryst. A 79, 390-398 (2023) (open access)

@article{spglibv2,
  author = "Shinohara, Kohei and Togo, Atsushi and Tanaka, Isao",
  title = "{Algorithms for magnetic symmetry operation search and identification of magnetic space group from magnetic crystal structure}",
  journal = "Acta Cryst. A",
  year = "2023",
  volume = "79",
  number = "5",
  pages = "390--398",
  month = "Sep",
  doi = {10.1107/S2053273323005016},
  url = {https://doi.org/10.1107/S2053273323005016},
}

贡献

我们欢迎从库的核心开发到文档改进的任何贡献。有关更多详细信息，请参阅 Contributing.md。

文档

请参阅 https://spglib.readthedocs.io/ 以获取进一步的文档。请参阅 documentation 以获取有关如何为文档做出贡献的更多信息。