cube-compress 0.1.0

Compress and decompress Gaussian CUBE files using 24-bit float packing.

cube_compress.py

一个用于将 Gaussian CUBE 体数据文件压缩为 .cubexs，并可解压回 .cube 的小工具。核心思路是把 float32 数据压缩为 24-bit（1 位符号 + 8 位指数 + 15 位尾数），再用 gzip 进行二次压缩。

依赖

• Python 3.x
• numpy

gzip 为 Python 标准库，无需额外安装。

功能概览

• float32_to_24bit(data_array)
  将 float32 数组压缩为 24-bit（3 字节）表示。

• uint8_from_24bit(byte_array, num_values)
  将 24-bit 数据还原为 float32 数组。

• compress(input_file, output_file)
  读取 .cube 文件，压缩数据并写入 .cubexs。

• decompress(input_file, output_file)
  读取 .cubexs 文件，解压并输出 .cube。

使用示例

from cube_compress import compress, decompress, compress_cube_file

# 压缩
compress("input.cube", "output.cubexs")

# 解压
decompress("output.cubexs", "restored.cube")

安装（本地开发）

在项目根目录执行：

pip install -e .

然后即可通过 import cube_compress 使用。

文件结构说明

.cubexs 的结构为：

1. 原 .cube 的头部文本（UTF-8，逐行写入）
2. 三行元数据：
   • compressed_size=...
   • original_size=...
   • num_values=...
3. gzip 压缩后的二进制数据（24-bit 数据重排后压缩）

注意事项

• 该压缩是有损的（尾数从 23 位缩减为 15 位）。
• .cube 文件头部必须符合标准格式（前几行标题、Fermi 信息、原子数与网格信息）。