Platform compatibility and validation
This matrix separates implemented execution paths from testing evidence. The Linux CPU/NVIDIA, preliminary ROCm GAE, and experimental MPS statuses below are maintainer-reported. CPU CI scope is derived from the checked-in cross-platform workflow and its test sources. No hosted CI run was independently checked for this documentation update; “CI-tested” describes the reported CPU testing and configured coverage, not a claim that a particular revision’s run passed.
Training validation
The maintainer reports that model training has been tested on NVIDIA GPUs only. Training has not been tested on CPU, AMD ROCm, Apple MPS, Intel XPU, or any other backend. This records testing scope, not a claim that training on other backends is impossible.
The matrix below describes compression/decompression execution and residual correction validation. Extensive CPU inference testing and CPU CI coverage do not establish model-training validation on CPU. NGLR’s per-compression correction training is distinct from foundation-model training in this statement.
Compatibility matrix
Operating system |
Compute backend |
GAE |
LBRC |
NGLR |
Verification scope |
|---|---|---|---|---|---|
Linux |
CPU |
Extensively tested |
Extensively tested |
Experimental / limited validation |
Maintainer reports reliable GAE/LBRC in normal configurations; CPU CI also exercises both. |
Linux |
NVIDIA CUDA |
Extensively tested |
Extensively tested |
Experimental / limited validation |
Primary, most extensively tested GPU deployment; maintainer-reported use, separate from CPU CI. |
Windows |
CPU |
CI-tested |
CI-tested |
Not established by CI |
MSVC/Conda CPU workflow; Release assertions and model-cache exclusion limit coverage. |
Windows |
GPU |
Not verified |
Not verified |
Not verified |
No verified Windows GPU execution. |
macOS |
CPU |
CI-tested |
CI-tested |
Not established by CI |
CPU model export and Debug build in the workflow. |
macOS / Apple Silicon |
MPS |
Experimental / limited |
Not sufficiently verified |
Not sufficiently verified |
GAE has worked for selected, less stringent targets; more stringent targets remain insufficiently validated. |
Linux |
AMD ROCm |
Preliminary validation |
Testing in progress |
Not sufficiently verified |
Maintainer reports successful GAE GPU execution; LBRC result is not established. |
Backend-dependent OS |
Intel XPU |
Not verified |
Not verified |
Not verified |
Device/export path exists; verified end-to-end execution is not established. |
“Extensively tested” describes substantial use and testing, not a mathematical error guarantee for every input. “CI-tested” has the narrower scope described below. “Preliminary validation” describes selected execution evidence, not a representative dataset/error-target campaign. “Experimental / limited” and “Not sufficiently verified” require further numerical and compatibility checks. “Testing in progress” records a pending result. “Not verified” does not assert that an implementation is absent or that execution must fail.
NGLR is implemented but has more limited validation even on Linux CPU and NVIDIA; issues may occur. Keep it available as an API method without assuming parity with GAE and LBRC. See NGLR.
Inference, entropy coding, and model artifacts
CPU inference executes the compiled neural components through LibTorch on CPU. GAE and LBRC are established CPU implementations, not GPU-only methods.
Accelerator inference runs eligible tensor/model operations on the selected accelerator. It does not imply that every correction or coding operation runs there, or that every correction method is validated.
Entropy coding has CPU rANS and NVIDIA-specific custom CUDA rANS paths. CMake excludes ROCm from
CAESAR_HAS_CUDA_RANS, and the runtime guard excludesUSE_ROCM. ROCm exposes its device through PyTorch’scudaAPI but uses CPU entropy coding in place of NVIDIA CUDA rANS. CPU and MPS also use CPU entropy coding. This fallback does not establish ROCm LBRC or NGLR correctness.nvCOMP is an NVIDIA-specific lossless acceleration library, distinct from neural inference and rANS. Its use depends on build/runtime paths. Although optional in the broader architecture, the current NVIDIA CUDA CMake path requires nvCOMP 5.0.0.6, reusing an exact SDK or downloading it. Setting
CAESAR_DOWNLOAD_NVCOMP=OFFrequires a local SDK; it does not disable nvCOMP. Automatic download requires Linux x86_64 and CUDA 12. CPU/ROCm builds do not download it. See NVIDIA build instructions.
Export the model for the intended backend (cpu, cuda for NVIDIA/ROCm with the
appropriate PyTorch build, mps, or xpu). The device/export choices are
implementation paths, not equal compatibility promises. AOTI compilation and
required backend operations must work on the actual platform and PyTorch version.
The runtime reads the compiled installation’s device; changing a runtime flag
cannot retarget CPU artifacts to a GPU. An unavailable compiled backend raises
an error rather than automatically falling back to CPU. Constructors and the current CLI do not
accept a device override. Keep all three .pt2 packages and six probability
tables from the matching installation. See models.
MPS compatibility depends on PyTorch and available backend operations. Float64
input on MPS is explicitly rejected. CPU CI and a successful
torch.backends.mps.is_available() check do not establish MPS numerical accuracy.
CPU CI scope and limitations
The workflow downloads caesar_v2, checks registry/checkpoint metadata, and
exports a CPU model. Linux/macOS use Python 3.11 and Debug builds; Windows uses
Python 3.10 and Release. The configured PyTorch versions are Linux 2.9.0,
macOS 2.8.0, and Windows 2.12.0 (CPU installation for Windows/Linux).
These are workflow pins, not an assertion that every PyTorch version works.
All three jobs run test_caesarCD, test_runGaeCuda, test_padding,
test_model_metadata, test_LBRC, test_serialization, test_rans_kernels,
and CLI GAE/LBRC round trips. The generated float32 fixture has shape
1,1,20,256,256. Despite its name, test_runGaeCuda exercises CPU operations
in these CPU jobs. test_caesarCD measures GAE NRMSE at target 0.0001
(with float epsilon tolerance); the CLI checks GAE/LBRC NRMSE against 0.001
and verifies reconstructed byte counts. These selected tests do not exhaust
shapes, models, datasets, or error targets.
Windows differs from Linux/macOS:
test_model_cacheis explicitly skipped: multiple AOTI runners encounter a locked extracted.pydfile (Windows error 32).Release defines
NDEBUG, so assertion-based checks (including checks intest_LBRCand GAE unit tests) do not provide the same validation as Debug. The CLI still explicitly checks NRMSE and file sizes.Some PowerShell test steps invoke native executables without explicitly propagating
$LASTEXITCODE; a green job alone is weaker evidence than each test’s logs. Review individual outputs before claiming revision-level success.Windows runs the CLI shell test through Git for Windows Bash and adds PyTorch’s
libdirectory toPATHfor serialization/rANS and CLI tests.
test_NGLR is built but not invoked by these workflow jobs. The quick CLI test
intentionally excludes NGLR because of its per-compression training cost.
Serialization coverage of NGLR fields is not NGLR inference validation. The
standalone test_caesarC and test_caesarD binaries are also not invoked as
separate workflow steps. No accelerator CI job is defined here.
Windows CPU installation
Windows dependency installation is more involved than Linux, particularly for
CompressAI. Use the existing Windows workflow
as the executable reference. It uses windows-latest, Visual Studio MSVC x64
(discovered with vswhere), Miniconda environment compress_env with Python
3.10, CMake/NMake, Conda zstd, and CPU PyTorch. Do not substitute the POSIX
virtual environment or an assumed CompressAI pip-only recipe.
Install Git for Windows, Miniconda, and Visual Studio C++ Build Tools with the x64 compiler and Windows SDK. CI enables Windows long paths. Its short temporary/source directories (
D:\T,D:\cai) also avoid long build paths; adapt these to a writable local drive when reproducing locally.Create
compress_envwith Python 3.10. From PowerShell in the repository, reproduce the workflow’s filtering and CPU dependencies:conda create -n compress_env python=3.10 -y $lines = Get-Content requirements.txt | Where-Object { $_ -notmatch "^torch" -and $_ -notmatch "^torchvision" -and $_ -notmatch "^--extra-index-url" -and $_ -notmatch "^cupy" -and $_ -notmatch "^nvidia" -and $_ -notmatch "^compressai" -and $_ -notmatch "^imageio" -and $_ -notmatch "^\s*$" } $lines | Set-Content temp_requirements.txt conda run -n compress_env python -m pip install --upgrade pip wheel setuptools conda run -n compress_env python -m pip install --no-cache-dir -r temp_requirements.txt Remove-Item temp_requirements.txt conda run -n compress_env python -m pip install torch==2.12.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu conda install -n compress_env -y -c conda-forge cmake zstd
Build CompressAI from its source as CI does. The workflow clones its default branch without a commit pin, so dependency reproducibility is limited. It excludes
imageiofrom the initial requirements; despite the step name, it does not issue a separate explicit imageio installation command.$env:TEMP = "D:\T" $env:TMP = "D:\T" New-Item -ItemType Directory -Force -Path D:\T git clone https://github.com/InterDigitalInc/CompressAI.git D:\cai Push-Location D:\cai Get-ChildItem -Recurse -Filter "*.py" | ForEach-Object { $content = Get-Content $_.FullName -Raw -Encoding UTF8 if ($content -match '"-std=c\+\+17"' -or $content -match '"-O3"') { $content = $content -replace '"-std=c\+\+17"', '"/std:c++17"' $content = $content -replace '"-O3"', '"/O2"' Set-Content $_.FullName $content -Encoding UTF8 } } conda run -n compress_env python -m pip install pybind11 wheel setuptools conda run -n compress_env python setup.py bdist_wheel --dist-dir D:\cai\dist $wheel = Get-ChildItem D:\cai\dist\compressai-*.whl | Select-Object -First 1 conda run -n compress_env python -m pip install $wheel.FullName Pop-Location
Download/check the model and export under the MSVC environment. In CI,
$env:GITHUB_WORKSPACEis the checkout; locally set it to the repository root first. Check each native command’s exit code before proceeding.$env:GITHUB_WORKSPACE = (Get-Location).Path $env:CAESAR_MODEL_DIR = "$env:GITHUB_WORKSPACE\exported_model" $env:PYTHONPATH = $env:GITHUB_WORKSPACE conda run -n compress_env python model_registry.py caesar_v2 --output "$env:GITHUB_WORKSPACE\pretrained" conda run -n compress_env python tests/test_model_registry.py conda run -n compress_env python tests/check_registered_checkpoints.py $vsPath = & "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath $vcvars = Join-Path $vsPath "VC\Auxiliary\Build\vcvars64.bat" $python = (conda run -n compress_env python -c "import sys; print(sys.executable)").Trim() $selection = Join-Path $env:GITHUB_WORKSPACE "pretrained\selected_model.json" cmd /c "`"$vcvars`" && `"$python`" compile_model.py cpu --selection `"$selection`" --output `"$env:CAESAR_MODEL_DIR`""
CI requires nonempty
model_metadata.txt, all threecaesar_*.pt2packages (compressor, hyper-decompressor, decompressor), and the sixvbr_*/gs_*.bintables before CMake configuration.Configure and build using MSVC/NMake and the same environment’s Torch:
$TORCH_PATH = (conda run -n compress_env python -c "import torch; print(torch.utils.cmake_prefix_path)").Trim() New-Item -ItemType Directory -Force -Path build Push-Location build cmd /c "`"$vcvars`" && cmake .. -G `"NMake Makefiles`" -DCMAKE_PREFIX_PATH=`"$TORCH_PATH`" -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Release" cmd /c "`"$vcvars`" && cmake --build ." Pop-Location conda run -n compress_env python tests/gen_data.py build/tests --filename TCf48.bin.f32
Follow the workflow’s per-test working directories, DLL paths, output-directory
creation, MSVC setup for test_caesarCD.exe, and Git Bash invocation for CLI
round trips. The CLI executable is build/CAESAR/caesar_cli.exe. The model-cache
skip and Release limitations above remain applicable. This procedure documents
the checked-in CPU workflow; it does not verify Windows GPU execution.
Numerical accuracy and decoding portability
A requested NRMSE is a target whose achieved error must be checked against the original data. It is not an unconditional guarantee. Extensive CPU/NVIDIA testing does not remove the documented filtering failures, possible padding issues, GAE/LBRC block artifacts, or float32 precision limitations. Keep the recorded examples and unresolved hypotheses in known limitations.
GPU-generated compressed data is not currently guaranteed to decode correctly on CPU and can reconstruct garbled data. Latent indexes are regenerated by the hyper-decoder rather than serialized; matching probability tables are also required separately. A common serialization format or CPU-compatible rANS kernel test does not establish full cross-device numerical/entropy-decoding portability. Validate reconstruction and achieved error for the actual producer and consumer configurations.
Pending AMD LBRC evidence
AMD ROCm LBRC: Testing in progress. No success or failure result is recorded here. Preserve the CPU, NVIDIA, Apple, and Windows classifications unless new evidence directly warrants a change. Use the following record for each trial:
Field |
Value to record |
|---|---|
Software revision |
CAESAR commit and build options |
Hardware and OS |
GPU model, Linux distribution/version |
Runtime |
ROCm version, PyTorch version, relevant dependency versions |
Model |
Checkpoint name/identity/hash and export backend |
Input |
Dataset identifier, dimensions/axis order, dtype |
Correction |
LBRC settings and requested NRMSE |
Compression |
Success/failure, exit status, log location |
Decompression |
Success/failure, exit status, log location |
Reconstruction |
Expected/actual shape and byte count |
Accuracy |
Measured NRMSE against original data and whether target was met |
Record missing fields as unknown. Distinguish successful execution, shape preservation, and achieved accuracy. A single successful end-to-end trial may justify “Preliminary validation” for that configuration; it cannot establish comprehensive validation. On failure, record its conditions and keep compatibility under investigation. Stronger wording requires representative datasets and error targets. SoftwareX manuscript platform revisions remain deferred until this evidence has been reviewed; no conditional success claim belongs in the paper yet.