Serafin for Python

Read and write Serafin binary files — the mesh / results format used by the TELEMAC-MASCARET hydraulic modelling system (also known as the Selafin format, file extension .slf).

Documentation: https://isl-ingenierie.gitlab.io/modules-python/python-serafin/

serafin provides a typed, dependency-light I/O layer for Serafin files:

• single and double precision floats;
• big- and little-endian byte ordering;
• 2D and 3D meshes, with 2D ⇄ 3D conversion;
• mesh geometry, boundary detection and transformations;
• a catalogue of 2D / 3D variables and derived-variable computation.

The read/write code is adapted from PyTelTools; credits to its authors for documenting the format.

Installation

pip install python-serafin

It is also available on conda from the conda-forge channel:

conda install -c conda-forge python-serafin

The distribution is named python-serafin on both PyPI and conda-forge; the import name is serafin (a common pattern, like python-dateutil → import dateutil).

Quickstart

Read a Serafin file

from serafin import SerafinReader

with SerafinReader("results.slf", "en") as f:
    f.read_header()
    f.get_time()

    print(f.header.nb_nodes, "nodes,", f.header.nb_frames, "frames")
    print("variables:", f.header.var_ids)

    # values of variable "U" at the first time frame -> numpy array (nb_nodes,)
    u = f.read_var_in_frame(0, "U")
    print(u.shape, u.min(), u.max())

Write a Serafin file

from serafin import SerafinReader, SerafinWriter

with SerafinReader("results.slf", "en") as src:
    src.read_header()
    src.get_time()
    header = src.header

    with SerafinWriter("copy.slf", "en", overwrite=True) as dst:
        dst.write_header(header)
        for time_index, time in enumerate(src.time):
            values = src.read_vars_in_frame(time_index)
            dst.write_entire_frame(header, time, values)

Requirements

• Python 3.10 or newer
• numpy ≥ 1.24

Development

git clone https://gitlab.com/isl-ingenierie/modules-python/python-serafin.git
cd python-serafin
python -m venv .venv
. .venv/Scripts/activate     # PowerShell: . .venv/Scripts/Activate.ps1
pip install -e ".[dev]"
pre-commit install
pytest

Releasing

See CHANGELOG.md for the version history (format: Keep a Changelog 1.1.0, versions follow Semantic Versioning 2.0.0).

The release flow:

1. Move entries from ## [Unreleased] to a new ## [VERSION] - YYYY-MM-DD section in CHANGELOG.md.
2. Commit and tag (git tag vVERSION && git push origin vVERSION).
3. GitLab CI uploads to PyPI / TestPyPI via Trusted Publisher (OIDC, no API token stored as a CI variable) and creates a GitLab Release whose body is the matching CHANGELOG section.

The leading v is optional; hatch-vcs strips it when computing the package version.

License

This project is released under the GNU General Public License v3.0 or later.

The Serafin I/O code is adapted from PyTelTools, which is itself distributed under the GPL v3 — this package therefore inherits the same license.