Top-Level API

These are the main objects and helpers exposed from import ionerdss as ion.

Public entry points

  • build_system_from_pdb: convenience wrapper for the structure-to-system pipeline.
  • System: top-level molecular system container with registries and JSON serialization.
  • Simulation: helper for editing and running a NERDSS workspace.
  • Analyzer: entry point for post-processing simulation outputs.
  • ODEPipelineConfig: configuration object for ODE solves.
  • run_ode_pipeline: execute the ODE workflow.
  • platonic_solid_generator: build a platonic-solid-based model.
  • build_system_from_plat: convenience helper for platonic solid workflows.
  • prepare_structure_validation_for_system: export the irreversible one-copy validation setup.
  • compare_structure_to_design: align observed coordinates against the design target and report RMSD.
  • StructureValidationConfig: configuration dataclass for the validation workflow.
  • StructureValidationArtifacts: generated files and metadata from validation export.
  • StructureAlignmentResult: output object returned by rigid alignment.
  • render_trajectory_movie: render a NERDSS run to a GIF or MP4 quickly, with no extra dependencies.
  • visualize_trajectory_ovito: deprecated; use render_trajectory_movie.
  • convert_simularium: export simulation outputs to Simularium.

build_system_from_pdb

import ionerdss as ion

system = ion.build_system_from_pdb(
    source="4v6x",
    workspace_path="4v6x_dir",
    ode_enabled=True,
    count_transition=True,
)

Parameters

  • source: PDB identifier such as "4v6x" or a local PDB/mmCIF path.
  • workspace_path: output directory for generated files. Defaults to <source>_dir.
  • fetch_format: optional remote structure format. Overrides the pdb_file_format hyperparameter (default "bioassembly1").
  • molecule_counts: optional explicit counts for NERDSS export. When omitted, nerdss_total_molecule_count (default 75) is split across the molecule types by their stoichiometry in the structure, rounding up.
  • structure_validation: if True, also export the validation deck during the build. It goes to structure_validation/ in the workspace, beside the regular export in nerdss_files/, and is exported with the same hyperparameters, so nerdss_n_itr, nerdss_time_step, nerdss_overlap_sep_limit and default_on_rate_3d_ka apply to it as they do to the regular export. nerdss_total_molecule_count and nerdss_water_box do not: the deck holds one copy of the designed assembly, in a box of its own.
  • structure_validation_options: optional settings for the validation export. The keys read are box_nm (default (100.0, 100.0, 100.0)), titration_on_rate (default 1e-5), target_filename and parms_overrides; other keys are ignored. Entries in parms_overrides are written over the values the hyperparameters give, for example {"nItr": 2000000}.
  • **hyperparams_kwargs: any field accepted by PDBModelHyperparameters.

Returns

A populated System object ready for export, simulation setup, or analysis.

Structure validation helpers

Validation deck

Every validation export — build_system(structure_validation=True), prepare_structure_validation_for_system, and setup_simulation and prepare in ionerdss.model.pdb.validation — writes the same kind of deck:

  • It holds one copy of the designed assembly, every molecule type at its designed copy number (eight A for an eight-subunit homomer; setup_simulation(initial_molecule_count=n) supplies n copies), with every off-rate zero and titration reactions that add further copies. The target JSON holds the designed centre of mass of every molecule instance.
  • It is written to its own directory, structure_validation/ in the workspace, or under the current working directory when there is no workspace: parms.inp, its titration copy parms_titrate.inp, one .mol file per molecule type and the target JSON. A regular export in nerdss_files/ is left alone. setup_simulation and prepare take deck_dir= to write it somewhere else, for example one directory per set of options.
  • Unless parms_overrides sets bondedComplexWrite, it asks NERDSS for a DATA/COMPLEXES snapshot every nItr / 100 steps. NERDSS writes none otherwise, and the result readers then see only the final restart snapshot, which misses an assembly that formed and later grew.
  • Transition counting stays off, even when the hyperparameters turn on count_transition: the titration reactions keep adding copies, so a complex can outgrow any transitionMatrixSize.

prepare_structure_validation_for_system

Prepare the validation deck: export one copy of the designed assembly with off-rates forced to zero and titration reactions added, and write the designed target coordinates for later comparison.

It takes the system plus the keyword arguments box_nm (default (100.0, 100.0, 100.0)), titration_on_rate (default 1e-5), target_filename (default "structure_validation_target.json") and parms_overrides, and writes its files to structure_validation/ under the current working directory. The functions that run the validation simulation and read its result live in ionerdss.model.pdb.validation; see PDB Modeling.

Typical return values are packaged in StructureValidationArtifacts, including:

  • chosen molecule counts
  • designed coarse-grained coordinates
  • target JSON file path
  • generated NERDSS input files
  • preflight_warning_message: set when the designed assembly graph is disconnected
  • free_interface_warning_message: set when the design leaves binding capacity unused
  • interface_com_proximity_warning_message: set when a reacting interface site sits on its molecule's centre of mass, or a molecule type's sites coincide, so NERDSS cannot define the binding angles
  • box_fit_warning_message: set when the designed assembly is larger than the simulation box

Over-assembly preflight warning

A coarse-grained design can leave interfaces unbound. A molecule type declares every interface it can bind through, but a given copy in the deposited assembly only realizes the contacts observed in the PDB; anything declared but unrealized is a free slot. Because a fresh copy arrives with all of its own interfaces free, that slot can bind another subunit and grow the assembly past the deposited stoichiometry — over-assembly.

get_free_interface_capacity(system) returns {molecule type: {interface type: number of copies leaving it free}}, and get_free_interface_message(system, prefix=...) formats it. Both live in ionerdss.model.pdb.structure_validation. The message is also raised as a RuntimeWarning during validation export and carried on the artifacts.

Free interfaces are not necessarily a defect. A filament such as actin genuinely nucleates beyond the deposited asymmetric unit, so the warning says a larger structure may form, not that the model is wrong.

Two caveats worth knowing:

  • The check is static, over the finished design. Over-assembly can also arise kinetically: during assembly, partial complexes transiently expose interfaces, and with irreversible binding they can fuse before completing. A saturated design is not a guarantee.
  • Over-assembly is unobservable at one copy of the deposited stoichiometry, since the largest possible assembly is then the target itself. Supply more copies to test for it.

Interface-at-centre-of-mass preflight warning

NERDSS defines the angles of a bond from the vector between a molecule's centre of mass (COM) and the reacting interface site: theta is the angle between that vector and sigma, and phi is the rotation about it. Before enforcing them it orients the molecule onto its .mol template from the same site vectors, which needs a site that is not on the COM. Coarse-graining places a site at the centroid of the contacting residues, so when a chain contacts its partners along its whole length — collagen-like triple helices, a peptide lying in a groove, amyloid segments — every site falls on the chain's COM, all of the chain's sites coincide, and NERDSS exits at the first association with Cannot resolve phi angle ... Exiting.

get_near_com_interface_sites(system, threshold_nm=...) lists every reacting interface site closer than the threshold to its molecule's COM, and get_degenerate_site_layouts(system, threshold_nm=...) lists the molecule instances whose sites coincide or all lie within the threshold. get_interface_com_proximity_message(system, prefix=..., threshold_nm=...) formats both. The threshold is the interface_com_proximity_threshold hyperparameter (default 0.15 nm). The validation export resolves its own threshold: StructureValidationConfig.interface_com_proximity_threshold_nm (also a keyword of ionerdss.model.pdb.validation.prepare and setup_simulation), then the hyperparameters in parms_overrides['hyperparams'], then 0.15 nm. build_system(structure_validation=True) puts the build's hyperparameters there unless structure_validation_options['parms_overrides'] carries its own; prepare_structure_validation_for_system does not. The message is raised as a RuntimeWarning by build_system and during validation export, and carried on the artifacts.

Two things are worth knowing:

  • Proximity alone is a symptom, not the cause. In the x5 benchmark the closest reacting site of a crashing entry lies a median 0.07 nm from its COM against 0.72 nm in size-matched controls, but 8% of healthy multi-site models also have a site within 0.15 nm and simulate fine. What NERDSS cannot handle is a multi-site molecule whose sites coincide: 92% of the crashing entries have one, no control does. The benchmark driver therefore skips a model (status IC) only for a degenerate layout, and just prints the message for a lone site near the COM.
  • A single-interface molecule type is exempt, because the exporter writes phi = nan for it and NERDSS then skips the phi rotation; such a subunit binds, but with an arbitrary orientation.

Setting the interface_site_placement hyperparameter to 'auto' moves the flagged sites onto the chain surface facing the partner's COM, which gives NERDSS a usable geometry (see the hyperparameter page).

Box-fit preflight warning

NERDSS keeps every molecule inside the box: it reflects a complex that reaches a wall, cancels an association whose product would span the box, and exits with Molecule seems outside simulation volume when a molecule is pushed out anyway. get_designed_assembly_extent(system) returns the bounding-sphere diameters of the designed assembly and of its largest molecule, measured from the interface sites the way NERDSS measures its template radius, and get_box_fit_message(system, box_nm, prefix=...) warns when the assembly is larger than the shortest box edge. The check is static: a filament that keeps growing past the deposited stoichiometry (see the over-assembly warning) can still leave the box.

compare_structure_to_design

Rigidly align observed coarse-grained coordinates onto the design target and compute RMSD.

This function accepts either:

  • dictionaries keyed by molecule label; when the two label sets differ, each label is reduced to its molecule type and the copies of a repeated type are paired to give the lowest RMSD
  • ordered coordinate arrays

It returns a StructureAlignmentResult containing labels, RMSD, the rotation and translation, and the aligned coordinates.

Rendering and export helpers

render_trajectory_movie

Render a NERDSS run directory to a movie, drawing each molecule as a sphere at its center of mass. It needs only numpy and Pillow; a frame of 10^5 molecules takes about 0.2 s on one core.

import ionerdss as ion

ion.render_trajectory_movie("nerdss_output/1", "trajectory.gif")
ion.render_trajectory_movie("nerdss_output/1", "trajectory.mp4", frame_stride=5)  # MP4 needs ffmpeg
  • The camera and the simulation box (WaterBox in parms.inp) are fixed for the whole movie; molecules moving never shift the frame.
  • The time label is iteration × timeStep, in one unit (µs, ms or s) chosen for the whole movie and printed large, in a fixed-width field at a fixed position. time_font_size= sets its height in pixels.
  • Each molecule type has its own color, whether the molecule is free or in a complex. Only the time is labeled by default; show_legend=True also lists each type's color and radius, in parms.inp order.
  • The sphere radius is the one ionerdss used to compute D and Dr, recovered from the .mol files by inverting Stokes-Einstein. When D and Dr were set by hand (they do not agree on a radius), the NERDSS radius, i.e. the largest COM-to-interface distance, is used instead, with a warning. Pass radii= to override.
  • Spheres are drawn radius_scale times that radius, 3 by default, because at true size molecules in a box hundreds of nanometres wide are a pixel or two across; radius_scale=1 draws them to scale.
  • source="auto" reads PDB/<iteration>.pdb when present and DATA/trajectory.xyz otherwise.
  • n_jobs= renders frames in worker processes; it helps most on machines with many performance cores.

visualize_trajectory_ovito

Deprecated: use render_trajectory_movie. Renders an XYZ trajectory with OVITO and optionally saves it as a GIF; requires the ovito_rendering optional extra.

convert_simularium

Convert supported simulation outputs into Simularium files for interactive 3D viewing. This requires the simularium optional extra.