> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCMC Optimizer
> Markov chain Monte Carlo (Metropolis-Hastings): proposes mutations from the generators and stochastically accepts or rejects each to minimize the weighted constraint energy, with a simulated-annealing temperature schedule that shifts from broad exploration to local refinement over the run.
This optimizer is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.
Metropolis-Hastings MCMC optimizer for constraint-driven sequence optimization.
This optimizer implements Metropolis-Hastings sampling with simulated annealing
to optimize sequences against constraint-based energy functions. It uses mutation
generators as proposal distributions and accepts/rejects proposals based on energy
changes and temperature.
At each step, the optimizer generates `num_results x proposals_per_result`
proposals by mutating each of the K sequences `proposals_per_result` times.
Each trajectory (result index) is independent. For each trajectory, the best proposal
(lowest energy) is selected, then MH acceptance is applied to decide whether to
accept or reject that proposal. If rejected, the trajectory keeps its previous state.
* Typically used with mutation generators (`category="mutation"`)
* Uses Metropolis-Hastings acceptance: always accepts improvements,
accepts worse proposals with probability exp(-ΔE/T)
* Simulated annealing via configurable `temperature_schedule`
* Lower energy scores are better (minimization objective)
* When `proposals_per_result > 1`, generates multiple proposals per
trajectory, selects the best one, then applies a single MH accept/reject decision
## How It Works
MCMC walks a single trajectory: each step proposes a mutation, then accepts it outright if it lowers the energy or, when worse, with a temperature-dependent probability that cools over the run.
Each step replicates every tracked sequence into a pool of `P` proposals (`P = proposals_per_result`), mutates them with a randomly chosen generator, scores the pool, and takes the lowest-energy proposal `x′`. A Metropolis-Hastings test then decides whether to move there:
```
α = min(1, exp(−(E(x′) − E(x)) / T)) accept x′ when u ~ U(0,1) < α
T(t) = T_max · (T_min / T_max)^((t−1)/(N−1)) temperature anneals T_max → T_min
```
Improving moves (`ΔE ≤ 0`) are always accepted; a worse move is still taken with probability `exp(−ΔE/T)`, so hot early steps explore and cold late steps exploit. An infeasible proposal (`E = ∞`) is always rejected, and `num_results` independent trajectories run in parallel.
## API Reference
Configuration object for MCMCOptimizer.
This class defines configuration parameters for the Metropolis-Hastings MCMC
optimizer, which explores sequence space through iterative mutation with
probabilistic acceptance based on energy improvements.
* The field default is `None` (inherits the program-level `num_results`).
* When `num_results=1`, behaves like standard single-chain MCMC.
* When `num_results > 1`, maintains that many independent trajectories and
generates `proposals_per_result` (default: 1) proposals per result sequence each step.
Number of Metropolis-Hastings steps. Each step proposes, evaluates, and accept/reject samples.
Independent MCMC trajectories run in parallel; each yields one candidate. Overrides program count.
Proposals per trajectory each step; the best by energy is chosen, then accept/reject is applied.
Starting temperature for simulated annealing; higher accepts worse proposals more readily.
Ending dimensionless temperature for simulated annealing; must be greater than 0 and below the max.
Annealing schedule from max to min temperature.
Options: `constant`, `cosine`, `exponential`, `hinge`, `linear`, `quadratic`
Random seed for reproducible optimization, generator, and constraint tool streams.
Save history and log progress every N steps. Step 0 and final step always saved.
Save granular per-proposal results (accept/reject) in history snapshots.
Emit per-step debug information about proposals, scores, and acceptance through the logger.
evo-design/proto-language/proto\_language/optimizer/mcmc\_optimizer.py
dguo8412