A constraint encodes a biological requirement, such as a GC-content range, protein folding confidence, structural similarity, or motif presence, as a scoring function that the optimizer minimizes.Every constraint answers one question about a proposal sequence: how far is it from the requirement? The answer is a score between 0.0 (perfect) and 1.0 (worst). The optimizer combines all constraint scores into a single energy value and searches for sequences that minimize it.
Proto uses a unified scoring model where all constraints return values on the same [0.0, 1.0] scale:
Perfect Worst |------------------------------------------| 0.0 0.5 1.0 GC content GC 5% outside GC 20% outside in range target range target range
The optimizer combines scores into a single energy:
Energy = Sigma(weight_i x score_i)
Lower energy is better. A sequence with energy 0.0 satisfies all constraints perfectly.
python
# Example: Three constraints with different weights# If a proposal scores 0.1 on GC, 0.3 on structure, 0.0 on homopolymer:## Energy = (1.0 x 0.1) + (2.0 x 0.3) + (1.0 x 0.0) = 0.7
Uses threshold to create a binary pass/fail gate: a proposal passes when score <= threshold, otherwise it is rejected.
Proposals that fail are immediately rejected
Rejected proposals skip all scoring constraints
Saves compute on expensive evaluations
python
# "Homopolymers MUST be <= 4bp"Constraint( inputs=[segment], function=max_homopolymer_constraint, function_config={"max_length": 4}, threshold=0.0, # score must be <= 0.0)
weight and threshold are mutually exclusive. A constraint is either a weighted scorer OR a binary filter, never both. Setting both raises a ValueError.
When the optimizer calls score_energy(), constraints are evaluated in a specific order designed to reject bad proposals early and save expensive computation:Key insight: Filter constraints run before scoring constraints. Rejected proposals skip expensive scoring entirely (like GPU-based structure prediction). Use cheap filters to screen out bad proposals before expensive scoring kicks in.
GPU memory and constraints: Constraint functions receive all passing proposals in a single batch call (the full List[Tuple[Sequence, ...]]), not one at a time. Unlike generators, constraints have no framework-level batch_size parameter; GPU memory management is handled internally by each tool. For example, ESMFold splits by total residue count (max_batch_residues), while Boltz2 and AlphaFold3 process complexes sequentially. Memory usage can be controlled via tool-specific config fields (e.g., max_batch_residues for ESMFold) rather than a constraint-level batch size.
The segments this constraint evaluates. Single-segment constraints get one sequence per proposal. Multi-segment constraints get a tuple of sequences (one per segment), enabling cross-segment evaluations like protein-protein interactions.
The scoring function from the constraint registry. Must accept (input_sequences: list[tuple[Sequence, ...]], config) and return list[ConstraintOutput], one per proposal, each with a score in [0.0, 1.0].
Configuration for the scoring function. Can be a dictionary (auto-validated against the function’s Pydantic config class) or a Pydantic model instance.
After evaluation, constraints write detailed results back to each sequence’s metadata. This shows why a sequence got its score:
python
# After running the optimizer...sequence = segment.result_sequences[0]# Access constraint metadatagc_data = sequence.metadata["constraints"]["gc_content_constraint"]# Standard fieldsgc_data["score"] # 0.12 (raw score before weighting)gc_data["weight"] # 1.0gc_data["weighted_score"] # 0.12 (score x weight)# Custom data from the scoring functiongc_data["data"]["gc_content"] # 52.3 (the actual GC percentage)
Full Metadata Structure
The metadata structure varies by constraint mode and number of input segments:Single-segment scoring constraint:
The data field contains constraint-specific metrics that vary by function. It exposes the actual measured values (GC percentage, pLDDT score, RMSD in angstroms) rather than just the normalized score.
A constraint function can be defined without using the registry decorator:
python
def my_custom_constraint(input_sequences, config) -> list[ConstraintOutput]: """Score sequences by how close their length is to a target.""" results = [] for (seq,) in input_sequences: # Single-segment: unpack 1-tuple actual = len(seq.sequence) target = config["target_length"] deviation = abs(actual - target) / target # Scoring functions return one ConstraintOutput per input: score in # [0.0, 1.0] (0 = perfect) plus optional diagnostic metadata. results.append(ConstraintOutput(score=min(deviation, 1.0), metadata={"length": actual})) return resultsconstraint = Constraint( inputs=[segment], function=my_custom_constraint, function_config={"target_length": 200},)
Custom constraint functions must return a list[ConstraintOutput], one per input tuple, each with score in [0.0, 1.0] (0 = perfect) plus optional metadata. Add from proto_language import ConstraintOutput. Returning bare floats raises a TypeError at evaluation, and a non-finite score raises a ValueError.
