Megascale RNA 3D Structure Prediction · 0.509 private TM-score · Stanford RNA 3D Folding Part 2 (Kaggle)
Safety and scope: This repository is for non-infectious computational structure modeling, relaxation, and visualization. It does not contain infectious material, reverse-genetics workflows, synthesis-ready constructs, or laboratory protocols. See SAFETY.md.
Multi-model RNA 3D structure prediction pipeline with a custom physics relaxation engine, designed for megascale targets (up to 4,640 nt). Achieves a private/public score inversion (0.387 public → 0.509 private) through physics-guided generalization rather than benchmark overfitting.
📄 Full technical whitepaper with derivations · Reviewer notes · Kaggle competition
Reproducibility note:
SobolevRNA.ipynbis Kaggle-native — model weights are mounted as Kaggle datasets under/kaggle/input/. Running locally requires substituting paths to locally downloaded weights for RNA-FM, Boltz-1, Protenix, and RibonanzaNet-2. See ATTRIBUTION.md for source links to each model.
Input Sequence (L nucleotides)
│
├─── L ≤ 1022 nt ──► RNA-FM (single pass, 640-dim embeddings)
│
└─── L > 1022 nt ──► HWS (Hierarchical Windowed Sensor)
sliding window + taper blend
│
┌───────────▼───────────┐
│ Global Contact Map │
│ C_ij ∈ {0,1}^{N×N} │
└───────────┬───────────┘
│
┌─────────────── Routing by L ──────────────────┐
│ │
L ≤ 512 nt L > 512 nt
│ │
┌─────────▼──────────┐ ┌──────────────▼────────────┐
│ Ensemble: Boltz-1 │ │ SHR Megascale Path │
│ + Protenix (N=5) │ │ (Stochastic Hamiltonian │
└─────────┬──────────┘ │ Relaxation, JAX x64) │
│ └──────────────┬────────────┘
└──────────────────┬────────────────────────────┘
│
┌───────────▼───────────┐
│ SHR Physics Polish │
│ (E_bond + E_rep + │
│ E_DL + E_Rg) │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ Hungarian Chain Map │
│ + Kabsch Alignment │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ submission.csv │
│ (C1' coordinates) │
└───────────────────────┘
RNA-FM has a hard architectural truncation at 1,022 nt. For megascale targets (e.g. 9MME = 4,640 nt), a single-pass embedding is impossible. HWS extracts embeddings via overlapping windows and blends them with a linear taper to eliminate hard boundary artifacts.
Parameters:
| Symbol | Value | Description |
|---|---|---|
| 1022 nt | RNA-FM max window | |
| 768 nt | Stride between windows | |
| 128 nt | Taper length at boundaries | |
| 640 | Embedding dimension |
Weighted accumulation:
For each window
The blended embedding at position
The blended embeddings are converted to a global pairwise contact map via cosine similarity. The cosine is rescaled to
Defaults are
The physics engine operates on C1′ backbone coordinates
The Flory-scaling target enforces physical compaction:
with
Gradient descent on
with
SobolevRNA was originally created for the Stanford 3D RNA Part 2's Kaggle Competition, but was thereafter generalized to SobolevMacromolecule, which now first pivoted with sobolev_polish_gate.py, a production-safe bridge for
using SHR as a post-processing layer on strong external candidates such as the
Competition's 1st-place ensemble. The intended integration is
serial:
external predictors (Boltz2 / Protenix / DRFold2 / RNAPro / TBM)
→ C1' candidate slots
→ SobolevRNA contact map C
→ guarded shr_polish
→ accept/reject gate
→ submission.csv
The bridge deliberately calls shr_polish, not shr_refine_single. External
DL/TBM candidates already have plausible global folds, so the polish stage uses
the input coordinates as the initial condition and never adds stochastic
Gaussian jitter. The polish Hamiltonian is the local C1′ objective
$$ H_{\mathrm{polish}}(X; C) = E_{\mathrm{bond}}(X)
- E_{\mathrm{steric}}(X)
- E_{\mathrm{DL}}(X; C), $$
with
$$ E_{\mathrm{steric}}(X) = \sum_{j>i+1} \left[ \max\left( 0,; \sigma_{\mathrm{clash}}
- \sqrt{\lVert x_i-x_j\rVert_2^2 + 10^{-2}} \right) \right]^2, $$
The gradient update uses the same Sobolev
where sobolev_polish_gate.py imports jax.scipy.fft as jfft and enables
jax_enable_x64=True. The production defaults are
clip = 2.0,
In a fixed best-of-5 submission, post-processing is not automatically additive: replacing a raw candidate can reduce the best slot if the refined structure drifts away from the native fold. The bridge therefore accepts a polished candidate only if all checks pass:
- Shape matches the raw candidate and all coordinates are finite, non-sentinel, and within the sanitizer bound.
- Bond violations do not increase, where a violation is an adjacent C1′
distance with
$\lvert d - 5.95\rvert > 2.0$ Å. - Steric clashes do not increase, using KDTree pairs below 3.0 Å and excluding adjacent residues.
-
$H_{\mathrm{polish}}(X_{\mathrm{refined}}; C) < H_{\mathrm{polish}}(X_{\mathrm{raw}}; C)$ . -
$R_g(X_{\mathrm{refined}})$ lies in$[0.7, 1.5]\cdot 3.5N^{0.45}$ . -
$\max_i \lVert x_{i+1}-x_i\rVert_2 < 12.0$ Å. -
tm_self >= 0.85, computed by Kabsch-aligning refined coordinates to raw coordinates and applying a TM-style C1′ similarity over valid residues.
Rejected candidates leave the original external prediction unchanged. Accepted
candidates are recorded in sobolev_polished_slots.csv; all candidates receive
metrics and reject reasons in sobolev_polish_report.csv.
| Variable | Default | Effect |
|---|---|---|
SOBOLEVRNA_POLISH |
1 |
Set to 0 to disable the gate and preserve raw slots |
SOBOLEVRNA_POLISH_SLOTS |
all | Optional comma-separated slot allowlist, e.g. 1,2,3 |
SOBOLEVRNA_POLISH_STEPS |
2000 |
Number of polish steps |
SOBOLEVRNA_POLISH_LR |
0.01 |
Polish learning rate |
The module also accepts the earlier prototype prefix SOBOLERNA_* as a
backward-compatible alias.
Parameters adapt linearly with sequence length across three tiers:
| Parameter | |||
|---|---|---|---|
| 10.0 | |||
| 3.0 Å |
|
|
|
|
|
1,000 | 1,500 | 8,000 |
| 0.02 | 0.01 | 0.005 | |
|
|
5 | 3 | 1 |
9MME at
Consecutive 3D chunks are aligned via the Kabsch algorithm (Kabsch 1976). Given mobile anchor
The seam between aligned chunks is blended with a linear taper over the overlap region to prevent harmonic-force spikes in the subsequent SHR polish.
| Set | TM-score |
|---|---|
| Public leaderboard | 0.38650 |
| Private leaderboard | 0.50934 |
The private > public inversion reflects that SHR physics generalizes to novel RNA families (the private set composition) better than pure deep learning baselines.
adaptive_contacts.py provides the pure-NumPy contact-map utilities used to tune this layer outside the Kaggle notebook. The intended A/B protocol is:
- Match the predicted contact-density decay curve to polymer scaling,
$P(s) \propto s^{-\gamma}$ , targeting$\gamma \approx 1.0$ to$1.4$ for folded RNA. - Report MCC or F1 separately for short (
$6 \leq s \leq 24$ ), medium ($25 \leq s \leq 100$ ), and long-range ($s > 100$ ) contacts when labels are available. - Track downstream SHR energy and polish-gate
tm_self; good thresholds reduce energetic frustration without moving accepted structures out of their raw-model basin.
The Sobolev sobolev_macromolecule.py turns that into a small object-oriented factory. The JAX optimization loop is shared; the factory swaps only the bead identity, physical constants, optional bending term, and expected restraint frontends:
| Domain | Bead | Compaction | Frontend restraints | |
|---|---|---|---|---|
| RNA | C1′ | 5.95 Å | RNA-FM, RibonanzaNet-2, templates | |
| Proteins | Cα | 3.80 Å | ESM-3, Chai-1, Boltz/Protenix confidence maps | |
| dsDNA | C1′ or P | ~4.8 Å | worm-like-chain bending term, not Flory collapse | Boltz/Protenix/AF3 nucleic-acid complex restraints |
For dsDNA, disable the RNA-style collapse basin and add bending plus inter-strand Watson-Crick restraints so the optimizer preserves helix stiffness rather than crushing the duplex.
from sobolev_macromolecule import create_macromolecule, watson_crick_contact_map
protein_engine = create_macromolecule("protein")
protein_terms = protein_engine.energy_terms(ca_coords, contact_map=protein_contacts)
dna_engine = create_macromolecule("dsdna", bend_stiffness=8.0)
watson_crick_contacts = watson_crick_contact_map(n_base_pairs=1000)
polished_dna = dna_engine.polish(p_coords, contact_map=watson_crick_contacts)The presets are deliberately lightweight. A new frontend only needs to emit a square contact/restraint matrix in the same residue order as the coordinates; SobolevMacromolecule.polish() handles the shared bond, steric, contact, radius-of-gyration, optional bending, and Sobolev watson_crick_contact_map() builds the explicit inter-strand pairing restraints while the bending term preserves helix stiffness.
SobolevComplex extends the same engine to CRISPR-Cas9-like protein/RNA/DNA assemblies. The key change is tensor masking: bonds are evaluated only inside chains, steric radii and bond lengths are looked up from each bead's molecular type, radius-of-gyration basins are computed per chain, and the Sobolev DCT filter is applied independently to each chain gradient slice so unrelated chain endpoints are never smoothed together.
from sobolev_macromolecule import SobolevComplex
sequence, complex_engine = SobolevComplex.from_fasta("""
>Cas9|protein
MKK...
>guide|rna
GGA...
>target|dsdna
ATGC...
""")
terms = complex_engine.energy_terms(coords, contact_map=af3_or_boltz_contacts)
polished = complex_engine.polish(coords, contact_map=af3_or_boltz_contacts)The complex contact Hamiltonian reports contacts_intra and contacts_inter separately. ComplexSpec(w_intra=..., w_inter=...) lets interface restraints carry a different weight from intra-chain folding restraints, which is useful when preserving docking geometry matters more than relaxing internal monomer noise.
The Kaggle notebook's original SHR cells are too linear and monolithic to swap the 1D DCT for a graph filter in place. The extracted sobolev_macromolecule.py layer is the modular boundary: SobolevMacromolecule keeps single-chain DCT smoothing, SobolevComplex keeps per-chain DCT smoothing for central-dogma complexes, and SobolevMacro replaces the DCT with a graph Laplacian spectral filter for branched or non-polymer systems.
from sobolev_macromolecule import SlabPotential, create_macro_graph
glycan = create_macro_graph(
node_types=["glycan", "glycan", "glycan", "glycan"],
bonds=[(0, 1, 1.4), (1, 2, 1.4), (1, 3, 1.6)],
)
membrane_patch = create_macro_graph(
node_types=["lipid_tail", "lipid_head"],
bonds=[],
slab=SlabPotential(half_thickness=15.0),
)
filtered_gradient = glycan.smooth_gradient(raw_gradient)
polished = glycan.polish(coords, contact_map=boltz_or_af3_restraints)SobolevMacro uses GraphSpec tensors for node types, bead radii, arbitrary covalent edges, contact weights, and optional implicit membrane slab potentials. The Sobolev filter is
U @ ((U.T @ gradient) / (1 + alpha * lambda)), where U and lambda come from the graph Laplacian L = D - A. This acts like the old DCT on a line, but also handles glycan trees, ligand bond graphs, disconnected systems, lipid patches, and coarse MARTINI-style beads without smoothing across non-edges.
Whole-cell scenes should be rendered by an instanced WebGPU/OpenUSD/Unreal frontend, not by loading every bead into a desktop molecular viewer. sobolev_visualization.py adds the thin adapter layer: binary coordinate frames for SHM/gRPC/WebSocket transport, renderer-ready (N, 4, 4) instance matrices, abundance-to-asset-id expansion, JSON scene manifests, minimal OpenUSD PointInstancer export, and far-field coarse graining around an active-site sphere.
See docs/whole-cell-visualization.md for the multi-scale data integration and cloud rendering architecture, including the recommended split between A100/H100-class SobolevMacro compute and L4/G5-class Pixel Streaming visualization.
This repository includes a non-infectious, integrative, multi-scale structural visualization of a Bundibugyo ebolavirus–associated virion architecture, assembled from public structural components, homologous templates, and computationally relaxed placement/packing coordinates. This is a hypothesis-generating model, not an experimentally validated complete virion reconstruction and not a genome or infectious-virus reconstruction.
The initially assigned PDB IDs have been corrected after review against RCSB annotations:
- 6N7J: BDBV223 Fab bound to a 16-residue synthetic GP stalk peptide
(X-ray, 3.68 Å). This is NOT a full GP trimer — it is a small stalk
epitope + antibody complex. Set to
Nonein the ChimeraX script until a full GP trimer structure is properly vetted. - 4LDB: Zaire ebolavirus (EBOV) VP40 dimer (X-ray, 2.6 Å). This is NOT BDBV VP40 — it is a homologous template (~60% identity). Labeled as a homolog in the provenance table.
- 7ZPE: Human branched-chain keto acid dehydrogenase kinase — completely unrelated to ebolavirus. This was a wrong PDB ID. Removed.
- No nucleotide or amino acid sequences of any pathogen
- No synthesis-ready construct designs or cloning vectors
- No reverse-genetics systems, minigenomes, replicons, or rescue protocols
- No wet-lab protocols of any kind
- No "one-click" pipeline that turns a sequence into a buildable pathogen
- Education: visualizing filovirus architecture for students and trainees
- Structural interpretation: communicating antibody-epitope geography
- Defensive research communication: illustrating virion-scale organization
- Method demonstration: showing the Sobolev/graph-relaxation engine
- Scene-building toolkit: the visualization adapters are domain-agnostic
- SAFETY.md — full safety and scope statement
- PROVENANCE.md — component-level provenance table (source, organism, method, resolution, chain IDs, copy number, placement rule, uncertainty) with the PDB accession audit
- docs/pathogen-modeling-provenance-template.md — blank provenance template for future pathogen-associated models
⚠️ Caveat: This is an integrative non-infectious BDBV-associated virion visualization, not a complete coordinate-exact reconstruction. It is a hypothesis-generating model assembled from public structural components, homologous templates, and computationally relaxed placement/packing coordinates. See PROVENANCE.md for the full provenance table and PDB accession audit.
The video shows a 1,081 nm BDBV-associated, hypothesis-generating filovirus architecture visualization in UCSF ChimeraX. Public structural components and homologous templates are instanced at computationally relaxed positions for educational and structural-communication purposes.
Full-resolution MP4 (35s, 1720×1080): download
| Model | Source | Role |
|---|---|---|
| RNA-FM | Chen et al. 2022 | Sequence embeddings (HWS input) |
| RibonanzaNet-2 | Shujun717/Kaggle | Contact map (E_DL fallback) |
| Boltz-1 | odat1248/Kaggle | 3D seed generation (L ≤ 800 nt) |
| Protenix v1 | qiweiyin/Kaggle | 3D generation (L ≤ 512 nt) |
| USalign | Zhang Lab | TM-score evaluation |
See ATTRIBUTION.md for full credits and licenses.
If you build on HWS or SHR, please cite:
@misc{kinder2026rna,
author = {Kinder, Hunter},
title = {SobolevRNA: Megascale RNA 3D Structure Prediction with Hierarchical
Windowed Sensing and Stochastic Hamiltonian Relaxation},
year = {2026},
url = {https://github.com/aurascoper/SobolevRNA}
}
