External Input Files

This page documents every external file that Tolosa-sw reads at runtime, beyond input.txt and m_user_data.f90. All files are resolved relative to the run directory (bin/) via pathto().

---

Binary File Conventions

Tolosa-sw uses paired .a / .b files for structured binary data:

• .a — binary data file. Typically direct-access Fortran unformatted, 4-byte (single-precision) real values unless noted.
• .b — text index file. Contains metadata: number of records, dates, field names, dimensions.
• Endianness — big-endian by default for most ocean-origin files (e.g. tidal constituents, grid files); little-endian for atmospheric forcing. Controlled by endian_forcing, endian_ssht in input.txt.

---

Quick Reference Table

File	Required when	Format	Endian
regional.grid-node.a	optional — lon/lat per cell	binary indexed, 4-byte floats	big (hardcoded)
regional.depth-ele.a	bathy_in = 2	binary indexed, 4-byte floats	auto
bc_<name>.txt	BC type q/q(t), ssh/ssh(t), h/h(t)	formatted text, time-value pairs	—
tide.list	tidal BC or tbf_forcing > 0	formatted text, one constituent per line	—
forcing.<name>tide.a / .b	constituent in tide.list	binary direct-access, 4-byte floats / text index	big
ssht_edge_at_bc.a / .b	ssht BC or ssht/tide	binary stream / text index (CNES Julian days)	endian_ssht
forcing.msl / .b	patm_forcing > 0	binary indexed, 4-byte floats / text index	endian_forcing
prmsl_ref.a	patm_ref_var = 1	binary indexed, 4-byte floats	auto
forcing.usst / .b	wind_forcing > 0	binary indexed, 4-byte floats / text index	endian_forcing
forcing.vsst / .b	wind_forcing > 0	binary indexed, 4-byte floats / text index	endian_forcing
bottom_fric_qua.a	friction_model = 1 or 2 (optional)	binary indexed, 4-byte floats	auto
bottom_fric_z0.a	friction_model = 2 (optional)	binary indexed, 4-byte floats	auto
bottom_fric_lin.a	friction_model > 0 (optional)	binary indexed, 4-byte floats	auto
bottom_fric_manning.a	friction_model = 3 (optional)	binary indexed, 4-byte floats	auto
restart.bin	restart = 1	binary stream, native endian	native

---

Boundary Condition Files

bc_<name>.txt — time series for q(t), ssh(t), h(t)

Plain text, two columns: time (seconds) and BC value. Linear interpolation applied between records.

$ q(t)
0.      100.
3600.   200.
7200.   250.
10800.  300.

The <name> matches the Gmsh physical group name (Gmsh mesh) or the tag set in bc_N/S/W/E (Cartesian mesh).

---

tide.list — tidal constituents

One constituent per line after a --- separator:

---
M2  255555  28.98410420  0.9081  0.037  349.0  0.000  0.0
S2  273555  30.00000000  0.4227  0.000    0.0  0.000  0.0
K1  165555  15.04106864  0.5305  0.115   45.0 -0.115 -45.0

Columns: name doodson vit_ang(°/h) coef_pot c1 k1 c2 k2

For each constituent <name> listed, the pair forcing.<name>tide.a / forcing.<name>tide.b must be present in bin/. Constituents are loaded individually — only those found on disk are activated.

---

forcing.<name>tide.a / .b — tidal harmonic amplitudes

Binary direct-access, big-endian, 4-byte floats. The .b text index specifies the number of boundary edges and the harmonic coefficients (amplitude and phase per edge). Used for both open boundary tidal forcing (tide BC) and tidal body forces (tbf_forcing).

---

ssht_edge_at_bc.a / .b — spatially-varying SSH time series

• .b — text file listing CNES Julian day dates, one per line
• .a — binary stream, endian_ssht (default little). Stores one record per date: SSH value per open boundary edge (4-byte floats)

Two consecutive records are held in memory and linearly interpolated at each time step. Can be combined with tidal BCs (ssht/tide) — contributions are summed.

---

Physical Forcing Files

forcing.msl / .b — atmospheric mean sea level pressure

Binary direct-access, 4-byte floats, endianness set by endian_forcing (default little). Required when patm_forcing > 0. The .b index provides record dates and grid dimensions.

prmsl_ref.a — spatially variable reference pressure

Required when patm_ref_var = 1. Same format as forcing.msl, auto-detected endianness. Provides the spatially variable background pressure subtracted from forcing.msl before computing the pressure gradient.

forcing.usst / .b and forcing.vsst / .b — wind stress

Binary direct-access, 4-byte floats, endianness from endian_forcing. Required when wind_forcing > 0. Stores the x and y components of the surface wind stress (Pa) at each cell, per time record.

---

Grid and Bathymetry Files

regional.grid-node.a — longitude / latitude per cell

Optional. Big-endian (hardcoded), binary indexed, 4-byte floats. When present, enables Coriolis with spatially variable f (coriolis = 1) and activates lon/lat output fields in VTK/Tecplot.

Layout: one record per cell, storing (longitude, latitude) in degrees.

regional.depth-ele.a — external bathymetry

Required when bathy_in = 2. Auto-detected endianness, binary indexed, 4-byte floats. Provides seafloor elevation (positive upward) per mesh node, bypassing bathy_user() in m_user_data.f90.

---

Friction Coefficient Files

All friction files are optional. If absent, the uniform values from input.txt (cb, cl, z0, n) are used instead. Files must be binary indexed, 4-byte floats, auto-detected endianness.

File	Friction model	Quantity stored
bottom_fric_qua.a	friction_model = 1 or 2	Spatially variable cb (quadratic coefficient)
bottom_fric_z0.a	friction_model = 2	Spatially variable z0 (roughness length, m)
bottom_fric_lin.a	friction_model > 0	Spatially variable cl (linear coefficient)
bottom_fric_manning.a	friction_model = 3	Spatially variable Manning n

One value per mesh cell, stored as a single direct-access record.

---

Restart File

restart.bin

Fortran unformatted binary stream, native endianness. Written at intervals set by dt_restart in input.txt. To restart from it, set restart = 1.

Contains the full model state (h, hu, hv) per cell at the saved time, plus simulation metadata (time, step number).

Note

Friction coefficient files are optional per spatial field — if a file is absent, the uniform scalar from input.txt is used for that quantity. Tidal constituent files are optional per constituent; only those found are loaded.