> ## 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.
# Semigreedy Mutation Generator
> Logit-guided single-point mutations for semigreedy discrete refinement
This generator 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.
Introduce single-point mutations guided by a PSSM derived from `seq.logits`.
Each call to `sample()` selects one position per proposal sequence and
replaces the amino acid there by sampling from the softmax distribution over
logits (with the current residue optionally excluded). Position selection is
controlled by `position_weighting`:
* `"uniform"`: every position is equally likely.
* `"entropy"`: positions with higher Shannon entropy in the PSSM are more
likely, targeting the most uncertain residues.
* `"plddt"`: positions are weighted by `(1 - pLDDT)` read from the
canonical `proposal.structure.per_residue_plddt` property when a
`Structure` with pLDDT B-factors is present, so structurally uncertain
residues are mutated more frequently; otherwise it falls back to uniform.
`frozen_positions` hard-excludes listed indices from selection (deterministic
counterpart to `sequence_bias`); whatever residue is there stays. Implements
Germinal's `design_semigreedy` phase (`MCMCOptimizer` at near-zero
temperature, `proposals_per_result > 1`).
`clear_logits=False` (default) requires upstream `GradientOptimizer` logits at
runtime; `clear_logits=True` runs as pure sequence-only mutation.
## API Reference
Configuration for semigreedy single-point mutation sampling.
Converts `seq.logits` (from a preceding gradient-based optimizer) to a PSSM
via softmax and samples single-point mutations from it. Stage 2 of the Germinal
pipeline: paired with `MCMCOptimizer` at near-zero temperature for
greedy/semigreedy discrete refinement.
'uniform' picks at random; 'entropy' picks high-entropy positions; 'plddt' picks low-pLDDT.
Options: `uniform`, `entropy`, `plddt`
Softmax temperature on logits when building the PSSM. Below 1 sharpens; above 1 flattens (> 0).
Zero out the current amino acid before sampling to guarantee a mutation.
Optional declarative sequence-symbol bias applied before AA sampling.
When True, ignore proposal logits and sample replacement from sequence\_bias (or uniform if unset).
Position indices to keep untouched during mutation (Python-style zero-based).
## Usage
```python python icon="python" theme={null}
>>> from proto_language.core import Segment
>>> segment = Segment(sequence="ACDEF", sequence_type="protein")
>>> gen = SemigreedyMutationGenerator(SemigreedyMutationGeneratorConfig(position_weighting="entropy"))
>>> gen.assign(segment)
>>> # Normally logits come from a GradientOptimizer; here we set them manually:
>>> import numpy as np
>>> segment.proposal_sequences[0].logits = np.random.randn(5, 20)
>>> gen.sample()
>>> # Exactly one position differs from "ACDEF"
```
## Metadata
| Property | Value |
| ------------------------ | ----------------------------- |
| Key | `semigreedy-mutation` |
| Class | `SemigreedyMutationGenerator` |
| Category | `mutation` |
| Input Type | `starting_sequence` |
| Uses GPU | `False` |
| Supported Sequence Types | `protein` |
| Allows Empty Start | `False` |
evo-design/proto-language/proto\_language/generator/semigreedy\_mutation\_generator.py
dguo8412