bioRxiv2026
Macromolecular self-assembly is a fundamental process in living and engineered systems, producing molecular machines like the ribosome or highly symmetric viral capsids. Thanks to sources like the Protein Data Bank (PDB) and AlphaFold3, the final target complexes are often known, but these static structures do not provide information on the self-assembly process directly. Computational models provide critical tools to study these essential pathways of self-assembly, but substantial coarse-graining of assembly subunits is necessary to achieve computational tractability of these relatively slow processes while retaining multi-valency. While rule-based or local interactions overcome the often-prohibitive enumeration of all possible assembly intermediates, they must ensure global structural constraints are met. We here demonstrate ioNERDSS, a user-friendly Python package that transforms 3D atomic structures into coarse-grained models for immediate simulation with the stochastic reaction-diffusion NERDSS software, converting static structures into time-resolved assembly trajectories. NERDSS uses rule-based interactions to simulate multi-component self-assembly at the minutes timescales and without limits to complex size or growth pathways. With ioNERDSS, each protein chain is defined by a rigid subunit with discrete interfaces and explicit orientational constraints that enforce a structured assembly. Repeated subunits (such as in viral capsids) are regularized to preserve the target topology across distinct stochastic assembly pathways, supporting assembly of structures with thousands of subunits. We initialize pairwise binding affinities using open-source machine-learned prediction tools, and our default coarse-grained (CG) models are all constrained by thermodynamic reversibility to reach an equilibrium steady-state. The binding rates and subunit abundances necessary to perform simulations are initialized at default values but represent the key variables (along with affinities) that cells and thus users would tune to control productive assembly. Benchmarking on over 40,000 PDB structures shows that the majority of CG models stochastically assemble into target structures. The ioNERDSS Python library links directly to open-source tools for visualization and analysis to facilitate fast and user-friendly structure validation and analysis of output for thermodynamic, kinetic, and nonequilibrium drivers of macromolecular self-assembly.