sgtlearn 0.2.0__tar.gz → 0.3.1__tar.gz

sgtlearn-0.3.1/CONTEXT.md

@@ -0,0 +1,46 @@
+# Shape Generalized Trees
+
+Language for learning trees whose branching decisions are represented by shape functions.
+
+## Language
+
+**Outer tree**:
+The prediction tree whose internal nodes route samples through learned shape functions.
+
+**Inner tree**:
+The tree used to partition a feature, or a pair of features, into bins for a shape function.
+
+**Bin**:
+A region produced by an inner tree whose samples share one branch assignment.
+
+**Branch assignment**:
+The mapping from inner bins to the children of an outer node.
+
+**Branching factor**:
+The upper bound on the number of children produced by an outer split.
+
+**Split arity**:
+The number of children actually produced by a particular outer split.
+
+**Sample mass**:
+The sum of sample weights in a dataset or region; it equals the sample count when every sample has weight one.
+
+**Outer impurity**:
+The arithmetic mean of per-target weighted impurity measures at an outer node. Multiplying it by sample mass gives the node's total weighted impurity contribution.
+
+**Leaf budget**:
+The maximum permitted number of outer leaves. Replacing one leaf with a split of arity k consumes k - 1 additional leaves.
+_Avoid_: Node budget, when referring to `max_leaf_nodes`.
+
+**Best-first outer growth**:
+Outer-tree growth that selects the available split with the greatest positive regularized impurity improvement.
+_Avoid_: BFS, which commonly means breadth-first search and does not describe this ordering.
+
+**Regularized split improvement**:
+The decrease in total weighted leaf impurity minus the additional complexity costs incurred by a split. Zero or negative improvement does not justify growth.
+
+**Split candidate**:
+A proposed outer split with its shape function, branch assignments, actual arity, and impurity improvement.
+
+**Pair-screening proxy**:
+A feasible univariate partition with positive raw impurity improvement used to estimate the promise of a feature interaction. Eligibility is independent of complexity penalties.

{sgtlearn-0.2.0 → sgtlearn-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sgtlearn
-Version: 0.2.0
+Version: 0.3.1
 Summary: Shape Generalized Trees learning library
 Author-Email: Nakul Upadhya <nakulupadhya1@gmail.com>, Joshua Lee <joshua.lee.9880@gmail.com>, Eldan Cohen <eldan.cohen@utoronto.ca>
 License: MIT
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 
 `sgtlearn` is a Python package for learning [Shape Generalized Trees (SGTs)](https://neurips.cc/virtual/2025/loc/san-diego/poster/115950).
 
-- 🌳 **Shape Generalized Trees (SGTs):** A class of decision trees where each node applies a learnable, axis-aligned shape function to a feature for non-linear and interpretable splits.
+- 🌳 **Shape Generalized Trees (SGTs):** A class of decision trees where each node applies a learnable, axis-aligned shape function to one or two logical features for non-linear and interpretable splits.
 - 👁 **Interpretability:** Each node's shape function can be visualized directly.
 - ⚡ **ShapeCART Algorithm:** An efficient induction method for learning SGTs from data.
 - 🔀 **Extensions:**
@@ -39,10 +39,9 @@ Description-Content-Type: text/markdown
   - **SGT<sub>K</sub>:** Multi-way branching generalization.
   - **Shape²CART & ShapeCART<sub>K</sub>:** Algorithms for learning S²GTs and SGT<sub>K</sub>s.
 
+
 > [!NOTE]
-> This codebase is an efficient, but working implementation of the algorithms in the paper "Empowering Decision Trees via Shape Function Branching". Please refer to the [ROADMAP](ROADMAP.md) for a detailed list of features that are currently implemented and those that are planned for future releases. For the canonical code base for the paper, please refer to https://github.com/optimal-uoft/Empowering-DTs-via-Shape-Functions. Features in the paper that are not yet implemented in this codebase include: 
-> * Bivariate shape functions (Shape$^2$CART) + Higher branching factors for bivariate splits (Shape$^2$SGT$_K$)
-> * Visualization for bivariate splits (ex. contour plots)
+> This codebase is an efficient implementation of the algorithms in "Empowering Decision Trees via Shape Function Branching." See the [ROADMAP](ROADMAP.md) for implementation status and the [canonical research code](https://github.com/optimal-uoft/Empowering-DTs-via-Shape-Functions) for the paper's original implementation.
 
 ## Installation
 
@@ -73,6 +72,22 @@ plt.show()
 ```
 
 Read the full docs here: https://sgtlearn.readthedocs.io/en/latest/index.html 
+
+Outer growth now always selects the best available regularized split and
+strictly respects `max_leaf_nodes`, including multiway splits. Its impurity
+improvement uses total sample weight and the mean across target outputs.
+`min_impurity_decrease`, `branching_penalty` (new, default `0.0`), and
+`pairwise_penalty` subtract constant costs in these units; existing positive
+penalties may need retuning. Inner CART and TAO retain their separate settings.
+See [outer-growth semantics](docs/api/estimators.rst) for the scoring formula.
+
+For `SGTRegressor` and `RandomSGForestRegressor`, MAE (`criterion="absolute_error"`
+or `"mae"`) leaves coordinate descent disabled by default. Each top-level fit
+emits one `UserWarning`, including parallel forest fits. Set the environment
+variable `SGTLEARN_MAE_CD=1` before fitting to enable it and omit the warning.
+The native flag also accepts exactly `true`, `TRUE`, or `yes`; other values keep
+CD disabled. This does not change TAO settings or affect classification/MSE.
+
 ## Developer Setup
 
 Use a **project-local virtual environment** (`.venv`) so Python, pytest, and

{sgtlearn-0.2.0 → sgtlearn-0.3.1}/README.md

@@ -4,7 +4,7 @@
 
 `sgtlearn` is a Python package for learning [Shape Generalized Trees (SGTs)](https://neurips.cc/virtual/2025/loc/san-diego/poster/115950).
 
-- 🌳 **Shape Generalized Trees (SGTs):** A class of decision trees where each node applies a learnable, axis-aligned shape function to a feature for non-linear and interpretable splits.
+- 🌳 **Shape Generalized Trees (SGTs):** A class of decision trees where each node applies a learnable, axis-aligned shape function to one or two logical features for non-linear and interpretable splits.
 - 👁 **Interpretability:** Each node's shape function can be visualized directly.
 - ⚡ **ShapeCART Algorithm:** An efficient induction method for learning SGTs from data.
 - 🔀 **Extensions:**
@@ -12,10 +12,9 @@
   - **SGT<sub>K</sub>:** Multi-way branching generalization.
   - **Shape²CART & ShapeCART<sub>K</sub>:** Algorithms for learning S²GTs and SGT<sub>K</sub>s.
 
+
 > [!NOTE]
-> This codebase is an efficient, but working implementation of the algorithms in the paper "Empowering Decision Trees via Shape Function Branching". Please refer to the [ROADMAP](ROADMAP.md) for a detailed list of features that are currently implemented and those that are planned for future releases. For the canonical code base for the paper, please refer to https://github.com/optimal-uoft/Empowering-DTs-via-Shape-Functions. Features in the paper that are not yet implemented in this codebase include: 
-> * Bivariate shape functions (Shape$^2$CART) + Higher branching factors for bivariate splits (Shape$^2$SGT$_K$)
-> * Visualization for bivariate splits (ex. contour plots)
+> This codebase is an efficient implementation of the algorithms in "Empowering Decision Trees via Shape Function Branching." See the [ROADMAP](ROADMAP.md) for implementation status and the [canonical research code](https://github.com/optimal-uoft/Empowering-DTs-via-Shape-Functions) for the paper's original implementation.
 
 ## Installation
 
@@ -46,6 +45,22 @@ plt.show()
 ```
 
 Read the full docs here: https://sgtlearn.readthedocs.io/en/latest/index.html 
+
+Outer growth now always selects the best available regularized split and
+strictly respects `max_leaf_nodes`, including multiway splits. Its impurity
+improvement uses total sample weight and the mean across target outputs.
+`min_impurity_decrease`, `branching_penalty` (new, default `0.0`), and
+`pairwise_penalty` subtract constant costs in these units; existing positive
+penalties may need retuning. Inner CART and TAO retain their separate settings.
+See [outer-growth semantics](docs/api/estimators.rst) for the scoring formula.
+
+For `SGTRegressor` and `RandomSGForestRegressor`, MAE (`criterion="absolute_error"`
+or `"mae"`) leaves coordinate descent disabled by default. Each top-level fit
+emits one `UserWarning`, including parallel forest fits. Set the environment
+variable `SGTLEARN_MAE_CD=1` before fitting to enable it and omit the warning.
+The native flag also accepts exactly `true`, `TRUE`, or `yes`; other values keep
+CD disabled. This does not change TAO settings or affect classification/MSE.
+
 ## Developer Setup
 
 Use a **project-local virtual environment** (`.venv`) so Python, pytest, and

{sgtlearn-0.2.0 → sgtlearn-0.3.1}/ROADMAP.md

@@ -17,6 +17,18 @@
 - [x] **NaN routing at predict**: if training saw missing at that split, follow the stored direction; otherwise route to the majority child.
 
 ## v0.3.0
-- [ ] multioutput support
-- [ ] Shape$^2$CART
-- [ ] Shape$^2$CART Random Forest Ensembling  
+- [x] multioutput support
+- [x] Opt-in Shape$^2$CART for SGT estimators, including continuous/categorical
+  pairs, joint missing routing, and multiway branching ([tutorial](https://sgtlearn.readthedocs.io/en/latest/tutorials/bivariate-branching.html))
+- [x] Shape$^2$CART Random Forest Ensembling
+- [x] Pair-aware TAO refinement ([#48](https://github.com/optimal-uoft/sgtlearn/issues/48))
+- [x] Shape$^2$CART routing heatmap visualization ([#28](https://github.com/optimal-uoft/sgtlearn/issues/28))
+
+See the implementation specification in [#42](https://github.com/optimal-uoft/sgtlearn/issues/42)
+and the umbrella issue [#27](https://github.com/optimal-uoft/sgtlearn/issues/27).
+
+
+## v1.0.0
+- [ ] Cross-Feature Tree Binning (Similar to [DPDT](https://github.com/KohlerHECTOR/DPDTreeEstimator) 
+- [ ] Boosting
+- [ ] Default Optuna Support

sgtlearn-0.3.1/benchmarks/check_outer_growth.py

@@ -0,0 +1,23 @@
+"""Runnable checks for benchmark scoring and comparison (no training required)."""
+import numpy as np
+
+from outer_growth import quality, summarize
+from compare_outer_growth import performance_ratios, quality_change
+
+y = np.array([[0, 0], [1, 1], [1, 0]])
+p = np.array([[0, 1], [0, 1], [1, 0]])
+assert quality(y, p, np.array([1, 2, 1]), "gini") == {
+    "metric": "accuracy", "mean": 0.625, "per_output": [0.5, 0.75]
+}
+assert quality(y, p, None, "squared_error")["mean"] == 1 / 3
+assert summarize([1, 2, 3, 4, 5]) == {"median": 3.0, "mad": 1.0, "min": 1.0, "max": 5.0}
+old = {k: {"median": 100} for k in ("fit_seconds", "predict_seconds_per_row", "peak_fit_process_tree_rss_bytes")}
+new = {"fit_seconds": {"median": 126}, "predict_seconds_per_row": {"median": 125}, "peak_fit_process_tree_rss_bytes": {"median": 151}}
+ratios = performance_ratios(old, new)
+assert ratios["fit_seconds"] == {"ratio": 1.26, "investigate": True}
+assert ratios["predict_seconds_per_row"] == {"ratio": 1.25, "investigate": False}
+assert ratios["peak_fit_process_tree_rss_bytes"] == {"ratio": 1.51, "investigate": True}
+assert quality_change({"metric": "accuracy", "mean": 0.8}, {"mean": 0.81}) == "+1.000 pp"
+assert quality_change({"metric": "mse", "mean": 2}, {"mean": 1.5}) == "-0.500000 (-25.00%)"
+assert quality_change({"metric": "mae", "mean": 0}, {"mean": 0.1}) == "+0.100000 (relative undefined (baseline 0))"
+print("benchmark checks passed")

sgtlearn-0.3.1/benchmarks/compare_outer_growth.py

@@ -0,0 +1,155 @@
+"""Interleave matched old/new workers from outer_growth.py; no training at import."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+
+from outer_growth import report
+
+
+def performance_ratios(old, new):
+    return {key: {"ratio": new[key]["median"] / old[key]["median"],
+                  "investigate": new[key]["median"] / old[key]["median"] > limit}
+            for key, limit in (("fit_seconds", 1.25), ("predict_seconds_per_row", 1.25),
+                               ("peak_fit_process_tree_rss_bytes", 1.5))}
+
+
+def quality_change(before, after):
+    delta = after["mean"] - before["mean"]
+    if before["metric"] == "accuracy":
+        return f"{100 * delta:+.3f} pp"
+    relative = f"{100 * delta / before['mean']:+.2f}%" if before["mean"] != 0 else "relative undefined (baseline 0)"
+    return f"{delta:+.6f} ({relative})"
+
+
+def comparison(rows):
+    summaries = {label: report([r for r in rows if r["build"] == label])
+                 for label in ("baseline", "candidate")}
+    result = {}
+    for name in summaries["baseline"].keys() & summaries["candidate"].keys():
+        old, new = (summaries[label][name] for label in ("baseline", "candidate"))
+        if "fit_seconds" not in old or "fit_seconds" not in new:
+            continue
+        quality = []
+        for before in old["quality"]:
+            after = next((q for q in new["quality"] if q["seed"] == before["seed"]), None)
+            if after is None:
+                continue
+            delta = after["sgt"]["mean"] - before["sgt"]["mean"]
+            quality.append({"seed": before["seed"], "baseline": before, "candidate": after,
+                            "candidate_minus_baseline": delta,
+                            "training_quality_decreased": delta < 0 if before["sgt"]["metric"] == "accuracy" else delta > 0})
+        result[name] = {"performance": performance_ratios(old, new), "baseline": old,
+                        "candidate": new, "quality": quality}
+    return dict(sorted(result.items()))
+
+
+def write_report(output, rows, settings):
+    result = comparison(rows)
+    (output / "comparison.json").write_text(json.dumps(result, indent=2) + "\n")
+    lines = ["# Matched outer-growth comparison", "",
+             "Training quality is the primary soft signal. Changes below are candidate minus baseline: accuracy changes use percentage points (pp); regression losses show absolute and relative changes. Higher accuracy and lower loss are better. No numeric quality cutoff is imposed. Every worse-than-CART seed remains flagged.", ""]
+    if settings["candidate_branching_penalty"] is not None:
+        lines += [f"Separate regularization experiment: candidate branching_penalty={settings['candidate_branching_penalty']}; baseline has no public branching penalty. This is not the common zero-penalty comparison.", ""]
+    lines += ["| Workload / seed | Metric | Baseline | Candidate | Change | CART | Worse than CART (old/new) | Structural leaves (old/new) |",
+              "|---|---|---:|---:|---:|---:|---|---|"]
+    for name, entry in result.items():
+        for q in entry["quality"]:
+            before, after = q["baseline"], q["candidate"]
+            cart = f"{before['cart']['mean']:.6f}" if "cart" in before else "Excluded: grouped categorical/missing"
+            flags = f"{before.get('worse_than_cart', 'excluded')}/{after.get('worse_than_cart', 'excluded')}"
+            leaves = [[t["structural_leaves"] for t in row["structure"]] for row in (before, after)]
+            lines.append(f"| {name} / {q['seed']} | {before['sgt']['metric']} | {before['sgt']['mean']:.6f} | {after['sgt']['mean']:.6f} | {quality_change(before['sgt'], after['sgt'])} | {cart} | {flags} | {leaves[0]}/{leaves[1]} |")
+    lines += ["", "Ratios are candidate / baseline medians. Investigate fit or prediction >1.25× and peak RSS >1.50×; confirm breaches with matched reruns beyond measured noise. Review changed tree sizes alongside costs.", "",
+              "| Workload | Fit ratio | Predict latency ratio | Peak RSS ratio | Review gates |",
+              "|---|---:|---:|---:|---|"]
+    for name, entry in result.items():
+        perf = entry["performance"]
+        flags = [key for key, value in perf.items() if value["investigate"]]
+        values = [perf[key]["ratio"] for key in ("fit_seconds", "predict_seconds_per_row", "peak_fit_process_tree_rss_bytes")]
+        lines.append(f"| {name} | {values[0]:.3f}× | {values[1]:.3f}× | {values[2]:.3f}× | {', '.join(flags) or 'No breach'} |")
+    lines += ["", "Raw per-output quality, occupied leaves, depth, node counts, timing dispersion and provenance are preserved in raw.jsonl and comparison.json. Each matched pair uses the same manifest, dataset hash and seed; order alternates by round. Warmup and extra quality runs are excluded from timing medians. The runner documents memory scope in outer_growth.md.", ""]
+    (output / "comparison.md").write_text("\n".join(lines))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--baseline-python", required=True)
+    parser.add_argument("--baseline-checkout", required=True)
+    parser.add_argument("--candidate-python", required=True)
+    parser.add_argument("--candidate-checkout", required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--manifest", type=Path, default=Path(__file__).with_name("outer_growth_manifest.json"))
+    parser.add_argument("--workload")
+    parser.add_argument("--candidate-branching-penalty", type=float)
+    args = parser.parse_args()
+    runner = Path(__file__).with_name("outer_growth.py").resolve()
+    manifest = json.loads(args.manifest.read_text())
+    settings = {"baseline_python": str(Path(args.baseline_python).absolute()),
+                "baseline_checkout": str(Path(args.baseline_checkout).resolve()),
+                "candidate_python": str(Path(args.candidate_python).absolute()),
+                "candidate_checkout": str(Path(args.candidate_checkout).resolve()),
+                "candidate_branching_penalty": args.candidate_branching_penalty,
+                "manifest": manifest, "runner_sha256": hashlib.sha256(runner.read_bytes()).hexdigest()}
+    for label in ("baseline", "candidate"):
+        settings[f"{label}_revision"] = subprocess.check_output(
+            ["git", "-C", settings[f"{label}_checkout"], "rev-parse", "HEAD"], text=True).strip()
+    args.output.mkdir(parents=True, exist_ok=True)
+    settings_path = args.output / "settings.json"
+    if settings_path.exists() and json.loads(settings_path.read_text()) != settings:
+        raise ValueError("Output directory belongs to different settings; use a new directory")
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+    raw = args.output / "raw.jsonl"
+    rows = [json.loads(line) for line in raw.read_text().splitlines()] if raw.exists() else []
+    env = dict(os.environ, **manifest["environment"])
+    env.pop("PYTHONPATH", None)
+    for work in manifest["workloads"]:
+        if args.workload and args.workload != work["id"]:
+            continue
+        cases = [("sgt", manifest["timing_seed"], rep) for rep in range(-1, manifest["repetitions"])]
+        cases += [("sgt", seed, -1) for seed in manifest["quality_seeds"] if seed != manifest["timing_seed"]]
+        cases += [("cart", seed, -1) for seed in manifest["quality_seeds"]]
+        for round_index, (model, seed, rep) in enumerate(cases):
+            order = ("baseline", "candidate") if round_index % 2 == 0 else ("candidate", "baseline")
+            pair = []
+            for label in order:
+                existing = next((r for r in rows if r["build"] == label and r["workload"] == work["id"] and r["model"] == model and r["seed"] == seed and r.get("rep", -1) == rep), None)
+                if existing is not None:
+                    pair.append(existing)
+                    continue
+                command = [settings[f"{label}_python"], str(runner), "--worker", "--manifest", str(args.manifest.resolve()),
+                           "--checkout", settings[f"{label}_checkout"], "--workload", work["id"], "--model", model, "--seed", str(seed), "--rep", str(rep)]
+                if label == "candidate" and args.candidate_branching_penalty is not None:
+                    command += ["--branching-penalty", str(args.candidate_branching_penalty)]
+                run = subprocess.run(command, cwd=settings[f"{label}_checkout"], env=env, capture_output=True, text=True, timeout=300)
+                with (args.output / "stderr.log").open("a") as log:
+                    log.write(f"{label} {work['id']} {model} {seed} {rep}\n{run.stderr}\n")
+                if run.returncode:
+                    raise RuntimeError(f"Worker failed: {command}\n{run.stderr}\n{run.stdout}")
+                row = dict(json.loads(run.stdout), build=label, round=round_index)
+                if label == "baseline" and "provenance" in row and row["provenance"]["revision"] != manifest["baseline_revision"]:
+                    raise ValueError("Baseline source revision does not match frozen manifest")
+                rows.append(row)
+                pair.append(row)
+                with raw.open("a") as handle:
+                    handle.write(json.dumps(row) + "\n")
+                print(label, work["id"], model, seed, rep, row.get("fit_seconds", row.get("excluded")), flush=True)
+            if all("provenance" in row for row in pair):
+                if pair[0]["dataset_sha256"] != pair[1]["dataset_sha256"]:
+                    raise ValueError("Matched workers produced different datasets")
+                for key in ("python", "platform", "machine", "numpy", "sklearn", "environment"):
+                    if pair[0]["provenance"][key] != pair[1]["provenance"][key]:
+                        raise ValueError(f"Matched environments differ: {key}")
+                pools = [[{k: v for k, v in p.items() if k != "filepath"} for p in r["provenance"]["threadpools"]] for r in pair]
+                if pools[0] != pools[1]:
+                    raise ValueError("Matched native thread pools differ")
+            write_report(args.output, rows, settings)
+    print(args.output / "comparison.md")
+
+
+if __name__ == "__main__":
+    main()

sgtlearn-0.3.1/benchmarks/outer_growth.md

@@ -0,0 +1,102 @@
+# Outer growth baseline and comparison
+
+Issue [#55](https://github.com/optimal-uoft/sgtlearn/issues/55), baseline commit
+`90fb148e8b9b4181534dd2a19a5837aa85fba506`. Run the same manifest and runner
+against separately built baseline and candidate environments. The runner rejects
+SGT Python/native imports outside its virtual environment and records their SHA256
+hashes, source revision, resolved estimator parameters and data hashes.
+
+```sh
+git worktree add --detach /tmp/sgtlearn-baseline-90fb148 90fb148e8b9b4181534dd2a19a5837aa85fba506
+uv venv /tmp/sgtlearn-baseline-90fb148/.venv --python 3.14.5
+uv pip install --python /tmp/sgtlearn-baseline-90fb148/.venv/bin/python -r benchmarks/results/outer-growth-baseline/dependencies.txt
+CMAKE_BUILD_PARALLEL_LEVEL=4 uv pip install --python /tmp/sgtlearn-baseline-90fb148/.venv/bin/python --no-build-isolation --no-deps /tmp/sgtlearn-baseline-90fb148 --config-settings build-dir=/tmp/sgtlearn-baseline-90fb148/build
+/tmp/sgtlearn-baseline-90fb148/.venv/bin/python benchmarks/check_outer_growth.py
+/tmp/sgtlearn-baseline-90fb148/.venv/bin/python benchmarks/outer_growth.py --checkout /tmp/sgtlearn-baseline-90fb148 --output benchmarks/results/outer-growth-baseline
+```
+
+Use an absolute runner path when invoking from another directory. An interrupted
+run resumes completed rows; use a new output directory for matched reruns or a
+different build/configuration. `--workload ID` selects a workload. To compare new
+branching regularization separately, use `--branching-penalty VALUE` with a new
+output directory. The baseline does not support that public parameter. Equal
+positive old/new `min_impurity_decrease` or `pairwise_penalty` values do **not**
+represent equal regularization units. The frozen common suite uses zero penalties.
+
+The nine bounded synthetic workloads cover Gini, entropy, MSE, MAE; binary and
+multiway; capped and finite-depth uncapped growth; pairs; weights; multiple
+outputs; missing/grouped categorical data; serial and two-thread forests; MAE CD
+off/on; and induction only versus the unchanged automatic default TAO (10 runs).
+The queue workload has depth 8 and 31 leaves; the four-way/12-leaf pair workload
+forces repeated feasible-arity reductions near its cap. These characterize
+behavior; public exports cannot establish private queue sizes. The duplicate-X
+MAE case reuses the stress pattern in `tests/test_mae_regression_stress.py`.
+The existing native `cpp/tests/bench_mae_branch_assignment.cpp` remains the
+standalone branch-optimizer diagnostic; no duplicate microbenchmark is added.
+
+Each workload has one fresh-process warmup at timing seed 17, then five
+fresh-process measured repetitions. Extra warmup/quality processes use seeds 29
+and 43. Raw rows retain all measurements. Startup, imports, dataset creation,
+quality scoring, exports and warning collection are outside fit timing. Multiple
+fits per process amortize timers where needed; their durations remain in raw
+data. Predictions repeat for at least 0.25 seconds on the full training matrix.
+Warnings are suppressed during timing and captured by a separate fit in quality
+processes. Run while no other builds/tests are active. The OS, compiler, build
+flags and exact package versions are preserved alongside results.
+
+Peak fit memory is the maximum RSS sampled every 5 ms over the process and its
+descendants, including worker memory. Existing forests use joblib threads, so
+workers share the process RSS. Summing RSS can double count shared pages in a
+future subprocess backend. The separate OS lifetime high-water RSS ends just
+after timed fits and includes interpreter/import/data overhead. Sampling can
+miss brief allocations; these figures are process footprint, not isolated native
+allocation counts. Native BLAS/OpenMP threads are fixed at one; forest n_jobs
+is fixed independently. Medians and median absolute deviations (MAD) are reported
+with min/max; gates are review thresholds, never ordinary CI timing assertions.
+
+Classification training accuracy is sample-weighted where weights are supplied;
+multioutput results are per-output accuracy plus their arithmetic mean (not
+subset/exact-match accuracy). Regression reports criterion-appropriate weighted
+MSE or MAE per output and their mean. Each quality seed has a scikit-learn CART
+reference on the same data/weights, with the same criterion, outer maximum depth,
+maximum leaves and minimum leaf samples. CART remains binary with axis-aligned
+thresholds; SGT can route noncontiguous bins, group categories, use pairs, multiple
+children, TAO, and forests. Thus constraints are comparable rather than model
+families equivalent. CART forests are deliberately not substituted for CART.
+Grouped-categorical/missing comparison is explicitly excluded because preserving
+SGT's logical category/missing routing needs different preprocessing; no silent
+imputation changes the task. Exported structural/occupied leaves, depth and node
+counts accompany all quality measurements (per constituent for forests).
+
+Investigate >25% median fit/prediction slowdown or >50% peak-memory increase,
+confirming any breach beyond measured noise with repeated matched runs. Interpret
+performance alongside learned tree size. Training quality is the primary soft
+gate: similar or improved accuracy is expected, slight degradation is acceptable,
+and large reproducible drops need investigation without an invented numeric
+cutoff. Lower regression loss is better. Every worse-than-CART quality result is
+flagged without automatically failing the change. Default TAO and future positive
+regularization comparisons stay separate from induction-only zero-cost results.
+
+For the final common-configuration comparison, build the candidate in another
+isolated checkout/venv with the same dependency pins and Release settings, then
+interleave matching fresh-process runs:
+
+```sh
+.venv/bin/python benchmarks/compare_outer_growth.py \
+  --baseline-python /tmp/sgtlearn-baseline-90fb148/.venv/bin/python \
+  --baseline-checkout /tmp/sgtlearn-baseline-90fb148 \
+  --candidate-python /tmp/sgtlearn-candidate/.venv/bin/python \
+  --candidate-checkout /tmp/sgtlearn-candidate \
+  --output benchmarks/results/outer-growth-comparison
+```
+
+The driver alternates old/new order each round, verifies matching data hashes,
+Python/NumPy/sklearn versions, environment and native thread pools, and writes
+`raw.jsonl`, `comparison.json`, `comparison.md` and settings with revision/runner
+hashes. The Markdown report lists performance review gates and every quality seed
+with old/new/CART scores and leaf counts. Use `--workload ID` and a fresh output
+directory to confirm a suspected breach. Optional
+`--candidate-branching-penalty VALUE` produces a clearly labeled separate
+regularization experiment; use another output directory. Do not change/rebuild
+either environment during a run. Resume support skips completed rows; if a run
+is interrupted mid-pair, use a fresh directory for strict temporal matching.