Read/Write Examples
===================

The read/write helpers operate on in-memory text or bytes. They are intended for
application code that already has file contents in memory, for runner outputs,
or for tests that should not touch local paths.

Kraken Environment Round Trip
-----------------------------

.. literalinclude:: examples/readwrite_roundtrip.py
   :language: python
   :start-after: # -- kraken-env-start
   :end-before: # -- kraken-env-end

Read a Runner Output
--------------------

.. code-block:: python

   from at_py import read_modes_bin, read_shd_bin

   result = client.kraken(file_root="pekeris", inputs={"pekeris.env": env_text})

   if "pekeris.shd" in result.files:
       shade = read_shd_bin(result.files["pekeris.shd"])
       print(shade.pressure.shape)

   if "pekeris.mod" in result.files:
       modes = read_modes_bin(result.files["pekeris.mod"], freq=0.0)
       print(modes.num_modes)

MAT Files
---------

MATLAB ``.mat`` support is explicit, not auto-detected by binary/ASCII
dispatchers:

.. code-block:: python

   from at_py import load_mat_normalized, read_shd_from_mat

   bundle = load_mat_normalized(mat_bytes)
   print(bundle.format)
   print(sorted(bundle.variables))

   shade = read_shd_from_mat(mat_bytes, freq=50.0)

Use ``pip install 'oalib-at-py[mat]'`` or ``pip install -e '.[mat]'`` from a
checkout before calling MAT helpers.

Formatter Scope
---------------

Serializers return ``str`` or ``bytes``. They do not open paths and do not mirror
Matlab append-mode APIs such as ``fopen(..., 'at')``. If application code needs a
local file, write the returned value with the caller's own file policy.