OM-File-Format 库

Open-Meteo OM-File 格式专为高效存储和分发多维环境数据而设计。 通过对数据进行分块、压缩和索引，OM-Files 能够实现云原生随机读取，同时最大限度地减小文件大小。 该格式支持类似于 NetCDF 或 HDF5 的分层数据结构。

此库以 C 语言实现该格式，并将高级 Swift 抽象直接集成到 Open-Meteo 天气 API 中。 计划未来支持 Python、TypeScript 和 Rust 的绑定。

注意： 此库正处于高度实验阶段。 虽然 Open-Meteo 多年来一直使用该格式，但此独立库于 2024 年 10 月启动，旨在提供 Python 绑定。 我们的目标是提供一个强大的 Python 库，以便通过 AWS 开放数据赞助访问 S3 上的 Open-Meteo 天气数据库。

• 分块、压缩的多维数组
• 高速整数压缩： 以高压缩率实现快速压缩速度
• 无损和有损压缩： 通过比例因子调整精度，进一步减小数据大小
• 针对云原生随机 IO 访问进行了优化： 支持 IO 合并和拆分
• 顺序文件写入： 允许流式写入到云存储； 元数据存储在文件末尾
• Sans-IO C 实现： 专为更高级别库中的异步支持和并发而设计

• 分块数据存储： OM-Files 将大型数据数组划分为单独压缩的块，并使用查找表跟踪块位置。 这允许仅读取和解压缩所需的块，非常适合气象数据集等用例，在这些用例中，用户通常查询特定区域而不是全局数据。
• 针对气象用例进行了优化： 示例： 在天气再分析中（例如，Copernicus ERA5-Land），0.1° 空间分辨率的全球数据集可能达到海量级别。 具有 3600 x 1800 像素（使用 32 位浮点数约为 25 MB）的单个时间步长，对于一年的小时数据（8760 小时）会增长到 211.5 GB。 几十年后，并且跨越数千个变量，数据集很容易达到 PB 级别。 传统的 GRIB 文件在压缩方面效率很高，但需要解压缩整个文件才能访问特定子集。 另一方面，OM-Files 通过利用小块大小（例如 3 x 3 x 120）来直接访问本地化数据（例如，单个国家或城市）。
• • 高速数据访问： OM-Files 最大限度地减少了数据传输和解压缩开销，从而能够在基于 FastPFOR 的强大压缩率下实现极快的读取速度，并使用 SIMD 指令，从而实现 GB/s 范围内的压缩率。 这为 Open-Meteo 天气 API 提供了支持，使其能够以亚毫秒级的速度交付预报，并支持大规模数据分析，而无需用户下载数百 GB 的 GRIB 文件。
• 提高压缩效率： 分块利用空间和时间数据相关性来增强压缩。 例如，天气数据在不同位置和时间显示出逐渐变化。 最佳分块维度（每个块压缩 1,000–2,000 个值，最后一个维度 >100）在压缩效率和性能之间取得了平衡。 过多的块会同时降低两者。

• 记录 Swift 函数
• 记录 C 函数
• 支持字符串属性和字符串数组
• 构建 Python 库
• 有关如何使用 Python FSSPEC 和缓存来访问 S3 上的 OM-Files 的示例
• 构建 Web 界面，使整个 Open-Meteo 天气数据库可以通过自动 Python 代码生成来访问

Swift 代码可以在 ./Swift 中找到，测试代码可以在 ./Tests 中找到

TODO：记录函数 + 示例

C 代码位于 /c 中

TODO 记录 C 函数

• 文件尾部包含根 Variable 的位置
• 每个 Variable 都有一个数据类型和有效负载。 例如，Int16 的有效负载为 2 字节的数字。 数组存储查找表位置和数组维度信息。 实际压缩的数组数据存储在文件的开头。
• 每个 Variable 都有一个名称
• 每个 Variable 都有 0...N 个变量 -> 变量类似于键值存储，其中每个值可以有 N 个子项。

Variable 可以是不同的类型

• None：不包含任何值。 用于定义组
• Scalar 或类型 Int8、Int16、Int32、Int64、Float、Double 等
• 类型为 Int8、Int16 等的 Array，带有维度、块和压缩类型信息
• 要实现的 String
• 要实现的 String Array

以下示例演示了如何将带有属性的数据编码为 OM-File 格式

示例 1：OM-File 内的普通数组

Root: Name="temperature_2m" Type=Float32-Array Dimensions=[720,1400,24] Chunks=[1,50,24]

示例 2：带有属性的数组

Root: Name="temperature_2m" Type=Float32-Array Dimensions=[720,1400,24] Chunks=[1,50,24]
|- Name="dimension_names" Type=String-Array Dimensions=[3]
|- Name="long_name" Type=String Value="Temperature 2 metres above ground"
|- Name="unit" Type=String Value="Celsius"
|- Name="height" Type=Int32 Value=2

示例 3：带有属性的多个数组

Root: Type=None
|- Name="temperature_2m" Type=Float32-Array Dimensions=[720,1400,24] Chunks=[1,50,24]
  |- Name="dimension_names" Type=String-Array Dimensions=[3]
  |- Name="long_name" Type=String Value="Temperature 2 metres above ground"
  |- Name="unit" Type=String Value="Celsius"
  |- Name="height" Type=Int32 Value=2
|- Name="relative_humidity_2m" Type=Float32-Array Dimensions=[720,1400,24] Chunks=[1,50,24]
  |- Name="dimension_names" Type=String-Array Dimensions=[3]
  |- Name="long_name" Type=String Value="Relative Humidity 2 metres above ground"
  |- Name="unit" Type=String Value="Percentage"
  |- Name="height" Type=Int32 Value=2

classDiagram
    Variable <|-- Variable
    Variable --|> Int8
    Variable --|> Int16
    Variable --|>String
    Variable --|> Array
    Trailer --|> Variable
    Variable : +String_name
    Variable : +Variable[]_children
    Variable : +Enum_data_type
    Variable : +Enum_compression_type
    Variable: +number_of_childen()
    Variable: +get_child(int n)
    Variable: +get_name()
    class Trailer {
        +version
        +root_variable
    }
    class Int8{
      +Int8 value
      +read()
    }
    class Int16{
      +Int16 value
      +read()
    }
    class String{
      +String_value
      +read()
    }
    class Array{
        +Int64[]_dimensions
        +Int64[]_chunks
      +Int64_look_up_table_offset
      +Int64_look_up_table_size
      +read(offset:Int64[],count:Int64[])
    }

旧版二进制格式

• Int16：魔数“OM”
• Int8：版本
• Int8：带有过滤器的压缩类型
• Float32：缩放因子
• Int64：dim0 dim（慢）
• Int64：dim0 dim1（快）
• Int64：块 dim0
• Int64：块 dim1
• 64 位整数数组：偏移量查找表
• Blob：每个块的数据，偏移量但查找表

新的二进制格式

• 3 字节：标头（魔数“OM”+ 版本）
• Blob：压缩数据和查找表 LUT
• Blob：二进制编码的元数据
• 24 字节：带有根变量地址的尾部

二进制表示

• 带有魔数和版本的文件标头
• 带有根变量的偏移量和大小的文件尾部
• 变量具有属性：数据类型 (8bit)、压缩类型 (8bit)、name_size (16bit)、attribute_count (32bit)
• 根据数据类型，后跟给定数据类型的有效负载
• 后跟名称作为字符串，以及每个属性的偏移量和大小
• 通常，所有压缩数据都在文件的开头，后跟所有元数据和属性（流式写入，无需向后查找！）

标头消息

尾部消息

变量消息