Skip to content

Commit 8a27042

Browse files
JiajunHuang1999JiajunHuang1999
committed
FSZ 1.0.0 is released
0 parents  commit 8a27042

30 files changed

Lines changed: 5934 additions & 0 deletions

‎.github/workflows/build.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Build verification across CUDA toolkits. GitHub-hosted runners have no
2+
# GPU, so this compiles the library, tool, examples, and tests but does not
3+
# execute them; execution tests (ctest) run on developer machines with a GPU.
4+
name: build
5+
6+
on:
7+
push:
8+
branches: [main]
9+
pull_request:
10+
workflow_dispatch:
11+
12+
jobs:
13+
cuda-build:
14+
runs-on: ubuntu-24.04
15+
strategy:
16+
fail-fast: false
17+
matrix:
18+
cuda: ["12.4.1", "12.8.1", "13.2.1"]
19+
container:
20+
image: nvidia/cuda:${{ matrix.cuda }}-devel-ubuntu22.04
21+
steps:
22+
- uses: actions/checkout@v4
23+
- name: Install build tools
24+
run: |
25+
apt-get update
26+
apt-get install -y --no-install-recommends cmake make g++ gfortran python3
27+
- name: Configure
28+
# No architecture override: CI compiles the library's defaults, which
29+
# is what a plain clone-and-build gets (sm_80;90, plus sm_100 and PTX
30+
# when the toolkit knows it).
31+
run: cmake -S . -B build
32+
- name: Build
33+
run: cmake --build build -j
34+
- name: Python package syntax check
35+
run: |
36+
python3 -m compileall python

‎.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
build/
2+
build_*/
3+
cmake-build/
4+
*.o
5+
*.a
6+
*.so
7+
*.fsz
8+
*.dec.f32
9+
*.log
10+
__pycache__/
11+
*.egg-info/
12+
dist/
13+
.pytest_cache/

‎CHANGELOG.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Changelog
2+
3+
All notable changes to FSZ are recorded here. Versions follow
4+
[semantic versioning](https://semver.org/): the stream format is part of the
5+
public interface, so any change that makes an existing `.fsz` file unreadable
6+
is a major version.
7+
8+
## [1.0.0] - 2026-08-07
9+
10+
First public release: the compressor described in the SC'26 paper
11+
*FSZ: Breaking the Prediction-Throughput Trade-off in GPU Lossy Compression*
12+
(arXiv:2607.15413).
13+
14+
- Strict pointwise absolute or relative error bound, float32 and float64.
15+
- Interfaces: the `fsz` command-line tool, C, C++, Python, and Fortran APIs.
16+
Fortran offers host-array and device-pointer entry points, so CUDA Fortran,
17+
OpenACC, and OpenMP codes can compress data already resident on the GPU.
18+
- The device-pointer calls accept a reusable workspace for repeated
19+
compression, or `NULL` for one-shot use.
20+
- Self-describing `.fsz` container recording shape, element type, and bound;
21+
bare bitstream mode for zero container overhead.
22+
- Quality reporting in the tool: PSNR and NRMSE on every round trip, windowed
23+
structural similarity with `--ssim`.
24+
- `pip install` builds and bundles the shared library when a CUDA toolkit is
25+
present.
26+
- CMake package export (`find_package(fsz)`), Makefile build, and a build
27+
matrix covering CUDA 12.4, 12.8, and 13.2, for GPU generations from Ampere
28+
on.

‎CMakeLists.txt‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
cmake_minimum_required(VERSION 3.18)
2+
3+
# Default GPU architectures. Users can override with
4+
# -DCMAKE_CUDA_ARCHITECTURES=... ; sm_100 (Blackwell) is appended
5+
# automatically when the CUDA toolkit is new enough to know it.
6+
if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
7+
set(CMAKE_CUDA_ARCHITECTURES 80 90)
8+
set(_fsz_default_archs ON)
9+
endif()
10+
11+
project(fsz LANGUAGES CXX CUDA VERSION 1.0.0)
12+
13+
if(_fsz_default_archs AND CMAKE_CUDA_COMPILER_VERSION VERSION_GREATER_EQUAL 12.8)
14+
list(APPEND CMAKE_CUDA_ARCHITECTURES 100)
15+
endif()
16+
17+
set(CMAKE_CXX_STANDARD 17)
18+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
19+
set(CMAKE_CUDA_STANDARD 17)
20+
set(CMAKE_CUDA_STANDARD_REQUIRED ON)
21+
22+
if(NOT CMAKE_BUILD_TYPE)
23+
set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
24+
endif()
25+
26+
find_package(CUDAToolkit REQUIRED)
27+
28+
option(FSZ_BUILD_SHARED "Also build the shared library (libfsz.so)" ON)
29+
option(FSZ_BUILD_TOOLS "Build the fsz command-line tool" ON)
30+
option(FSZ_BUILD_EXAMPLES "Build FSZ examples" ON)
31+
option(FSZ_BUILD_TESTS "Build FSZ tests" ON)
32+
33+
set(FSZ_SOURCES src/fsz.cu)
34+
35+
# Static library (the default link target, exported as fsz::fsz).
36+
add_library(fsz STATIC ${FSZ_SOURCES})
37+
add_library(fsz::fsz ALIAS fsz)
38+
39+
# Shared library for dynamic linking and the Python bindings.
40+
if(FSZ_BUILD_SHARED)
41+
add_library(fsz_shared SHARED ${FSZ_SOURCES})
42+
set_target_properties(fsz_shared PROPERTIES OUTPUT_NAME fsz)
43+
endif()
44+
45+
foreach(_fsz_lib IN ITEMS fsz fsz_shared)
46+
if(NOT TARGET ${_fsz_lib})
47+
continue()
48+
endif()
49+
target_include_directories(${_fsz_lib}
50+
PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
51+
$<INSTALL_INTERFACE:include>
52+
PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
53+
target_link_libraries(${_fsz_lib} PUBLIC CUDA::cudart)
54+
set_target_properties(${_fsz_lib} PROPERTIES
55+
CUDA_SEPARABLE_COMPILATION OFF
56+
POSITION_INDEPENDENT_CODE ON)
57+
target_compile_options(${_fsz_lib} PRIVATE
58+
$<$<COMPILE_LANGUAGE:CUDA>:-O3>)
59+
endforeach()
60+
61+
# Command-line tool: the binary is named `fsz`.
62+
if(FSZ_BUILD_TOOLS)
63+
add_executable(fsz_cli tools/fsz.cu)
64+
set_target_properties(fsz_cli PROPERTIES OUTPUT_NAME fsz)
65+
target_include_directories(fsz_cli PRIVATE tools)
66+
target_link_libraries(fsz_cli PRIVATE fsz::fsz)
67+
endif()
68+
69+
if(FSZ_BUILD_EXAMPLES)
70+
add_executable(fsz_example_roundtrip examples/example_roundtrip.cu)
71+
target_link_libraries(fsz_example_roundtrip PRIVATE fsz::fsz)
72+
73+
add_executable(fsz_example_hostptr examples/example_hostptr.cu)
74+
target_link_libraries(fsz_example_hostptr PRIVATE fsz::fsz)
75+
endif()
76+
77+
if(FSZ_BUILD_TESTS)
78+
enable_testing()
79+
add_executable(fsz_test_roundtrip tests/test_roundtrip.cu)
80+
target_link_libraries(fsz_test_roundtrip PRIVATE fsz::fsz)
81+
add_test(NAME roundtrip COMMAND fsz_test_roundtrip)
82+
83+
add_executable(fsz_test_hostptr tests/test_hostptr.cu)
84+
target_include_directories(fsz_test_hostptr PRIVATE src)
85+
target_link_libraries(fsz_test_hostptr PRIVATE fsz::fsz)
86+
add_test(NAME hostptr COMMAND fsz_test_hostptr)
87+
endif()
88+
89+
include(GNUInstallDirs)
90+
include(CMakePackageConfigHelpers)
91+
92+
# Fortran interface: built whenever a Fortran compiler is available.
93+
option(FSZ_BUILD_FORTRAN "Build the Fortran interface" ON)
94+
if(FSZ_BUILD_FORTRAN)
95+
include(CheckLanguage)
96+
check_language(Fortran)
97+
if(CMAKE_Fortran_COMPILER)
98+
enable_language(Fortran)
99+
add_library(fsz_fortran STATIC fortran/fsz.f90)
100+
target_link_libraries(fsz_fortran PUBLIC fsz::fsz stdc++)
101+
set_target_properties(fsz_fortran PROPERTIES
102+
Fortran_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/fortran_modules)
103+
target_include_directories(fsz_fortran INTERFACE
104+
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/fortran_modules>)
105+
if(FSZ_BUILD_EXAMPLES)
106+
add_executable(fsz_example_fortran fortran/example_fsz.f90)
107+
target_link_libraries(fsz_example_fortran PRIVATE fsz_fortran)
108+
endif()
109+
if(FSZ_BUILD_TESTS)
110+
add_executable(fsz_test_fortran fortran/test_fsz.f90)
111+
target_link_libraries(fsz_test_fortran PRIVATE fsz_fortran)
112+
add_test(NAME fortran COMMAND fsz_test_fortran)
113+
endif()
114+
install(TARGETS fsz_fortran
115+
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
116+
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/fortran_modules/fsz.mod
117+
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/fsz)
118+
else()
119+
message(STATUS "FSZ: no Fortran compiler found; skipping the Fortran interface")
120+
endif()
121+
endif()
122+
123+
install(TARGETS fsz EXPORT fszTargets
124+
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
125+
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
126+
if(FSZ_BUILD_SHARED)
127+
install(TARGETS fsz_shared EXPORT fszTargets
128+
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
129+
endif()
130+
if(FSZ_BUILD_TOOLS)
131+
install(TARGETS fsz_cli RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
132+
endif()
133+
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
134+
135+
install(EXPORT fszTargets
136+
FILE fszTargets.cmake
137+
NAMESPACE fsz::
138+
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fsz)
139+
140+
configure_package_config_file(cmake/fszConfig.cmake.in
141+
${CMAKE_CURRENT_BINARY_DIR}/fszConfig.cmake
142+
INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fsz)
143+
write_basic_package_version_file(
144+
${CMAKE_CURRENT_BINARY_DIR}/fszConfigVersion.cmake
145+
VERSION ${PROJECT_VERSION}
146+
COMPATIBILITY SameMajorVersion)
147+
install(FILES
148+
${CMAKE_CURRENT_BINARY_DIR}/fszConfig.cmake
149+
${CMAKE_CURRENT_BINARY_DIR}/fszConfigVersion.cmake
150+
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/fsz)

‎CONTRIBUTING.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Contributing to FSZ
2+
3+
Bug reports, questions, and patches are welcome.
4+
5+
## Reporting a problem
6+
7+
Please include:
8+
9+
- the GPU and its compute capability (`nvidia-smi --query-gpu=name,compute_cap --format=csv`),
10+
- the CUDA toolkit version (`nvcc --version`),
11+
- how FSZ was built (CMake or Makefile, and any options),
12+
- the element count, dimensions, element type, and error bound,
13+
- what you expected and what happened.
14+
15+
A reproducer that runs from the `fsz` tool is the most useful form, for example
16+
`fsz -i field.f32 -eb rel 1e-3 -d 512 512 512`. If the data cannot be shared, a
17+
synthetic array that shows the same behavior works just as well.
18+
19+
For anything that looks like wrong output, please say whether the error bound
20+
was respected: the tool prints `max_err` against the bound and exits 1 when the
21+
bound is violated.
22+
23+
## Building and testing
24+
25+
```bash
26+
cmake -S . -B build
27+
cmake --build build -j
28+
ctest --test-dir build --output-on-failure # requires a GPU
29+
```
30+
31+
The suites cover the C and C++ APIs (`roundtrip`, `hostptr`) and the Fortran
32+
interface (`fortran`). The Python tests run separately:
33+
34+
```bash
35+
PYTHONPATH=python python3 python/tests/test_fsz.py
36+
```
37+
38+
## What a change needs
39+
40+
FSZ is an error-bounded compressor, so correctness has a specific meaning and
41+
patches are held to it:
42+
43+
1. **The bound holds.** Every reconstructed value must be within
44+
`1.01 x` the absolute error bound, and no output may be non-finite. The
45+
1 percent slack absorbs float32 rounding at the last bit and nothing more.
46+
2. **The stream does not move unintentionally.** A change meant to affect only
47+
performance, memory, or the build must leave the compressed bytes identical.
48+
The quickest check is to compress a field before and after and compare
49+
checksums; `fsz -z -i field.f32 -o out.fsz -eb rel 1e-3` then `md5sum`.
50+
3. **Deliberate format changes are versioned.** The container carries a version
51+
field, and an existing `.fsz` file must keep decompressing. If it cannot,
52+
that is a major version.
53+
4. **New behavior comes with a test.** Add the case to the suite that covers the
54+
affected interface, and prefer a case that fails before the change.
55+
5. **Measurements are real.** If a change claims a speed or ratio improvement,
56+
include the numbers and the hardware they came from. Throughput figures are
57+
GPU compression and decompression rates on device-resident data.
58+
59+
## Style
60+
61+
- Follow the surrounding code: four-space indent, and the naming already in
62+
each file.
63+
- Comments explain why something is done, not what the line does.
64+
- Keep the public headers free of implementation detail; `src/fsz_internal.cuh`
65+
is where format constants live.
66+
67+
## License
68+
69+
Contributions are accepted under the BSD 3-Clause license that covers the
70+
project. See `LICENSE`.

‎LICENSE‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2026, University of South Florida
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice,
10+
this list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
3. Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23+
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24+
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25+
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26+
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27+
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28+
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29+
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30+
POSSIBILITY OF SUCH DAMAGE.

0 commit comments

Comments
 (0)