Readers

HDF5

read_hdf5(fpath, timestep=None)

Read a CFD HDF5 file into dict-of-arrays form.

Automatically detects the layout:

• Timestep groups -- /flow/00001/uvel, /flow/00002/uvel
• Flat flow group -- /flow/uvel (single timestep)
• Flat root -- /uvel (single timestep)

For multi-timestep files the flow dict uses integer keys::

{1: {"uvel": ndarray, ...}, 2: {"uvel": ndarray, ...}}

For single-timestep files (or when timestep is specified) the flow dict is flat::

{"uvel": ndarray, ...}

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the HDF5 file.	required
timestep	int | None	If given, read only this timestep from a multi-timestep file. Returns flat flow dict.	None

Returns:

Type	Description
Dataset	Tuple of (grid, flow, attrs) where:
Dataset	grid -- {"x": ndarray, ...}
Dataset	flow -- flat dict (single ts) or {int: dict} (multi ts)
Dataset	attrs -- scalar metadata from root attributes, plus "timesteps" listing available timestep indices when the file contains timestep groups

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.
KeyError	If timestep is given but not present in file.

Plot3D

read_plot3d(fpath)

Read a Plot3D grid file (ASCII or binary, 2-D or 3-D).

The file format is auto-detected by inspecting the first 4 bytes.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the .x file.	required

Returns:

Type	Description
Dataset	Tuple of (grid, flow, attrs):
Dataset	grid -- {"x": (nx, ny, nz), "y": ..., "z": ...}
Dataset	flow -- always {} (Plot3D grid files have no flow data)
Dataset	attrs -- empty dict

read_plot3d_flow(fpath)

Read a Plot3D solution file (ASCII or binary, 2-D or 3-D).

The file format is auto-detected by inspecting the first 4 bytes.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the .q file.	required

Returns:

Type	Description
Dataset	Tuple of (grid, flow, attrs):
Dataset	grid -- always {} (.q files have no grid data)
Dataset	flow -- {"dens": (ni,nj,nk), "xmom": ..., ...}
Dataset	attrs -- {"mach": float, "alpha": float, "re": float, "time": float}

Tecplot ASCII

read_tecplot_ascii(fpath)

Read a Tecplot ASCII .dat file.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the .dat file.	required

Returns:

Type	Description
Dataset	Dataset with a StructuredGrid.

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.
ValueError	If the header cannot be parsed.

Fortran Binary Sequential

FortranBinaryReader

Read files containing Fortran unformatted sequential records.

Each record is bracketed by 4-byte integer length markers (header and trailer). This is the default format produced by gfortran and most other Fortran compilers for FORM='UNFORMATTED', ACCESS='SEQUENTIAL'.

Parameters:

Name	Type	Description	Default
fname	str | PathLike[str]	Path to the binary file.	required
endianness	str	Byte order ("<" little-endian, ">" big-endian).	'<'
int_dtype	dtype	NumPy dtype for integer records.	int32
real_dtype	dtype	NumPy dtype for real-valued records.	float64

Example

Read a double-precision, little-endian grid file:

with FortranBinaryReader("grid.x") as reader:
    dims = reader.read_ints(expected_count=3)
    coords = reader.read_array_real(shape=(dims[0], dims[1], dims[2]))

Single-precision file with big-endian byte order:

with FortranBinaryReader(
    "grid.x",
    endianness=">",
    int_dtype=np.int32,
    real_dtype=np.float32,
) as reader:
    dims = reader.read_ints(expected_count=3)

read_string_fixed(length=64, encoding='ascii')

Read a fixed-length string record, strip trailing spaces, decode.

Parameters:

Name	Type	Description	Default
length	int	Expected byte length of the string record.	64
encoding	str	Character encoding.	'ascii'

Returns:

Type	Description
str	Decoded and right-stripped string.

read_ints(*, expected_count=None)

Read an integer record.

Parameters:

Name	Type	Description	Default
expected_count	int | None	If given, verify the number of integers read.	None

Returns:

Type	Description
ndarray	1-D integer array.

read_reals(*, expected_count=None)

Read a real-valued record.

Parameters:

Name	Type	Description	Default
expected_count	int | None	If given, verify the number of reals read.	None

Returns:

Type	Description
ndarray	1-D real array.

read_array_real(shape, *, fortran_order=True)

Read a real-valued array written as one record.

Parameters:

Name	Type	Description	Default
shape	tuple[int, ...]	Desired shape of the returned array.	required
fortran_order	bool	If True, interpret bytes as column-major (Fortran) order.	True

Returns:

Type	Description
ndarray	Array reshaped to shape.

skip_records(n=1)

Discard the next n Fortran records without returning data.

close()

Close the underlying file.

Binary Direct (split format)

BinaryHeader dataclass

Grid dimensions and metadata parsed from a header file.

Attributes:

Name	Type	Description
nx	int	Number of grid points in x.
ny	int	Number of grid points in y.
nz	int	Number of grid points in z.
nt	int	Number of timesteps.
np	int	Number of field variables (parameters).
var_names	list[str]	Variable names in ivar order (from the header file).
info_lines	list[str]	Free-form info lines from the header file.
timesteps	list[int]	Integer timestep indices from the header file.
precision	str	"float64" or "float32".

dtype property

NumPy dtype corresponding to the file precision.

bytes_per_value property

Bytes consumed by one scalar value on disk.

apply_byteswap(vals)

Byteswap vals if needed, caching the result for future calls.

read_header(fpath)

Read grid dimensions and metadata from a header file.

Parses both the minimal format (4 lines) and the extended format that includes variable names, info lines, and timestep indices.

Expected extended format::

 size of array:
 m3 =     1     m2 =   496     m1 =   245
 number of parameters =     6
 number of timesteps  =     1

 Information about file :   (  2  info lines )
 <info line 1>
 <info line 2>
 Information about parameters :
 pres
 temp
 uvel
 Numbers of timesteps :
          1

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the header file.	required

Returns:

Type	Description
BinaryHeader	Parsed header with grid dimensions and metadata.

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.

read_binary_direct(fpath, gpath, *, it=1)

Read IOS grid and flow binary files into dict-of-arrays form.

Reads the companion .cd header files to determine grid dimensions and variable names.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the flow binary file.	required
gpath	str | Path	Path to the grid binary file.	required
it	int	Timestep index (1-based). Default 1.	1

Returns:

Type	Description
dict[str, ndarray]	Tuple of (grid, flow, attrs) where:
dict[str, ndarray]	grid -- {"x": ndarray, "y": ndarray} each (nx, ny, nz)
dict[str, Any]	flow -- {"pres": ndarray, ...} each (nx, ny, nz)
tuple[dict[str, ndarray], dict[str, ndarray], dict[str, Any]]	attrs -- dict with "info_lines", "timesteps" if present in the .cd file

Raises:

Type	Description
FileNotFoundError	If any input file or its .cd companion is missing.
ValueError	If a .cd header does not contain variable names.

read_binary_direct_xy_plane(fpath, header, k, ivar, it)

Read an xy plane from a binary file.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the binary data file.	required
header	BinaryHeader	Parsed header from read_header.	required
k	int	Z-index (1-based).	required
ivar	int	Variable index (1-based).	required
it	int	Timestep index (1-based).	required

Returns:

Type	Description
ndarray	2-D array with shape (ny, nx).

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.
ValueError	If any index is out of range.

read_binary_direct_x_line(fpath, header, j, k, ivar, it)

Read a single x-line from an IOS binary file.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the binary data file.	required
header	BinaryHeader	Parsed header from read_header.	required
j	int	Y-index (1-based).	required
k	int	Z-index (1-based).	required
ivar	int	Variable index (1-based).	required
it	int	Timestep index (1-based).	required

Returns:

Type	Description
ndarray	1-D array with shape (nx,).

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.
ValueError	If any index is out of range.

read_binary_direct_xyz_volume(fpath, header, ivar, it)

Read a full 3-D volume for one variable from a binary file.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the binary data file.	required
header	BinaryHeader	Parsed header from read_header.	required
ivar	int	Variable index (1-based).	required
it	int	Timestep index (1-based).	required

Returns:

Type	Description
ndarray	3-D array with shape (nx, ny, nz).

Raises:

Type	Description
FileNotFoundError	If fpath does not exist.
ValueError	If any index is out of range.