Cross-Platform Binary File Reader

Build a utility that reads binary groundwater model output files generated on different computer architectures, handling byte-order differences automatically.

Background

Groundwater modeling software generates binary output files containing numerical simulation results (hydraulic heads, flow rates, etc.). These files may be created on different computer systems with different byte orders (big-endian vs little-endian). Your task is to create a reader that can correctly interpret these files regardless of the platform where they were created.

Requirements

Binary File Format

The binary files follow this structure:

1. Header record (repeats for each time step):

   • kstp (4-byte integer): time step number
   • kper (4-byte integer): stress period number
   • pertim (4-byte float): elapsed time in current stress period
   • totim (4-byte float): total elapsed time
   • text (16-byte string): description text (e.g., 'HEAD')
   • ncol (4-byte integer): number of columns
   • nrow (4-byte integer): number of rows
   • ilay (4-byte integer): layer number

2. Data record (follows each header):

   • Array of floating-point values (size: ncol * nrow)
   • Values in row-major order

Implementation Tasks

1. Create a function detect_file_endianness(filename) that:

   • Opens a binary file
   • Attempts to read header information with both byte orders
   • Determines correct byte order by validating header values
   • Returns 'little' or 'big' indicating the detected byte order

2. Create a class BinaryFileReader that:

   • Takes a filename and optional precision parameter ('single' or 'double')
   • Automatically detects and handles byte-order differences
   • Provides a method get_data(idx=0) to retrieve data arrays by index
   • Provides a method get_times() to list all available time values
   • Validates that array dimensions are reasonable (e.g., between 1 and 100,000)

Validation Criteria

Your detection algorithm should validate that:

• Integer values (ncol, nrow, kstp, kper, ilay) are positive and reasonable (< 100,000)
• Float values (pertim, totim) are finite (not NaN or Inf)
• Text field contains valid ASCII characters

Test Cases

• Reading a little-endian binary file returns the correct array shape and values @test
• Reading a big-endian binary file returns the correct array shape and values @test
• The detect_file_endianness function correctly identifies little-endian format @test
• The detect_file_endianness function correctly identifies big-endian format @test
• Retrieved time values match expected simulation times @test

@generates

API

def detect_file_endianness(filename: str) -> str:
    """
    Detect byte order of a binary file.

    Args:
        filename: Path to binary file

    Returns:
        'little' or 'big' indicating detected byte order

    Raises:
        ValueError: If file format cannot be determined
    """
    pass

class BinaryFileReader:
    """
    Reader for cross-platform binary groundwater model files.
    """

    def __init__(self, filename: str, precision: str = 'single'):
        """
        Initialize reader with automatic byte-order detection.

        Args:
            filename: Path to binary file
            precision: 'single' or 'double' for float precision
        """
        pass

    def get_data(self, idx: int = 0) -> tuple:
        """
        Get data array for specified record index.

        Args:
            idx: Record index (0-based)

        Returns:
            tuple: (header_dict, data_array) where header_dict contains
                   metadata (kstp, kper, pertim, totim, text, ncol, nrow, ilay)
                   and data_array is a 2D numpy array of shape (nrow, ncol)
        """
        pass

    def get_times(self) -> list:
        """
        Get list of all simulation times in file.

        Returns:
            list: Simulation time values (totim from each record)
        """
        pass

Dependencies { .dependencies }

flopy { .dependency }

Provides utilities for reading and processing MODFLOW binary output files with cross-platform byte-order handling.