Xarray-binfile

Custom Xarray file engine to handle raw binary files

• QA:

• Docs:

• Package:

• Meta:

Overview

Xarray-binfile is a Python package that integrates raw binary files with xarray. You provide the metadata that describes each binary file, and the package exposes those files through xarray datasets and data arrays with optional lazy chunking through Dask.

The package was first designed around binary outputs from the Fortran framework 2DECOMP&FFT and the CFD solver Xcompact3d, which is built on top of it. It is not limited to those ecosystems and can be used with any raw binary convention once the corresponding metadata mapping is provided.

It is aimed at workflows where raw binary files are part of an existing convention, such as simulation outputs or NumPy .tofile() dumps. Once opened, the data can be indexed, reduced, plotted, and computed with the usual xarray and Dask APIs.

See the documentation for end-to-end examples covering lazy loading, Dask-backed computations, task-graph visualization, writing derived results back to .bin files, parallel and larger-than-memory workflows, benchmarking on your own data, batch dtype conversion, probe time-series export to CSV, and quick matplotlib plots.

[!CAUTION] Raw binary files are machine- and convention-dependent. Differences such as little-endian vs big-endian byte order, word size, record layout, and memory ordering can change how bytes should be interpreted. Always verify dtype and endianness when sharing files across machines or toolchains.

Copyright and License

© 2025 Felipe N. Schuch. All content is under MIT License.