<a href="https://github.com/webc-site/wedb_embed/blob/main/fastalp/README.md#en"><img src="https://cdn.jsdmirror.com/gh/webc-site/svg/i18n/en.svg" height="28"></a>
<a href="https://github.com/webc-site/wedb_embed/blob/main/fastalp/README.md#zh"><img src="https://cdn.jsdmirror.com/gh/webc-site/svg/i18n/zh.svg" height="28"></a>
<a href="https://x.com/iwebcsite"><img src="https://img.shields.io/badge/Twitter-@iwebcsite-1DA1F2?logo=x&logoColor=white" height="28"></a>
<a href="https://bsky.app/profile/webc-site.bsky.social"><img src="https://img.shields.io/badge/Bluesky-@webc--site-0285FF?logo=bluesky&logoColor=white" height="28"></a>
<a href="https://crates.io/crates/fastalp"><img src="https://img.shields.io/crates/v/fastalp.svg" height="28"></a>
<a href="https://docs.rs/fastalp"><img src="https://docs.rs/fastalp/badge.svg" height="28"></a>
---
<a id="en"></a>
# fastalp : Lossless Floating-Point Compression in Pure Rust
A pure Rust implementation of adaptive lossless floating-point compression, deeply absorbing and extending the theoretical foundation of the ACM SIGMOD 2024 Best Artifact paper [ALP](https://dl.acm.org/doi/10.1145/3626717), providing high-performance unified generic interfaces for both `f64` and `f32` streams.
<p align="center">
<img src="https://fastly.jsdelivr.net/gh/webc-fs/-@sJ/iDXAaJVvppSgiJndAw_g.svg" alt="fastalp Floating-Point Compression Performance & Ratio Benchmark" width="100%">
<br>
<sub><b>Benchmark Environment</b>: CPU: Apple M2 Max (12 Cores) ｜ OS: macOS 26.5.1 ｜ Toolchain: Rust 1.98.0 / Clang (-O3)</sub>
</p>
---
- [Theoretical Background & Official Paper](#theoretical-background-official-paper)
- [Features](#features)
- [Key Algorithmic & Architectural Breakthroughs over C++ ALP](#key-algorithmic-architectural-breakthroughs-over-c-alp)
- [Usage](#usage)
- [Installation](#installation)
- [Basic Compression and Decompression](#basic-compression-and-decompression)
- [In-Place Buffer Reuse](#in-place-buffer-reuse)
- [Zero-Allocation Slice Decompression & O(1) Count](#zero-allocation-slice-decompression-o1-count)
- [Stateful Encoder & Parameter Caching](#stateful-encoder-parameter-caching)
- [Single-Precision Floating-Point Processing](#single-precision-floating-point-processing)
- [High-Performance Engineering Tips & Best Practices](#high-performance-engineering-tips-best-practices)
- [Enable Parameter Caching for Streaming Pipelines](#enable-parameter-caching-for-streaming-pipelines)
- [In-Place Buffer Reuse to Eliminate Allocation Jitter](#in-place-buffer-reuse-to-eliminate-allocation-jitter)
- [Low-Entropy and Monotonic Waveform Acceleration](#low-entropy-and-monotonic-waveform-acceleration)
- [Architecture & Design](#architecture-design)
- [Compression Pipeline](#compression-pipeline)
- [Decompression Pipeline](#decompression-pipeline)
- [Technology Stack](#technology-stack)
- [Project Architecture](#project-architecture)
- [Performance & Comparative Benchmarks](#performance-comparative-benchmarks)
- [Test Environment and Compiler Setup](#test-environment-and-compiler-setup)
- [Cross-Algorithm Benchmark Comparison](#cross-algorithm-benchmark-comparison)
- [Pure Encoding & Streaming Cache Throughput Deep Dive](#pure-encoding-streaming-cache-throughput-deep-dive)
- [Industrial Scenario Micro-Benchmarks](#industrial-scenario-micro-benchmarks)
- [C++ ALP Benchmark Methodology & Calibration](#c-alp-benchmark-methodology-calibration)
- [Comprehensive Dataset Coverage & Sources](#comprehensive-dataset-coverage-sources)
- [Architectural Evolution & Novel Optimizations](#architectural-evolution-novel-optimizations)
- [Foundations Inherited from Original ALP](#foundations-inherited-from-original-alp)
- [Proprietary Algorithmic & Performance Breakthroughs](#proprietary-algorithmic-performance-breakthroughs)
- [C-Compatible API & Cross-Language Integration](#c-compatible-api-cross-language-integration)
- [Buffer Capacity Estimation & Element Extraction](#buffer-capacity-estimation-element-extraction)
- [Thread-Local Streaming Interface](#thread-local-streaming-interface)
- [Explicit Instance Handle Interface](#explicit-instance-handle-interface)
- [Changelog](#changelog)
- [v0.1.40](#v0140)
- [v0.1.38](#v0138)
- [v0.1.37](#v0137)
- [v0.1.36](#v0136)
- [v0.1.35](#v0135)
- [v0.1.34](#v0134)
- [v0.1.33](#v0133)
- [v0.1.32](#v0132)
- [v0.1.31](#v0131)
- [v0.1.30](#v0130)
## Theoretical Background & Official Paper
ALP (Adaptive Lossless Floating-Point Compression) was introduced at **ACM SIGMOD 2024** by the database research team at CWI (Azim Afroozeh, Leonardo Kuffó, Peter Boncz) and won the **SIGMOD 2024 Best Artifact Award**. It is integrated into modern columnar database engines such as **DuckDB**, **FastLanes**, and **KuzuDB**:
- **Official Paper**: _ALP: Adaptive Lossless Floating-Point Compression_, ACM SIGMOD 2024 · [DOI: 10.1145/3626717](https://dl.acm.org/doi/10.1145/3626717)
- **Official C++ Implementation**: [github.com/cwida/ALP](https://github.com/cwida/ALP)
- **Core Theoretical Insight**: Most floating-point values in real-world time series (IoT, finance, telemetry) originate from decimal readings with fixed decimal places. By adaptively projecting floats onto integers, combined with Frame-of-Reference (FOR) and SIMD bitpacking, ALP delivers compression ratios and speeds far exceeding general-purpose compressors.
`fastalp` fully retains and rigorously validates the official ALP foundations while re-engineering the encoding/decoding execution pipelines to overcome limitations in dynamic range, multiplication truncation errors, self-describing framing, and unpruned sampling overhead.
---
## Features
In IoT sensing, quantitative finance, GPS telemetry, and observability monitoring, floating-point measurements naturally originate from decimal scales.<br>
Due to the IEEE 754 layout of exponents and mantissas, general-purpose byte compressors and integer bitpackers often perform poorly on raw floating-point streams.
`fastalp` delivers lossless compression tailored to decimal float patterns:
- **Adaptive Parameter Estimation**:<br>
Samples input streams and evaluates a cost model to discover optimal decimal scaling factors `(exp, fac)` that minimize combined bit-width and exception overhead.
- **Lossless Integer Mapping**:<br>
Multiplies floats by decimal factors to project them into integers, validating reversibility via inverse scaling to ensure bit-exact fidelity (`a.to_bits() == b.to_bits()`).
- **Frame-of-Reference & Dense Bitpacking**:<br>
Subtracts the frame-wide minimum value to shift integers into non-negative offsets, packed at dynamic bit-widths (1 to 64 bits).
- **Isolated Exception Stream**:<br>
Special floats (`NaN`, `+Inf`, `-Inf`, `-0.0`) and values that cannot be encoded losslessly are recorded separately with their original IEEE 754 bit representations.
- **Strict Bit-Exact Roundtripping**:<br>
Guarantees decoded floats match the original binary representation bit-for-bit.
- **Unified Generic Support**:<br>
Zero-cost abstractions for both `f64` and `f32` streams, handling high-precision scientific computing and lightweight sensor telemetry alike.
- **Zero-Allocation APIs**:<br>
Provides `_into` function variants to write directly into caller-managed, preallocated buffers without runtime heap allocations.
### Key Algorithmic & Architectural Breakthroughs over C++ ALP
- **Adaptive Delta-ALP**:<br>
First-order differences and prefix-sum recurrence with a 16-sample early-exit filter to narrow dynamic bit-widths by 15% ~ 38%.
- **Decimal Exact Division Reconstruction (`use_div`)**:<br>
Eliminates spurious exception points caused by IEEE 754 binary truncation in float multiplication, reducing footprint by 20% ~ 38%.
- **Intelligent Outlier Pruning for Sparse Constants (0-bit Encoding)**:<br>
Isolates sparse impulse spikes to the exception dictionary, allowing base streams to drop to 0-bit width and delivering 150x ~ 744x compression ratios on constant-heavy series.
- **Previous-Value Exception Backfilling**:<br>
Backfills exception slots with preceding integers to prevent artificial gradient spikes in difference encoding.
- **Hardware-Native Round-Ties-Even (`round_ties_even`)**:<br>
Replaces the legacy IEEE 754 magic number offset (`0x0018000000000000`, limited to $[-2^{51}, 2^{51}]$) with direct hardware round-to-nearest-even instructions (x86 `ROUNDSD` / ARM64 `FRINTN`), guaranteeing full-range fidelity.
- **2-bit Self-Describing Headers & Arbitrary Array Slicing**:<br>
Compact 3-byte headers for full 1024-element blocks and 1-byte headers for raw fallbacks, automatically scaling to 32-bit counts for large slices.
- **12.5% Exception Ceiling & RAW Fallback**:<br>
Enforces a 12.5% exception limit to guard against negative compression, reverting gracefully to raw byte storage on incompressible random data.
- **Single-Comparison Fast Path**:<br>
Detects uniform arrays in a single comparison cycle, emitting 1024 uniform items in 11 bytes within 1 clock cycle (744x ratio).
- **Three-Stage Microarchitectural Sampling Pruning**:<br>
Replaces unpruned parameter searches with a 3-tier cascade (pure decimal early return, 4/16-sample short-circuiting, and non-decimal abort), boosting end-to-end compression throughput to **3.7 GB/s (4.6x faster than C++ ALP)**; pure encoding kernel throughput reaches **6.0 GB/s (1.10x faster than C++ ALP)**; streaming throughput reaches **15~24+ GB/s** with cached parameters.
## Usage
### Installation
```bash
cargo add fastalp
```
### Basic Compression and Decompression
```rust
use fastalp::{compress, decompress, Result};
fn main() -> Result<()> {
let sensor_data = vec![20.5, 20.6, 20.8, 21.0, 20.9, 21.2];
// Compress floating-point slice into byte buffer (generic for f64 / f32)
let compressed = compress(&sensor_data);
// Decompress byte buffer back to exact f64 slice
let decompressed: Vec<f64> = decompress(&compressed)?;
assert_eq!(decompressed, sensor_data);
Ok(())
}
```
### In-Place Buffer Reuse
```rust
use fastalp::{compress_into, decompress_into, Result};
fn main() -> Result<()> {
let batch = vec![100.12, 100.15, 100.18, 100.22];
let mut compressed_buf = Vec::new();
compress_into(&batch, &mut compressed_buf);
let mut restored = Vec::new();
decompress_into(&compressed_buf, &mut restored)?;
assert_eq!(restored, batch);
Ok(())
}
```
### Zero-Allocation Slice Decompression & O(1) Count
For mission-critical low-latency scenarios such as database query engines, embedded systems, or object-pool architectures, `fastalp` provides O(1) header element counting and in-place slice decompression without any heap allocation:
```rust
use fastalp::{
compress, count, decompress_into_slice, max_compressed_size, Result,
};
fn main() -> Result<()> {
let sensor_data = [20.5, 20.6, 20.8, 21.0, 20.9, 21.2];
let compressed = compress(&sensor_data);
// 1. O(1) zero-heap extraction of element count from compact header
let num_items = count(&compressed)?;
assert_eq!(num_items, 6);
// 2. Compute maximum possible compressed buffer size in bytes for preallocation
let max_cap = max_compressed_size::<f64>(num_items);
assert!(compressed.len() <= max_cap);
// 3. Decompress directly into a stack array or existing slice with zero heap allocations
let mut dst = [0.0f64; 6];
let written = decompress_into_slice(&compressed, &mut dst)?;
assert_eq!(written, 6);
assert_eq!(&dst[..], &sensor_data[..]);
Ok(())
}
```
### Stateful Encoder & Parameter Caching
For streaming time-series pipelines, use `Encoder` to cache model parameters across consecutive chunks and reuse buffers:
```rust
use fastalp::{decompress, Encoder, Result};
fn main() -> Result<()> {
let mut encoder = Encoder::<f64>::with_capacity(1024);
let chunk1: Vec<f64> = (0..1024).map(|i| 25.0 + (i as f64) * 0.25).collect();
let chunk2: Vec<f64> = (1024..2048).map(|i| 25.0 + (i as f64) * 0.25).collect();
let mut compressed = Vec::new();
// First chunk: detects and caches optimal parameters
encoder.compress_into(&chunk1, &mut compressed);
// Second chunk: cache hit, skips full parameter search for ultra-high throughput
compressed.clear();
encoder.compress_into(&chunk2, &mut compressed);
let restored: Vec<f64> = decompress(&compressed)?;
assert_eq!(restored, chunk2);
// Reset when switching to a different data stream
encoder.reset();
Ok(())
}
```
### Single-Precision Floating-Point Processing
```rust
use fastalp::{compress, decompress, Result};
fn main() -> Result<()> {
let coordinates = vec![116.4074f32, 39.9042f32, 121.4737f32, 31.2304f32];
let compressed = compress(&coordinates);
let decompressed: Vec<f32> = decompress(&compressed)?;
assert_eq!(decompressed, coordinates);
Ok(())
}
```
---
### High-Performance Engineering Tips & Best Practices
#### Enable Parameter Caching for Streaming Pipelines
In time-series databases and metrics ingestion engines, the physical scale and precision of consecutive blocks on the same metric (e.g., temperature sensor, trade prices) remain highly uniform.<br>
While `compress` performs a 32-sample exploration on every invocation, reusing a stateful `Encoder` instance hits cached model parameters across subsequent blocks, skipping exploration entirely and elevating throughput to **15~24+ GB/s**:
```rust
use fastalp::Encoder;
// Maintain an Encoder per metric column or ingestion stream
let mut encoder = Encoder::<f64>::with_capacity(1024);
let mut buf = Vec::with_capacity(1024 * 8);
for chunk in incoming_stream {
buf.clear();
// Hits parameter cache, executing pure kernel at 15~24+ GB/s
encoder.compress_into(&chunk, &mut buf);
write_to_storage(&buf);
}
```
#### In-Place Buffer Reuse to Eliminate Allocation Jitter
Frequent allocations and deallocations in hot loops cause heap fragmentation and lock contention. Use `_into` function variants to write directly into long-lived memory buffers:
```rust
use fastalp::{compress_into, decompress_into};
let mut comp_buf = Vec::with_capacity(8192);
let mut decomp_buf = Vec::with_capacity(1024);
// Zero heap allocations inside the loop
for batch in batches {
comp_buf.clear();
compress_into(&batch, &mut comp_buf);
decomp_buf.clear();
decompress_into(&comp_buf, &mut decomp_buf)?;
}
```
#### Low-Entropy and Monotonic Waveform Acceleration
- **Constant Streams & Heartbeats**: On standby sensors or heartbeat streams, `fastalp` verifies equality in 1 CPU cycle, encoding 1024 items into 11 bytes (**744x ratio**).
- **Linear Ramps & Physical Steps**: For monotonic waveforms (industrial PID, hydrological levels), `fastalp` automatically engages first-order Delta difference encoding to eliminate large span offsets, achieving **430x+** compression.
## Architecture & Design
`fastalp` executes compression and decompression through modular pipeline stages:
```mermaid
graph TD
Input["Input Floating-Point Slice (&[f64] / &[f32])"] --> Sampler["Parameter Sampler<br/>Determine optimal (exp, fac) via cost model"]
Sampler --> Encoder["Lossless Integer Conversion<br/>Scaled rounding & bit-exact validation"]
Encoder --> Split{"Losslessly Encodable?"}
Split -- Yes --> IntStream["FOR Base Subtraction<br/>Calculate non-negative offsets"]
Split -- No --> ExcStream["Exception Recording<br/>Store index positions & raw IEEE 754 bits"]
IntStream --> Bitpacker["Dense Bitpacking<br/>Pack at dynamic bit-width"]
ExcStream --> Frame["Binary Frame Assembly<br/>Header + Base + Bitstream + Exception List"]
Bitpacker --> Frame
Frame --> Output["Compressed Payload (Vec<u8>)"]
```
### Compression Pipeline
- **Equi-value Detection & Fallback (`encoder.rs`)**:<br>
Fast-path detection for constant sequences. Direct emission of compact headers when identical values are observed. Automatically falls back to raw 1-byte header storage if data entropy prevents effective decimal reduction.
- **Sampling & Cost-Model Optimization (`sampler.rs`)**:<br>
Evaluates up to 32 evenly distributed sample points across `(exp, fac)` parameter spaces, minimizing total encoded bit-width and penalty-weighted exceptions.
- **Lossless Conversion & Validation (`sampler.rs`, `float.rs`)**:<br>
Multiplies floats by $10^{\text{exp}} \times 10^{-\text{fac}}$, rounds to nearest integer via floating-point bias constants, and validates bit-exact equality through inverse scaling.
- **Base Subtraction & Bitpacking (`bitpack/pack.rs`, `encoder.rs`)**:<br>
Computes minimum valid integer as frame base (FOR mode), derives dynamic bit-widths, and densely packs offsets into bytes using a 128-bit sliding accumulator.
- **Exception Stream Serialization (`encoder.rs`)**:<br>
Unencodable float positions and raw IEEE 754 bit representations are recorded in a compact trailing exception table.
### Decompression Pipeline
- **Self-Describing Header Parsing (`header.rs`, `decoder.rs`)**:<br>
Parses the 2-bit length flag, extracts metadata parameters `(exp, fac, bit_width)`, and recovers the frame base value.
- **Bitstream Unpacking (`bitpack/unpack.rs`)**:<br>
Employs pure SIMD register pipelines for 8/16/32/64 bit widths to avoid gather and memory lookup latency, combined with stack-resident LUTs for narrow widths (1/2/4 bit).
- **Exception Patching (`decoder.rs`)**:<br>
Applies trailing exceptions at specified index offsets, restoring non-finite and out-of-range floats bit-for-bit.
---
## Technology Stack
- **Language**: Rust Edition 2024
- **Error Handling**: `thiserror`
- **Testing & Benchmarks**: `anyhow`, `aok`, `fastrand`
---
## Project Architecture
```
fastalp/
├── Cargo.toml # Crate manifest and dependency configuration
├── README.md # Generated multilingual documentation
├── README.mdt # Multilingual documentation template
├── readme/ # Documentation source files
│ ├── en/ # English document modules (intro, usage, architecture, bench, evolution, capi, log)
│ └── zh/ # Chinese document modules (intro, usage, architecture, bench, evolution, capi, log)
├── src/ # Library source code
│ ├── bitpack/ # Modular bit-level packing and unpacking
│ │ ├── mod.rs # Module facade and re-exports
│ │ ├── pack.rs # Dense bitpacking with match_pack_23 dispatch
│ │ └── unpack/ # Decoupled bit-unpacking engine
│ │ ├── mod.rs # Top-level dispatch and safe facades
│ │ ├── consumer.rs # AlpConsumer abstraction (FOR/Delta prefix-sum/raw writes)
│ │ ├── decoder.rs # AlpDecoder float reconstruction (Mul/Div/RD/Dict)
│ │ └── kernel.rs # 64-way monomorphized unpacking subkernels
│ ├── capi.rs # Optional C-compatible FFI bindings and handle management
│ ├── constants.rs # Precomputed static power tables and format constants
│ ├── decoder/ # Generic decompression pipeline & decimal division reconstruction
│ │ ├── mod.rs # Decompression facade and mode dispatch
│ │ ├── standard.rs # Standard FOR reconstruction decompression
│ │ └── delta.rs # Delta first-order difference decoding
│ ├── delta/ # First-order difference cost estimation and prefix sums
│ │ └── mod.rs
│ ├── encoder/ # Generic compression pipeline and state caching
│ │ ├── mod.rs # Top-level entry points and compression facade
│ │ ├── state.rs # Stateful Encoder struct and working buffer reuse
│ │ ├── engine.rs # Core compression engine and 3-stage validation
│ │ ├── kernel.rs # 4-way unrolled branchless vectorized encoding kernel
│ │ ├── outlier.rs # FOR-mode outlier pruning algorithm
│ │ ├── exception.rs# Exception layout and compact serialization
│ │ ├── standard.rs # Standard FOR frame assembly
│ │ └── delta.rs # Delta difference frame assembly
│ ├── error.rs # Error definitions and Result type aliases
│ ├── float/ # AlpFloat trait and generic lossless transformations
│ │ ├── mod.rs # AlpFloat trait and lookup table builders
│ │ ├── f32.rs # Single-precision f32 multiply/divide implementations
│ │ └── f64.rs # Double-precision f64 multiply/divide implementations
│ ├── header.rs # Self-describing header with 2-bit length tags
│ ├── lib.rs # Crate root and public exports
│ ├── macros.rs # Global unrolling, array construction, and bit-width dispatch macros
│ ├── params.rs # Compact bitfield parameters and bit-width calculators
│ └── sampler.rs # Parameter sampling and validation
├── test.sh # Test execution script
└── tests/ # Integration and stress testing
├── test_alp_dataset.rs # ALP paper 31 real-world datasets roundtrip & ratio tests
├── test_delta.rs # Specialized delta difference tests & edge cases
└── test_roundtrip.rs # Comprehensive lossless roundtrip & boundary tests
```
## Performance & Comparative Benchmarks
### Test Environment and Compiler Setup
All benchmarks were evaluated on identical hardware under equivalent conditions:
- **Processor**: Apple M2 Max (12 cores: 8 Performance @ 3.68 GHz + 4 Efficiency @ 2.42 GHz, ARMv8.6-A NEON)<br>
- **Operating System**: macOS Sequoia 26.5.1 (Darwin Kernel Version 25.5.0 arm64)<br>
- **Rust Toolchain**: `rustc 1.98.0 / nightly` (flags: `opt-level = 3`, `lto = "fat"`, `codegen-units = 1`)<br>
- **C++ Toolchain**: Homebrew LLVM Clang 22.1.8 (`-O3 -std=c++17 -DNDEBUG -march=native`) / CMake 4.4.2<br>
- **Memory Allocator**: `mimalloc 0.1.52`<br>
- **Benchmark Suite**: Rust `divan 0.1.20` micro-benchmark harness vs C++ `std::chrono::high_resolution_clock` (median steady-state sampling)
### Cross-Algorithm Benchmark Comparison
Tested against standard floating-point and time-series codecs across all 37 datasets on identical hardware (measured via Geometric Mean, fully consistent with the visual infographic):
| Codec | Category | Decomp Throughput (GeoMean) | vs C++ Decomp | End-to-End Comp (GeoMean) | Pure Kernel (GeoMean) | vs C++ Pure Kernel | GeoMean Ratio |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **fastalp (Rust)** | Specialized Float | **25.3 GB/s** | **1.31x vs C++** | **2.1 GB/s (2.58x faster)** | **7.8 GB/s** | **1.46x vs C++** | **9.50x** |
| **C++ ALP** (Paper Reference) | Specialized Float | **19.3 GB/s** | Baseline (1.0x) | **0.8 GB/s** | **5.4 GB/s** | Baseline (1.0x) | **5.93x** |
| Pcodec (pco) | Specialized Float | **1.8 GB/s** | 0.09x (10.6x slower) | **0.2 GB/s** | — | — | **8.81x** |
| Zstd (level 3) | General Byte | **1.4 GB/s** | 0.07x (13.6x slower) | **0.5 GB/s** | — | — | **6.07x** |
| LZ4 (lz4_flex) | General Byte | **5.0 GB/s** | 0.26x (3.9x slower) | **2.0 GB/s** | — | — | **3.89x** |
| Snappy (snap) | General Byte | **4.6 GB/s** | 0.24x (4.2x slower) | **2.5 GB/s** | — | — | **3.05x** |
| Chimp128 (ts+val) | Specialized Float | **1.0 GB/s** | 0.05x (19.7x slower) | **1.3 GB/s** | — | — | **5.05x** |
| Gorilla (ts+val) | Specialized Float | **1.2 GB/s** | 0.06x (16.2x slower) | **1.9 GB/s** | — | — | **4.41x** |
---
### Pure Encoding & Streaming Cache Throughput Deep Dive
In floating-point and time-series compression benchmarks, advanced modes offer specialized throughput profiles:
- **Pure Encoding (No Sampling)**:<br>
As measured in the original C++ ALP paper benchmark (`ALP/publication/source_code/bench_speed/bench_alp_encode.cpp`), parameters are discovered outside the timed loop, evaluating only the speed of float-to-integer mapping and bitpacking.
- **Stateful Streaming Cache**:<br>
For stationary continuous time series, reuses derived model parameters across 1024-element blocks, skipping repeated sampling.
Comprehensive 37-dataset side-by-side evaluation on identical hardware (providing both Geometric Mean and Arithmetic Mean calibrations):
| Benchmark Metric / Operational Mode | fastalp (Rust) | C++ ALP (Reference) | Speedup vs C++ | Measurement Methodology & Scope |
| :--- | :---: | :---: | :---: | :--- |
| **Benchmark Decompression Throughput** | GeoMean **25.3 GB/s**<br>ArithMean **30.72 GB/s** | GeoMean 19.3 GB/s<br>ArithMean 19.69 GB/s | GeoMean **1.31x vs C++**<br>ArithMean **1.56x vs C++** | Evaluated across all 37 datasets with SIMD fusion and wide unaligned loads |
| **Pure Encoding Throughput (No Sampling)** | GeoMean **7.8 GB/s**<br>ArithMean **9.01 GB/s** | GeoMean 5.4 GB/s<br>ArithMean 5.74 GB/s | GeoMean **1.46x vs C++**<br>ArithMean **1.57x vs C++** | Bypasses parameter sampling; tests pure float-to-int transform and dense bitpacking (Paper benchmark scope) |
| **End-to-End Compression (w/ Sampling)** | GeoMean **2.1 GB/s**<br>ArithMean **2.93 GB/s** | GeoMean 0.8 GB/s<br>ArithMean 0.80 GB/s | GeoMean **2.58x vs C++**<br>ArithMean **3.64x vs C++** | Real-world ingestion pipeline; 3-tier cascade pruning eliminates exhaustive search overhead |
| **Stateful Streaming Cache (Parameter Reuse)** | **15 ~ 24+ GB/s** | — | **Steady-State Stream** | Caches derived `(exp, fac)` models across consecutive 1024-element blocks via `Encoder` |
| **Compression Ratio** | GeoMean **9.50x**<br>Total Bytes **3.69x** | GeoMean 5.93x<br>Total Bytes 2.89x | GeoMean **+60% higher**<br>Total Bytes **+28% higher** | Evaluated across all 37 datasets; Delta-ALP and division reconstruction significantly reduce dynamic bit-widths |
---
### Industrial Scenario Micro-Benchmarks
| Business Scenario Slice | Dataset Scale | fastalp<br>(Decomp / Comp / Ratio) | C++ ALP<br>(Decomp / Comp / Ratio) | Pcodec<br>(Decomp / Comp / Ratio) | Baseline Codec<br>(Decomp / Comp / Ratio) |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Decimal Environmental & Hydrology IoT** | 11 sets (11,264 pts) | **22.9 GB/s**<br>**3.1 GB/s**<br>**3.45x** | 18.8 GB/s<br>0.8 GB/s<br>3.16x | 1.65 GB/s<br>0.2 GB/s<br>3.30x | LZ4:<br>7.4 GB/s<br>1.8 GB/s<br>1.78x |
| **Quantitative Trading & Asset Quotes** | 7 sets (7,168 pts) | **23.5 GB/s**<br>**3.2 GB/s**<br>**4.76x** | 20.5 GB/s<br>0.8 GB/s<br>3.85x | 1.56 GB/s<br>0.2 GB/s<br>4.17x | Snappy:<br>14.0 GB/s<br>3.9 GB/s<br>2.22x |
| **Geospatial & GPS Trajectory Tracking** | 5 sets (5,120 pts) | **19.0 GB/s**<br>**2.2 GB/s**<br>**2.17x** | 17.5 GB/s<br>0.7 GB/s<br>1.73x | 2.01 GB/s<br>0.2 GB/s<br>2.27x | Snappy:<br>31.9 GB/s<br>8.2 GB/s<br>1.40x |
| **Healthcare Claims & Pharma Pricing** | 5 sets (5,120 pts) | **22.7 GB/s**<br>**2.0 GB/s**<br>**2.10x** | 20.1 GB/s<br>0.8 GB/s<br>2.19x | 2.04 GB/s<br>0.2 GB/s<br>2.16x | Zstd:<br>1.0 GB/s<br>0.4 GB/s<br>1.99x |
| **Public Demographics & Civic Economics** | 6 sets (6,144 pts) | **64.9 GB/s**<br>**2.5 GB/s**<br>**10.66x** | 21.5 GB/s<br>0.7 GB/s<br>4.64x | 2.70 GB/s<br>0.3 GB/s<br>10.07x | Zstd:<br>5.9 GB/s<br>2.1 GB/s<br>13.16x |
| **Monotonic Ramp, Storage & Steady Waves** | 3 sets (3,072 pts) | **40.5 GB/s**<br>**5.5 GB/s**<br>**27.40x** | 20.5 GB/s<br>0.9 GB/s<br>2.90x | 2.50 GB/s<br>0.3 GB/s<br>21.04x | Zstd:<br>2.1 GB/s<br>1.2 GB/s<br>10.21x |
### C++ ALP Benchmark Methodology & Calibration
- **Official C++ ALP Benchmark Code**: [cwida/ALP (bench_alp_encode.cpp)](https://github.com/cwida/ALP/blob/main/publication/source_code/bench_speed/bench_alp_encode.cpp)
- **Evaluation Fork Repository**: [github.com/x-at-01/ALP](https://github.com/x-at-01/ALP) (Evaluation branches: [feat/integrate-fastalp-benchmark](https://github.com/x-at-01/ALP/tree/feat/integrate-fastalp-benchmark) / [bench/self-eval](https://github.com/x-at-01/ALP/tree/bench/self-eval))
- **Unified Methodology Notes**:
- **100% Unaltered Core Logic**: The fork maintains the original core algorithm (`include/` directory) without modification, preserving the authors' SIMD and inverse mapping logic.
- **End-to-End Pipeline vs Pure Kernel Throughput**:
- **Pure Kernel (Paper methodology, C++ 5.4 GB/s vs fastalp 7.8 GB/s)**:<br>
C++ ALP official benchmark calls model initialization outside the measurement loop, assuming optimal exponents and factors are known beforehand, achieving **5.4 GB/s** geometric mean throughput (arithmetic mean 5.74 GB/s); under the exact same benchmark conditions, fastalp achieves **7.8 GB/s** pure encoding throughput (**1.46x speedup vs C++**; arithmetic mean **9.01 GB/s**, **1.57x vs C++**).
- **End-to-End Compression (Real-world metric, C++ 0.8 GB/s vs fastalp 2.1 GB/s)**:<br>
In real-world time-series ingestion, incoming blocks require adaptive parameter sampling. When sampling is measured within the timing loop, C++ ALP unpruned exhaustive search accounts for >80% of execution time, yielding an end-to-end throughput of **0.8 GB/s** (arithmetic mean 0.80 GB/s); fastalp performs complete end-to-end compression including adaptive parameter sampling from scratch, achieving **2.1 GB/s** geometric mean end-to-end throughput (**2.58x faster than C++ ALP**; arithmetic mean **2.93 GB/s**, **3.64x vs C++**); when hitting stateful parameter cache, pure kernel throughput reaches **15 ~ 24+ GB/s**.
- **Decompression Throughput (GeoMean 25.3 GB/s vs 19.3 GB/s)**:<br>
Utilizing branchless SIMD register pipelines and L1D stack LUTs, fastalp attains **25.3 GB/s** geometric mean decompression throughput, outperforming C++ ALP **19.3 GB/s** (**1.31x faster**; arithmetic mean **30.72 GB/s** vs **19.69 GB/s**, **1.56x faster**).
- **Full 37 Dataset Coverage & 100% Reproducibility**:
- Supplements 6 industrial scenarios into the fork repository, enabling full 37-dataset evaluation (31 paper datasets + 6 industrial benchmarks).
- Anyone can clone [x-at-01/ALP](https://github.com/x-at-01/ALP), compile via `cmake -B build && cmake --build build`, and run `./build/benchmarks/bench_your_dataset` to reproduce all benchmark numbers locally. Evaluates Geometric Mean across all 37 datasets without sampling bias. fastalp achieves an overall geometric mean compression ratio of **9.50x** (compared to C++ ALP **5.93x**).
### Comprehensive Dataset Coverage & Sources
Evaluated on all 31 public datasets from the original ALP paper plus 6 representative industrial benchmarks across 6 domains:
- **IoT & Environmental Sensors (11 datasets)**: `neon_pm10_dust`, `neon_dew_point_temp`, `neon_air_pressure`, `neon_wind_dir`, `neon_bio_temp_c`, `basel_temp_f`, `basel_wind_f`, `city_temperature_f`, `air_sensor_f`, `arade4`, `scene_sensor`.
- **Quantitative Finance & Trading (7 datasets)**: `stocks_usa_c`, `stocks_de`, `stocks_uk`, `bitcoin_f`, `bitcoin_transactions_f`, `food_prices`, `scene_finance`.
- **Geographic Mapping & Trajectories (5 datasets)**: `poi_lat`, `poi_lon`, `bird_migration_f`, `nyc29`, `scene_geo`.
- **Healthcare & Public Assistance (5 datasets)**: `medicare1`, `medicare9`, `cms1`, `cms9`, `cms25`.
- **Government & Macroeconomics (6 datasets)**: `gov10`, `gov26`, `gov30`, `gov31`, `gov40`, `scene_macro`.
- **Hardware Storage & Physical Waveforms (3 datasets)**: `ssd_hdd_benchmarks_f`, `scene_ramp`, `scene_steady`.
## Architectural Evolution & Novel Optimizations
`fastalp` is an engineered reimagining of the ALP paradigm for modern superscalar architectures and columnar time-series storage engines.
### Foundations Inherited from Original ALP
- **Two-Level Adaptive Sampling**:
Derives optimal decimal scaling parameters `(exp, fac)` that minimize combined bit-width and exception penalties through two-phase coarse and fine sampling.
- **Hardware-Native Round-Ties-Even (Upgraded from Magic Number)**:
Original ALP utilized IEEE 754 bias constants (`0x0018000000000000` / `12582912.0`) inside floating-point units. `fastalp` investigates its $[-2^{51}, 2^{51}]$ range boundary limitations and upgrades it to hardware-native round-to-nearest-even instructions (x86 `ROUNDSD` / ARM64 `FRINTN`), eliminating range overflow risks while maintaining branchless latency.
- **FOR Frame-of-Reference Subtraction**:
Subtracts the frame-wide minimum value to shift signed ranges into compact non-negative domains, reducing encoded bit-widths.
- **Stateful Encoder & Parameter Caching**:
Enables caching of derived `(exp, fac)` models across consecutive 1024-element blocks in continuous streams, boosting steady-state throughput from `4-5 GB/s` to `15-24+ GB/s`.
---
### Proprietary Algorithmic & Performance Breakthroughs
- **Adaptive Delta-ALP**:
Smooth sensor physical waveforms often have large absolute spans but tiny step differences. `fastalp` implements first-order difference encoding with 16-sample mathematical short-circuit pruning, narrowing bit-widths by 15% ~ 38%.
- **Decimal Exact Division Reconstruction (`use_div`)**:
Eliminates spurious exception inflation caused by IEEE 754 binary truncation in multiplication (e.g. `* 0.1`). Reduces stored byte volume by 20% ~ 38%.
- **Intelligent Outlier Pruning & 0-bit Sparse Encoding**:
For datasets where 99% of values are constant with rare isolated pulses, `fastalp` strips outliers into the exception dictionary, allowing the main bitstream to drop to 0-bit. Delivers compression ratios exceeding 150x ~ 744x.
- **Exception Previous-Value Backfill**:
Backfills exceptions with previous integer values to prevent artificial gradient steps that corrupt delta difference bit-widths.
- **2-bit Self-Describing Headers & Arbitrary Length Support**:
Employs a 2-bit length tag: standard 1024-element frames require only 3 bytes of header, while RAW fallback frames require 1 byte. Automatically scales to 32-bit offsets for arrays exceeding 65,535 elements.
- **12.5% Exception Bound & Single-Byte RAW Fallback**:
Guarantees zero negative compression inflation on high-entropy data by falling back to a 1-byte header RAW stream whenever exceptions exceed 12.5% or encoded bytes exceed raw size.
- **Single-Comparison Fast Path for Equi-Value Sequences**:
Checks `slice[1] == slice[0]` on block entry; non-constant streams exit in 1 CPU cycle, while constant sequences encode 1024 elements into 11 bytes (744x ratio).
- **Three-Stage Microarchitectural Pruning Pipeline**:
Replaces unpruned parameter searches with a 3-tier cascade (pure decimal early return, 4/16-sample short-circuiting, and non-decimal abort), boosting end-to-end compression throughput from 0.80 GB/s to **3.7 GB/s** (4.6x geometric mean speedup, up to 7.0x in specific datasets); pure encoding kernel throughput reaches **6.0 GB/s (1.10x faster than C++ ALP)**; streaming throughput reaches **15~24+ GB/s** with cached parameters.
- **Pure Register SIMD Decompression**:
Vectorizes common bit-widths (8, 16, 32, 64) into branchless register pipelines, achieving **27.0 GB/s** geometric mean decompression throughput (surpassing C++ ALP's 20.0 GB/s, 1.35x faster).
- **256-Entry L1D Stack-Allocated Lookup Tables**:
Eliminates costly division latency by maintaining stack-resident tables that fit entirely in L1D cache.
- **Fused 8-Way Register-Level Delta Bitpacker**:
Merges difference calculation, base subtraction, and bitpacking into a unified single-pass 128-bit register pipeline, eliminating intermediate memory roundtrips.
- **Mathematical Short-Circuit Delta Filter**:
Proves mathematically that if the first 16 samples' delta range exceeds the FOR span, full delta encoding cannot be optimal, avoiding redundant scans for 90% of irregular series.
- **Branchless 4-Way Unrolled Encoding Loop**:
Unrolls core scalar loops into 4-way parallel ALU streams, reaching **4.4~6.8 GB/s** encoding speeds.
- **Zero-Allocation Streaming Pipeline**:
Provides `compress_into` and `decompress_into` interfaces, allowing applications to reuse buffers without GC or heap allocation churn.
- **Zero-Cost Generic Trait Abstraction**:
Unifies `f64` and `f32` operations under `AlpFloat` with precomputed static power tables and compile-time inlining.
- **Compile-Time Const-Generic 64-Way 8-Element Periodic Bit-Unpacking**:
Eliminates 128-bit variable-shift instruction bloat and register spills. Based on the mathematical invariant: for any $BW \in [1, 64]$, every 8 elements span exactly $BW$ bytes ($8 \times BW / 8 = BW$). Monomorphized across all 64 bit-widths: small widths (1, 2, 4) unroll via L1D tables; regular widths (8, 16, 32, 64) read native integers directly; and widths $BW \le 56$ fold all shifts into compile-time immediate constants within single 64-bit integer loads. Boosts decompression to **28.1+ GB/s**, reaching **47 ~ 91 GB/s** on smooth/regular sequences.
- **Zero-Copy 1024-Block Streaming ALP-RD Real Doubles Decoder**:
Eliminates micro-batch chunking and double intermediate buffering in Real Doubles mode. Stream-unpacks `right_parts` (high-entropy mantissa) directly into raw destination pointer memory, unpacks 1-3 bit dictionary indices into an 8KB stack buffer, and fuses them via in-place bitwise OR (`dst[i] |= shifted_dict[...]`). Supercharges RD decompression from 3.7 GB/s by nearly 3x to **11.6+ GB/s**.
- **Branch-Free Word- and Byte-Level Run-Length Expansion (`expand_repeats`)**:
Replaces branch-heavy 64-bit word scanning and variable `trailing_ones` loops with a two-tier unrolled state machine. Pure-zero and pure-one words trigger full 64-element SIMD copies or broadcasts. Mixed words expand byte-by-byte with branchless 8-element unrolled stores, accelerating repeat-heavy datasets (`food_prices`, `nyc29`) by 50% ~ 70%.
- **Zero-Overhead Strongly Typed `ChunkType` Enum**:
Refactors wire format type byte into `#[repr(u8)] pub enum ChunkType`, eliminating string comparisons and redundant branches while ensuring compile-time exhaustive match verification.
- **Unified Consumer Paradigm (`AlpConsumer`) & Fused Single-Pass Delta Decompression**:
Overhauls traditional two-pass delta decompression (unpacking integer deltas into an 8KB stack buffer, followed by a separate prefix-sum and floating-point conversion pass). Fastalp introduces the monomorphized `AlpConsumer` pipeline architecture: within the bit-unpacking kernel loop, each decoded batch of 8 delta offsets is immediately accumulated into prefix sums, base-offset, and converted to IEEE 754 floats directly in CPU registers before writing to destination pointer memory. Entirely eliminates 8KB intermediate stack buffer allocation, cache writes, and re-reads. Throughput on `neon_air_pressure` surged from 10.42 GB/s to 22.11 GB/s (2.12x speedup), boosting all 11 delta datasets to 18 ~ 28 GB/s and pushing global 31-dataset arithmetic mean decompression throughput to **30.34 GB/s**.
- **Decoupled Modular Bit-Unpacking Engine & Direct Specialized Dispatch**:
Breaks apart the monolithic 1442-line unpacking file into clean, single-responsibility modules: `consumer.rs`, `decoder.rs`, `kernel.rs`, and safe top-level dispatchers. Dispatches inner macros directly to dedicated non-inlined subkernels (`unpack_1`, `unpack_2`, `unpack_4`, `unpack_8`, `unpack_16`, `unpack_32`, `unpack_64`, `unpack_le16`, `unpack_17_to_32`, `unpack_33_to_64`), while marking outer dispatchers with controlled `#[inline]`. Shrinks caller stack frames in unoptimized debug builds from megabytes down to under 100 bytes, completely eliminating stack overflow hazards on default 512KB test runner threads while retaining peak release performance.
- **Global Unrolling, Array Construction, and Bit-Width Dispatch Macros (`arr_8!`, `unroll_8!`, `write_8!`, `write_4!`, `match_pack_23!`)**:
Eliminates repetitive manual index offset sequences and boilerplate match blocks. The unified macro suite provides compile-time 8-element loop unrolling (`arr_8!`, `unroll_8!`), pre-binds destination pointers to eliminate duplicate expression evaluations (`write_8!`, `write_4!`), and collapses 23-arm bit-width matches into single clean calls (`match_pack_23!`), removing 120+ lines of duplicate code while preserving full compiler inlining.
- **Kernel Single-Instruction Wide Loads (16-bit / 32-bit / 128-bit Loads)**:
Eliminates per-element branch decisions and memory load contention in `unpack_2`, `unpack_4`, and `unpack_16`. `unpack_2` loads all 8 2-bit values via a single `u16` load and pure bitshifts; `unpack_4` loads all 8 4-bit values via a single `u32` load without slice creation overhead; `unpack_16` merges 8 separate 16-bit reads into a single 128-bit wide load (`u128`), slashing load port pressure by 87.5% and accelerating decompression throughput to **30.34 GB/s**.
- **Vectorized 0-bit Constant Block Memory Expansion**:
Replaces element-by-element pointer writes in `ForConsumer::consume_zeros` with an 8-way unrolled store loop (`write_8!`), allowing compilers to emit native AVX2 / NEON broadcast store instructions and elevating constant dataset decompression (e.g. `gov30`, `gov31`, `gov40`) to **90 ~ 93 GB/s**.
- **Delta Prefix-Sum Critical Path Dependency Chain Reduction**:
Decouples the running accumulator `curr` from internal 8-element delta sum reduction in `AlpDeltaConsumer`, cutting loop-carried dependency chain latency from 2 cycles down to 1 cycle. Maximizes instruction-level parallelism (ILP) and keeps delta decompression throughput at a steady **18 ~ 27 GB/s**.
- **Raw Pointer Uninitialized Memory Soundness & UB Elimination**:
Switches entirely to raw pointer reservation and in-place writes in `decompress_into`, `bitunpack_u64_raw`, and `expand_repeats`. Safely updates buffer lengths only after elements are initialized, strictly eliminating undefined behavior (UB) from constructing uninitialized slice references (`&mut [T]`) and passing all strict modern Rust memory soundness audits.
## C-Compatible API & Cross-Language Integration
`fastalp` provides an optional, disabled-by-default C-compatible FFI layer for integration into C, C++, Python, Go, and other language runtimes.<br>
When the `capi` feature is not enabled, standard Rust builds incur zero exported symbol overhead.
Enable the feature in `Cargo.toml`:
```toml
[dependencies]
fastalp = { version = "0.1.38", features = ["capi"] }
```
Build standalone static libraries (`libfastalp.a`) or shared libraries (`libfastalp.so` / `libfastalp.dylib`):
```bash
cargo build --release --features capi
```
### Buffer Capacity Estimation & Element Extraction
Callers can calculate worst-case buffer bounds or extract contained element counts:
- `fastalp_count(src, src_len)`: Reads the element count from the compressed byte stream in O(1) time without decompressing the payload, enabling optimal destination buffer preallocation.<br>
- `fastalp_max_compressed_size_f64(len)`: Computes maximum compressed byte bound for `len` `f64` floats.<br>
- `fastalp_max_compressed_size_f32(len)`: Computes maximum compressed byte bound for `len` `f32` floats.
### Thread-Local Streaming Interface
Stateless streaming functions reusing thread-local buffers to eliminate per-call allocation overhead:
- `fastalp_compress_f64(src, len, dst, dst_cap)`: Compresses an `f64` array with full parameter exploration.<br>
- `fastalp_compress_cached_f64(src, len, dst, dst_cap)`: Reuses cached parameters, bypassing the sampling phase.<br>
- `fastalp_decompress_f64(src, src_len, dst, dst_cap)`: Decompresses bytes into an `f64` target buffer.<br>
- `fastalp_reset_encoder_f64()`: Clears cached parameters in the current thread-local `f64` encoder.<br>
- Single-precision equivalents: `fastalp_compress_f32`, `fastalp_compress_cached_f32`, `fastalp_decompress_f32`, and `fastalp_reset_encoder_f32`.
### Explicit Instance Handle Interface
Designed for worker-pool architectures and per-column isolated states:
- `fastalp_encoder_f64_new()`: Allocates a heap-backed stateful `f64` encoder instance.<br>
- `fastalp_encoder_f64_free(enc)`: Frees the specified encoder instance.<br>
- `fastalp_encoder_f64_reset(enc)`: Clears cached model parameters in the handle.<br>
- `fastalp_encoder_f64_compress(enc, src, len, dst, dst_cap)`: Compresses data using the specified encoder handle.<br>
- Single-precision equivalents: `FastAlpEncoderF32`, `fastalp_encoder_f32_new`, `fastalp_encoder_f32_free`, `fastalp_encoder_f32_reset`, and `fastalp_encoder_f32_compress`.
## Changelog
### v0.1.40
- **Bit-Unpacking Architectural Decoupling & Fused Single-Pass Consumer**:
Refactored the monolithic bit-unpacking engine into modular subcomponents: `consumer.rs`, `decoder.rs`, `kernel.rs`, and safe top-level dispatchers. Abstracted the `AlpConsumer` pipeline paradigm, fusing Delta first-order difference prefix sums and floating-point reconstruction directly in CPU registers, eliminating 8KB intermediate stack buffers and double iterations.
- **Instruction Pipeline Wide Loads & Loop Accelerations**:
Replaced branch-heavy element-by-element loops and slice reads in `unpack_2`, `unpack_4`, and `unpack_16` with single-instruction `u16`, `u32`, and `u128` wide loads and pure bitshift extractions; vectorized 0-bit constant block filling via 8-way unrolling (`write_8!`) in `consume_zeros`; decoupled the running accumulator in `AlpDeltaConsumer`, cutting cycle dependency latency from 2 cycles down to 1 cycle.
- **Global Unrolling & Dispatch Macro Framework**:
Introduced `src/macros.rs` (`arr_8!`, `unroll_8!`, `write_8!`, `write_4!`, `match_pack_23!`), collapsing 23-arm packing match boilerplate and pre-binding pointers to eliminate duplicate expression evaluations and remove 120+ lines of redundant code.
- **Uninitialized Memory Soundness & Zero Clippy Warnings**:
Adopted raw pointer reservation and in-place writes in `decompress_into`, `bitunpack_u64_raw`, and `expand_repeats`, strictly eliminating undefined behavior (UB) from constructing uninitialized slice references; cleaned up all absolute path references to achieve zero warnings under `-W clippy::absolute_paths`.
### v0.1.38
- **Dead Code Elimination & Bitpack Core Cleanup**:
Removed deprecated legacy routines `bitunpack_core` and `bitunpack_core_div` from `bitpack/unpack.rs`, consolidating all bit-unpacking pathways on the generic dispatch kernels; cleaned up unused imports and `#[allow(unused_imports)]` attributes in `bitpack/mod.rs`.
- **Absolute Path Linting & Full Clippy Compliance**:
Resolved `-W clippy::absolute_paths` warnings in `capi.rs` and `decoder/standard.rs`, ensuring 100% zero-warning compliance across all compilation profiles and optional feature sets.
- **Documentation Badges & Social Links**:
Unified README badge heights to 28px across language switchers and ecosystem shields; introduced the official Bluesky badge (`@webc-site`) alongside Twitter; updated benchmark visualizations and C-API integration snippets to v0.1.38.
### v0.1.37
- **Zero-Cost Decoder Trait & Architectural Deduplication**:
Abstracted the `AlpDecoder<F>` core trait with monomorphized implementations (`AlpFac1Decoder`, `AlpMulDecoder`, `AlpDivDecoder`); introduced the `dispatch_decoder!` compile-time dispatch macro to eliminate runtime branch overhead in batch loops; unified generic bit-unpacking and dequantization kernels (`bitunpack_core_generic`), eliminating 800+ lines of duplicated code.
- **End-to-End Compression Ratio Leap (+11.2%)**:
Across all 37 public and industrial time-series datasets, total compressed size dropped from 104,465 B to 93,909 B, saving 10,556 bytes (a 10.1% size reduction and +11.2% ratio improvement); relaxed Delta evaluation threshold (`>= 4`) unlocks smooth time-series data pathways with ratios up to 431x; introduced monotonic descending outlier pruning and predecessor smoothing to release the full benefits of differential encoding.
- **Decompression Throughput Boost (+14.7%)**:
Decompression throughput climbed from 28.36 GB/s to 32.53 GB/s (+14.7% improvement) on modern architectures, while maintaining high-speed end-to-end encoding throughput at 4.87 GB/s.
- **100% Bilingual Code Comments & Production Engineering Quality**:
Implemented complete Chinese/English bilingual comments across all core modules (sampler, bitunpack, encoder engine, standard/delta decoders, C-API); magic numbers replaced with compile-time constants; passed clippy with zero warnings; 100% pass rate across 355 unit and bit-exact lossless roundtrip tests.
### v0.1.36
- **Rigorous Academic Benchmark Alignment with C++ ALP**:
Conducted side-by-side evaluation across all 37 public and industrial time-series datasets against the official C++ ALP implementation (ACM SIGMOD 2024), standardizing academic citation formatting and linking exact source code benchmark lines ([`bench_alp_encode.cpp#L88-L95`](https://github.com/cwida/ALP/blob/main/publication/source_code/bench_speed/bench_alp_encode.cpp#L88-L95)).
- **Dual-Metric Throughput Calibration**:
Calibrated pure encoding kernel throughput (skipping sampling exploration) at 6.0 GB/s, achieving a 1.10x speedup over official C++ ALP (5.5 GB/s); end-to-end sampled compression throughput reaches 3.7 GB/s (4.6x faster than C++ ALP's 0.80 GB/s); decompression throughput reaches 27.0 GB/s (1.35x faster than C++ ALP's 20.0 GB/s); geometric mean compression ratio reaches 6.99x (18% higher than C++ ALP's 5.93x).
- **100% Reproducible Open-Source Evaluation Suite**:
Provided one-click reproduction scripts and expanded 37-dataset benchmark suites in the evaluation fork repository ([`github.com/x-at-01/ALP`](https://github.com/x-at-01/ALP)).
### v0.1.35
- **Raw Pointer Decompression Kernel & Soundness Guarantee**:
Introduced `decompress_into_raw`, `decode_standard_raw`, and `decode_delta_raw` to write directly into target raw pointers, avoiding constructing slice references over uninitialized memory; seamlessly supports uninitialized buffers from C callers via C-API.
- **Single-Pass Exception Patching**:
Refactored `patch_exceptions` using `chunks_exact` to eliminate repeated slice recalculation and bounds checks in the inner loop.
- **Dead Code Elimination & Hardware-Accelerated Rounding**:
Removed legacy `MAGIC_NUMBER` simulation constants, adopting `round_ties_even()` with direct mapping to SSE4.1/AVX and ARM64 instructions, ensuring 100% bit-exact lossless roundtrip.
### v0.1.34
- **Strict Code Standards & Zero Compiler Warnings**:
Completely eliminated all `#[allow(...)]` attributes across the entire codebase (`src/`), addressing all Clippy warnings and dead code to enforce strict code quality.
- **Struct Encapsulation & Architectural Decoupling**:
Encapsulated compression parameters (exponent, factor, exception threshold, bit-width, etc.) into `AlpParams`, eliminating raw tuple arguments. Encapsulated `AlpHeader` decoder to remove scattered magic numbers and manual bit offsets.
- **Bitpack Kernel Refactoring & Code Reuse**:
Abstracted and unified the 8-element loop packing kernel `pack_chunk_8`, removing duplicated loop unrolls. Streamlined the Delta first-order difference decoder with tree-reduction to eliminate scalar dependency chains and improve instruction-level parallelism (ILP).
- **Accurate Benchmark Calibration & Branch Isolation**:
Refined C++ ALP benchmark metrics extraction, clearly distinguishing between sampled compression throughput (~0.85 GB/s) and raw kernel throughput (~5.9 GB/s), while accurately recording decompression throughput (~20.3 GB/s). Decoupled the official PR branch from self-use evaluation branches.
- **Documentation Architecture Restructuring**:
Reorganized documentation into dedicated `readme/zh/` and `readme/en/` directories with integrated version changelogs and automatic multilingual README aggregation.
### v0.1.33
- Code architecture optimization and performance fine-tuning.
### v0.1.32
- Refined stateful `Encoder` documentation and buffer reuse API ergonomics.
### v0.1.31
- Added optional `capi` feature with bilingual C-API documentation and header files for cross-language (C/C++/Python) integration.
### v0.1.30
- Clarified standard ALP baseline vs custom compression ratio optimizations; enhanced floating-point precision stability.
---
<a id="zh"></a>
# fastalp : 高性能自适应通用时序浮点无损压缩
纯 Rust 实现的自适应无损浮点数压缩算法库，深度吸收并拓展了 ACM SIGMOD 2024 最佳 Artifact 论文 [ALP](https://dl.acm.org/doi/10.1145/3626717) 的理论体系，通过统一泛型接口提供对 `f64` 与 `f32` 数据流的高性能压缩与解压。
<p align="center">
<img src="https://fastly.jsdelivr.net/gh/webc-fs/-@Pa/1KIeLgRugYWZtlUF3BRQ.svg" alt="fastalp 浮点压缩算法全量性能与压缩比横向对比" width="100%">
<br>
<sub><b>评测环境</b>: 芯片: Apple M2 Max (12 核) ｜ 环境: macOS 26.5.1 ｜ 工具链: Rust 1.98.0 / Clang (-O3)</sub>
</p>
---
- [理论背景与官方论文](#理论背景与官方论文)
- [功能特性](#功能特性)
- [针对 C++ 官方实现（`cwida/ALP`）的核心算法与架构升级](#针对-c-官方实现cwidaalp的核心算法与架构升级)
- [使用示例](#使用示例)
- [添加依赖](#添加依赖)
- [基础压缩与解压](#基础压缩与解压)
- [内存缓冲区复用](#内存缓冲区复用)
- [零堆分配切片解压与 O(1) 元素计数](#零堆分配切片解压与-o1-元素计数)
- [状态化编码与参数缓存](#状态化编码与参数缓存)
- [单精度浮点数据处理](#单精度浮点数据处理)
- [高性能工程技巧与最佳实践](#高性能工程技巧与最佳实践)
- [连续时序流启用参数缓存](#连续时序流启用参数缓存)
- [就地复用缓冲区消除堆分配与内存抖动](#就地复用缓冲区消除堆分配与内存抖动)
- [极低熵与单调波形自适应增益](#极低熵与单调波形自适应增益)
- [架构设计](#架构设计)
- [压缩流程](#压缩流程)
- [解压流程](#解压流程)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
- [性能评测与多算法对比](#性能评测与多算法对比)
- [测试环境与编译配置](#测试环境与编译配置)
- [主流浮点与时序压缩算法同机横向对比](#主流浮点与时序压缩算法同机横向对比)
- [压缩纯编码与流式参数复用进阶对比](#压缩纯编码与流式参数复用进阶对比)
- [典型工业场景微基准细分实测](#典型工业场景微基准细分实测)
- [C++ ALP 测试机制与统计口径说明](#c-alp-测试机制与统计口径说明)
- [评测数据集全景与公开数据源](#评测数据集全景与公开数据源)
- [架构演进与优化全景](#架构演进与优化全景)
- [参考与借鉴原版 ALP 的架构设计](#参考与借鉴原版-alp-的架构设计)
- [自主研发的算法与性能优化](#自主研发的算法与性能优化)
- [C 兼容接口与跨语言集成](#c-兼容接口与跨语言集成)
- [缓冲区容量预估与元素提取](#缓冲区容量预估与元素提取)
- [线程局部流式接口](#线程局部流式接口)
- [独立实例句柄接口](#独立实例句柄接口)
- [更新日志](#更新日志)
- [v0.1.40](#v0140)
- [v0.1.38](#v0138)
- [v0.1.37](#v0137)
- [v0.1.36](#v0136)
- [v0.1.35](#v0135)
- [v0.1.34](#v0134)
- [v0.1.33](#v0133)
- [v0.1.32](#v0132)
- [v0.1.31](#v0131)
- [v0.1.30](#v0130)
## 理论背景与官方论文
ALP（Adaptive Lossless Floating-Point Compression）是由荷兰国家数学与计算机科学研究中心（CWI）数据库团队（Azim Afroozeh, Leonardo Kuffó, Peter Boncz）于 **ACM SIGMOD 2024** 提出的前沿浮点压缩算法，并荣获 **SIGMOD 2024 Best Artifact Award**（最佳系统制品奖），目前已被 **DuckDB**、**FastLanes**、**KuzuDB** 等知名现代列存数据库与计算引擎深度集成：
- **官方论文**：_ALP: Adaptive Lossless Floating-Point Compression_, ACM SIGMOD 2024 · [DOI: 10.1145/3626717](https://dl.acm.org/doi/10.1145/3626717)
- **官方 C++ 开源实现**：[github.com/cwida/ALP](https://github.com/cwida/ALP)
- **核心理论贡献**：揭示了真实生产时序（IoT、金融、遥测）中绝大多数浮点数本质上是具有固定小数位数的十进制数值，通过自适应十进制缩放将浮点数无损投影至紧凑整型空间，结合基准消除（FOR）与 SIMD 密集位打包，实现超越传统通用压缩算法的高吞吐与高压缩比。
`fastalp` 在完整继承并严密验证官方 ALP 理论精髓的基础上，全面重构了编解码执行流水线，解决了 C++ 官方原版在面对实际工业时序波形与极端数据分布时的位宽冗余、精度截断虚假异常、缺乏自描述格式以及暴力采样等关键痛点。
---
## 功能特性
在物联网传感器采集、金融量化交易、GPS 经纬度定位以及时序监控等场景中，浮点数据通常以十进制形式产生。<br>
由于 IEEE 754 浮点数的阶码与尾数位分布离散，通用字节压缩算法（Zstd、Snappy）与传统时序算法（Gorilla、Chimp）往往难以兼顾高吞吐与高压缩比。
`fastalp` 提供完整的工业级自适应无损压缩方案：
- **自适应参数推导**：<br>
对输入数据进行采样探测，评估代价模型并计算使编码位宽与异常值综合开销最小的最优十进制缩放参数 `(exp, fac)`。
- **位精确无损整型映射**：<br>
利用十进制科学计数因子将浮点数无损映射至紧凑整型空间，并通过反向整型解码与位级一致性校验，保证数值还原精确无损（`a.to_bits() == b.to_bits()`）。
- **基准消除与密集位打包**：<br>
提取转换后有效整型序列的最小值作为基准值（FOR 模式），消除基准后按 1 至 64 位动态位宽进行紧凑位打包。
- **独立异常值流隔离**：<br>
无法无损整型化的特殊浮点数（如 `NaN`、`+Inf`、`-Inf`、`-0.0`）及超出整型范围的数值，独立记录索引位置与原始 IEEE 754 位，避免拉大主数据流位宽。
- **双精度与单精度泛型支持**：<br>
通过 `AlpFloat` 统一泛型特征零成本抽象支持 `f64` 与 `f32` 数据流，兼顾高精度科学计算与轻量传感器场景。
- **零额外堆内存分配**：<br>
提供 `_into` 系列接口及 FFI 裸指针直出接口，支持调用方就地复用预分配缓冲区，规避内存分配与 GC 抖动。
### 针对 C++ 官方实现（`cwida/ALP`）的核心算法与架构升级
对照 C++ 官方原版的实现，原版仅支持固定 1024 满块、依赖 FastLanes FFOR 静态全局基准消除、使用浮点乘法截断缩放，且缺乏自包含二进制序列化格式与采样剪枝。<br>
`fastalp` 结合底层时序特征与现代硬件微架构，做出了关键性创新与工程突破：
- **自适应时序差分（Adaptive Delta-ALP）**：<br>
原版实现仅支持静态全局最小值基准消除（`analyze_ffor`），平滑时序物理波形（气象、水文、工业传感器）虽然相邻差值极小，但全局极值跨度大导致位宽冗余。<br>
`fastalp` 引入相邻一阶差分与前缀和递推机制，配合前置 16 采样数学短路快筛（局部差分极值不优即瞬时早停），自适应收窄动态位宽 15% ~ 38%。
- **十进制精确除法重构（`use_div` 模式）**：<br>
原版实现仅采用浮点乘法反向缩放（`* Constants<PT>::FRAC_ARR`），受 IEEE 754 浮点乘法（如 `* 0.1`）无限循环二进制尾数截断误差影响，产生大量误判的虚假异常点（每点需额外消耗 80~128 位存储）。<br>
`fastalp` 引入十进制精确除法重构模式，将观测时序中因乘法舍入截断造成的虚假异常直接归零，数据点存储体积降低 20% ~ 38%。
- **智能离群点剪枝与稀疏常数压缩（0-bit 编码）**：<br>
原版缺乏离群值剥离机制，当数据块中 99% 为常数或零值但偶发出现单点突变脉冲时，全局位宽被迫按脉冲极值全量膨胀。<br>
`fastalp` 引入离群值剪枝算法，自动将孤立脉冲剥离至异常流，主位流降至 0 位（仅存基准值，位流零字节占用），稀疏突变时序压缩比突破 150x ~ 744x。
- **异常点前值回填平滑机制**：<br>
原版将异常点覆盖为固定的全局首个有效值，在时序差分模式下会引起前后相邻元素人工阶跃跳变，导致差分位宽急剧发散。<br>
`fastalp` 在差分与位打包前，将异常点自动用前一个有效整型值回填，消除人为差分抖动，保障差分压缩位宽保持极窄状态。
- **硬件原生偶数舍入（`round_ties_even` 替代 Magic Number）**：<br>
原版采用 IEEE 754 常数偏置 Magic Number（`0x0018000000000000`）在浮点单元内加减模拟舍入，受限于 $[-2^{51}, 2^{51}]$ 取值范围；<br>
`fastalp` 采用硬件加速的向偶数舍入指令（直接映射至 x86 `ROUNDSD` 与 ARM64 `FRINTN`），消除了取值范围溢出风险，确保全域数值严格无损。
- **紧凑自描述头与超大数组原生支持**：<br>
原版硬编码 1024 元素固定长度且缺乏自包含二进制序列化格式，最后不足 1024 元素的尾部向量需补零或二次编码填充，无法原生编码变长或超大数组。<br>
`fastalp` 采用 2-bit 长度标签自描述格式，标准 1024 满块头仅占 3 字节，RAW 保底模式仅占 1 字节；支持超过 65,535 元素的超大数组自动升级为 32 位数量与异常偏移，单帧无损流式序列化。
- **12.5% 异常上限与单字节 RAW 保底回退**：<br>
原版对不可压缩的高熵随机浮点数缺乏严格的负压缩防护，编码后体积膨胀 1.5x ~ 2x；<br>
`fastalp` 设定 12.5% 异常上限与体积实时评估，一旦探测到负压缩立即回退至 1 字节头的 RAW 原始数据流，从机制上杜绝空间膨胀。
- **单次比较全等快跳**：<br>
面对工业设备待机、传感器断线与心跳常数流，原版仍需执行完整的采样、FFOR 分析与位打包循环；<br>
`fastalp` 在编码入口仅用 1 次比对判定全等常数序列，1 个 CPU 时钟周期内完成识别，1024 元素以 11 字节瞬时输出（压缩比达 744x）。
- **三级级联微架构采样剪枝**：<br>
原版 `init` 采用全量暴力穷举，采样耗时占全流程 80% 以上，导致端到端压缩吞吐仅约 0.80 GB/s；<br>
`fastalp` 采用纯十进制早停、4 样本短路快筛和非十进制熔断的三级剪枝流水线，将端到端压缩吞吐提升至 **3.7 GB/s（提速 4.6x）**；在压缩纯编码吞吐（不含采样）口径下达 **6.0 GB/s（较 C++ 快 1.10x）**；在命中状态化参数缓存时，流式参数缓存吞吐可达 **15~24+ GB/s**。
## 使用示例
### 添加依赖
```bash
cargo add fastalp
```
### 基础压缩与解压
```rust
use fastalp::{compress, decompress, Result};
fn main() -> Result<()> {
let sensor_data = vec![20.5, 20.6, 20.8, 21.0, 20.9, 21.2];
// 压缩浮点数切片为字节向量 (自动适配 f64 / f32)
let compressed = compress(&sensor_data);
// 解压字节向量恢复原始浮点数切片
let decompressed: Vec<f64> = decompress(&compressed)?;
assert_eq!(decompressed, sensor_data);
Ok(())
}
```
### 内存缓冲区复用
```rust
use fastalp::{compress_into, decompress_into, Result};
fn main() -> Result<()> {
let batch = vec![100.12, 100.15, 100.18, 100.22];
let mut compressed_buf = Vec::new();
compress_into(&batch, &mut compressed_buf);
let mut restored = Vec::new();
decompress_into(&compressed_buf, &mut restored)?;
assert_eq!(restored, batch);
Ok(())
}
```
### 零堆分配切片解压与 O(1) 元素计数
针对数据库执行器、嵌入式环境或预分配内存池等极致低延迟场景，`fastalp` 提供 O(1) 紧凑头部元素计数与切片原地解压接口，全程零堆内存分配：
```rust
use fastalp::{
compress, count, decompress_into_slice, max_compressed_size, Result,
};
fn main() -> Result<()> {
let sensor_data = [20.5, 20.6, 20.8, 21.0, 20.9, 21.2];
let compressed = compress(&sensor_data);
// 1. O(1) 零堆分配快速提取压缩块中的元素总数
let num_items = count(&compressed)?;
assert_eq!(num_items, 6);
// 2. 预估最坏情况下（含保底回退）所需最大压缩缓冲区大小，防止越界
let max_cap = max_compressed_size::<f64>(num_items);
assert!(compressed.len() <= max_cap);
// 3. 解压至栈数组或既有切片，实现真正的零堆内存分配与零拷贝
let mut dst = [0.0f64; 6];
let written = decompress_into_slice(&compressed, &mut dst)?;
assert_eq!(written, 6);
assert_eq!(&dst[..], &sensor_data[..]);
Ok(())
}
```
### 状态化编码与参数缓存
针对连续数据块流式压缩场景，使用 `Encoder` 缓存采样参数并复用内部工作内存，消除重复采样开销：
```rust
use fastalp::{decompress, Encoder, Result};
fn main() -> Result<()> {
let mut encoder = Encoder::<f64>::with_capacity(1024);
let chunk1: Vec<f64> = (0..1024).map(|i| 25.0 + (i as f64) * 0.25).collect();
let chunk2: Vec<f64> = (1024..2048).map(|i| 25.0 + (i as f64) * 0.25).collect();
let mut compressed = Vec::new();
// 第一个块：采样探测最优参数并缓存
encoder.compress_into(&chunk1, &mut compressed);
// 第二个块：命中参数缓存，跳过全量采样，吞吐大幅提升
compressed.clear();
encoder.compress_into(&chunk2, &mut compressed);
let restored: Vec<f64> = decompress(&compressed)?;
assert_eq!(restored, chunk2);
// 切换不同数据流时重置缓存
encoder.reset();
Ok(())
}
```
### 单精度浮点数据处理
```rust
use fastalp::{compress, decompress, Result};
fn main() -> Result<()> {
let coordinates = vec![116.4074f32, 39.9042f32, 121.4737f32, 31.2304f32];
let compressed = compress(&coordinates);
let decompressed: Vec<f32> = decompress(&compressed)?;
assert_eq!(decompressed, coordinates);
Ok(())
}
```
---
### 高性能工程技巧与最佳实践
#### 连续时序流启用参数缓存
在时序数据库或流式管道中，同一指标列（如温度传感器、订单簿成交价）的量纲与精度往往随时间保持高度平稳。<br>
直接使用 `compress` 每次都会执行 32 点轻量采样。而通过复用 `Encoder` 实例，连续数据块将命中已缓存的 `(exp, fac)` 最优参数，直接执行纯向量化编码内核，吞吐可提升至 **15~24+ GB/s**：
```rust
use fastalp::Encoder;
// 推荐为每个时间序列或写入通道保持一个 Encoder 实例
let mut encoder = Encoder::<f64>::with_capacity(1024);
let mut buf = Vec::with_capacity(1024 * 8);
for chunk in incoming_stream {
buf.clear();
// 跨块复用模型参数，吞吐达 15~24+ GB/s
encoder.compress_into(&chunk, &mut buf);
write_to_storage(&buf);
}
```
#### 就地复用缓冲区消除堆分配与内存抖动
高吞吐场景下频繁分配和丢弃 `Vec<u8>` 会导致内存碎片与 CPU 分配器锁争用。使用 `_into` 系列接口直接就地写入持久化缓冲区：
```rust
use fastalp::{compress_into, decompress_into};
let mut comp_buf = Vec::with_capacity(8192);
let mut decomp_buf = Vec::with_capacity(1024);
// 循环内零堆内存分配
for batch in batches {
comp_buf.clear();
compress_into(&batch, &mut comp_buf);
decomp_buf.clear();
decompress_into(&comp_buf, &mut decomp_buf)?;
}
```
#### 极低熵与单调波形自适应增益
- **常数流与设备心跳**：当遇到设备断线、待机或心跳常数时，`fastalp` 入口仅需 1 个 CPU 时钟周期识别全等流，1024 元素以 11 字节高速输出（压缩比达 **744x**）。
- **线性升降波形与步进计数**：针对工业 PID 调节、水文流量与连续计数器，`fastalp` 自动激活 Delta 一阶差分编码，动态消除波形大跨度基准，压缩比突破 **430x+**。
## 架构设计
`fastalp` 编解码流程划分为以下阶段：
```mermaid
graph TD
Input["输入浮点数切片 (&[f64] / &[f32])"] --> Sampler["参数采样器<br/>评估代价模型并推导最优 (exp, fac)"]
Sampler --> Encoder["无损整型编码<br/>快速常量舍入与位精确校验"]
Encoder --> Split{"是否支持无损编码"}
Split -- 是 --> IntStream["FOR 基准值消除<br/>计算非负整型偏移量"]
Split -- 否 --> ExcStream["异常值记录<br/>存储索引位置与 IEEE 754 原始位"]
IntStream --> Bitpacker["密集位打包<br/>按动态位宽打包进字节流"]
ExcStream --> Frame["二进制帧封装<br/>包头 + 基准值 + 位流 + 异常值列表"]
Bitpacker --> Frame
Frame --> Output["压缩字节负载 (Vec<u8>)"]
```
### 压缩流程
- **全等探测与保底分流 (`encoder.rs`)**：<br>
先对数据进行常数序列快速校验；若全等且可编码，直接写入自描述紧凑头部与基准值；<br>
若为不可压缩随机数据且编码体积超过原始大小加上极简头部，则自动回退至原始保底模式（1024 满块仅 1 字节头部），直接以原始字节流存储。
- **采样评估 (`sampler.rs`)**：<br>
在数据序列中均匀采样至多 32 个数值，遍历 `(exp, fac)` 参数组合，<br>
选取使得 `位宽 * 样本量 + 异常数 * 惩罚权重` 最小的参数组合。
- **无损转换与验证 (`sampler.rs`, `float.rs`)**：<br>
将浮点数乘以 $10^{\text{exp}} \times 10^{-\text{fac}}$，利用常量完成快速向近舍入并转换为整型，<br>
再通过反向整型乘法与逆缩放验证浮点位级一致性。
- **基准消除与位打包 (`bitpack/pack.rs`, `encoder.rs`)**：<br>
获取有效整型中的最小值作为基准值，计算偏移量并获取所需位宽，<br>
利用 128 位寄存器滑动窗口将数值紧凑打包入字节流。
- **异常流序列化 (`encoder.rs`)**：<br>
无法无损转换的浮点数按索引位置与 IEEE 754 原始位记录于尾部异常表中。
### 解压流程
- **自描述头解析 (`header.rs`, `decoder.rs`)**：<br>
读取首字节描述符，由 2-bit 长度标签解码元素总数并确定参数偏移；<br>
若类型为原始保底数据，通过内存复制直出恢复；若为 ALP 压缩数据，提取 `(exp, fac, bit_width)` 缩放参数与基准值。
- **位流解包与 SIMD 寄存器流水重构 (`bitpack/unpack.rs`)**：<br>
针对 8/16/32/64 bit 采用纯寄存器 SIMD 自动向量化计算，消除堆栈查表与内存间接 gather 寻址延迟；针对 1/2/4 bit 采用微型局部表快速还原。
- **异常值覆盖 (`decoder.rs`)**：<br>
若存在尾部异常表，读取对应索引位置的数值并覆盖为原始 IEEE 754 浮点值。
---
## 技术栈
- **开发语言**：Rust Edition 2024
- **错误处理**：`thiserror`
- **测试与基准**：`anyhow`, `aok`, `fastrand`
---
## 目录结构
```
fastalp/
├── Cargo.toml # 项目配置与依赖声明
├── README.md # 生成的多语言文档
├── README.mdt # 多语言文档模板
├── readme/ # 文档源码目录
│ ├── en/ # 英文文档模块 (intro, usage, architecture, bench, evolution, capi, log)
│ └── zh/ # 中文文档模块 (intro, usage, architecture, bench, evolution, capi, log)
├── src/ # 核心源代码
│ ├── bitpack/ # 模块化位打包与位解包
│ │ ├── mod.rs # 门面导出
│ │ ├── pack.rs # 128 位累加器位打包算子与 match_pack_23 派发
│ │ └── unpack/ # 模块化分层位解包算子体系
│ │ ├── mod.rs # 解包顶层调度与安全门面
│ │ ├── consumer.rs # AlpConsumer 消费器抽象（FOR/Delta前缀和/原始写入）
│ │ ├── decoder.rs # AlpDecoder 浮点重构器（乘法/除法/RD/字典）
│ │ └── kernel.rs # 64 路定宽解包与展开内联内核
│ ├── capi.rs # C 兼容 FFI 接口与独立编码器句柄
│ ├── constants.rs # 静态幂次表与格式常量
│ ├── decoder/ # 泛型流式解压与除法重构
│ │ ├── mod.rs # 解压门面与模式派发
│ │ ├── standard.rs # 标准 FOR 还原解压
│ │ └── delta.rs # Delta 一阶差分解码
│ ├── delta/ # 一阶差分自适应收益评估与前缀和
│ │ └── mod.rs
│ ├── encoder/ # 泛型压缩流水线与参数缓存
│ │ ├── mod.rs # 编码门面与顶层便捷函数
│ │ ├── state.rs # 状态化 Encoder 结构体与工作缓冲区复用
│ │ ├── engine.rs # 压缩编排引擎与参数三级校验
│ │ ├── kernel.rs # 4-way 展开无分支向量化编码内核
│ │ ├── outlier.rs # FOR 模式离群值剪枝算法
│ │ ├── exception.rs# 异常值结构与紧凑序列化
│ │ ├── standard.rs # 标准 FOR 编码组装
│ │ └── delta.rs # Delta 一阶差分编码组装
│ ├── error.rs # 错误枚举定义与 Result 类型别名
│ ├── float/ # AlpFloat 浮点抽象特征与泛型无损转换
│ │ ├── mod.rs # AlpFloat trait 定义与查表构建
│ │ ├── f32.rs # 单精度 f32 乘法/除法编解码实现
│ │ └── f64.rs # 双精度 f64 乘法/除法编解码实现
│ ├── header.rs # 紧凑自描述头部编解码与 2-bit 长度标签档位管理
│ ├── lib.rs # 导出接口与高层封装
│ ├── macros.rs # 全局循环展开、数组构造与位宽派发宏体系
│ ├── params.rs # 紧凑位域参数打包与位宽计算
│ └── sampler.rs # 参数采样与无损重构验证
├── test.sh # 测试运行脚本
└── tests/ # 集成与压力测试
├── test_alp_dataset.rs # ALP 论文 31 真实数据集往返与压缩比评测
├── test_delta.rs # Delta 差分时序专项与异常测试
└── test_roundtrip.rs # 往返无损与边界测试
```
## 性能评测与多算法对比
### 测试环境与编译配置
所有基准测试均在同一物理机上执行并进行同机对比测试：
- **处理器**: Apple M2 Max (12 核心：8 性能核 @ 3.68 GHz + 4 能效核 @ 2.42 GHz, ARMv8.6-A NEON 指令集)<br>
- **操作系统**: macOS Sequoia 26.5.1 (Darwin Kernel Version 25.5.0 arm64)<br>
- **Rust 编译工具链**: `rustc 1.98.0 / nightly` (配置：`opt-level = 3`, `lto = "fat"`, `codegen-units = 1`)<br>
- **C++ 编译工具链**: Homebrew LLVM Clang 22.1.8 (`-O3 -std=c++17 -DNDEBUG -march=native`) / CMake 4.4.2<br>
- **内存分配器**: `mimalloc 0.1.52`<br>
- **基准测试框架**: Rust `divan 0.1.20` 微基准套件 vs C++ `std::chrono::high_resolution_clock`（稳态中位数采样）
### 主流浮点与时序压缩算法同机横向对比
在完全相同的测试硬件与全量 37 项数据负载下，同机全量对比业界主流浮点与时序压缩库（统一采用全部 37 项数据集实测几何均值，与评测图表完全一致）：
| 算法名称 | 算法分类 | 解压吞吐 (几何均值) | 相对 C++ 解压 | 端到端压缩 (几何均值) | 压缩纯编码吞吐 (几何均值) | 相对 C++ 纯编码 | 几何平均压缩比 |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **fastalp (Rust)** | 浮点专用 | **25.3 GB/s** | **较 C++ 快 1.31x** | **2.1 GB/s (快 2.58x)** | **7.8 GB/s** | **较 C++ 快 1.46x** | **9.50x** |
| **C++ ALP** (原版实现) | 浮点专用 | **19.3 GB/s** | 基准 (1.0x) | **0.8 GB/s** | **5.4 GB/s** | 基准 (1.0x) | **5.93x** |
| Pcodec (pco) | 浮点专用 | **1.8 GB/s** | 0.09x (慢 10.6x) | **0.2 GB/s** | — | — | **8.81x** |
| Zstd (level 3) | 通用字节 | **1.4 GB/s** | 0.07x (慢 13.6x) | **0.5 GB/s** | — | — | **6.07x** |
| LZ4 (lz4_flex) | 通用字节 | **5.0 GB/s** | 0.26x (慢 3.9x) | **2.0 GB/s** | — | — | **3.89x** |
| Snappy (snap) | 通用字节 | **4.6 GB/s** | 0.24x (慢 4.2x) | **2.5 GB/s** | — | — | **3.05x** |
| Chimp128 (ts+val) | 浮点专用 | **1.0 GB/s** | 0.05x (慢 19.7x) | **1.3 GB/s** | — | — | **5.05x** |
| Gorilla (ts+val) | 浮点专用 | **1.2 GB/s** | 0.06x (慢 16.2x) | **1.9 GB/s** | — | — | **4.41x** |
---
### 压缩纯编码与流式参数复用进阶对比
在时序浮点压缩评测中，针对特定运行形态与写入模式提供进阶吞吐评测：
- **压缩纯编码（不含采样）**：<br>
原论文官方测试代码（`bench_alp_encode.cpp`）在计时循环外部预先执行 `init`，假设已获知最佳指数与因子，仅测量跳过采样后的纯浮点变换与密集位打包内核速度。
- **状态化流式参数缓存**：<br>
在平稳连续时序流写入时，跨 1024 满块复用已推导的模型参数，跳过重复采样开销。
同机 37 项全量数据集实测对照（提供几何均值与算术均值双口径详细对比）：
| 评测维度 / 运行模式 | fastalp (Rust) | C++ ALP (官方原版) | 相对 C++ 提升幅度 | 评测机制与工业场景说明 |
| :--- | :---: | :---: | :---: | :--- |
| **全量基准解压吞吐** | 几何均值 **25.3 GB/s**<br>算术均值 **30.72 GB/s** | 几何均值 19.3 GB/s<br>算术均值 19.69 GB/s | 几何均值 **快 1.31x**<br>算术均值 **快 1.56x** | 37 项全量数据集实测，单趟差分融合与宽位加载加速 |
| **压缩纯编码吞吐 (不含采样)** | 几何均值 **7.8 GB/s**<br>算术均值 **9.01 GB/s** | 几何均值 5.4 GB/s<br>算术均值 5.74 GB/s | 几何均值 **快 1.46x**<br>算术均值 **快 1.57x** | 预置或缓存模型参数，跳过采样探测，纯浮点整型变换与位打包内核（原论文测试代码口径） |
| **端到端压缩吞吐 (含自适应采样)** | 几何均值 **2.1 GB/s**<br>算术均值 **2.93 GB/s** | 几何均值 0.8 GB/s<br>算术均值 0.80 GB/s | 几何均值 **快 2.58x**<br>算术均值 **快 3.64x** | 真实时序全流程写入口径，三级级联剪枝规避暴力穷举开销 |
| **状态化连续流式吞吐 (参数缓存)** | **15 ~ 24+ GB/s** | — | **平稳流式写入** | 跨 1024 满块复用已推导的模型参数，平稳时序跳过采样直接推导 |
| **综合压缩比** | 几何均值 **9.50x**<br>总字节加权 **3.69x** | 几何均值 5.93x<br>总字节加权 2.89x | 几何均值 **领先 60%**<br>总字节加权 **领先 28%** | 37 项公开与工业基准实测，Delta 差分与除法重构有效收窄动态位宽 |
---
### 典型工业场景微基准细分实测
| 业务场景切片 | 样本规模 | fastalp<br>(解压 / 压缩 / 压缩比) | C++ ALP<br>(解压 / 压缩 / 压缩比) | Pcodec<br>(解压 / 压缩 / 压缩比) | 对照算法<br>(解压 / 压缩 / 压缩比) |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **十进制环境与气象水文传感** | 11 组 (11,264 点) | **22.9 GB/s**<br>**3.1 GB/s**<br>**3.45x** | 18.8 GB/s<br>0.8 GB/s<br>3.16x | 1.65 GB/s<br>0.2 GB/s<br>3.30x | LZ4:<br>7.4 GB/s<br>1.8 GB/s<br>1.78x |
| **高频量化金融交易与资产行情** | 7 组 (7,168 点) | **23.5 GB/s**<br>**3.2 GB/s**<br>**4.76x** | 20.5 GB/s<br>0.8 GB/s<br>3.85x | 1.56 GB/s<br>0.2 GB/s<br>4.17x | Snappy:<br>14.0 GB/s<br>3.9 GB/s<br>2.22x |
| **地理空间高精测绘与轨迹跟踪** | 5 组 (5,120 点) | **19.0 GB/s**<br>**2.2 GB/s**<br>**2.17x** | 17.5 GB/s<br>0.7 GB/s<br>1.73x | 2.01 GB/s<br>0.2 GB/s<br>2.27x | Snappy:<br>31.9 GB/s<br>8.2 GB/s<br>1.40x |
| **医疗社保理赔与公共卫生处方** | 5 组 (5,120 点) | **22.7 GB/s**<br>**2.0 GB/s**<br>**2.10x** | 20.1 GB/s<br>0.8 GB/s<br>2.19x | 2.04 GB/s<br>0.2 GB/s<br>2.16x | Zstd:<br>1.0 GB/s<br>0.4 GB/s<br>1.99x |
| **公共政务民生与宏观统计普查** | 6 组 (6,144 点) | **64.9 GB/s**<br>**2.5 GB/s**<br>**10.66x** | 21.5 GB/s<br>0.7 GB/s<br>4.64x | 2.70 GB/s<br>0.3 GB/s<br>10.07x | Zstd:<br>5.9 GB/s<br>2.1 GB/s<br>13.16x |
| **物理单调波形、设备指标与稳态流** | 3 组 (3,072 点) | **40.5 GB/s**<br>**5.5 GB/s**<br>**27.40x** | 20.5 GB/s<br>0.9 GB/s<br>2.90x | 2.50 GB/s<br>0.3 GB/s<br>21.04x | Zstd:<br>2.1 GB/s<br>1.2 GB/s<br>10.21x |
### C++ ALP 测试机制与统计口径说明
- **C++ ALP 官方原版测试代码**：[cwida/ALP (bench_alp_encode.cpp)](https://github.com/cwida/ALP/blob/main/publication/source_code/bench_speed/bench_alp_encode.cpp)
- **评测复现 Fork 仓库**：[github.com/x-at-01/ALP](https://github.com/x-at-01/ALP)（评测分支：[feat/integrate-fastalp-benchmark](https://github.com/x-at-01/ALP/tree/feat/integrate-fastalp-benchmark) / [bench/self-eval](https://github.com/x-at-01/ALP/tree/bench/self-eval)）
- **统计口径统一与测试机制说明**：
- **核心算法保持官方原貌**：Fork 仓库未对 C++ ALP 的核心算法逻辑（`include/` 目录）做任何修改，保留官方实现的向量化与十进制反向映射逻辑。
- **端到端全流程与纯编码内核的双重口径统一**：
- **压缩纯编码（不含采样，原论文测试口径，C++ 5.4 GB/s vs fastalp 7.8 GB/s）**：<br>
C++ ALP 官方原版测试代码在测速计时循环外部调用了模型初始化，假设已预先获知最佳指数与因子，仅测量跳过采样后的纯浮点变换与位打包内核速度，在同机测得几何平均吞吐为 **5.4 GB/s**（算术均值 5.74 GB/s）；在此相同基准下，fastalp 压缩纯编码吞吐（不含采样）几何均值达到 **7.8 GB/s**（较 C++ 快 **1.46x**；算术均值达到 **9.01 GB/s**，较 C++ 快 **1.57x**）。
- **端到端全量流水线（真实写入口径，C++ 0.8 GB/s vs fastalp 2.1 GB/s）**：<br>
在真实时序写入时，新数据块无法预知模型参数，必须经历采样分析。为了公平衡量工程实际性能，我们在评测分支中将采样分析纳入计时循环。由于 C++ ALP 采用无剪枝的暴力穷举，采样阶段占用了 80% 以上的时间，其实际端到端几何平均吞吐测得为 **0.8 GB/s**（算术均值 0.80 GB/s）；fastalp 凭借三级级联剪枝机制（纯十进制早停、4/16 样本快筛、高熵早停），端到端压缩几何平均吞吐达到 **2.1 GB/s**（较 C++ 提速 **2.58x**；算术均值达到 **2.93 GB/s**，较 C++ 提速 **3.64x**）；在平稳流式命中状态化参数缓存时，纯编码吞吐可达 **15 ~ 24+ GB/s**。
- **解压性能（几何均值 25.3 GB/s vs 19.3 GB/s）**：<br>
得益于纯寄存器 SIMD 展开与 L1D 局部查表，fastalp 解压几何平均吞吐达到 **25.3 GB/s**，较 C++ ALP 的 **19.3 GB/s** 提速 **1.31x**（算术均值达到 **30.72 GB/s**，较 C++ 的 **19.69 GB/s** 提速 **1.56x**）。
- **37 项数据集全量无偏实测与一键复现**：
- 在 Fork 仓库中补充了 6 大典型工业场景，使 C++ ALP 在本物理机上完整跑完全量全部 37 个评测数据集（31 个论文公开数据集 + 6 个工业场景补充数据集）。
- 任何人均可克隆 [x-at-01/ALP](https://github.com/x-at-01/ALP)，通过 `cmake -B build && cmake --build build` 并在本地直接运行 `./build/benchmarks/bench_your_dataset`，同机复现评测数据。所有算法统一采用全量 37 项评测数据计算几何平均值，杜绝采样偏倚。fastalp 综合几何平均压缩比达到 **9.50x**（C++ ALP 为 **5.93x**）。
### 评测数据集全景与公开数据源
本评测采用 ALP 官方论文收录的全部 31 个公开时序与列存测试集，并补充 6 个典型工业场景样本（共 37 项基准），覆盖 6 大业务领域：
- **物联网与环境传感（11 项）**
- `neon_pm10_dust`：PM10 悬浮微粒粉尘浓度传感（μg/m³）· [NEON 官方生态观测网络](https://doi.org/10.48443/4E6X-V373)
- `neon_dew_point_temp`：气象露点温度连续观测时序（°C）· [NEON 官方生态观测网络](https://doi.org/10.48443/Z99V-0502)
- `neon_air_pressure`：大气海平面连续气压传感（kPa）· [NEON 官方生态观测网络](https://doi.org/10.48443/RXR7-PP32)
- `neon_wind_dir`：超声波气象风向角度传感（0-360°）· [NEON 官方生态观测网络](https://doi.org/10.48443/S9YA-ZC81)
- `neon_bio_temp_c`：红外土壤地表温度物理遥测（°C）· [NEON 官方生态观测网络](https://doi.org/10.48443/JNWY-B177)
- `basel_temp_f`：瑞士巴塞尔地表历史逐时气温（°C）· [Meteoblue 历史高精度气象观测数据库](https://www.meteoblue.com/en/weather/archive/export/basel_switzerland)
- `basel_wind_f`：瑞士巴塞尔观测站地表连续风速（km/h）· [Meteoblue 历史高精度气象观测数据库](https://www.meteoblue.com/en/weather/archive/export/basel_switzerland)
- `city_temperature_f`：全球主要城市日平均气温实测时序 · [Kaggle 全球城市气温历史基准集](https://www.kaggle.com/datasets/sudalairajkumar/daily-temperature-of-major-cities)
- `air_sensor_f`：高频空气质量多传感器监测阵列 · [CWI PublicBI 时序数据库公开基准](https://github.com/cwida/public_bi_benchmark)
- `arade4`：葡萄牙 Arade 水文站水尺高度监控 · [CWI PublicBI Arade 水文站观测数据](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/Arade/)
- `scene_sensor`：工业物联网十进制环境传感聚合基准（1024 点）· 真实物理传感多参数聚合切片
- **量化金融与资产行情（7 项）**
- `stocks_usa_c`：美股微秒级高频订单簿成交价时序 · [Zenodo 全球金融量化交易公开集](https://zenodo.org/record/3886895)
- `stocks_de`：德股法兰克福证券交易所交易成交价 · [Zenodo 全球金融量化交易公开集](https://zenodo.org/record/3886895)
- `stocks_uk`：英股伦敦证券交易所股票交易价格 · [Zenodo 全球金融量化交易公开集](https://zenodo.org/record/3886895)
- `bitcoin_f`：历史比特币美元交易指数时序 · [InfluxDB 官方比特币时序分析样本集](https://raw.githubusercontent.com/influxdata/influxdb2-sample-data/master/bitcoin-price-data/bitcoin-historical-annotated.csv)
- `bitcoin_transactions_f`：比特币区块链主网微秒级单笔转账金额 · [Blockchair 比特币主链转账流水](https://gz.blockchair.com/bitcoin/transactions/)
- `food_prices`：联合国粮农组织全球基础食品价格指数 · [联合国粮农与人道救援数据平台 (WFP)](https://data.humdata.org/dataset/wfp-food-prices)
- `scene_finance`：高频量化金融交易深度行情基准（1024 点）· 真实交易所逐笔撮合行情切片
- **地理测绘与轨迹跟踪（5 项）**
- `poi_lat`：全球兴趣点高精度地理纬度坐标 · [Kaggle POI 全球地理空间数据库](https://www.kaggle.com/datasets/ehallmar/points-of-interest-poi-database)
- `poi_lon`：全球兴趣点高精度地理经度坐标 · [Kaggle POI 全球地理空间数据库](https://www.kaggle.com/datasets/ehallmar/points-of-interest-poi-database)
- `bird_migration_f`：野生候鸟迁徙微秒级卫星 GPS 坐标 · [InfluxDB 候鸟迁徙高精地理时序追踪集](https://github.com/influxdata/influxdb2-sample-data/blob/master/bird-migration-data/bird-migration.csv)
- `nyc29`：纽约出租车连续营运 GPS 轨迹与计程 · [CWI PublicBI NYC 出租车地理时序数据库](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/NYC/)
- `scene_geo`：无人机航迹与连续经纬度测绘基准（1024 点）· 高精卫星轨迹与连续导航定位切片
- **医疗社保与公共卫生（5 项）**
- `medicare1`：门诊医疗保险理赔结算账单流水 · [CWI PublicBI Medicare 医疗卫生统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/Medicare3/)
- `medicare9`：专科就诊补贴与报销费用时序 · [CWI PublicBI Medicare 医疗卫生统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/Medicare3/)
- `cms1`：医疗保险供应商结算明细记录 · [CWI PublicBI CMSProvider 医疗保险数据库](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CMSprovider/)
- `cms9`：专科处方药品报销结算价格流水 · [CWI PublicBI CMSProvider 医疗保险数据库](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CMSprovider/)
- `cms25`：医疗设备使用与专科诊疗收费项目 · [CWI PublicBI CMSProvider 医疗保险数据库](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CMSprovider/)
- **公共政务与宏观经济（6 项）**
- `gov10`：财政预算与公共支出明细统计指标 · [CWI PublicBI CommonGovernment 统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CommonGovernment/)
- `gov26`：国家人口普查低熵常数序列流 · [CWI PublicBI CommonGovernment 统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CommonGovernment/)
- `gov30`：宏观经济运行指标与财政综合统计 · [CWI PublicBI CommonGovernment 统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CommonGovernment/)
- `gov31`：财政转移支付与地区扶持资金时序 · [CWI PublicBI CommonGovernment 统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CommonGovernment/)
- `gov40`：市政公用管网工程高精测绘与统计 · [CWI PublicBI CommonGovernment 统计集](https://homepages.cwi.nl/~boncz/PublicBIbenchmark/CommonGovernment/)
- `scene_macro`：宏观政务指标与公共医疗结算基准（1024 点）· 真实公共财政与医保综合报销切片
- **硬件存储与物理波形（3 项）**
- `ssd_hdd_benchmarks_f`：固态硬盘与机械硬盘连续 I/O 吞吐基准 · [Kaggle 存储设备吞吐实测数据库](https://www.kaggle.com/datasets/alanjo/ssd-and-hdd-benchmarks)
- `scene_ramp`：平滑升降坡道、连续物理量与单调时序（1024 点）· 工业 PID 调节、水文流量与连续步进计数器
- `scene_steady`：恒定传感、无故障零冗余与心跳流（1024 点）· 设备自检心跳流与高频常数工业监控
## 架构演进与优化全景
fastalp 并非简单的语言转译，而是在完整吸收 C++ ALP 论文精髓的基础上，针对现代多核流水线与时序数据库列存痛点重构的高性能压缩引擎。
### 参考与借鉴原版 ALP 的架构设计
在架构演进中，fastalp 完整保留并吸收了 C++ ALP 经数学严密证明的基础架构设计：
- **两级采样与自适应十进制推导**：<br>
用于自适应推导使编码位宽与异常代价综合最小的十进制缩放参数 `(exp, fac)`。<br>
完整继承并实现了原版 ALP 的两级采样架构思想：通过第一级粗粒度快速采样筛选高频候选组合，第二级细粒度向量采样精确定位最优指数与因子。
- **快速浮点整型舍入与向偶数舍入设计**：<br>
用于在浮点寄存器内无损完成紧凑整型化转换并避免分支预测惩罚。<br>
原版 ALP 利用 IEEE 754 双精度浮点常数偏置 `0x0018000000000000`（单精度 `12582912.0`），通过加减偏置在浮点单元内一步完成舍入；fastalp 深入研究其取值受限缺点（取值受限于 $[-2^{51}, 2^{51}]$），全面升级为现代硬件原生向偶数舍入指令（ARM64 `FRINTN` / x86 `ROUNDSD`），在保持无分支高吞吐的同时消除了大数值溢出隐患。
- **FOR 帧参考基准值消除**：<br>
用于消除整型序列中的偏置偏移量以收敛位打包位宽。<br>
继承原版的全局最小值消除机制，将有符号整数序列平移为从 0 开始的紧凑非负整数，显著减少位打包所需要的比特数。
- **状态化编码器与跨块参数缓存**：<br>
用于解决时序数据库连续写入时频繁重复采样的性能瓶颈。<br>
在工业时序流中，同一指标列（如温度）相邻数据块的量纲和精度具有高度连续性。fastalp 借鉴 C++ 跨块状态管理思想，支持跨 1024 元素数据块复用上一数据块探测出的指数 `exp` 与因子 `fac`。连续写入时直接跳过全部样本扫描，使连续压缩吞吐由 `4-5 GB/s` 跃升至 `15-24+ GB/s`。
---
### 自主研发的算法与性能优化
为了突破 C++ 原版的吞吐上限与时序压缩率瓶颈，fastalp 自主研发了以下核心架构优化：
- **自适应时序差分 Delta-ALP**：<br>
用于消除平滑物理时序波形大跨度基准导致的冗余位宽。<br>
原版实现仅支持静态全局最小值基准消除（FOR 模式），平滑时序物理波形（气象、水文、工业传感器）全局极值跨度大导致位宽偏宽。fastalp 引入相邻一阶差分与前缀和递推机制，配合前置 16 采样数学短路快筛（局部差分极值不优即瞬时早停），自适应收窄动态位宽 15% ~ 38%。
- **十进制精确除法重构 use_div**：<br>
用于消除 IEEE 754 乘法舍入误差导致的虚假异常点。<br>
原版实现仅采用浮点乘法反向缩放，受 IEEE 754 浮点乘法（如 `* 0.1`）无限循环二进制尾数截断误差影响，产生大量误判的虚假异常点（每点需额外消耗 80~128 位存储）。fastalp 引入十进制精确除法重构模式，将观测时序中因乘法舍入截断造成的虚假异常直接归零，数据点存储体积降低 20% ~ 38%。
- **智能离群点剪枝与 0-bit 稀疏常数压缩**：<br>
用于针对 99% 为 0.0 仅有极少突变脉冲的数据集（如财政公共支出 `gov30`），实现百倍压缩比。<br>
自动将少量脉冲离群值分离到异常字典中，主位流以 0-bit 存储，压缩体积从原版的 2100 字节降至 43 字节（压缩比突破 **150x**）。配合前 16 采样离群点快筛，高熵数据 2 个采样点即刻早停，零额外性能损耗。
- **异常点前值回填平滑机制**：<br>
用于消除原版全局固定值回填引发的差分阶跃尖峰与位宽发散。<br>
原版将异常点覆盖为全局首个非异常值，在时序差分模式下会引起前后相邻元素人工阶跃跳变，导致差分位宽急剧发散。fastalp 在差分与位打包前，将异常点自动用前一个有效整型值回填，消除人为差分抖动，保障差分压缩位宽保持极窄状态。
- **2-bit 长度标签极简自描述帧头与超大数组原生支持**：<br>
用于消除帧头冗余开销并打破 65,535 元素单块截断限制。<br>
采用 2-bit 长度标签自描述格式，标准 1024 元素满块头仅需 3 字节，RAW 保底模式仅需 1 字节；对于超过 65,535 元素的超大数组，自动升级为 32 位数量与异常偏移字段，无需人为分块截断即可实现单帧无损编码。
- **12.5% 异常上限与单字节 RAW 保底回退**：<br>
用于有效消除高熵浮点数（如高精 GPS 坐标、科学计算随机数）压缩时空间膨胀的负压缩隐患。<br>
当异常值数量超过 128 个（占 1024 元素的 12.5%）或压缩体积超过原始大小时，强制判定不可有效进行十进制变换，直接降级存储为单字节头部的 RAW 紧凑原始流，杜绝 C++ 原版中曾出现的 1.5x ~ 2.0x 体积膨胀。
- **单次比较全等快跳**：<br>
用于应对工业断线、设备待机与心跳常数流的高效瞬时压缩。<br>
在编码入口仅用 1 次 `slice[1] == slice[0]` 快速比对。非全等序列仅耗费 1 个 CPU 时钟周期即可退出；全等序列仅需 11 字节即可压缩 1024 元素（压缩比高达 **744x**）。
- **三级级联微架构采样剪枝流水线**：<br>
用于解决 C++ 原版暴力穷举导致采样耗时超 80%、端到端吞吐仅 0.80 GB/s 的核心瓶颈。<br>
首创三级级联剪枝机制：第 1 级（纯十进制早停）对 32 个采样点进行基础十进制验证，无异常即刻确定参数返回，避免探索后续 170 种乘除因子；第 2 级（4 样本与 16 样本快筛）在评估候选因子时优先以 4 样本探测，超阈值即刻剪枝淘汰，避免全量 32 样本遍历；第 3 级（高熵科学浮点全面早停）若基础十进制异常率达 100%，判定为不可压缩科学高熵数据，直接跳出全部因子枚举。端到端编码吞吐因此从 0.80 GB/s 提升至 **3.7 GB/s（几何平均 4.6x 提速，单场景最高达 7.0x）**；在同等压缩纯编码（不含采样）口径下，fastalp 达到 **6.0 GB/s（较 C++ 官方 5.5 GB/s 快 1.10x）**；在命中状态化参数缓存时，流式参数缓存吞吐可达 **15~24+ GB/s**。
- **纯寄存器 SIMD 自动向量化解压流水线**：<br>
用于突破传统查表解压的内存寻址延迟与缓存未命中惩罚。<br>
针对 8、16、32、64 等常见位宽，重构为零分支、纯寄存器的并行 SIMD 展开指令序列（利用 ARM NEON 与 x86 AVX2 硬件向量寄存器），消除 gather 内存间接读取与缓存停顿，几何平均解压吞吐达到 **27.0 GB/s**（超越 C++ ALP 的 20.0 GB/s，提速 1.35x）。
- **256 项栈上 L1D 局部查找表加速除法与小位宽**：<br>
用于消除循环体内耗费数十周期的硬件除法延迟与动态内存分配。<br>
针对 1、2、4 位小位宽以及十进制除法重构模式，在函数栈上直接构建 256 项局部查找表，数据 100% 常驻 CPU L1D 缓存，将原本几十个时钟周期的浮点硬件除法运算转化为单次纳秒级 L1D 查表。
- **8 路寄存器级熔合差分位打包**：<br>
用于消除差分压缩时 8KB 内存回写带来的内存带宽与缓存挤占开销。<br>
传统实现采用遍历计算差分写回 8KB 内存并读回做位打包的双 pass 模式。fastalp 独创 8 路寄存器熔合流水线：在读取相邻元素求差的同时，直接减去基准，并流水线移位推入 128 位寄存器累加器打包输出，全过程**零临时内存分配、零内存回写**，差分压缩吞吐提升 30% 以上。
- **数学前置短路差分快筛**：<br>
用于消除对无序或震荡数据无意义的全量一阶差分计算。<br>
基于数学定理局部子集的一阶极值跨度必小于等于全局极值跨度，在决定是否启用差分模式时，仅探测前 16 个采样点。若前 16 项的差分位宽已大于等于 FOR 基准位宽，则数学证明全局差分绝不可能更优，即刻早停跳出，避免了 90% 非平滑序列的全量差分扫描。
- **4 路流水线无闭包展开编码**：<br>
用于释放现代 CPU 超标量流水线的乱序执行与多算术逻辑单元（ALU）吞吐潜能。<br>
将核心采样与整型缩放循环全面消除动态闭包与间接跳转，特化为专用的 4 路展开指令流。连续 4 项无异常时走全寄存器极值更新路径，使压缩吞吐突破 **4.4~6.8 GB/s**。
- **栈缓冲融合与异常值单次批量提交**：<br>
用于避免动态扩容与堆内存碎片。<br>
解码与编码全程利用固定大小栈缓存；异常值位置索引与原始值在栈上定长组装后单次批量推入，将异常写出的系统开销降低 50%。
- **零堆分配流水线与内存缓冲区就地复用**：<br>
用于高频流式管道中避免 GC 与堆分配压力。<br>
对外统一提供 `compress_into` 与 `decompress_into` 接口，支持上层应用预分配并永久复用底层向量缓冲区，在海量流式写入中实现真正的**零额外堆内存分配**。
- **统一泛型零成本抽象与预计算常数表**：<br>
用于一套代码兼顾 `f64` 与 `f32`，避免代码膨胀与运行时分支开销。<br>
通过 `AlpFloat` 特征将双精度与单精度浮点运算统一为泛型流水线，配合编译期预计算的 10 的幂次表与逆乘数表，实现无额外开销的高效内联。
- **编译期常量级 64 路 8 元周期位解包与浮点重构内核**：<br>
用于消除通用位解包中 128 位变量移位指令膨胀与寄存器堆溢出。<br>
基于数学定理：任意位宽 $BW \in [1, 64]$ 下，每 8 个元素正好严格占据 $BW$ 个整字节（$8 \times BW / 8 = BW$）。fastalp 实现了覆盖 1~64 全位宽的编译期 const generics 单态化分发体系：小位宽（1, 2, 4）直通 L1D 预查表展开；规整位宽（8, 16, 32, 64）直通原生对齐/非对齐加载；$BW \le 56$ 的任意位宽全量在单次 64 位无符号读取内利用编译期折叠立即数完成解包与浮点缩放。解压吞吐跃升至 **28.1+ GB/s**，部分规整与单调数据集突破 **47 ~ 91 GB/s**。
- **ALP-RD 真实双精度 1024 块级直通流式解码（零中间缓冲拷贝）**：<br>
用于消除高低位解耦数据块微小分批切片与双重内存回写造成的性能断崖。<br>
针对真实双精度科学数据（如高精 GPS、物理仿真），淘汰旧版 64 元素切片与双重切片循环机制，重构为 1024 元素块级直通解码流水线：高位宽尾数（`right_parts`）直接单次解包流式写入目标裸指针内存，1-3 位高位字典索引一次性解包至 8KB 栈缓冲，随后利用硬件超标量并行单次原地原位合并 `dst[i] |= shifted_dict[...]`。极端高位宽数据集（如 `cms1`, `poi_lat`, `poi_lon`）解压吞吐从 3.7 GB/s 暴增近 3 倍至 **11.6+ GB/s**。
- **时序行程重复展开（expand_repeats）字级与字节级分支预测消除**：<br>
用于消除密集交替重复时序高频分支预测失败惩罚。<br>
原版依赖 64 位扫描与可变 `trailing_ones` / `bits >> run` 动态循环，在交替时序上引发大量 CPU 流水线冲刷。fastalp 重构为双层无分支架构：全零字与全壹字直接触发 64 元素原生 SIMD 拷贝或填充；混合字按字节展开（`0x00` 走 8 元素直通拷贝，`0xFF` 走 8 元素连写，其余按 8 步展开单周期条件递推），剔除全部动态移位与 `min` 边界计算，使重复密集型数据集（`food_prices`, `nyc29` 等）解压速度大幅提升 50% ~ 70%。
- **强类型紧凑枚举 ChunkType 零开销重构**：<br>
用于消除元数据解析阶段的字符串匹配与冗余类型分支。<br>
将压缩块自描述标识重构为底层严格紧凑的 `#[repr(u8)] pub enum ChunkType`，与二进制线缆协议实现 1:1 零成本无缝映射，保证编译期类型穷尽检查与完全内联的分支跳转。
- **统一解包消费器范式（AlpConsumer）与单趟差分解码融合**：<br>
用于消除差分时序数据解码时 8KB 栈缓冲往返拷贝与双重循环延迟。<br>
重构原版 C++ ALP 及旧版先解包整型差分至 8KB 临时栈缓冲、再单独循环计算前缀和并转换为浮点数的双重内存遍历模式。fastalp 抽象出通用单态化 `AlpConsumer` 流水线范式，实现单趟寄存器流式解码：在位解包内核循环体内，解出的每 8 个差分偏移量直接在 CPU 寄存器内进行前缀和累加，加基准后流水线转换为浮点数直接写入目标裸指针内存，全过程零栈缓冲分配、零中间内存回写与重读。差分典型数据集（如 `neon_air_pressure`）解压吞吐从 10.42 GB/s 跃升至 22.11 GB/s（提速 2.12x），所有 11 个 Delta 数据集吞吐全线上扬至 18 ~ 28 GB/s；全量 31 数据集算术平均解压吞吐正式突破 **30.34 GB/s**。
- **解包内核解耦重构与无栈溢出专业化分发**：<br>
用于消除单体巨型文件耦合与非优化 Debug 模式下 192 路单态化展开导致的栈帧溢出风险。<br>
将单体 1442 行位解包逻辑重构解耦为 `consumer.rs`、`decoder.rs`、`kernel.rs` 与顶层安全入口。将内层宏直接分发到独立专业化无内联膨胀的子内核（`unpack_1`, `unpack_2`, `unpack_4`, `unpack_8`, `unpack_16`, `unpack_32`, `unpack_64`, `unpack_le16`, `unpack_17_to_32`, `unpack_33_to_64`），外层分发函数标记为受控 `#[inline]`，使测试调用栈帧从数兆字节降至百字节以内，根治 macOS 默认 512KB 测试线程栈溢出隐患，兼顾模块复用与高吞吐性能。
- **全局展开、数组构造与位宽派发宏体系（`arr_8!`、`unroll_8!`、`write_8!`、`write_4!`、`match_pack_23!`）**：<br>
用于消除重复的手动索引偏移序列与冗长的多分支位宽分发匹配样板代码。<br>
抽象全局通用宏体系：`arr_8!` 与 `unroll_8!` 提供编译期 8 元素循环展开；`write_8!` 与 `write_4!` 在局部预绑定基础目标裸指针以杜绝表达式重复计算；`match_pack_23!` 基于块级编译期常量特化将 1 至 32 常用位宽的 23 分支模式匹配统一收敛，消除 120+ 行重复样板逻辑并保障编译内联。
- **打包与解包内核单次宽位加载优化（16 位 / 32 位 / 128 位 Load）**：<br>
用于消除细粒度解包时的逐元素分支判断与频繁的 CPU Load 端口争用。<br>
在 `unpack_2`、`unpack_4` 与 `unpack_16` 非查表分支中：`unpack_2` 直接以单次 `u16` 加载 8 个 2-bit 元素并纯位移提取；`unpack_4` 直接以单次 `u32` 加载 8 个 4-bit 元素并纯位移提取，消除切片构造与中间开销；`unpack_16` 将连续 8 个 16 位整数读合并为单次 `u128` 宽位加载，Load 端口压力骤降 87.5%，使常规规整序列解压吞吐跃升至 **30.34 GB/s**。
- **0 位宽常量填充向量化展开**：<br>
用于消除常数块逐元素写入对硬件向量化流水线的阻塞。<br>
在 `ForConsumer::consume_zeros` 中基于 `write_8!` 按 8 元素展开写入，余数逐个写入，使编译器自动生成 AVX2 或 NEON 向量广播存储指令，稀疏常数序列（如 `gov30`、`gov31`、`gov40`）解压吞吐跃升至 **90 ~ 93 GB/s**。
- **解压前缀和关键路径依赖延迟削减**：<br>
用于打破流水线循环累加的时钟周期依赖链瓶颈。<br>
在 `AlpDeltaConsumer` 中解耦当前累加器 `curr` 与内部差分总和计算，将时钟周期循环依赖关键路径由 2 周期缩短至 1 周期，增强 CPU 指令级并行度（ILP），平滑时序差分数据集解压吞吐维持在 **18 ~ 27 GB/s**。
- **裸指针未初始化内存安全写入与 Soundness 保证**：<br>
用于从机制上杜绝未初始化内存构造引用引发的未定义行为。<br>
在 `decompress_into`、`bitunpack_u64_raw` 与 `expand_repeats` 中全面采用裸指针预留与原地写入，在元素完全初始化写入后安全更新长度，完全消除在未初始化内存上构造切片引用的隐患，通过严苛的内存安全模型与静态检查。
## C 兼容接口与跨语言集成
`fastalp` 提供默认不启用的可选 C 兼容接口（FFI），便于集成到 C、C++、Python、Go 等多语言运行环境中。<br>
在未开启 `capi` 特性时，纯 Rust 构建不引入任何额外导出符号或运行时开销。
在 `Cargo.toml` 中按需启用特性：
```toml
[dependencies]
fastalp = { version = "0.1.38", features = ["capi"] }
```
构建独立的静态库（`libfastalp.a`）或动态库（`libfastalp.so` / `libfastalp.dylib`）：
```bash
cargo build --release --features capi
```
### 缓冲区容量预估与元素提取
调用方可预先计算最差情况下的缓冲区需求或提取压缩块元素数，确保不发生容量不足异常：
- `fastalp_count(src, src_len)`：从压缩字节流自描述头部以 O(1) 复杂度快速解析出包含的浮点元素总数，便于调用方按需预分配解压目标缓冲区。<br>
- `fastalp_max_compressed_size_f64(len)`：计算 `len` 个 `f64` 浮点数所需的最大目标缓冲区字节容量。<br>
- `fastalp_max_compressed_size_f32(len)`：计算 `len` 个 `f32` 浮点数所需的最大目标缓冲区字节容量。
### 线程局部流式接口
针对高吞吐时序场景提供的无状态流式接口，内部复用线程局部工作缓冲区，避免每次调用的堆内存分配：
- `fastalp_compress_f64(src, len, dst, dst_cap)`：压缩 `f64` 浮点数组（包含动态模型参数采样探测）。<br>
- `fastalp_compress_cached_f64(src, len, dst, dst_cap)`：复用已缓存模型参数执行纯编码内核，跳过采样开销。<br>
- `fastalp_decompress_f64(src, src_len, dst, dst_cap)`：解压字节流至 `f64` 浮点数组。<br>
- `fastalp_reset_encoder_f64()`：重置当前线程局部的 `f64` 编码器模型参数缓存。<br>
- 单精度浮点对应接口：`fastalp_compress_f32`、`fastalp_compress_cached_f32`、`fastalp_decompress_f32` 以及 `fastalp_reset_encoder_f32`。
### 独立实例句柄接口
适用于多线程工作池、按列维护独立编码状态的复杂系统集成：
- `fastalp_encoder_f64_new()`：在堆上创建新的 `f64` 状态化独立编码器实例。<br>
- `fastalp_encoder_f64_free(enc)`：释放由 `fastalp_encoder_f64_new` 分配的编码器实例。<br>
- `fastalp_encoder_f64_reset(enc)`：重置指定编码器句柄中的已缓存模型参数。<br>
- `fastalp_encoder_f64_compress(enc, src, len, dst, dst_cap)`：使用指定编码器句柄压缩 `f64` 浮点数组。<br>
- 单精度浮点对应句柄接口：`FastAlpEncoderF32`、`fastalp_encoder_f32_new`、`fastalp_encoder_f32_free`、`fastalp_encoder_f32_reset` 以及 `fastalp_encoder_f32_compress`。
## 更新日志
### v0.1.40
- **位解包架构解耦与单趟消费器融合**：<br>
将巨型位解包逻辑重构解耦为 `consumer.rs`、`decoder.rs`、`kernel.rs` 与顶层安全调度；抽象 `AlpConsumer` 消费流范式，实现 Delta 一阶差分寄存器树状前缀和累加与浮点重构单趟流式输出，省去 8KB 临时栈缓冲往返拷贝与双重遍历。
- **打包与解包内核宽位加载与指令流水线加速**：<br>
在 `unpack_2`、`unpack_4` 与 `unpack_16` 中淘汰逐元素分支与切片读取开销，分别升级为单次 `u16`、`u32` 与 `u128` 宽位加载与纯位移展开；在 `consume_zeros` 中实现基于 `write_8!` 的常数块向量化展开；在 `AlpDeltaConsumer` 中解耦累加器关键路径，将循环依赖延迟由 2 周期缩短至 1 周期。
- **全局展开与位宽分发宏体系**：<br>
引入 `src/macros.rs` 全局宏体系（`arr_8!`、`unroll_8!`、`write_8!`、`write_4!`、`match_pack_23!`），精简 23 分支打包样板代码，预绑定裸指针消除重复计算，消除 120+ 行冗余代码。
- **未初始化内存 Soundness 与 Clippy 零告警保障**：<br>
在 `decompress_into`、`bitunpack_u64_raw` 与 `expand_repeats` 中全面采用裸指针预留与原地写入，安全更新长度，完全消除在未初始化内存上构造切片引用的未定义行为（UB）隐患；规范全部绝对路径导入，确保 `-W clippy::absolute_paths` 零告警通过。
### v0.1.38
- **清理冗余死代码与位解包内核精简**：<br>
从 `bitpack/unpack.rs` 中彻底移除过时的历史兼容函数 `bitunpack_core` 与 `bitunpack_core_div`，将全部解包执行路径统一收敛至泛型调度内核；清理 `bitpack/mod.rs` 中多余的导入项与 `#[allow(unused_imports)]` 属性。
- **绝对路径规范与 Clippy 零告警对齐**：<br>
修复 `capi.rs` 与 `decoder/standard.rs` 中的 `-W clippy::absolute_paths` 路径规范提示，确保所有编译模式及可选特性组合下均维持 0 编译器与 Clippy 告警。
- **文档徽标与社区链接规范化**：<br>
统一 README 语言切换与生态状态徽标高度为 28px；在 Twitter 旁新增官方 Bluesky 社区徽标（`@webc-site`）；同步更新基准测试对比图与 C-API 依赖版本至 v0.1.38。
### v0.1.37
- **零成本抽象与解码内核统一去重重构**：<br>
抽象 `AlpDecoder<F>` 核心特质及单态化实现 `AlpFac1Decoder`（单位因子）、`AlpMulDecoder`（十进制乘法）与 `AlpDivDecoder`（十进制除法）；引入 `dispatch_decoder!` 编译期调度宏，消除标准与 Delta 解码内层批处理中的运行时分支判断；统一任意位宽通用位解包与反量化逻辑（`bitunpack_core_generic`），消除 800+ 行重复实现。
- **端到端综合压缩率跃升 +11.2%**：<br>
在 37 项公开及工业时序数据集上，压缩总体积从 104,465 字节降至 93,909 字节，净节省 10,556 字节（体积降低 10.1%，综合压缩率跃升 +11.2%）；放宽 Delta 一阶差分评估门限（`>= 4`）打通平滑时序通道，平滑时序数据集压缩比突破 431x；引入单调降序离群值剪枝与前值平滑回填，消除相邻跳变断崖，释放时序差分红利。
- **解码吞吐显著提升 +14.7%**：<br>
在现代硬件架构上，解码吞吐从 28.36 GB/s 进一步攀升至 32.53 GB/s（提升 +14.7%），端到端编码吞吐维持在 4.87 GB/s 极高水准。
- **全量代码双语注释与生产级工程规范达标**：<br>
核心模块（采样器、位解包、编码引擎、标准/差分解码器、C-API）实现全量中英文双语注释；魔法数字 100% 编译期常量化，消除冗余分支与内存分配；Clippy 零告警，全量 355 项单元测试与端到端往返无损测试 100% 通过。
### v0.1.36
- **对照 C++ 官方原版学术评测标准体系**：<br>
在全量 37 项公开及工业时序数据集上完成与 C++ ALP 官方原版（ACM SIGMOD 2024）的双口径严密对照评测，规范标注文档学术引用标准与测试代码源码行（[`bench_alp_encode.cpp#L88-L95`](https://github.com/cwida/ALP/blob/main/publication/source_code/bench_speed/bench_alp_encode.cpp#L88-L95)）。
- **压缩纯编码与端到端双口径性能校准**：<br>
校准压缩纯编码吞吐（不含采样，跳过采样分析）达到 6.0 GB/s，较 C++ ALP 官方原版（5.5 GB/s）提速 1.10x；端到端压缩吞吐达到 3.7 GB/s，较 C++ ALP（0.80 GB/s）提速 4.6x；全量解压吞吐达到 27.0 GB/s，较 C++ ALP（20.0 GB/s）提速 1.35x；综合几何平均压缩比达到 6.99x（较 C++ ALP 5.93x 领先 18%）。
- **评测代码与数据集完全开源可复现**：<br>
在 Fork 评测仓库（[`github.com/x-at-01/ALP`](https://github.com/x-at-01/ALP)）中提供 37 项数据集一键复现套件与自动化对比脚本。
### v0.1.35
- **解码裸指针内核与内存 Soundness 严格保障**：<br>
引入 `decompress_into_raw`、`decode_standard_raw` 与 `decode_delta_raw`，解码时直接向目标裸指针写出还原浮点数据，并在元素完全写入后安全更新长度，杜绝在未初始化内存上构造切片引用的未定义行为隐患；C API 解码接口无缝对接 C 语言调用方分配的未初始化缓冲区。
- **异常值补丁单遍流式迭代**：<br>
重构 `patch_exceptions`，改用 `chunks_exact` 替代循环内多次切片重算与隐式越界检查，直接通过裸指针更新异常槽位。
- **清理冗余死代码与硬件舍入指令对齐**：<br>
移除过时的模拟舍入魔数 `MAGIC_NUMBER`，全面基于标准库 `round_ties_even()`（硬件级 SSE4.1/AVX 与 ARM64 指令加速），保障 100% 浮点无损往返精度与高吞吐。
### v0.1.34
- **严苛代码规范与零编译器告警**：<br>
全面移除源码中全部 `#[allow(...)]` 属性，消除所有 Clippy 警告与死代码，通过严苛的代码审查规范。
- **结构体封装与架构解耦**：<br>
将编码参数（指数、乘数、异常值阈值、基准位宽等）完整封装入 `AlpParams` 结构体，消除裸元组传递；封装 `AlpHeader` 解析器，消除散落的魔数与手动位偏移，增强数据格式的演进安全性。
- **Bitpack 位打包内核优化与逻辑复用**：<br>
抽象并统一 8 元素循环打包内核 `pack_chunk_8`，消除各分支重复展开代码；优化 Delta 一阶差分解码器，利用树状归约消除逐元素链式依赖，提升 ILP（指令级并行度）。
- **评测基准精准校准与评测分支隔离**：<br>
优化 C++ ALP 基准评测对比数据提取逻辑，精准分离采样压缩吞吐（~0.85 GB/s）与纯内核压缩吞吐（~5.9 GB/s），准确校准 C++ 解码吞吐（~20.3 GB/s）；将向官方提交 PR 的分支与自用测试分支严格解耦隔离。
- **文档架构重构**：<br>
将中英文档结构拆分为 `readme/zh/` 与 `readme/en/` 独立目录，引入版本更新日志并自动生成多语言整合 README。
### v0.1.33
- 代码架构优化与性能微调。
### v0.1.32
- 状态化编码器 `Encoder` 文档与 Buffer 内存复用接口规范化。
### v0.1.31
- 新增可选 `capi` 特性，提供双语 C-API 接口与头文件支持，便于多语言（C/C++/Python）无缝集成。
### v0.1.30
- 明确标准 ALP 基线与定制算法压缩比对比；增强浮点极值与高精度时序数据压缩稳定性。