Metadata-Version: 2.4
Name: ffmtools
Version: 0.1.0
Summary: Flood/flow modelling tools for 3Di subgrid: ffmgen (build .mdu files) and ffmclr (clean run outputs).
Author-email: aaronchh <aaronhsu219@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AaronOET/ffmtools
Project-URL: Changelog, https://github.com/AaronOET/ffmtools/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3
Requires-Dist: openpyxl>=3.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# ffmtools

## ffmgen

Builds 3Di subgrid `.mdu` input files (plus a `_run_<name>.bat` launcher) from an
`mdu_prep.xlsx`-style workbook or an existing `.mdu`. Packaged from
`prototype/Singapore_003/mdugen_gui_v3_tk.py`.

### Install

```bat
cd D:\GITHUB_OET\ffmtools
pip install -e .
```

### GUI

```bat
ffmgen                    :: loads .\mdu_prep.xlsx if present, else the built-in template
ffmgen gui STAMFORD_basis.mdu
python -m ffmgen
```

Each tab is one parameter group (= one sheet of the workbook). The **On** checkbox
decides whether a line is active or written commented out with `#`.
`EndDate` / `EndTime` in the *time* tab are used on Preview/Generate to compute
`NTimesteps = (End - Start) / Dt` (rounded up if it does not divide evenly).

### Command line

```bat
ffmgen generate mdu_prep.xlsx -o runs -n STAMFORD_basis -t 4
ffmgen generate STAMFORD_basis.mdu --dry-run
ffmgen convert STAMFORD_basis.mdu mdu_prep.xlsx
ffmgen template STAMFORD_template.mdu
```

### Python

```python
import ffmgen

data = ffmgen.ensure_end_rows(ffmgen.read_any("mdu_prep.xlsx"))
ffmgen.update_ntimesteps(data)
ffmgen.write_mdu(data, out_dir="runs", name="STAMFORD_basis", threads=4)
```

### Layout

| module | contents |
|---|---|
| `ffmgen.core` | parse/read/write `.mdu` and `.xlsx`, `to_mdu_text`, `write_mdu` |
| `ffmgen.timecalc` | `ensure_end_rows`, `update_ntimesteps` |
| `ffmgen.gui` | tkinter GUI (`App`, `run`) |
| `ffmgen.cli` | `ffmgen` console command |
| `ffmgen/templates/STAMFORD_basis.mdu` | built-in template |

## ffmclr

Removes the files a 3Di (subgrid) run leaves in a model folder. Packaged from
`prototype/Singapore_003/clean_3di_outputs.py`. Dry run by default.

```bat
ffmclr                              :: list what would be removed in the current folder
ffmclr D:\models\STAMFORD --yes     :: delete
ffmclr --yes --keep-table           :: keep the TableDataFile (faster restart)
ffmclr --move-to _old_run --yes     :: move into <model>\_old_run instead of deleting
ffmclr -r                           :: also scan sub-folders
```

Removed: `*_his.nc`, `*_map.nc`, `*_rst.nc`, `*.rst`, `*.dia`, `*_numlimdt.xyz`,
`*_timings.txt`, `.test`, and the `TableDataFile` named in the `.mdu`.
Never removed: anything referenced as input in an `.mdu`/`.ext`, and input
extensions (`.mdu .ini .ext .pli .pol .xyn .tim .tif .asc .rgb ...`).

```python
import ffmclr
res = ffmclr.clean("D:/models/STAMFORD", dry_run=False, move_to="_old_run")
print(len(res.removed), res.failed)
```

## Tests

```bat
pip install -e .[test]
pytest
```
