4. XTC头部解析：magic number、版本号、原子数量、natoms的读取与验证

在动手写代码之前，我习惯先把文件头部的每个字段搞清楚。

说白了，XTC文件和我们平时写的JSON、YAML一样，前面都有一段“元信息”。这段元信息告诉你，这个文件里装了什么东西，怎么去读。如果连头部都解析错了，那后面的原子坐标就不用看了。

4.1 幻数（magic number）——文件的身份证

每个XTC文件的开头，都是一个固定不变的整数。这个整数就是幻数，它的值是 1995。

为什么是1995？因为GROMACS项目就是从1995年开始的。嗯，这里算是一点历史彩蛋。

读取幻数的方式很简单。用C语言举例，直接从文件流里读取一个int32即可：

#include <stdio.h>
#include <stdint.h>

int32_t magic;
fread(&magic, sizeof(int32_t), 1, fp);

if (magic != 1995) {
    fprintf(stderr, "错误：不是有效的XTC文件，幻数=%d\n", magic);
    return -1;
}

我有一个教训要分享。曾经我解析一个奇奇怪怪的二进制文件，差点把1995这个值写成了1996。事后才发现，0.01%的文件因为编码原因，读取顺序反了。所以这里要特别注意字节序（endianness）。XTC规范明确规定，文件头部的所有整数都是小端序（little-endian）。

4.2 版本号——格式的版本控制

幻数验证通过之后，下一个字段就是版本号。它同样是一个int32的小端序整数。

不同版本的XTC文件，其内部压缩方式和数据排列可能会有差异。我刚开始做解析时跳过这一步，结果遇到一个旧版文件直接崩溃。从那以后，我再也不敢省略版本号检查了。

XTC的版本号目前常见的有两种：

• 版本1：早期格式，压缩方式单一，现已不常见。
• 版本3：当前主流格式，使用了更高效的压缩算法。

读取版本号并做兼容性检查：

int32_t version;
fread(&version, sizeof(int32_t), 1, fp);

if (version < 1) {
    fprintf(stderr, "错误：版本号无效，version=%d\n", version);
    return -2;
}

// 我这里只兼容版本1和版本3
if (version != 1 && version != 3) {
    fprintf(stderr, "警告：不支持该版本的XTC文件，version=%d\n", version);
    return -3;
}

4.3 原子数量（natoms）——正确的内存分配依据

接下来这个字段就是 natoms，也就是这个轨迹文件中包含的原子总数。

为什么要先读取这个？你想想看，如果没有它，我们不知道后面需要分配多少内存来装坐标数据。直接读下去，分配少了会溢出，分配多了浪费内存。

读取原子数量：

int32_t natoms;
fread(&natoms, sizeof(int32_t), 1, fp);

if (natoms <= 0) {
    fprintf(stderr, "错误：原子数量无效，natoms=%d\n", natoms);
    return -4;
}

// 这里可以加一个合理范围的检查
if (natoms > 10000000) { // 1000万个原子，太大了吧？
    fprintf(stderr, "警告：原子数量异常大，natoms=%d\n", natoms);
    // 你可以选择继续，或者退出
}

我个人习惯在这里多做一个步骤——记录 natoms 到一个全局变量中，因为在解析后续帧的时候会反复用到它。一旦写好就不要再改，除非你明确知道自己在干什么。

4.4 natoms的双重校验

这里有一个小陷阱。在XTC文件头部，natoms 其实出现了两次：

• 第一次在头部，紧跟在版本号后面。
• 第二次在每个帧（frame）的头部。

为什么这么设计？

因为轨迹文件可能非常大，有时候你只读头部就能知道文件包含的原子数，而不需要跳转去读帧头部。但有些工具在写入时，帧头部的 natoms 可能与文件头部的不一致。这种情况我遇到过一次，原因是有个老旧的模拟程序在输出轨迹时，把某个帧的原子数写错了。

为了避免踩坑，我建议在读帧数据时，对比帧头部的natoms和文件头部的natoms：

// 假设 frame_natoms 是从帧头部读取的
if (frame_natoms != natoms) {
    fprintf(stderr, "错误：帧内原子数量与文件头部不一致\n");
    fprintf(stderr, "头部 natoms=%d，帧 natoms=%d\n", natoms, frame_natoms);
    // 一般以文件头部的 natoms 为准
}

4.5 实践：完整头部解析流程

把上面几个字段串起来，就是一个完整的XTC头部解析流程。我用一个函数来封装：

#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>

typedef struct {
    int32_t magic;
    int32_t version;
    int32_t natoms;
} XtcHeader;

int read_xtc_header(FILE *fp, XtcHeader *header) {
    if (!fp || !header) return -1;

    // 读取幻数
    fread(&header->magic, sizeof(int32_t), 1, fp);
    if (header->magic != 1995) {
        fprintf(stderr, "幻数不对\n");
        return -1;
    }

    // 读取版本号
    fread(&header->version, sizeof(int32_t), 1, fp);
    // 这里只支持版本1和3
    if (header->version != 1 && header->version != 3) {
        fprintf(stderr, "版本号不支持: %d\n", header->version);
        return -2;
    }

    // 读取原子数量
    fread(&header->natoms, sizeof(int32_t), 1, fp);
    if (header->natoms <= 0) {
        fprintf(stderr, "原子数量无效\n");
        return -3;
    }

    return 0; // 成功
}

int main() {
    FILE *fp = fopen("trajectory.xtc", "rb");
    if (!fp) {
        perror("文件打开失败");
        return 1;
    }

    XtcHeader header;
    int ret = read_xtc_header(fp, &header);
    if (ret != 0) {
        fprintf(stderr, "头部解析失败\n");
        fclose(fp);
        return 1;
    }

    printf("XTC文件头部解析完成\n");
    printf("magic: %d\n", header.magic);
    printf("version: %d\n", header.version);
    printf("natoms: %d\n", header.natoms);

    fclose(fp);
    return 0;
}

你可以看到，这个流程其实很简单，总共也就读三个整型字段，外加一些校验。但我再强调一次，不要小看这段代码——它在实际生产环境中是第一个被执行的，如果它错了，后面的所有数据都会崩掉。