Port Status
===========

Current Scope
-------------

The Matlab ``ReadWrite`` reader matrix is implemented, and writer-style
``format_*`` ports cover the Matlab ``Matlab/ReadWrite/write*.m`` helpers. The
remaining differences are intentional design choices or demand-driven MAT v7.3
coverage.

* Public APIs use in-memory ``bytes`` or ``str`` rather than filename-based
  runtime parsing.
* Execution goes through ``ATClient`` -> ``AtRunnerBackend`` -> ``at-runner``.
* Read/write ports follow Matlab ``ReadWrite`` behavior and binary/text layout
  fidelity where a direct port exists.
* Optional MAT support lives behind the ``[mat]`` extra.

ReadWrite Readers
-----------------

.. list-table::
   :header-rows: 1
   :widths: 23 18 32 27

   * - Matlab file
     - Status
     - Python entry points
     - Notes
   * - ``read_env_core.m``
     - done
     - ``parse_env_core``, ``parse_env_core_bytes``
     - Fortran-aligned attenuation hooks, including ``L``, ``m``, and ``B``.
   * - ``read_env.m``
     - done
     - ``parse_read_env``, ``parse_read_env_bytes``
     - Dispatches by model to Kraken-family, Bellhop, Bellhop3D, or RAM parsers.
   * - ``read_bell.m``
     - done
     - ``parse_env_bellhop``, ``parse_env_bellhop3d``
     - Env-tail parsers are the canonical Python API.
   * - ``read_flp.m`` / ``read_flp3d.m``
     - done
     - ``parse_field_flp*``
     - FIELD and FIELD3D driver parsing.
   * - ``readvector.m``
     - done
     - ``read_fortran_vector``, ``parse_readvector_lines``
     - Includes a compatibility shorthand used by real fixtures.
   * - ``read_shd*.m`` / ``read_modes*.m``
     - done
     - ``read_shd*``, ``read_modes*``, MAT-specific entry points
     - Binary, ASCII, dispatcher, and supported MAT mappings.
   * - ``read_arrivals*.m``
     - done
     - ``read_arrivals*``
     - Binary/ASCII 2D and 3D arrivals plus dispatcher.
   * - ``read_ts.m``
     - done
     - ``read_ts*``, ``read_ts_from_mat``
     - ASCII time series and explicit MAT mapping.
   * - ``read_ram_tlgrid.m``
     - done
     - ``read_ram_tlgrid*``
     - RAM ``tl.grid`` with marker autodetection and truncation checks.
   * - ``readrc.m``, ``readpat.m``
     - done
     - ``read_rc*``, ``read_beam_pattern_bytes``
     - Reflection coefficients and beam patterns.
   * - ``readbty.m``, ``readati.m``, ``readbdry3d.m``
     - done
     - ``parse_bty*``, ``parse_ati*``, ``parse_bdry3d*``
     - 2D and 3D boundary inputs.
   * - ``readssp2d.m``, ``readssp3d.m``
     - done
     - ``parse_ssp2d*``, ``parse_ssp3d*``
     - SSPFIL grids.
   * - ``merge_shd_files.m``
     - done
     - ``merge_shd_mat_bytes``
     - Writes classic MAT format 5; requires ``[mat]``.

Folded Reader Helpers
---------------------

Some Matlab helpers are intentionally not separate top-level Python APIs because
they are only meaningful while reading a larger file from an open handle:

* ``readsxsy.m``, ``readszrz.m``, ``readr.m``, and ``readtheta.m`` are absorbed
  into Bellhop and Bellhop3D environment-tail parsing.
* ``readRcvrBearings.m`` is absorbed into ``parse_field_flp3d``.

ReadWrite Writers
-----------------

.. list-table::
   :header-rows: 1
   :widths: 24 14 31 31

   * - Category
     - Status
     - Python entry points
     - Notes
   * - Env core
     - done
     - ``format_env_core*``
     - Inline SSP and boundary formatting.
   * - Kraken-family tail
     - done
     - ``format_env_kraken*``
     - CMIN/CMAX, RMAX, source-depth and receiver-depth vectors.
   * - Bellhop / Bellhop3D
     - done
     - ``format_env_bellhop*``, ``format_env_bellhop3d*``
     - Full env file layout.
   * - Dispatch
     - done
     - ``format_parsed_env*``
     - Pairs with ``parse_read_env*`` for supported model names.
   * - FIELD 2D / 3D
     - done
     - ``format_field_flp*``, ``format_field_flp3d*``
     - Inverse of the FIELD parsers.
   * - Minimal Scooter ``.flp``
     - done
     - ``format_fields_flp*``
     - Minimal ``write_fieldsflp.m`` layout.
   * - Boundaries
     - done
     - ``format_bty*``, ``format_ati*``, ``format_bdry3d*``
     - 2D bathymetry/altimetry and 3D grids.
   * - Vectors
     - done
     - ``format_fortran_vector_data_line``, ``format_readvector_*``
     - Shared by env tails and FIELD drivers.
   * - SSPFIL
     - done
     - ``format_ssp2d*``, ``format_ssp3d*``
     - Interoperable with parsers; not byte-identical to Matlab formatting.
   * - RAM env
     - done
     - ``format_env_ram*``
     - Fortran ``ram.in`` layout.

Writer Gaps
-----------

``parse_read_env`` and ``format_parsed_env`` support the Kraken-family set,
``BELLHOP``, ``BELLHOP3D``, and ``RAM``. Matlab ``write_env.m`` also writes a
Bellhop-like tail for ``simplePE``, but Matlab ``read_env.m`` does not treat
``simplePE`` like ``BELLHOP`` for reading. ``at-py`` follows the read dispatch
set.

Serializers return text or bytes only. There is no API that mirrors Matlab
append mode for ``.env`` files.

MAT Support
-----------

``load_mat_normalized`` supports the documented subset needed by Acoustics
Toolbox workflows: classic MAT files through SciPy, MATLAB v7.3/HDF5 through
h5py, cells/references, uint16 char arrays, logical datasets, and CSC sparse
data including complex values.

High-level MATLAB types such as ``table``, ``timetable``, ``datetime``,
``string`` arrays, and SciPy ``MatlabOpaque`` intentionally fail loudly unless a
real AT workflow requires support.

Known Differences
-----------------

* Bellhop and Bellhop3D env content uses env-tail parser names rather than a
  separate ``read_bell`` shim.
* Parsers take in-memory content instead of Matlab filename or ``load`` flows.
* MAT files use separate entry points instead of magic detection in binary
  dispatchers.
* ``read_fortran_vector`` accepts an additional shorthand used by fixtures in
  this repository.