cfd-io

I/O toolkit for structured CFD data: read, write, and convert between formats.

Install

pip install cfd-io

Quick Start

from cfd_io import read_file, write_file, get_info

# inspect a file
info = get_info("flow.h5")
print(info.nx, info.ny, info.var_names)

# read data
grid, flow, attrs = read_file("flow.h5")

# write to a different format
write_file("flow.h5", grid, flow, attrs)

Features

• Unified API: read_file / write_file dispatch by file extension
• Format conversion: do_convert reads one format, writes another
• File inspection: get_info returns structured metadata without loading data
• CLI: cfd-io convert and cfd-io info for quick terminal use

CLI

# convert between formats
cfd-io convert grid.x grid.h5

# inspect a file
cfd-io info grid.h5

Testing

pytest tests/ --cov --cov-report=term-missing \
    --ignore=tests/test_tecplot_ascii.py \
    --ignore=tests/test_tecplot_binary.py \
    --ignore=tests/test_plt.py -q

Documentation

Full documentation: https://uahypersonics.github.io/cfd-io

Citation

If cfd-io contributes to published work, please cite the software release:

• DOI (concept, always latest): 10.5281/zenodo.18926271

GitHub also provides machine-readable citation metadata via CITATION.cff in this repository.

Code Style

This project follows established Python community conventions so that contributors can focus on the physics rather than inventing formatting rules.

Versioning & Releasing

This project uses Semantic Versioning (vMAJOR.MINOR.PATCH):

• MAJOR (v1.0.0, v2.0.0): Breaking API changes
• MINOR (v0.3.0, v0.4.0): New features, backward-compatible
• PATCH (v0.3.1, v0.3.2): Bug fixes, minor corrections

To publish a new version to PyPI:

1. Update the version in pyproject.toml
2. Regenerate the API architecture diagram:

   pydeps src/cfd_io --noshow --max-bacon=4 --cluster -o docs/assets/architecture.svg
   

3. Commit and push to main
4. Tag and push:

   git tag -a vMAJOR.MINOR.PATCH -m "Release vMAJOR.MINOR.PATCH"
   git push origin vMAJOR.MINOR.PATCH
   

Use a signed tag when your GPG/SSH signing is configured:

git tag -s vMAJOR.MINOR.PATCH -m "Release vMAJOR.MINOR.PATCH"
git push origin vMAJOR.MINOR.PATCH

The GitHub Actions workflow will automatically build and publish to PyPI via Trusted Publishing.

License

GNU General Public License v3.0 or later. See LICENSE for the complete license terms.