Metadata-Version: 2.4
Name: python-serafin
Version: 0.2.0
Summary: Read and write Serafin (TELEMAC) binary files
Project-URL: Homepage, https://gitlab.com/isl-ingenierie/modules-python/python-serafin
Project-URL: Documentation, https://isl-ingenierie.gitlab.io/modules-python/python-serafin/
Project-URL: Source, https://gitlab.com/isl-ingenierie/modules-python/python-serafin
Project-URL: Issues, https://gitlab.com/isl-ingenierie/modules-python/python-serafin/-/issues
Project-URL: Changelog, https://gitlab.com/isl-ingenierie/modules-python/python-serafin/-/blob/main/CHANGELOG.md
Author-email: Nicolas Godet <godet@isl.fr>
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: hydraulics,mesh,selafin,serafin,slf,telemac
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.8; extra == 'docs'
Requires-Dist: myst-parser[linkify]>=3.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.6; extra == 'docs'
Requires-Dist: sphinx-llm>=0.4; extra == 'docs'
Requires-Dist: sphinx>=7.3; extra == 'docs'
Description-Content-Type: text/markdown

# Serafin for Python

![PyPI - Version](https://img.shields.io/pypi/v/python-serafin) ![Conda Version](https://img.shields.io/conda/vn/conda-forge/python-serafin)

Read and write **Serafin** binary files — the mesh / results format used by the
[TELEMAC-MASCARET](http://www.opentelemac.org/) 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](https://github.com/CNR-Engineering/PyTelTools); credits to its
authors for documenting the format.

## Installation

```sh
pip install python-serafin
```

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

```sh
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

```python
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

```python
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`](https://numpy.org/) ≥ 1.24

## Development

```sh
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`](CHANGELOG.md) for the version history (format: [Keep a
Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), versions follow
[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)).

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.

| Tag pattern                          | Target                     |
| ------------------------------------ | -------------------------- |
| `0.1.0a1`, `v0.1.0rc2`, `0.1.0.dev3` | TestPyPI (`pypi-test` job) |
| `0.1.0`, `v1.2.3`                    | PyPI prod (`pypi` job)     |

## License

This project is released under the [GNU General Public License v3.0 or later](LICENSE).

The Serafin I/O code is adapted from
[PyTelTools](https://github.com/CNR-Engineering/PyTelTools), which is itself
distributed under the GPL v3 — this package therefore inherits the same
license.
