Read/write parsers

This page documents the full at_py.readwrite package: binary and ASCII parsers, format writers, and MAT helpers re-exported from submodules. It complements the API reference page, which focuses on the client, runner, and core types.

class at_py.readwrite.AltimetryRead(interp_type: str, range_m: ndarray, depth_m: ndarray, tangent_u: ndarray, normal_u: ndarray, segment_length_m: ndarray, segment_curvature: ndarray, tangent_node_u: ndarray | None, normal_node_u: ndarray | None)[source]

Bases: object

2D sea-surface altimetry from an .ati file (ranges in m after km→m).

depth_m: ndarray

interp_type: str

normal_node_u: ndarray | None

normal_u: ndarray

range_m: ndarray

segment_curvature: ndarray

segment_length_m: ndarray

tangent_node_u: ndarray | None

tangent_u: ndarray

class at_py.readwrite.BathymetryRead(interp_type: str, range_m: ndarray, depth_m: ndarray, tangent_u: ndarray, normal_u: ndarray, segment_length_m: ndarray, segment_curvature: ndarray, tangent_node_u: ndarray | None, normal_node_u: ndarray | None)[source]

Bases: object

2D bathymetry from a .bty file (ranges in m after km→m).

depth_m: ndarray

interp_type: str: L piecewise-linear or C curvilinear (first letter).

normal_node_u: ndarray | None: Node normals for C; None for L.

normal_u: ndarray: Outward unit normal, shape (2, nseg).

range_m: ndarray

segment_curvature: ndarray: Curvature dφ/ds on each segment; zero for L.

segment_length_m: ndarray

tangent_node_u: ndarray | None: Node tangents for C (curvilinear); None for L.

tangent_u: ndarray: Unit tangent along each segment, shape (2, nseg) (range, depth).

class at_py.readwrite.Bdry3DRead(interp_type: str, x_km: ndarray, y_km: ndarray, z_km: ndarray)[source]

Bases: object

3D grid: x_km, y_km, depths z_km shaped (n_y, n_x) (readbdry3d).

interp_type: str: R piecewise-linear or C curvilinear (first letter, padded like Matlab).

x_km: ndarray

y_km: ndarray

z_km: ndarray

class at_py.readwrite.BeamPatternRead(n_points: int, angle_deg: ndarray, power_linear: ndarray)[source]

Bases: object

power_linear is 10 ** (dB / 20) per Matlab readpat.

angle_deg: ndarray

n_points: int

power_linear: ndarray

class at_py.readwrite.Bellhop3DEnvTail(source_x_m: ndarray, source_y_m: ndarray, source_z_m: ndarray, receiver_z_m: ndarray, receiver_range_km: ndarray, receiver_theta_deg: ndarray, beam: BellhopBeamParams)[source]

Bases: object

Bellhop3D tail: readsxsy, readszrz, readr, readtheta, read_bell.

beam: BellhopBeamParams

receiver_range_km: ndarray

receiver_theta_deg: ndarray

receiver_z_m: ndarray

source_x_m: ndarray

source_y_m: ndarray

source_z_m: ndarray

class at_py.readwrite.BellhopBeamParams(run_type: str, nbeams: int, ibeam: int | None, alpha_deg: ndarray, nbeta: int | None, beta_deg: ndarray | None, deltas_m: float, box_z_m: float, box_r_km: float | None, box_x_km: float | None, box_y_km: float | None, beam_type_ms: str | None, epmult: float | None, r_loop: float | None, n_image: int | None, ib_win: int | None)[source]

Bases: object

Bellhop control block from read_bell.m (partial — omits unused globals).

alpha_deg: ndarray

beam_type_ms: str | None

beta_deg: ndarray | None

box_r_km: float | None

box_x_km: float | None

box_y_km: float | None

box_z_m: float

deltas_m: float

epmult: float | None

ib_win: int | None

ibeam: int | None

n_image: int | None

nbeams: int

nbeta: int | None

r_loop: float | None

run_type: str

class at_py.readwrite.BellhopEnvTail(source_z_m: ndarray, receiver_z_m: ndarray, receiver_range_km: ndarray, beam: BellhopBeamParams)[source]

Bases: object

Post-core Bellhop 2D: readszrz + readr + read_bell.

beam: BellhopBeamParams

receiver_range_km: ndarray

receiver_z_m: ndarray

source_z_m: ndarray

class at_py.readwrite.BioLayer(z1: float, z2: float, f0: float, q: float, a0: float)[source]

Bases: object

Biological layer for Fortran AttenMod volume B (dB/km resonance parameters).

a0: float

f0: float

q: float

z1: float

z2: float

class at_py.readwrite.EnvCore(title: str, freq_hz: float, ssp: SSP, bdry: Bdry)[source]

Bases: object

Common .env header: title, frequency, and full SSP plus boundary section.

bdry: Bdry

freq_hz: float

ssp: SSP

title: str

class at_py.readwrite.FieldFlp3DResult(title: str, opt: str, component: str, m_limit: int, source_x_m: ndarray, source_y_m: ndarray, n_sx: int, n_sy: int, source_z_m: ndarray, receiver_z_m: ndarray, receiver_range_m: ndarray, r_min_m: float, r_max_m: float, theta_deg: ndarray, node_x_m: ndarray, node_y_m: ndarray, mode_file_names: tuple[str, ...], elt_nodes: ndarray)[source]

Bases: object

In-memory field3d driver parameters from a .flp file (read_flp3d.m).

component: str

elt_nodes: ndarray: Shape (3, n_elts), 1-based node indices as in the file.

m_limit: int

mode_file_names: tuple[str, ...]

n_sx: int

n_sy: int

node_x_m: ndarray

node_y_m: ndarray

opt: str

r_max_m: float

r_min_m: float

receiver_range_m: ndarray

receiver_z_m: ndarray

source_x_m: ndarray

source_y_m: ndarray

source_z_m: ndarray

theta_deg: ndarray

title: str

class at_py.readwrite.FieldFlpResult(title: str, opt: str, component: str, m_limit: int, r_prof_km: ndarray, n_prof: int, receiver_range_m: ndarray, source_z_m: ndarray, receiver_z_m: ndarray, range_offset_m: ndarray, n_range_offset: int)[source]

Bases: object

In-memory field driver parameters from a .flp file.

component: str: Comp from Opt(3) (1-based), default P.

m_limit: int

n_prof: int

n_range_offset: int

opt: str: Normalized option string (length ≥ 4 after Matlab defaults).

r_prof_km: ndarray

range_offset_m: ndarray

receiver_range_m: ndarray

receiver_z_m: ndarray

source_z_m: ndarray

title: str

class at_py.readwrite.KrakenEnvTail(c_low: float, c_high: float, r_max_km: float, source_z: ndarray, receiver_z: ndarray)[source]

Bases: object

Options after read_env_core for KRAKEN/SCOOTER/SPARC/BOUNCE (Matlab read_env.m).

c_high: float

c_low: float

r_max_km: float

receiver_z: ndarray

source_z: ndarray

class at_py.readwrite.MatBundle(variables: dict[str, Any], source_format: Literal['mat_classic', 'mat_v7_3'], raw_backend: str, scipy_meta: dict[str, Any] | None = None)[source]

Bases: object

Normalized top-level MATLAB variables.

raw_backend: str

scipy_meta: dict[str, Any] | None = None

source_format: Literal['mat_classic', 'mat_v7_3']

variables: dict[str, Any]

class at_py.readwrite.ModeHalfspace(bc: str, cp: complex128, cs: complex128, rho: float32, depth: float32)[source]

Bases: object

Top/bottom acoustic half-space coefficients from binary .mod (Matlab Top/Bot).

bc: str

cp: complex128

cs: complex128

depth: float32

rho: float32

class at_py.readwrite.ModesAscReadResult(lrecl: int, title: str, freq: float, nmedia: int, ntot: int, nmat: int, num_modes: int, z: ndarray, k: ndarray, phi: ndarray)[source]

Bases: object

Parsed ASCII .mod (Matlab read_modes_asc).

freq: float

k: ndarray

lrecl: int

nmat: int

nmedia: int

ntot: int

num_modes: int

phi: ndarray

title: str

z: ndarray

class at_py.readwrite.ModesReadResult(title: str, nfreq: int, nmedia: int, ntot: int, nmat: int, n_per_medium: ndarray, mater: list[bytes], depth: ndarray, rho: ndarray, freq_vec: ndarray, z: ndarray, num_modes: int, top: ModeHalfspace, bot: ModeHalfspace, phi: ndarray, k: ndarray)[source]

Bases: object

Parsed .mod contents for one frequency block.

bot: ModeHalfspace

depth: ndarray

freq_vec: ndarray

k: ndarray

mater: list[bytes]

n_per_medium: ndarray

nfreq: int

nmat: int

nmedia: int

ntot: int

num_modes: int

phi: ndarray

rho: ndarray

title: str

top: ModeHalfspace

z: ndarray

class at_py.readwrite.ParsedEnvBellhop(core: EnvCore, tail: BellhopEnvTail)[source]

Bases: object

Full 2D Bellhop .env: SSP/core plus Bellhop tail (sources, receivers, beam block).

core: EnvCore

tail: BellhopEnvTail

class at_py.readwrite.ParsedEnvBellhop3D(core: EnvCore, tail: Bellhop3DEnvTail)[source]

Bases: object

Full Bellhop3D .env: core plus 3D source/receiver grids and beam block.

core: EnvCore

tail: Bellhop3DEnvTail

class at_py.readwrite.ParsedEnvKraken(core: EnvCore, tail: KrakenEnvTail)[source]

Bases: object

Full .env parse for the KRAKEN-family tail section.

core: EnvCore

tail: KrakenEnvTail

class at_py.readwrite.ParsedEnvRAM(title: str, freq_hz: float, zs_m: float, zr_m: float, rmax_m: float, dr: float, ndr: int, zmax: float, dz: float, ndz: int, zmplt: float, c0: float, n_pade: int, n_starter: int, rs: float, bathy_r_m: ndarray, bathy_z_m: ndarray, segments: tuple[RamSegment, ...])[source]

Bases: object

Parsed RAM ram.in (inverse of Matlab write_env_RAM.m for canonical output).

bathy_r_m: ndarray

bathy_z_m: ndarray

c0: float

dr: float

dz: float

freq_hz: float

n_pade: int

n_starter: int

ndr: int

ndz: int

rmax_m: float

rs: float

segments: tuple[RamSegment, ...]

title: str

zmax: float

zmplt: float

zr_m: float

zs_m: float

class at_py.readwrite.RamSegment(rp_m: float | None, z_m: ndarray, c_m: ndarray, sediment_cp: float, rho: float, attn_z_m: ndarray, attn_alpha: ndarray)[source]

Bases: object

One range-dependent SSP block (Matlab write_env_RAM inner loop).

attn_alpha: ndarray

attn_z_m: ndarray

c_m: ndarray

rho: float

rp_m: float | None

sediment_cp: float

z_m: ndarray

class at_py.readwrite.RamTlGridPos(s_z: float, r_z: ndarray, r_r: ndarray)[source]

Bases: object

Vertical source depth and receiver depth/range grids for RAM tl.grid (meters).

r_r: ndarray

r_z: ndarray

s_z: float

class at_py.readwrite.RamTlGridResult(plot_title: str, plot_type: str, freq: float, atten: float, pos: RamTlGridPos, tl_db: ndarray, pressure_amp: ndarray)[source]

Bases: object

RAM transmission-loss grid: TL (dB) and derived linear amplitude on a 2-D grid.

atten: float

freq: float

plot_title: str

plot_type: str

pos: RamTlGridPos

pressure_amp: ndarray

tl_db: ndarray

class at_py.readwrite.ReflectionCoeffRead(n_points: int, theta: ndarray, r: ndarray, phi_rad: ndarray)[source]

Bases: object

Angles in radians (phi converted from degrees as in Matlab).

n_points: int

phi_rad: ndarray

r: ndarray

theta: ndarray

class at_py.readwrite.SSP2DRead(n_prof: int, nssp: int, r_prof_km: ndarray, cmat: ndarray)[source]

Bases: object

2D sound-speed field: cmat is (NSSP, NProf); r_prof_km has length NProf.

cmat: ndarray

n_prof: int

nssp: int

r_prof_km: ndarray

class at_py.readwrite.SSP3DRead(nx: int, ny: int, nz: int, segx_km: ndarray, segy_km: ndarray, segz_km: ndarray, cmat: ndarray)[source]

Bases: object

3D SSP cube cmat shape (Nz, Ny, Nx) (Matlab cmat(iz,:,:) is Ny``×``Nx).

cmat: ndarray

nx: int

ny: int

nz: int

segx_km: ndarray

segy_km: ndarray

segz_km: ndarray

class at_py.readwrite.ShdAscResult(plot_title: str, plot_type: str, freq_vec: ndarray, freq0: float, atten: float, theta: ndarray, source_z: ndarray, receiver_z: ndarray, receiver_r: ndarray, pressure: ndarray)[source]

Bases: object

ASCII shade file (port of Matlab read_shd_asc.m).

atten: float

freq0: float

freq_vec: ndarray

plot_title: str

plot_type: str

pressure: ndarray

receiver_r: ndarray

receiver_z: ndarray

source_z: ndarray

theta: ndarray

class at_py.readwrite.ShdPos(theta: ndarray, s: ShdPosS, r: ShdPosR, nsx: int, nsy: int, nsz: int, nrz: int, nrr: int, ntheta: int, nfreq: int)[source]

Bases: object

Axes and counts for binary .shd / read_shd_bin geometry (see Matlab Pos).

nfreq: int

nrr: int

nrz: int

nsx: int

nsy: int

nsz: int

ntheta: int

r: ShdPosR

s: ShdPosS

theta: ndarray

class at_py.readwrite.ShdReadResult(title: str, plot_type: str, freq_vec: ndarray, freq0: float, atten: float, pos: ShdPos, pressure: ndarray)[source]

Bases: object

Binary shade file payload: metadata, grids in pos, and complex pressure field.

atten: float

freq0: float

freq_vec: ndarray

plot_type: str

pos: ShdPos

pressure: ndarray

title: str

class at_py.readwrite.TsPos(r: TsPosR)[source]

Bases: object

Nested position struct matching Matlab Pos (here only receiver depths).

r: TsPosR

class at_py.readwrite.TsPosR(z: ndarray)[source]

Bases: object

Receiver depth vector for time-series output (meters, float64).

z: ndarray

class at_py.readwrite.TsReadResult(plot_title: str, pos: TsPos, tout: ndarray, rts: ndarray)[source]

Bases: object

ASCII time-series file: title, receiver depths, time vector, and RTS matrix.

plot_title: str

pos: TsPos

rts: ndarray

tout: ndarray

at_py.readwrite.format_ati(interp_type: str, range_km: ndarray, depth_m: ndarray) → str[source]

Format a 2D Bellhop .ati file (inverse of parse_ati() for tabulated nodes).

range_km and depth_m are internal file points only (km / meters), not the synthetic ±1e50 endpoints appended on read.

at_py.readwrite.format_ati_bytes(interp_type: str, range_km: ndarray, depth_m: ndarray, *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_ati().

at_py.readwrite.format_ati_from_read(a: AltimetryRead) → str[source]: Serialize altimetry using internal nodes from AltimetryRead (round-trip helper).

at_py.readwrite.format_bdry3d(b: Bdry3DRead) → str[source]: Format a Bellhop3D 3D boundary file (inverse of parse_bdry3d()).

at_py.readwrite.format_bdry3d_bytes(b: Bdry3DRead, *, encoding: str = 'utf-8') → bytes[source]: Like format_bdry3d() encoded to bytes.

at_py.readwrite.format_bty(interp_type: str, range_km: ndarray, depth_m: ndarray) → str[source]

Format a 2D Bellhop .bty file (inverse of parse_bty() for tabulated nodes).

range_km and depth_m are the internal file points only (km horizontal, depth positive down in meters), not the synthetic ±1e50 endpoints that parse_bty() appends when reading.

interp_type is 'L' (piecewise linear) or 'C' (curvilinear).

at_py.readwrite.format_bty_bytes(interp_type: str, range_km: ndarray, depth_m: ndarray, *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_bty().

at_py.readwrite.format_bty_from_read(b: BathymetryRead) → str[source]: Serialize bathymetry from BathymetryRead internal nodes (round-trip helper).

at_py.readwrite.format_env_bellhop(p: ParsedEnvBellhop) → str[source]: Format a 2D Bellhop .env (inverse of parse_env_bellhop()).

at_py.readwrite.format_env_bellhop3d(p: ParsedEnvBellhop3D) → str[source]: Format a Bellhop3D .env (inverse of parse_env_bellhop3d()).

at_py.readwrite.format_env_bellhop3d_bytes(p: ParsedEnvBellhop3D, *, encoding: str = 'utf-8') → bytes[source]: Like format_env_bellhop3d() encoded to bytes.

at_py.readwrite.format_env_bellhop_bytes(p: ParsedEnvBellhop, *, encoding: str = 'utf-8') → bytes[source]: Like format_env_bellhop() encoded to bytes.

at_py.readwrite.format_env_core(core: EnvCore) → str[source]: Format the core .env block (Matlab write_env / writessp core section).

at_py.readwrite.format_env_core_bytes(core: EnvCore, *, encoding: str = 'utf-8') → bytes[source]: Like format_env_core() encoded to bytes.

at_py.readwrite.format_env_kraken(p: ParsedEnvKraken) → str[source]: Format a KRAKEN-family .env (inverse of at_py.readwrite.env.parse_env_kraken()).

at_py.readwrite.format_env_kraken_bytes(p: ParsedEnvKraken, *, encoding: str = 'utf-8') → bytes[source]: Like format_env_kraken() encoded to bytes.

at_py.readwrite.format_env_ram(p: ParsedEnvRAM) → str[source]: Serialize RAM ram.in (inverse of parse_env_ram() for canonical Matlab layout).

at_py.readwrite.format_env_ram_bytes(p: ParsedEnvRAM, *, encoding: str = 'utf-8') → bytes[source]: Like format_env_ram() encoded to bytes.

at_py.readwrite.format_field_flp(r: FieldFlpResult) → str[source]

Format a FIELD 2D .flp file (inverse of parse_field_flp()).

Receiver range offsets must be zero (same restriction as the reader).

at_py.readwrite.format_field_flp3d(r: FieldFlp3DResult) → str[source]: Format a FIELD3D .flp file (inverse of parse_field_flp3d()).

at_py.readwrite.format_field_flp3d_bytes(r: FieldFlp3DResult, *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_field_flp3d().

at_py.readwrite.format_field_flp_bytes(r: FieldFlpResult, *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_field_flp().

at_py.readwrite.format_fields_flp(receiver_range_km: ndarray | Sequence[float]) → str[source]

Minimal Scooter-style FIELD .flp text (Matlab write_fieldsflp.m).

Emits the 'RP' option and one line with rMin, rMax (km), and NRr from min(Pos.r.r), max(Pos.r.r), and length(Pos.r.r). This is not the full FIELD driver from read_flp / write_fieldflp.m; use format_field_flp() for that.

at_py.readwrite.format_fields_flp_bytes(receiver_range_km: ndarray | Sequence[float], *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_fields_flp().

at_py.readwrite.format_fortran_vector_data_line(nx: int, x: ndarray | Sequence[float]) → str[source]: Emit one data line for a readvector block (inverse of read_fortran_vector()).

at_py.readwrite.format_parsed_env(parsed: ParsedEnvKraken | ParsedEnvBellhop | ParsedEnvBellhop3D | ParsedEnvRAM) → str[source]: Serialize a full .env from parse_read_env().

at_py.readwrite.format_parsed_env_bytes(parsed: ParsedEnvKraken | ParsedEnvBellhop | ParsedEnvBellhop3D | ParsedEnvRAM, *, encoding: str = 'utf-8') → bytes[source]: UTF-8 (or other) bytes for format_parsed_env().

at_py.readwrite.format_readvector_block(nx: int, x: ndarray | Sequence[float]) → tuple[str, str][source]: Emit count line and data line for a Matlab readvector block.

at_py.readwrite.format_readvector_lines(nx: int, x: ndarray | Sequence[float]) → str[source]: Two-line readvector section (count, then data), newline-separated.

at_py.readwrite.format_ssp2d(s: SSP2DRead) → str[source]

Format a 2D SSPFIL text (inverse of parse_ssp2d()).

Emits NProf, profile ranges (km), then sound speeds in the same flat order the parser expects (column-major block then transpose to cmat).

at_py.readwrite.format_ssp2d_bytes(s: SSP2DRead, *, encoding: str = 'utf-8') → bytes[source]

at_py.readwrite.format_ssp3d(s: SSP3DRead) → str[source]: Format a 3D SSPFIL text (inverse of parse_ssp3d()).

at_py.readwrite.format_ssp3d_bytes(s: SSP3DRead, *, encoding: str = 'utf-8') → bytes[source]

at_py.readwrite.load_mat_normalized(data: bytes) → MatBundle[source]

Load .mat bytes and return a normalized MatBundle.

Raises ImportError with install instructions if optional dependencies for the detected format are missing.

at_py.readwrite.load_mat_normalized_path(path: str | bytes | PathLike[str]) → MatBundle[source]: Load a .mat file from disk (convenience; reads entire file into memory).

at_py.readwrite.merge_shd_mat_bytes(mats: list[bytes]) → bytes[source]

Merge several broadband SHD .mat buffers into one (Matlab merge_shd_files).

Input buffers must each contain the variables PlotTitle, atten, Pos, freq0, freqVec, pressure, and PlotType (as produced by Acoustics Toolbox). atten, Pos, and PlotType must match across inputs; receiver grid dimensions (all pressure axes except frequency) must agree.

Frequencies from all inputs are concatenated, checked for duplicates, then sorted ascending with pressure rows permuted to match (same as Matlab).

Output format: SciPy savemat format 5 (MATLAB v7 compatible), not HDF5 v7.3—Matlab’s merge_shd_files uses -v7.3 for large files; use this merged file with read_shd_from_mat / load_mat_normalized the same way as classic MAT.

Requires optional dependency SciPy (pip install 'oalib-at-py[mat]').

at_py.readwrite.omni_beam_pattern() → BeamPatternRead[source]: Omni-directional default when Matlab SBP ~= '*' (two endpoints, 0 dB).

at_py.readwrite.parse_ati(text: str, *, min_depth_m: float | None = None) → AltimetryRead[source]

Parse a 2D Bellhop .ati file (Matlab readati).

Ranges in the file are km; returned range_m is in m. Endpoints use ±1e50 m as in Matlab.

If min_depth_m is set (e.g. depth of the first tabulated SSP point), any altimetry shallower than that raises ValueError (Matlab: altimetry above first SSP).

at_py.readwrite.parse_ati_bytes(data: bytes, *, encoding: str = 'utf-8', min_depth_m: float | None = None) → AltimetryRead[source]: Like parse_ati() after decoding data with encoding.

at_py.readwrite.parse_bdry3d(text: str) → Bdry3DRead[source]: Parse a Bellhop3D 3D boundary file (Matlab readbdry3d).

at_py.readwrite.parse_bdry3d_bytes(data: bytes) → Bdry3DRead[source]: Parse 3D boundary from UTF-8 text bytes.

at_py.readwrite.parse_bty(text: str, *, max_depth_m: float | None = None) → BathymetryRead[source]

Parse a 2D Bellhop .bty file (Matlab readbty).

Ranges in the file are km; returned range_m uses m (×1000), matching readbty. Endpoints at ±1e50 m are appended as in Matlab.

If max_depth_m is set (e.g. last SSP depth), bathymetry deeper than that raises ValueError, matching readbty.

at_py.readwrite.parse_bty_bytes(data: bytes, *, encoding: str = 'utf-8', max_depth_m: float | None = None) → BathymetryRead[source]: Like parse_bty() after decoding data with encoding.

at_py.readwrite.parse_env_bellhop(text: str) → ParsedEnvBellhop[source]: Parse a 2D Bellhop .env (Matlab read_env with model='BELLHOP').

at_py.readwrite.parse_env_bellhop3d(text: str) → ParsedEnvBellhop3D[source]: Parse a Bellhop3D .env (Matlab read_env with model='BELLHOP3D').

at_py.readwrite.parse_env_bellhop3d_bytes(data: bytes, *, encoding: str = 'utf-8') → ParsedEnvBellhop3D[source]: Like parse_env_bellhop3d() after decoding data with encoding.

at_py.readwrite.parse_env_bellhop_bytes(data: bytes, *, encoding: str = 'utf-8') → ParsedEnvBellhop[source]: Like parse_env_bellhop() after decoding data with encoding.

at_py.readwrite.parse_env_core(text: str) → EnvCore[source]

Parse the core .env structure (port of Matlab read_env_core.m).

This is intended as a faithful, filesystem-free parser. It is line-oriented, matching Matlab’s fscanf + fgetl pattern.

Lines after the core block (e.g. KRAKEN CMIN/CMAX, RMAX, source/receiver depths) are ignored. Use parse_env_kraken() to read those.

at_py.readwrite.parse_env_core_bytes(data: bytes, *, encoding: str = 'utf-8') → EnvCore[source]: Like parse_env_core() after decoding data with encoding.

at_py.readwrite.parse_env_kraken(text: str) → ParsedEnvKraken[source]

Parse a full .env including the KRAKEN-family tail (Matlab read_env).

After read_env_core() Matlab reads cInt (CMIN/CMAX), RMax, then at_py.readwrite.vector.parse_readvector_lines() twice for source and receiver depths (readszrz).

Applies to models using that block: KRAKEN, SCOOTER, SPARC, BOUNCE, etc. (see Matlab read_env.m).

at_py.readwrite.parse_env_kraken_bytes(data: bytes, *, encoding: str = 'utf-8') → ParsedEnvKraken[source]: Like parse_env_kraken() after decoding data with encoding.

at_py.readwrite.parse_env_ram(text: str) → ParsedEnvRAM[source]: Parse RAM ram.in (canonical Matlab write_env_RAM layout with ! comments).

at_py.readwrite.parse_env_ram_bytes(data: bytes, *, encoding: str = 'utf-8') → ParsedEnvRAM[source]: Like parse_env_ram() but decodes data first.

at_py.readwrite.parse_field_flp(text: str) → FieldFlpResult[source]

Parse FIELD .flp text (Matlab read_flp.m).

Receiver ranges in the file are km; results use meters for ranges (read_flp ×1000). Profile ranges r_prof_km stay in km as in the file.

at_py.readwrite.parse_field_flp3d(text: str) → FieldFlp3DResult[source]

Parse FIELD3D .flp text (Matlab read_flp3d.m).

Horizontal coordinates and receiver ranges in the file are km; results use meters. Trailing lines after the triangular mesh block are ignored (extended FIELD3D inputs).

at_py.readwrite.parse_field_flp3d_bytes(data: bytes, *, encoding: str = 'utf-8') → FieldFlp3DResult[source]: Like parse_field_flp3d() after decoding data with encoding.

at_py.readwrite.parse_field_flp_bytes(data: bytes, *, encoding: str = 'utf-8') → FieldFlpResult[source]: Like parse_field_flp() after decoding data with encoding.

at_py.readwrite.parse_read_env(text: str, model: str) → ParsedEnvKraken | ParsedEnvBellhop | ParsedEnvBellhop3D | ParsedEnvRAM[source]

Parse a full environmental file for the given AT model (Matlab read_env).

Dispatches to parse_env_kraken(), parse_env_bellhop(), parse_env_bellhop3d(), or parse_env_ram() according to model (case-insensitive), matching the branches in read_env.m plus RAM ram.in.

at_py.readwrite.parse_read_env_bytes(data: bytes, model: str, *, encoding: str = 'utf-8') → ParsedEnvKraken | ParsedEnvBellhop | ParsedEnvBellhop3D | ParsedEnvRAM[source]: Like parse_read_env() but decodes data with encoding first.

at_py.readwrite.parse_readvector_lines(lines: list[str], i: int) → tuple[ndarray, int, int][source]

Port of Matlab readvector.m using pre-split lines.

The count is taken from lines[i] (first integer), data from lines[i+1].

Returns:: length-Nx vector nx: requested count (matches x.size) i_next: index of first line after the readvector block
Return type:: x

at_py.readwrite.parse_ssp2d(text: str) → SSP2DRead[source]

Parse a 2D SSPFIL (Matlab readssp2d).

Layout: integer NProf, NProf range values (km), then a flat block of NProf * NSSP sound speeds read into [NProf, NSSP] column-wise and transposed to [NSSP, NProf].

at_py.readwrite.parse_ssp2d_bytes(data: bytes) → SSP2DRead[source]: Parse 2D SSPFIL from UTF-8 text bytes.

at_py.readwrite.parse_ssp3d(text: str) → SSP3DRead[source]

Parse a 3D SSPFIL (Matlab readssp3d).

For each depth index iz, one Nx``×``Ny block is read column-wise (Matlab fscanf(..., [Nx, Ny])), then transposed into cmat(iz, :, :).

at_py.readwrite.parse_ssp3d_bytes(data: bytes) → SSP3DRead[source]: Parse 3D SSPFIL from UTF-8 text bytes.

at_py.readwrite.read_arrivals(data: bytes | str, *, file_type: Literal['bin', 'asc'] | None = None, encoding: str = 'utf-8') → Arrivals2D | Arrivals3D[source]: Dispatch arrivals parsing (binary vs ASCII) for in-memory payloads.

at_py.readwrite.read_arrivals_asc(data: str | bytes, *, encoding: str = 'utf-8') → Arrivals2D | Arrivals3D[source]: Parse Bellhop/Bellhop3D ASCII arrivals (port of read_arrivals_asc.m).

at_py.readwrite.read_arrivals_asc_bytes(data: bytes, *, encoding: str = 'utf-8') → Arrivals2D | Arrivals3D[source]: Like read_arrivals_asc() for UTF-8 (or other) encoded bytes.

at_py.readwrite.read_arrivals_bin(data: bytes) → Arrivals2D | Arrivals3D[source]: Parse Bellhop/Bellhop3D binary arrivals file bytes (port of read_arrivals_bin.m).

at_py.readwrite.read_arrivals_bytes(data: bytes, *, file_type: Literal['bin', 'asc'] | None = None, encoding: str = 'utf-8') → Arrivals2D | Arrivals3D[source]: Like read_arrivals() for bytes input only.

at_py.readwrite.read_beam_pattern_bytes(data: bytes) → BeamPatternRead[source]: Parse .sbp bytes: count N, then N rows of angle_deg, power_dB.

at_py.readwrite.read_fortran_vector(nx: int, spec_line: str) → ndarray[source]

Parse one line after the count (Nx), emulating readvector.m.

Supports / termination:

Nx > 2 with two values a b / → linspace(a, b, Nx)
Nx > 2 with one value a / → full(Nx, a)
Nx <= 2 or explicit list → Nx floats from the line

at_py.readwrite.read_modes(data: bytes | str, *, freq: float = 0.0, modes: list[int] | None = None, file_type: Literal['mod', 'moa'] | None = None, encoding: str = 'utf-8') → ModesReadResult | ModesAscReadResult[source]

Dispatch mode parsing like Matlab read_modes.m for in-memory payloads.

file_type='mod': binary read_modes_bin
file_type='moa': ASCII read_modes_asc
file_type=None: infer from payload type/content (bytes->binary first, str->ASCII).

at_py.readwrite.read_modes_asc(data: str | bytes, *, modes: list[int] | None = None, encoding: str = 'utf-8') → ModesAscReadResult[source]

Parse Kraken ASCII mode file text (Matlab read_modes_asc.m).

modes lists 1-based mode indices to keep (default: all modes in the file).

at_py.readwrite.read_modes_asc_bytes(data: bytes, *, modes: list[int] | None = None, encoding: str = 'utf-8') → ModesAscReadResult[source]: Like read_modes_asc() for encoded bytes.

at_py.readwrite.read_modes_bin(data: bytes, freq: float, *, modes: list[int] | None = None) → ModesReadResult[source]

Parse Kraken binary mode file bytes (port of Matlab read_modes_bin).

modes uses 1-based mode indices, matching Matlab (e.g. [1, 2, 3]). If omitted, all modes at the selected frequency are returned.

Use freq=0 when the file contains a single frequency (Matlab convention).

at_py.readwrite.read_modes_bytes(data: bytes, *, freq: float = 0.0, modes: list[int] | None = None, file_type: Literal['mod', 'moa'] | None = None, encoding: str = 'utf-8') → ModesReadResult | ModesAscReadResult[source]: Like read_modes() for bytes input only.

at_py.readwrite.read_modes_from_mat(data: bytes, freq: float, *, modes: list[int] | None = None) → ModesReadResult[source]

Port of Matlab read_modes.m for .mod.mat (load provides Modes).

Expects a variable Modes matching Kraken/Krakel-style saves (see krakelM.m): title, Nfreq, Nmedia, N, depth, Mater, rho, freqVec, z, M, Top, Bot, k, phi.

modes uses 1-based indices like read_modes_bin().

Multi-frequency .mod.mat files must store eigenvectors and wavenumbers in a stacked layout so the nearest frequency to freq can be selected (same idea as Matlab read_modes_bin):

phi with shape (nmat, M, Nfreq)
k with shape (M, Nfreq) or (Nfreq, M)

Modes.M may be a scalar (same M at every frequency) or a vector of length Nfreq (mode count per frequency). Single-frequency files keep the Krakel-style 2-D phi and 1-D k.

at_py.readwrite.read_ram_tlgrid(data: bytes) → RamTlGridResult[source]: Parse RAM binary tl.grid bytes (Matlab read_ram_tlgrid).

at_py.readwrite.read_ram_tlgrid_bytes(data: bytes) → RamTlGridResult[source]: Alias of read_ram_tlgrid() (symmetry with other *_bytes APIs).

at_py.readwrite.read_rc_brc_bytes(data: bytes) → ReflectionCoeffRead[source]: Alias for a bottom .brc file (same parser as read_rc_bytes()).

at_py.readwrite.read_rc_bytes(data: bytes) → ReflectionCoeffRead[source]

Parse one top (.trc) or bottom (.brc) reflection coefficient file.

Format: integer N, then N lines of theta, R, phi with phi in degrees (converted to radians like Matlab readrc).

at_py.readwrite.read_rc_trc_bytes(data: bytes) → ReflectionCoeffRead[source]: Alias for a top .trc file (same parser as read_rc_bytes()).

at_py.readwrite.read_shd(data: bytes | str, *, freq: float | None = None, xs_km: float | None = None, ys_km: float | None = None, file_type: Literal['shd', 'asc', 'ram'] | None = None, encoding: str = 'utf-8') → ShdReadResult | ShdAscResult | RamTlGridResult[source]

Dispatch shade parsing like Matlab read_shd.m for in-memory payloads.

file_type='shd': binary read_shd_bin
file_type='asc': ASCII read_shd_asc
file_type='ram': RAM tl.grid via read_ram_tlgrid
file_type=None: str -> ASCII; bytes -> try binary, then ASCII decode

at_py.readwrite.read_shd_asc(data: str | bytes, *, encoding: str = 'utf-8') → ShdAscResult[source]

Parse ASCII shade file text (port of Matlab read_shd_asc.m).

Matlab reads a single source-depth slab (isd = 1 in the original); this port reads all Nsd slabs sequentially if Nsd > 1, stacking an extra dimension so pressure has shape (nsd, nrd, nrr).

For the common Nsd == 1 case, shape is (1, nrd, nrr).

at_py.readwrite.read_shd_bin(data: bytes, *, freq: float | None = None, xs_km: float | None = None, ys_km: float | None = None) → ShdReadResult[source]

Parse AT binary .shd/.grn bytes (ported from Matlab read_shd_bin.m).

This function is intentionally bytes-in / objects-out (no filesystem).

freq: select nearest frequency (defaults to first frequency)
xs_km / ys_km: select nearest source x/y in km (defaults to first x/y)

at_py.readwrite.read_shd_bytes(data: bytes, *, freq: float | None = None, xs_km: float | None = None, ys_km: float | None = None, file_type: Literal['shd', 'asc', 'ram'] | None = None, encoding: str = 'utf-8') → ShdReadResult | ShdAscResult | RamTlGridResult[source]: Like read_shd() for bytes input only.

at_py.readwrite.read_shd_from_mat(data: bytes, *, freq: float | None = None, xs_km: float | None = None, ys_km: float | None = None, greens_function: bool = False) → ShdReadResult[source]

Port of Matlab read_shd.m branches shdmat / grnmat.

Required variables (as loaded by Matlab load): PlotTitle, PlotType, freqVec, freq0, atten, Pos, pressure.

greens_function=True applies Pos.r.r = Pos.r.r.' like grnmat.
freq selects the nearest entry in freqVec (default: first index), matching the binary reader when freq is omitted.
xs_km / ys_km select nearest source grid point in meters via abs(Pos.s.x - xs*1000) / abs(Pos.s.y - ys*1000) when pressure has leading source axes (Nsx, Nsy, ...).

at_py.readwrite.read_ts(data: str | bytes, *, encoding: str = 'utf-8') → TsReadResult[source]: Parse ASCII time-series data (Matlab read_ts.m non-.mat path).

at_py.readwrite.read_ts_bytes(data: bytes, *, encoding: str = 'utf-8') → TsReadResult[source]: Like read_ts() for UTF-8 (or other) encoded bytes.

at_py.readwrite.read_ts_from_mat(data: bytes) → TsReadResult[source]

Port of Matlab read_ts.m for .mat (loads PlotTitle, Pos, tout, RTS).

Applies the same RTS = RTS.' transpose as the Matlab branch.

class at_py.readwrite.fortran_records.FortranRecordReader(data: memoryview, marker_len: int, offset: int = 0)[source]

Bases: object

Reader for Fortran unformatted sequential records over a bytes buffer.

data: memoryview

marker_len: int

offset: int = 0

read_record() → bytes[source]: Read one unformatted record payload (markers validated).

at_py.readwrite.fortran_records.autodetect_marker_len(data: bytes, *, allowed: tuple[int, ...] = (1, 2)) → int[source]: Detect record-marker word count by reading the first flag record.