From 2553a168d79a9ac2e66d73698e27bb03b0e7e862 Mon Sep 17 00:00:00 2001 From: yannrichet Date: Mon, 15 Jun 2026 12:54:35 +0200 Subject: [PATCH] release: prepare 1.1 - Bump version to 1.1 (fz/__init__.py; pyproject reads it dynamically, _version.py is CI-stamped). - NEWS.md: cut the Unreleased section to "Version 1.1 (2026-06-15)" and open a fresh Unreleased. 1.1 collects: CLI argument aliases, calculator-discovery fixes, the fzd CLI execution fix, recursive directory-tree staging, fzd input-flag aliases, CLI hardening, and the worked skill examples + skill hardening. - README version badge 1.0 -> 1.1. - Skill docs: flip the "git main / next release" caveats to "fz >= 1.1" (fzd auto-discovery, recursive case-subdir staging, --calculators alias acceptance, fzd input-flag aliases, positional paths); bump install hints to funz-fz>=1.1 where a feature needs it; keep accurate "fz 1.0 only" notes for what changed. Does not cut the release: publishing to PyPI happens when a GitHub Release (tag 1.1) is published, triggering release.yml. Co-Authored-By: Claude Fable 5 --- NEWS.md | 2 ++ README.md | 2 +- fz/__init__.py | 2 +- skills/examples/newton-cooling-calibration.md | 2 +- .../openfoam-dambreak-random-sampling.md | 8 ++--- skills/fz/SKILL.md | 30 ++++++++--------- skills/fz/code-wrapper.md | 5 ++- skills/fz/reference.md | 32 +++++++++---------- 8 files changed, 41 insertions(+), 42 deletions(-) diff --git a/NEWS.md b/NEWS.md index 01e05e0..2cbdc19 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,8 @@ ## Unreleased +## Version 1.1 (2026-06-15) + ### CLI argument aliases (README forms now work) - Input/output paths can be passed positionally: `fzi input.txt -m mymodel`. diff --git a/README.md b/README.md index e1629ed..f116a9a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Python Version](https://img.shields.io/pypi/pyversions/funz.svg)](https://pypi.org/project/funz/) --> [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![Version](https://img.shields.io/badge/version-1.0-blue.svg)](https://github.com/Funz/fz/releases) +[![Version](https://img.shields.io/badge/version-1.1-blue.svg)](https://github.com/Funz/fz/releases) A powerful Python package for parametric simulations and computational experiments. FZ wraps your simulation codes to automatically run parametric studies, manage input/output files, handle parallel execution, and collect results in structured DataFrames. diff --git a/fz/__init__.py b/fz/__init__.py index aae1fe3..bae4272 100644 --- a/fz/__init__.py +++ b/fz/__init__.py @@ -91,7 +91,7 @@ def list_models(global_list=False): return list_installed_models(global_list=global_list) -__version__ = "1.0" +__version__ = "1.1" __all__ = [ "fzi", "fzc", "fzo", "fzr", "fzl", "fzd", "install", "uninstall", "list_models", diff --git a/skills/examples/newton-cooling-calibration.md b/skills/examples/newton-cooling-calibration.md index 293f12b..788f1c8 100644 --- a/skills/examples/newton-cooling-calibration.md +++ b/skills/examples/newton-cooling-calibration.md @@ -33,7 +33,7 @@ zero. (The analytic answer, for checking: `T(t) = T_env + (T0−T_env)·e^{−kt ## Prerequisites -- `fz` on PATH (`pip install 'funz-fz>=1.0'`). +- `fz` on PATH (`pip install 'funz-fz>=1.1'`; the CLI `fzd` used here is fixed in 1.1). - The **fz skill** installed (see [../howto.md](../howto.md)). - **OpenModelica** (`omc` on PATH) — the Modelica wrapper shells out to it. Ubuntu/Debian: `sudo apt-get install openmodelica`; macOS: `brew install openmodelica`. diff --git a/skills/examples/openfoam-dambreak-random-sampling.md b/skills/examples/openfoam-dambreak-random-sampling.md index f4b4334..1d5aa6a 100644 --- a/skills/examples/openfoam-dambreak-random-sampling.md +++ b/skills/examples/openfoam-dambreak-random-sampling.md @@ -19,9 +19,9 @@ comes back empty: build the binding yourself, verify it cheaply, then run the st > an 8-sample study completes in ~30 s and yields a peak water height varying ~0.08–0.18 m > with obstacle height. OpenFOAM-internal names (paths, the `blockMeshDict` obstacle level, > the function-object column) are still **distribution/version dependent** — confirm them -> in your install. Two `fz` framework fixes were needed for a directory-tree code like -> OpenFOAM to run at all (recursive staging of case subdirectories into and out of the run -> directory); use a build that includes them. +> in your install. A directory-tree code like OpenFOAM needs **fz ≥ 1.1** to run at all +> (1.1 added recursive staging of case subdirectories into and out of the run directory, +> plus the `fzd` CLI/auto-discovery fixes this study relies on). ## The engineering problem @@ -37,7 +37,7 @@ downstream location. - **OpenFOAM** installed and its environment **sourced** (`blockMesh`, `setFields`, and the solver — `interFoam` or `foamRun` depending on your distribution — on PATH). The tutorial case ships under `$FOAM_TUTORIALS/multiphase/interFoam/laminar/damBreak/damBreak`. -- `fz` on PATH (`pip install 'funz-fz>=1.0'`) and the **fz skill** installed (see +- `fz` on PATH (`pip install 'funz-fz>=1.1'`) and the **fz skill** installed (see [../howto.md](../howto.md)). - `claude` CLI, logged in or `ANTHROPIC_API_KEY` set. diff --git a/skills/fz/SKILL.md b/skills/fz/SKILL.md index 17bf2e3..35d0d25 100644 --- a/skills/fz/SKILL.md +++ b/skills/fz/SKILL.md @@ -18,10 +18,12 @@ fz wraps any simulation code that reads input files and writes output files, so run as a parametric study: variables in input files are substituted for each case, cases run in parallel (locally, SSH, SLURM), and outputs are parsed back into a pandas DataFrame. -Install: `pip install 'funz-fz>=1.0'` (CLI commands `fz`, `fzi`, `fzc`, `fzo`, `fzr`, `fzl`, -`fzd` plus the `fz` Python package; `fz install` requires 1.0+). On PEP 668 -externally-managed systems (`error: externally-managed-environment`), use a venv: -`python3 -m venv .venv && .venv/bin/pip install 'funz-fz>=1.0'`. +Install: `pip install 'funz-fz>=1.1'` (CLI commands `fz`, `fzi`, `fzc`, `fzo`, `fzr`, `fzl`, +`fzd` plus the `fz` Python package). 1.1 is recommended — it fixes `fzd` on the CLI, +auto-discovers calculators for `fzd`, and stages directory-tree (case) inputs intact; +1.0 lacks these. On PEP 668 externally-managed systems +(`error: externally-managed-environment`), use a venv: +`python3 -m venv .venv && .venv/bin/pip install 'funz-fz>=1.1'`. ## The workflow @@ -45,7 +47,7 @@ tree. Codes like OpenFOAM or Telemac take a *case directory* (`system/`, `consta and the calculator runs inside the per-case copy with the tree intact. Authoring such a wrapper has extra gotchas (prefix collisions, directory I/O, locale) — see [code-wrapper.md](code-wrapper.md). (Recursive staging of case subdirectories requires -fz from git main / the next release; fz 1.0 on PyPI stages only top-level files.) +fz ≥ 1.1; fz 1.0 stages only top-level files.) ### 0. Check for an existing wrapper first @@ -64,15 +66,13 @@ This drops into the project's `.fz/` directory (add `--global` for `~/.fz/`): refer to it by bare alias, e.g. `--model Modelica`. - `.fz/calculators/.sh` — a runner script that executes the simulation code. - `.fz/calculators/localhost_.json` — a local calculator alias wired to that script. - In `fzr` it is auto-discovered: omit `calculators` and the installed alias matching the - model id is used. **fz 1.0 (current PyPI) caveats**: bare alias names are NOT accepted - by `--calculators`, and `fzd` does NOT auto-discover — omitting `calculators` there - silently runs an empty `sh://` command and every case fails; pass calculators explicitly - to `fzd`, e.g. a URI with an absolute script path: - `calculators="sh://bash /abs/path/.fz/calculators/.sh"` (absolute, because - calculator commands run inside each case directory). Both limitations are fixed in - newer fz (git main / next release): `fzd` auto-discovers like `fzr`, and - `--calculators ` works. + In both `fzr` and `fzd` (fz ≥ 1.1) it is auto-discovered: omit `calculators` and the + installed alias matching the model id is used; `--calculators ` also accepts a bare + alias name. **On fz 1.0** neither held — bare alias names were rejected by `--calculators` + and `fzd` did not auto-discover (omitting `calculators` ran an empty `sh://` and every + case failed), so on 1.0 you must pass `fzd` calculators explicitly, e.g. a URI with an + absolute script path: `calculators="sh://bash /abs/path/.fz/calculators/.sh"` + (absolute, because calculator commands run inside each case directory). With a wrapper installed, skip to step 1 just to add `$var` markers to your input file, then verify with steps 3–6 as usual. Write a custom model (step 2) only when no wrapper @@ -299,7 +299,7 @@ read [algorithm-wrapper.md](algorithm-wrapper.md). | All cases `failed`, `N calculator failures` | The calculator command itself errors — read the case's `err.txt`/`log.txt`. | | Output column is `null` but case is `done` | Output command matched nothing: wrong path/field, missing subdir output (see directory codes), locale (`LC_ALL=C`), or `python` vs `python3`. | | `fzi` lists extra/unexpected variables | `varprefix` collides with the code's own syntax — change it. | -| `fzd` runs an empty `sh://` / every case fails | On fz 1.0 PyPI, `fzd` doesn't auto-discover calculators — pass them explicitly (fixed in git main). | +| `fzd` runs an empty `sh://` / every case fails | fz 1.0 only: `fzd` didn't auto-discover calculators — pass them explicitly, or upgrade to fz ≥ 1.1. | ## Worked examples diff --git a/skills/fz/code-wrapper.md b/skills/fz/code-wrapper.md index cf183d7..d7dad7b 100644 --- a/skills/fz/code-wrapper.md +++ b/skills/fz/code-wrapper.md @@ -143,9 +143,8 @@ Some codes (OpenFOAM, Telemac, …) take a whole **case directory** (`system/`, - The output parser reads the result *and any output subdirectory* the run produced (e.g. `postProcessing/.../*.dat`). -Requires recursive staging of case subdirectories, which is fz from git main / the next -release; fz 1.0 on PyPI stages only top-level files into the run directory, so a case with -subdirectories will fail there. The +Requires recursive staging of case subdirectories — fz ≥ 1.1; fz 1.0 stages only top-level +files into the run directory, so a case with subdirectories fails there. The [OpenFOAM dam-break example](../examples/openfoam-dambreak-random-sampling.md) is a complete worked wrapper of this kind. diff --git a/skills/fz/reference.md b/skills/fz/reference.md index 0e8550d..6fb481d 100644 --- a/skills/fz/reference.md +++ b/skills/fz/reference.md @@ -112,26 +112,24 @@ fzd --input_dir/-i --input_vars/-v --model/-m --output_expression/-e ``` > **`fzd` flag divergence (easy to trip on):** `fzd`'s canonical input flags are -> `--input_dir`/`-i` and `--input_vars`/`-v` (in newer fz — git main / next release — it -> also accepts the `fzi`/`fzc`/`fzr` names `--input_path` and `--input_variables` as -> aliases; fz 1.0 on PyPI takes only the canonical names). It takes algorithm options via -> `--options`/`-o`, and has **no `--format`** — it prints a convergence summary and writes -> the design/analysis under `--results_dir`. `--input_dir` accepts a single file as well as -> a directory. - -- In fz 1.0 (current PyPI release), paths must be given via flag - (`fzi --input_path input.txt -m mymodel`) and only the canonical flag names below work. - Newer fz (git main / next release) additionally accepts positional paths - (`fzi input.txt -m mymodel`) and the aliases `--variables` = `--input_variables`, - `--calculator` = `--calculators` (repeatable), `--results` = `--results_dir`, - `--output` = `--output_dir`. The canonical flags work everywhere — prefer them. +> `--input_dir`/`-i` and `--input_vars`/`-v` (fz ≥ 1.1 also accepts the `fzi`/`fzc`/`fzr` +> names `--input_path` and `--input_variables` as aliases; fz 1.0 took only the canonical +> names). It takes algorithm options via `--options`/`-o`, and has **no `--format`** — it +> prints a convergence summary and writes the design/analysis under `--results_dir`. +> `--input_dir` accepts a single file as well as a directory. + +- Paths can be given positionally (`fzi input.txt -m mymodel`) or via flag + (`fzi --input_path input.txt -m mymodel`), and these aliases work: `--variables` = + `--input_variables`, `--calculator` = `--calculators` (repeatable), `--results` = + `--results_dir`, `--output` = `--output_dir`. (fz 1.0 required the canonical flag names + and had no positional form; the canonical flags work everywhere — prefer them.) - `--format` accepts: `json`, `csv`, `html`, `markdown`, `table`. - `--model` and `--input_variables` auto-detect their format: alias (bare name) → JSON file path (ends in `.json`) → inline JSON. `--calculators` takes a URI, JSON file path, - or inline JSON — in fz 1.0 NOT a bare alias name (newer fz accepts aliases too); omit it - entirely to auto-discover installed calculator aliases matching the model id (fzr always; - fzd only in newer fz — in 1.0 pass fzd calculators explicitly). Multiple calculators may - also be one inline JSON list: `--calculators '["cache://run1", "sh://bash calc.sh"]'`. + a bare alias name, or an inline JSON list (`'["cache://run1", "sh://bash calc.sh"]'`); + omit it entirely to auto-discover installed calculator aliases matching the model id + (both `fzr` and `fzd` in fz ≥ 1.1). (fz 1.0: `--calculators` rejected bare alias names + and `fzd` did not auto-discover — pass `fzd` calculators explicitly there.) - Inline model definition (instead of, or overriding, `--model`): `--varprefix`, `--formulaprefix`, `--delim`, `--commentline`, `--interpreter`, and repeatable `--output-cmd NAME=COMMAND` for output parsers.