Skip to content

Make operator target acceptance probability configurable; bump 1-D defaults to 0.3#71

Merged
rbouckaert merged 1 commit into
masterfrom
target-acceptance-1d-operators
May 18, 2026
Merged

Make operator target acceptance probability configurable; bump 1-D defaults to 0.3#71
rbouckaert merged 1 commit into
masterfrom
target-acceptance-1d-operators

Conversation

@alexeid
Copy link
Copy Markdown
Member

@alexeid alexeid commented May 4, 2026

Summary

Adds a targetAcceptanceProbability XML input on the Operator base class so users can override the auto-tune target per operator without code changes.
Refactors the resolution path (input -> getDefaultTargetAcceptanceProbability() -> base default) and migrates every existing override to the new method name.
Adjusts a few defaults at the same time.

What changes

Base class (Operator.java):

  • New Input<Double> targetAcceptanceProbabilityInput (default Double.NaN, meaning "use operator default").
  • getTargetAcceptanceProbability() now returns the input if set, otherwise calls getDefaultTargetAcceptanceProbability().
  • New getDefaultTargetAcceptanceProbability() returning 0.234, which subclasses override.

Migrated overrides (functionally equivalent, just renamed): BactrianScaleOperator, BactrianNodeOperator, BactrianRandomWalkOperator, BactrianIntervalOperator, BactrianDeltaExchangeOperator, EpochFlexOperator, AdaptableVarianceMultivariateNormalOperator (legacy and spec, drops final), IntervalScaleOperator (spec), AbstractScale (spec), RealRandomWalkOperator (spec), DeltaExchangeOperator (spec), IntervalOperator (spec).

Default bumped 0.234 -> 0.3 (1-D operators that were inheriting the base default):

  • SubtreeSlide, BactrianSubtreeSlide
  • ScaleOperator
  • TipDatesScaler, TipDatesRandomWalker (BactrianTipDatesRandomWalker inherits via its parent)
  • RealRandomWalkOperator (legacy inference)
  • DeltaExchangeOperator (legacy inference)

Default reverted 0.3 -> 0.234 (multi-D operators that should use the asymptotic target): BactrianUpDownOperator, UpDownOperator (spec).
The legacy inference/operator/UpDownOperator.java already inherited 0.234 and is unchanged.

Operators with deliberate non-default values are kept (EpochFlexOperator 0.4) but renamed to getDefaultTargetAcceptanceProbability.

Why

The 0.234 default comes from Roberts, Gelman, Gilks (1997) and is the asymptotic optimum for random-walk Metropolis as dimension increases.
For 1-D moves the optimum is closer to 0.44 (Gelman, Roberts, Gilks 1996; Roberts and Rosenthal 2001), so 0.234 is too low.

We observed this in practice on a real-data analysis: starting BactrianSubtreeSlide at size=0.002 with optimise="false" gave ~53% acceptance, but with optimise="true" the auto-tuner repeatedly increased step size to drive acceptance toward 0.234, and after enough moves the 1/n Robbins-Monro gain became too small to walk the size back when steady-state acceptance fell to ~5%.
A target of 0.3 is a conservative compromise that does not require the tuner to push as hard against the structural acceptance ceiling of these 1-D operators.

The XML input lets users override on a case-by-case basis without further code changes:

<operator id="treeSlide" spec="...BactrianSubtreeSlide" tree="@psi" weight="9.25"
          targetAcceptanceProbability="0.4"/>

Test plan

  • mvn -pl beast-base -am compile clean
  • mvn compile (all modules) clean
  • mvn -pl beast-base test -Dtest='*Operator*Test' -> 20/20 pass
  • Reviewer to confirm no XML schema/template assumes the absence of this input
  • Re-run the affected XML with the new defaults and confirm BactrianSubtreeSlide auto-tunes to a sensible step size

Add a 'targetAcceptanceProbability' Input on the Operator base class.
When set, it overrides the operator's default target.
The default is now resolved through a new getDefaultTargetAcceptanceProbability() method (returns 0.234 in the base class).
Subclasses that previously overrode getTargetAcceptanceProbability() now override getDefaultTargetAcceptanceProbability() instead, so the XML input applies uniformly across all operators.

Adjust per-operator defaults:
- 1-D operators that inherited the 0.234 default now return 0.3: SubtreeSlide, BactrianSubtreeSlide, ScaleOperator, TipDatesScaler, TipDatesRandomWalker (BactrianTipDatesRandomWalker inherits via its parent), RealRandomWalkOperator (inference), DeltaExchangeOperator (inference).
- BactrianUpDownOperator and spec UpDownOperator no longer override; they inherit the 0.234 base default (multi-D, asymptotic target applies).

Background: 0.234 is the asymptotic optimum for random-walk Metropolis in high dimension (Roberts, Gelman, Gilks 1997).
For 1-D moves the optimum is closer to 0.44 (Gelman, Roberts, Gilks 1996; Roberts, Rosenthal 2001).
A target of 0.3 is a conservative compromise.
The previous 0.234 default for 1-D operators caused the auto-tuner to inflate step size on data where natural acceptance at small sizes already exceeded 0.234, after which the 1/n Robbins-Monro gain was too small to recover when steady-state acceptance fell well below target.
@alexeid alexeid requested a review from rbouckaert May 13, 2026 05:01
@rbouckaert rbouckaert merged commit bb4809f into master May 18, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants