Guided Sampling with Constraints

STARLING exposes hooks for steering the diffusion process with physics-inspired constraints. Use this page when you need to encode experimental restraints or bias ensembles toward specific structural properties.

Constraint overview

All restraints live in starling.inference.constraints and derive from a common Constraint base class. They can be passed directly to starling.generate() through the constraint argument.

Class

Description

DistanceConstraint

Maintain a target distance (Å) between two residues with optional tolerance and force constant control.

RgConstraint

Bias ensembles toward a target radius of gyration.

ReConstraint

Enforce an end-to-end distance between the first and last residues.

HelicityConstraint

Encourage helix-like distance patterns within a residue range, useful for modelling local secondary structure.

BondConstraint

Penalise deviations from ideal backbone bond lengths.

StericClashConstraint

Discourage steric clashes by penalising distances below a threshold.

Any constraint accepts shared keyword arguments:

constraint_weight

Scalar applied to the gradient update (default 1.0).

guidance_start / guidance_end

Normalised diffusion timestep window (0 is the start, 1 the end) in which the constraint is active.

schedule

Strategy for time-dependent scaling. "cosine" (default) fades the influence in smoothly; "bell_shaped" ramps up mid-way; pass None to keep a constant weight.

verbose

Log per-step statistics when True.

Basic example

from starling import generate
from starling.inference.constraints import DistanceConstraint, RgConstraint

constraint = DistanceConstraint(
    resid1=15,
    resid2=42,
    target=35.0,
    tolerance=2.0,
    force_constant=3.0,
    guidance_start=0.2,
    guidance_end=0.8,
)

# Combine multiple restraints by wrapping them in a list
constraints = [
    constraint,
    RgConstraint(target=25.0, force_constant=1.5, schedule="bell_shaped"),
]

ensemble = generate(
    "MQDRVKRPMNAFIVWSRDQRRKMALENPRMRNSEISKQLGYQWKMLTEAEKWPFFQEAQKLQAMHREKYPNYKYRPRRKAKMLPK",
    conformations=200,
    constraint=constraints,
    return_single_ensemble=True,
)

Constraints receive the internal encoder and latent scaling factors automatically, so no additional setup is required. If multiple constraints are provided they are applied sequentially at each diffusion step.

Tuning gradients

The base class exposes helpers that make it easier to keep guidance stable:

  • constraint_weight – increase to tighten the restraint, decrease to allow more variation.

  • get_time_scale – schedules with strong mid-to-late emphasis tend to stabilise final structures without derailing early denoising.

  • get_adaptive_clip_threshold – advanced users can subclass and override to change gradient clipping behaviour.

See Also