Metadata-Version: 2.4
Name: sfincstools
Version: 0.2.0
Summary: Command-line tools for inspecting and monitoring SFINCS models
Author-email: aaronchh <aaronhsu219@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AaronOET/sfincstools
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: netCDF4>=1.5.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: openpyxl>=3.0.0
Dynamic: license-file

# sfincstools

Command-line tools for building, inspecting and monitoring [SFINCS](https://sfincs.readthedocs.io) models.

## Installation

```bash
pip install -e .
```

## Tools

### `sfpgs` — check the progress of a SFINCS run

```bash
sfpgs [MODEL_DIR] [--watch SECONDS] [--stall MINUTES]
```

- `MODEL_DIR` – folder with `sfincs.inp` (default: current folder)
- `--watch` – refresh every SECONDS until the run ends (default: report once)
- `--stall` – warn if the log has not changed for this many minutes (default 10)

Reads `sfincs.log` / `sfincs_log.txt` (percent complete, remaining time, errors, summary)
and the last time stamp in `sfincs_map.nc` / `sfincs_his.nc`. Safe to run while SFINCS is running.

### `sfcfg` — display the configuration of a SFINCS model

```bash
sfcfg [MODEL_DIR] [--plot] [--save FILE.png]
```

- `MODEL_DIR` – folder with `sfincs.inp` (default: current folder)
- `--plot` – also show a map (bed level, mask, boundary, drainage, weirs, obs) and the forcing time series
- `--save` – write the figure to a file instead of opening a window

Reports `sfincs.inp` grouped by topic with derived values, the presence/size of every
referenced input file, and a short summary of each file's contents.

### `sfclr` — remove the files generated by a SFINCS run

```bash
sfclr [MODEL_DIR] [--yes] [--post] [--recursive] [--move-to DIR]
```

- `MODEL_DIR` – model folder with a `*.inp` (default: current folder)
- `-y`, `--yes` – actually delete (default is a dry run that only lists the files)
- `--post` – also remove post-processing products (`sfincs_hmax*.tif` / `.png`, animations)
- `-r`, `--recursive` – clean every folder below MODEL_DIR that contains a `*.inp`
- `--move-to DIR` – move the files into DIR (relative to each model folder) instead of deleting

Removes NetCDF map / his output, run logs, restart output and binary / ascii output.
Files referenced in a `*.inp` (e.g. a restart file used as input) are never removed.

### `sfgen` — build a sfincs.inp in a desktop GUI

```bash
sfgen [SOURCE] [--out-dir DIR]
```

- `SOURCE` – `.xlsx` (one sheet per group) or `.inp` to load at start, or a model folder (its `sfincs.inp`); default: `inp_prep.xlsx` in the current folder if it exists, else the built-in defaults
- `--out-dir DIR` – output folder for the generated `.inp` / `.bat` (default: the folder of an `.inp` SOURCE, else the current folder)

One tab per parameter group with every SFINCS keyword; tick a keyword to write it. Preview / Generate
check the time settings and warn about missing input files and duplicate or unsupported keywords.
Optionally writes a `run_<name>.bat` that starts `sfincs.exe`.

## Python usage

```python
from sfincstools import sfpgs, sfcfg

sfpgs.main(["path/to/model"])
sfcfg.main(["path/to/model", "--save", "model.png"])
```
