runops 2.7.0__tar.gz → 2.8.0__tar.gz

{runops-2.7.0 → runops-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runops
-Version: 2.7.0
+Version: 2.8.0
 Summary: Run ledger and Slurm job submission for HPC simulation projects
 Project-URL: Homepage, https://github.com/Nkzono99/runops
 Project-URL: Documentation, https://github.com/Nkzono99/runops/blob/main/docs/reference.md

{runops-2.7.0 → runops-2.8.0}/SPEC.md

@@ -729,14 +729,14 @@ runops は `init` と `update` で次を行う。
 runops は次の 6 skill だけを同梱し、simulator skill と同じ仕組みで展開する。
 利用者が覚えるコマンドは `runo init` だけとし、それ以外（simulator の追加、更新、v1 移行を含む）は
 エージェントへの依頼で行う。
-各 SKILL.md は 60 行以内に収める。
+各 SKILL.md は 60 行以内に収める。詳しい指針や例が要る skill は、同じ directory に別 file として置き、SKILL.md から相対リンクで参照する。
 
 | skill | 内容 |
 |---|---|
 | `runops-create-run` | `new` / `sweep` の使い方。`--why` を必ず書く、scratch の使い分け |
 | `runops-check-status` | `sync` → `list` → `log` の順。失敗時の `retry` と `tidy --purge-work` |
 | `runops-tidy` | `tidy` を定期的に実行する判断基準。pin の使い方 |
-| `runops-analyze` | 依存する run の範囲で調査の置き場所を決め、script・結果・log・README をまとめる |
+| `runops-analyze` | 依存する run の範囲で調査の置き場所を決め、script・結果・log・README をまとめる。読み手に渡す比較レポートの書き方は同梱の `report-guide.md` と `example-report/` に置く |
 | `runops-reference` | command 一覧（§7.3 の表をそのまま載せる） |
 | `runops-maintain` | simulator の追加、runops と simulator package の更新、`migrate-v1`、`doctor` の読み方 |
 
@@ -1017,6 +1017,7 @@ v2 の文書は次の 4 ファイルだけにする。
 
 | 項目 | 決定 | 理由 |
 |---|---|---|
+| 比較レポートの書き方（2026-11-10） | `runops-analyze` に執筆ガイド `report-guide.md` と模擬データの例 `example-report/` を同梱する。README.md を本文の正本とし、例の `scripts/build_html.py` が図を埋め込んだ `report.html` を作る。command やレポート生成機構は足さない | 差分図と条件の列挙が中心のレポートは読み手に伝わらず、元の分布を同じ尺度で並べ、問い・観測・解釈をつなげて書き直すと伝わった（#119）。書き方は判断を伴うので、手順と例として skill に置く |
 | 解析の配置 2.6.0（2026-10-23） | 依存する run の範囲に応じて run 内 `analysis/`、group の `_analysis/<topic>/`、project の `analysis/<topic>/` にまとめる。skill、log の tidy、group archive、context を対応させる（§9.1） | 報告・図・script・job log が分散・混在していた。group は既存の directory として扱い、新しい entity や command は足さない。既存ファイルの整理は移動一覧を提示してから行う |
 | job の cwd | run_dir（v1 と同じ）。Slurm log は `work/` | v1 adapter の path 規約と実 project の job.sh をそのまま使える |
 | adapter の追加 hook | `configure(sim_config)`、`job_prelude(run_dir)` | generic の `command` 取得と、EMSES の `rm -f *_0000.h5` など v1 の setup command を表す |

{runops-2.7.0 → runops-2.8.0}/docs/guide.md

@@ -60,7 +60,8 @@ runops が扱う名詞は case、run、sweep の 3 つです。
 作った run の `manifest.toml` と `input/` は変更しません。入力を直したいときは新しい run を作ります。
 同じ入力の run が既にあると、作成時に警告が出ます。
 `new --from` は元の run の params を引き継ぎますが、入力ファイルは今の case から作ります。
-元の run を作った後に case の入力ファイルを直していると、作成時に警告が出ます。
+元の run を作った後に case の入力ファイルを直して値が変わると、作成時の警告に変わる key と値が並びます。
+元の値のまま続けたいときは `--set` で指定します。
 
 ### 名前の付け方
 
@@ -232,6 +233,10 @@ topic は `speed-by-version` のように問いの内容で名付け、同じ問
 
 エージェントは `runops-analyze` skill を使い、調査の README と、そこへのリンクを含む
 `LOG.md` の判断を更新します。`notes/` は run に依存しない知見に使います。
+比較の結果を人に見せるレポートを頼むと（「この 3 条件を比較してレポートにまとめて」）、
+エージェントは skill 同梱の執筆ガイドと例に沿って、問いと結論、条件を同じ尺度で並べた図、
+図の読み方と結果の意味、再現情報の順に書きます。README.md と、図を埋め込んで単体で
+読める `report.html` の両方ができます。
 解析の追加依存は `.runops/analysis-env/` に置き、重い読み込みや作図はサイトの規則に従って
 計算ノードで実行します。sbatch は調査 directory から投入し、事前に `logs/` を作って
 `#SBATCH -o logs/%x.%j.out` と `#SBATCH -e logs/%x.%j.err` を指定します。

{runops-2.7.0 → runops-2.8.0}/docs/reference.md

@@ -129,8 +129,10 @@ program を起動せずに終わり、`stage = "setup"` と exit code を記録
 
 `submit` は executable を hash し直して attempt に記録し、作成時と違えば警告します。
 `new` と `sweep --apply` は同じ入力（`input_hash`）の run が既にあれば警告します。
-`new --from RUN` は、元の run を作った後に case の入力ファイルが変わっていれば警告します
-（入力は今の case から作るため）。どれも作成や投入は拒否しません。
+`new --from RUN` は、元の run を作った後に case の入力ファイルが変わり、そのために入力の値が
+元の run と違うとき、違う key と値を警告に並べます（入力は今の case から作るため）。TOML 以外の
+入力は file 名だけを示します。`--set` した key と、adapter が `--continue` のために書いた key は
+並べません。どれも作成や投入は拒否しません。
 
 `submit`、`cancel`、`retry`、`sync` は lock の中で manifest を読み直してから更新します。
 同じ run を 2 回指定しても、複数のエージェントが同時に投入しても sbatch は 1 回です。

{runops-2.7.0 → runops-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runops"
-version = "2.7.0"
+version = "2.8.0"
 description = "Run ledger and Slurm job submission for HPC simulation projects"
 readme = "README.md"
 license = "Apache-2.0"

{runops-2.7.0 → runops-2.8.0}/src/runops/__init__.py

@@ -1,3 +1,3 @@
 """runops: run ledger and Slurm job submission for HPC simulation projects."""
 
-__version__ = "2.7.0"
+__version__ = "2.8.0"

{runops-2.7.0 → runops-2.8.0}/src/runops/ops/create.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import contextlib
 import itertools
 import shutil
+from collections.abc import Iterable
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from pathlib import Path
@@ -28,7 +30,17 @@ from runops.ops.common import SimContext, resolve_dest, sim_context
 from runops.ops.submit import write_job_for
 from runops.project import ARCHIVE_DIR, SCRATCH_DIR, Project
 from runops.runtime import resolve_runtime
-from runops.util import hash_tree, move_noreplace, now_iso, parse_value
+from runops.util import (
+    hash_file,
+    hash_tree,
+    load_toml,
+    move_noreplace,
+    now_iso,
+    parse_value,
+    tomllib,
+)
+
+SHOWN_INPUT_CHANGES = 10
 
 
 @dataclass
@@ -40,6 +52,7 @@ class RunSpec:
     sweep: str = ""
     job: dict[str, Any] = field(default_factory=dict)
     job_changed: list[str] = field(default_factory=list)
+    input_changes: list[str] = field(default_factory=list)  # set for a run derived from another
 
 
 @dataclass
@@ -118,6 +131,60 @@ def _job_keys(job: dict[str, Any]) -> dict[str, Any]:
     return {k: v for k, v in job.items() if k in JOB_KEYS}
 
 
+def _flat(value: Any, prefix: str = "") -> dict[str, Any]:
+    """The leaves of a TOML document under dotted keys, arrays of tables by index."""
+    items: Iterable[tuple[Any, Any]]
+    if isinstance(value, dict):
+        items = value.items()
+    elif isinstance(value, list) and any(isinstance(x, dict) for x in value):
+        items = enumerate(value)
+    else:
+        return {prefix: value}
+    flat: dict[str, Any] = {}
+    for key, item in items:
+        flat.update(_flat(item, f"{prefix}.{key}" if prefix else str(key)))
+    return flat
+
+
+def _input_values(input_dir: Path) -> dict[tuple[str, str], Any]:
+    """What a run's input files say: ``(file, dotted key)`` for TOML, ``(file, "")`` otherwise."""
+    values: dict[tuple[str, str], Any] = {}
+    for path in sorted(p for p in input_dir.rglob("*") if p.is_file()):
+        rel = path.relative_to(input_dir).as_posix()
+        document = None
+        if path.suffix == ".toml":
+            with contextlib.suppress(tomllib.TOMLDecodeError, UnicodeDecodeError):
+                document = load_toml(path)
+        if document is None:
+            values[(rel, "")] = hash_file(path)
+        else:
+            values.update({(rel, key): value for key, value in _flat(document).items()})
+    return values
+
+
+def _differing(
+    before: dict[tuple[str, str], Any], after: dict[tuple[str, str], Any]
+) -> list[tuple[str, str]]:
+    return sorted(k for k in before.keys() | after.keys() if before.get(k) != after.get(k))
+
+
+def _input_changes(
+    before: dict[tuple[str, str], Any],
+    after: dict[tuple[str, str], Any],
+    explained: set[str],
+) -> list[str]:
+    """What differs between two runs' inputs, leaving out the keys in *explained*."""
+    lines = []
+    for key in _differing(before, after):
+        rel, name = key
+        if not name:
+            lines.append(rel)
+        elif not any(name == k or name.startswith(f"{k}.") for k in explained):
+            old, new = (repr(side[key]) if key in side else "-" for side in (before, after))
+            lines.append(f"{name}: {old} -> {new}")
+    return lines
+
+
 def _diff(label: str, before: dict[str, Any], after: dict[str, Any]) -> str:
     keys = [k for k in after if before.get(k) != after[k]]
     keys += [k for k in before if k not in after]
@@ -263,14 +330,15 @@ def create_run(project: Project, request: CreateRequest) -> CreateResult:
         line = _diff("job vs case", dict(case.job), job)
         if line:
             result.changes.append(line)
-    if source is not None:
-        recorded = str(source.section("origin").get("case_input_hash", ""))
-        if recorded and recorded != case.input_hash():
-            # Inputs come from the case as it is now, not as it was for the source.
-            result.warnings.append(
-                f"case {case.name!r} input files changed since {source.id} was created; "
-                f"{result.manifests[0].id} differs from it by more than the inherited params"
-            )
+    if source is not None and spec.input_changes:
+        # Inputs come from the case as it is now, not as it was for the source.
+        shown = "; ".join(spec.input_changes[:SHOWN_INPUT_CHANGES])
+        hidden = len(spec.input_changes) - SHOWN_INPUT_CHANGES
+        more = f"; and {hidden} more" if hidden > 0 else ""
+        result.warnings.append(
+            f"case {case.name!r} input files changed since {source.id} was created; "
+            f"{result.manifests[0].id} differs from it beyond the params in: {shown}{more}"
+        )
     return result
 
 
@@ -483,8 +551,13 @@ def _populate(
         dst = input_dir / rel
         dst.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(src, dst)
+    recorded = str(source.section("origin").get("case_input_hash", "")) if source else ""
+    case_moved = bool(recorded) and recorded != case.input_hash()
+    rendered: dict[tuple[str, str], Any] = {}
     try:
         ctx.adapter.render_inputs(dict(spec.params), stage)
+        if case_moved:
+            rendered = _input_values(input_dir)
         if request.continue_run and source is not None:
             extend = getattr(ctx.adapter, "extend_inputs", None)
             if not callable(extend):
@@ -497,6 +570,16 @@ def _populate(
                 ) from None
     except (ValueError, KeyError, OSError) as exc:
         raise RunError(f"{run_id}: render_inputs failed: {exc}") from exc
+    if case_moved and source is not None:
+        values = _input_values(input_dir)
+        # Keys the user set, or the adapter wrote to continue, are not case changes.
+        explained = {
+            k.replace("[", ".").replace("]", "") for k in changed_keys(source.params, spec.params)
+        }
+        explained |= {name for _, name in _differing(rendered, values) if name}
+        spec.input_changes = _input_changes(
+            _input_values(source.run_dir / "input"), values, explained
+        )
 
     now = now_iso()
     run: dict[str, Any] = {

{runops-2.7.0 → runops-2.8.0}/src/runops/skills/runops-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: runops-analyze
-description: Analyze or compare run results in a runops project. Use when plotting, investigating a series or sweep, writing an analysis report, or choosing where analysis scripts and outputs belong.
+description: Analyze or compare run results in a runops project. Use when plotting, investigating a series or sweep, writing an analysis or comparison report for a reader, or choosing where analysis scripts and outputs belong.
 ---
 
 # Analyze run results
@@ -30,11 +30,16 @@ description: Analyze or compare run results in a runops project. Use when plotti
    In the script use `#SBATCH -o logs/%x.%j.out` and `#SBATCH -e logs/%x.%j.err`,
    the site's resource directives, and `srun` for the payload where required.
    Keep the working directory at the investigation root so `scripts/` and `out/` resolve.
-5. Update the investigation README, then append the decision and its README link to
+5. When the result is a report someone will read (a comparison of runs, a dependence,
+   "what changed and why"), write it by [report-guide.md](report-guide.md): question and
+   answer first, original fields side by side on one scale, each figure explained
+   before and after, provenance and checks at the end, as `README.md` plus a
+   self-contained `report.html`. [example-report/](example-report/README.md) shows it.
+6. Update the investigation README, then append the decision and its README link to
    `LOG.md`. Put reusable formulas, methods and pitfalls in `notes/<topic>.md`.
-6. `runo tidy --only analysis-logs` previews old job logs, retaining the newest pair per
+7. `runo tidy --only analysis-logs` previews old job logs, retaining the newest pair per
    job name in each logs directory. Apply with `runo tidy --apply --only analysis-logs`.
    Archiving a whole group directory also moves its `_analysis/`; a partial archive
    leaves shared analysis with the remaining runs. `restore RUN` restores only that run.
-7. For an existing project's scattered files, show source → destination paths before
+8. For an existing project's scattered files, show source → destination paths before
    moving anything, then fix affected script paths and document links. Keep results.

runops-2.8.0/src/runops/skills/runops-analyze/example-report/README.md

@@ -0,0 +1,97 @@
+# ヒーターを離して置いても、センサーの温度は上がるか
+
+> これは `runops-analyze` skill に同梱した書き方の見本です。数値は
+> `scripts/make_figures.py` が作る模擬データで、実在の計算結果ではありません。
+> run id などの再現情報も、書く場所を示すための例です。
+
+## 調べたことと結果
+
+金属板の中央に温度センサーがあり、板の上にヒーターを 1 個置きます。ヒーターを
+センサーの真上に置けばセンサーが温まるのは当然ですが、知りたいのは、ヒーターを
+センサーから離して置いたときです。センサーの温度は上がるのか。上がるなら、それは
+センサーだけが局所的に熱せられているのか、板の広い範囲が温まった結果なのか。
+
+ヒーターの出力（10 W）と板の条件は固定し、ヒーターとセンサーの距離だけを 0 cm から
+12 cm まで変えました。比較の基準は、ヒーターを切った計算です。
+
+結果は次のとおりです。ヒーターを 8 cm 離しても、センサーの温度は基準より約 8 K
+高くなりました。このときセンサーとその周囲の温度はほぼ同じで、センサーだけが熱い
+状態にはなっていません。離れたヒーターは、板の広い範囲を温めることを通して
+センサーの温度を上げています。
+
+## 温度分布を並べて見る
+
+まず、板全体の温度がどう変わるかを見ます。図 1 は、ヒーターを切った場合、センサーの
+真上に置いた場合、8 cm 離して置いた場合の温度分布を、同じ範囲と同じ色尺度で並べた
+ものです。色が明るいほど高温で、白い丸がセンサー、水色の三角がヒーターの位置です。
+白い破線の円（半径 3 cm）は、あとで「センサーの周囲」として温度を平均する範囲を
+示しています。どの分布も、計算が定常に達した後の最後の 1000 step の平均です。
+
+![図 1: ヒーターなし、センサー直上、8 cm 離した場合の温度分布](out/fig1_maps.png)
+
+左の図は一様に 20 °C で、これが比較の基準です。中央の図では、ヒーターを中心に
+温度が上がり、センサーは 50 °C と板の中で最も高温になっています。右の図では高温の
+中心がヒーターとともに右へ移りますが、温まった範囲はセンサーの位置まで広がって
+おり、センサーは 27.9 °C を示します。破線の円の中を見ると、中央の図では円の中心が
+周りより明らかに明るいのに対し、右の図では円の中に目立った明暗がありません。
+
+つまり、離れたヒーターでもセンサーの温度は上がりますが、その上がり方は直上に置いた
+場合と違い、センサーの位置が特別に熱いわけではないように見えます。ただし図 1 は
+2 つの距離しか示していません。次に、距離を細かく変えてこの見方を確かめます。
+
+## 距離を変えたときの変化
+
+図 2 は、ヒーターとセンサーの距離を横軸にとり、2 つの量を示しています。(a) は
+センサーの温度が基準（ヒーターなし）からどれだけ上がったか、(b) はセンサーの温度から
+周囲（図 1 の破線の円周上）の平均温度を引いた値です。(b) が正で大きいほど、
+センサーの位置だけが局所的に熱いことを表し、0 に近ければセンサーは周囲と同じ温度
+です。赤い点は図 1 で分布を示した 2 つの距離です。
+
+![図 2: センサーの温度上昇と、周囲との温度差の距離依存性](out/fig2_dependence.png)
+
+(a) の温度上昇は距離とともにゆるやかに小さくなり、8 cm で 7.9 K、12 cm でも 4.1 K
+残ります。一方、(b) の周囲との差は 0 cm の 11.8 K から急に小さくなり、4 cm で 0.6 K、
+8 cm 以上ではほぼ 0（−0.1 K）です。
+
+| 距離 [cm] | センサーの温度上昇 [K] | センサー − 周囲 [K] |
+|---|---|---|
+| 0 | 30.0 | 11.8 |
+| 2 | 21.5 | 3.9 |
+| 4 | 15.4 | 0.6 |
+| 8 | 7.9 | −0.1 |
+| 12 | 4.1 | −0.1 |
+
+2 つの量が違う速さで小さくなることが、最初の問いへの答えです。ヒーターを 4 cm 以上
+離すと、センサーの温度はまだ 15 K 上がっているのに、周囲との差はほとんど消えます。
+この距離では、センサーはヒーターに直接熱せられているのではなく、温まった板と同じ
+温度になっています。
+
+この結果からは判断できないこともあります。保存したのは板の温度分布だけなので、
+熱が板の中を伝わってセンサーに届いたのか、板の上の空気を通って届いたのかは
+区別できません。「板の広い範囲が温まる」という説明は分布の形から言えることで、
+熱の経路ごとの寄与を分けた結果ではありません。
+
+## 再現情報
+
+| 条件 | run | 計算コード | 平均した区間 |
+|---|---|---|---|
+| ヒーターなし（基準） | `R20261101-0001` | plate-sim 1.4.2 | step 9001–10000 |
+| 距離 0, 2, 4, 8, 12 cm | `R20261101-0002` – `0006` | plate-sim 1.4.2 | step 9001–10000 |
+
+- 6 本とも同じ版・同じ格子・同じ step 数の計算で、違いはヒーターの有無と位置だけです。
+  センサーの温度が最後の 1000 step で 0.01 K 以内に収まっていることを確認し、
+  その区間を平均しました。
+- 図に平滑化やマスクは使っていません。「周囲」は、センサーを中心とする半径 3 cm の
+  円周上の 720 点の平均です。
+- 図と表は `scripts/make_figures.py` が作ります。図 2 と表の元の数値は
+  [out/values.csv](out/values.csv) にあります。
+- `report.html` は `scripts/build_html.py` がこの README から作る、図を埋め込んだ
+  単体で読めるファイルです。
+
+## 確認記録
+
+- ファイル: `python scripts/build_html.py --check` が、`report.html` が README と一致し、
+  画像 2 枚を埋め込んでいると報告しました。
+- 図の内容: 2 枚の PNG を開き、軸ラベル、色尺度、各列の条件名と温度の文字が読めること、
+  表の値と図 2 の点が一致することを確認しました。
+- ブラウザ表示: `report.html` をブラウザで開いた確認はしていません。

runops-2.8.0/src/runops/skills/runops-analyze/example-report/out/values.csv

@@ -0,0 +1,6 @@
+offset_cm,sensor_degC,rise_K,ring_mean_degC,sensor_minus_ring_K
+0.0,50.0,30.0,38.2,11.8
+2.0,41.5,21.5,37.63,3.86
+4.0,35.4,15.4,34.79,0.62
+8.0,27.91,7.91,28.02,-0.11
+12.0,24.06,4.06,24.19,-0.13