QUICKREF.md

Quick Reference

Use this page for implementation-time reminders.

Canonical techniques

1. Adaptive fixpoint iteration
2. Scheduled fuel
3. Learned rewrite policy
4. Bounded join

Core mapping

Adaptive technique	Compiler role	Typical benefit
Adaptive fixpoint iteration	Dampen oscillation in cyclic flows	Fewer iterations in loops
Scheduled fuel	Allocate optimization work by phase	Less wasted rewrite effort
Learned rewrite policy	Pick rewrites from confidence data	Better phase-ordering behavior
Bounded join	Cap unstable fact growth	Better stability in hard domains

Working formulas

Adaptive fixpoint iteration

m_t = beta1 * m_{t-1} + (1 - beta1) * fact_t
fact'_t = m_t

Use for cyclic control flow and oscillating fact updates.

Scheduled fuel

fuel_t = max(minFuel, floor(fuel0 * decay^t))

Use when pass utility drops over time.

Learned rewrite policy

P(strategy_i) = exp(conf_i / tau) / sum_j exp(conf_j / tau)

Use when multiple rewrite options compete and profile data exists.

Bounded join

join(old, new) = if size(new) > threshold then top else new

Use in domains where facts can spike and destabilize convergence.

Parameter defaults

Parameter	Starting value	Notes
beta1	0.9	More smoothing as value increases
beta2	0.999	Optional variance tracking for adaptive updates
eps	1e-8	Numerical guard in adaptive equations
decay	0.9	Controls fuel taper rate
tau	1.0	Lower exploits, higher explores
threshold	domain-specific	Set from observed fact magnitudes

Common pitfalls

1. Over-smoothing (beta1 too high) can slow convergence.
2. Over-aggressive fuel decay can end optimization too early.
3. Extreme tau values can collapse to one rewrite or randomize choices.
4. Low threshold can destroy precision by forcing top too often.

Sanity checklist

• Monotonicity still holds under your join/update strategy.
• Termination arguments are explicit for your domain.
• Adaptive behavior outperforms static baseline on at least one cyclic case.
• Metrics are labeled illustrative unless benchmark method is documented.

Notes on reported numbers

Any speedups in this repository are demonstration results from small examples, not production benchmark claims.