Mechanism Diversity

Opt-in mechanism-family rollout workflows and diagnostics checks.

Use mechanism-diversity workflows when you want to exercise the existing family-mix surface, compare candidate mechanism behavior against the current baseline, and verify that the generated bundles actually realize the intended families or variants.

When to use

You want to compare the current baseline sampler against the shipped piecewise control or the widened gp candidate path.
You need realized mechanism-family and mechanism-variant counts in bundle metadata and audit reports.
You want diversity-audit and filter-calibration evidence before treating a new mechanism path as stable.

Public interface rule

This workflow intentionally keeps the config surface narrow:

No new config sections.
No family-specific scalar knobs.
No new CLI flags.
The public surface remains mechanism.function_family_mix; the widened gp behavior is an internal variant expansion behind the existing gp family label, while piecewise remains an explicit mix-controlled family.
mechanism.function_family_mix.piecewise must still be paired with at least one explicit branch family from tree, discretization, gp, linear, or quadratic.

The curated smoke presets now cover two roles:

piecewise remains the shipped control path with the explicit piecewise + linear staged mix.
gp presets isolate the widened gp family so diversity evidence can be attributed to gp.standard, gp.periodic, and gp.multiscale.

Generate with widened `gp`

Use the curated GP smoke preset for direct generation:

dagzoo generate \
  --config configs/preset_mechanism_gp_generate_smoke.yaml \
  --num-datasets 10 \
  --device cpu \
  --hardware-policy none \
  --out data/run_gp_smoke_local

Inspect shard metadata.ndjson for:

mechanism_families.sampled_family_counts
mechanism_families.families_present
mechanism_families.sampled_variant_counts
mechanism_families.variants_present
mechanism_families.total_function_plans

Diversity-audit workflow

Compare the matched baseline preset against the widened gp preset:

dagzoo diversity-audit \
  --baseline-config configs/preset_mechanism_baseline_benchmark_smoke.yaml \
  --variant-config configs/preset_mechanism_gp_benchmark_smoke.yaml \
  --suite smoke \
  --num-datasets 10 \
  --warmup 0 \
  --device cpu \
  --out-dir benchmarks/results/diversity_audit_gp

Inspect summary.json and summary.md for:

comparisons[*].diversity_composite_shift_pct
baseline.mechanism_family_summary
variants[*].mechanism_family_summary
variants[*].mechanism_family_summary.sampled_variant_counts
variants[*].mechanism_family_summary.dataset_presence_rate_by_variant

The audit status thresholds treat larger diversity shift as divergence, so use the raw shift percentages together with throughput and acceptance-yield metrics instead of treating pass/warn/fail as a standalone go/no-go decision.

piecewise remains the shipped control. Keep the matched control audit handy:

dagzoo diversity-audit \
  --baseline-config configs/preset_mechanism_baseline_benchmark_smoke.yaml \
  --variant-config configs/preset_mechanism_piecewise_benchmark_smoke.yaml \
  --suite smoke \
  --num-datasets 10 \
  --warmup 0 \
  --device cpu \
  --out-dir benchmarks/results/diversity_audit_piecewise_control

Filter-calibration workflow

Use the GP filter-enabled preset to check accepted-corpus throughput and yield against diversity shift:

dagzoo filter-calibration \
  --config configs/preset_mechanism_gp_filter_smoke.yaml \
  --suite smoke \
  --device cpu \
  --out-dir benchmarks/results/filter_calibration_gp