This README summarizes the operator approaches implemented in this package:
- Adapters
- Learned Conditional Proposals
- Learned Tree-Distance Proposals
- Slice-Based Proposals
- Transport-Based Proposals
- Gradient and MALA Proposals
- Large-Jump and Mode-Jump Proposals
- Preconditioned Crank-Nicolson Proposals
- Irreversible Guided Random Walks
- Delayed-Acceptance and ML-Assisted Runs
- Adaptive Operator Weighting and Scheduling
Many custom operators are built around an adapter layer, which exposes parts of the BEAST state as mutable and immutable vectors, often after a transform, so generic proposal machinery can work on scalar parameters, simplex parameters, tree heights, local tree geometry, or MAP/cube summaries.
Relevant classes:
adapters.TreeHeightAdapteradapters.MutableTreeHeightAdapteradapters.CubeAdapteradapters.TaxaDistanceAdapterGeneratoradapters.TreeTripletAdapteradapters.LocalTreeAdapteradapters.NodePositionAdapter
Relevant transform classes:
transforms.RealScalarLogTransformtransforms.RealScalarSigmoidTransformtransforms.RealVectorLogTransformtransforms.SimplexTransformtransforms.IntVectorIdentityTransform
The adaptive operator learns a conditional proposal distribution from observed mutable and immutable adapter vectors, then, after burn-in and training, samples new mutable values conditional on the current immutable state.
Relevant classes:
adaptiveoperators.AdaptiveOperatoradaptiveoperators.MultivariateNormalSampleradaptiveoperators.GaussianMixtureSampleradaptiveoperators.NeuralGaussianMixtureSampler
These operators learn distributions over taxon-pair or taxon-triplet distances, then propose tree edits by changing those distances directly.
Relevant classes:
adaptiveoperators.TaxaDistanceOperatoradaptiveoperators.TripletDistanceOperatoradaptiveoperators.LogNormalModeladaptiveoperators.NeuralLogNormalModel
The slice operators all expose adapted BEAST state as a vector, choose a one-dimensional direction through that vector space, draw a slice level from the current posterior, then use step-out and shrinkage along that line until they find an acceptable point.
There are three variants:
StepOutShrinkSliceOperatoris coordinate-wise: it chooses one mutable adapter coordinate, maintains an adaptive window size for that coordinate, and updates only that value.MultivariateStepOutShrinkSliceOperatoris random-direction slice sampling: it draws a normalized Gaussian direction across all mutable adapter coordinates, applies per-coordinate learning-rate scaling, and slices along that line.LinCombSliceOperatoris empirical-direction slice sampling: after burn-in it stores recent adapted states, chooses two previous states, and slices along their difference vector. This turns recent posterior movement into proposal directions.
Relevant classes:
slice.StepOutShrinkSliceOperatorslice.MultivariateStepOutShrinkSliceOperatorslice.LinCombSliceOperatormcmc.SliceMCMC
Tree-topology cube parameterizations can be multi-modal, which makes local moves inefficient. The transport operators look at two reference taxa and a subtree on the path between the references. It then approximates the posterior slice for all the possible (continuous) attachment points of the subtree and builds a triangular (Knothe-Rosenblatt) transport map that sends this approximation to a standard Gaussian. A move perturbs the Gaussian-space point, transports it back to distance space, and computes an exact log Hastings-ratio correction from the map's Jacobian. See transport/approach.md for details.
NodeTransportOperatorreattaches a subtree by resampling its attachment point along the path between two reference leaves.GuidedNodeTransportOperatorpicks reference leaves and a subtree node via sequence-distance-weighted triplet selection, then resamples its attachment point in the same way.
Relevant classes:
transport.NodeTransportOperatortransport.GuidedNodeTransportOperatortransport.PartialCubeTransportOperatortransport.UnivariateOptimalTransportMap
The MALA family proposes adapter vectors using approximate-gradient-guided proposals. MALAOperator learns a neural-network or Gaussian approximation to the gradient during a training phase, then uses a learned covariance for preconditioned proposals. FisherMALAOperator adds Fisher-style preconditioning and adaptive step-size behavior, and the MAP-guided variants use MAP/cube summaries to guide moves.
Relevant classes:
mala.MALAOperatormala.FisherMALAOperatormala.MAPGuidedMALAOperatormala.CubeMAPGuidedMALAOperatormcmc.MalaMCMC
Large-jump operators separate jump coordinates from optimization coordinates: a proposal first makes a large move in one adapter group, performs local random-walk optimization in another group, adds covariance-scaled noise, and computes the reverse construction for the Hastings correction. The unified variant also supports MAP jump candidates and transport noise controls.
Relevant classes:
The irreversible guided random-walk operator chooses an adapted coordinate, moves in a persistent direction, and flips that direction on rejection.
Relevant class:
The pCN operators learn a centered covariance over adapted mutable values and then propose by shrinking the current state toward the learned mean plus a covariance-scaled perturbation. The guided mixed variant combines this with guided adapter information.
Relevant classes:
The delayed-acceptance classes use an approximate posterior, including an MLP-backed approximation, to stage accept/reject work.
Relevant classes:
Two adaptive-control pieces are implemented separately from proposal kernels. AdaptiveWeightOperator chooses among child operators and learns their weights through a WeightScheme. DualAveragingOperatorSchedule provides better schedule-level adaptation compared to Robinson-Monro.
Relevant classes: