dynamic_network#

Dynamic bead–spring network for layout relaxation and visualization.

This module implements a simple 2D dynamic system over complex coordinates: nodes (beads) connected by springs (bonds), with optional angular constraints, chain stiffness, and short-range repulsion. It can be used to iteratively relax a layout and (optionally) visualize the evolution.

Design notes#

  • Geometry is represented with complex numbers for concise vector math.

  • To keep import knotpy fast, matplotlib is imported locally inside functions that actually plot or animate.

Functions

animate_simulation(network[, dt, show])

Animate the network dynamics with a two-panel view (geometry + force).

plot_bead_frame(ax, network[, show_indices])

Plot a single frame of the bead network onto the provided Axes.

plot_force_history(ax, network)

Plot the history of the mean net force magnitude over time.

plot_static_frame(network[, show_indices])

Plot a single static frame of the bead network.

simulation(network[, dt, force_constants, show])

Run a fixed number of steps and return the stability series.

Classes

Network(ideal_bond_length[, force_constants])

Dynamic bead–spring network in 2D (complex plane).
class Network(ideal_bond_length, force_constants=None)#

Bases: object

Dynamic bead–spring network in 2D (complex plane).

The network stores:

  • positions: bead positions (complex).

  • connections: pairs of indices (bonds).

  • angled_triplets: dict mapping (i, j, k) → ideal angle at j.

  • stiff_triplets: list of (i, j, k) for chain stiffness.

  • forces: current force on each bead (complex).

  • names: mapping from external names (e.g., knotpy nodes/endpoints) to indices.

Forces:

  • Bond stretching to an ideal length.

  • Angular force toward an ideal angle.

  • Stiffness (prefers straight lines, i.e., ideal π).

  • Short-range repulsion with a cutoff.

  • Global damping.

Parameters:

  • ideal_bond_length (float) – Equilibrium length of a bond (spring).

  • force_constants (dict | None) –

    Optional override: {

    ”bond”: float, “angle”: float, “stiffness”: float, “repulsion”: float, “repulsion_cutoff”: float, “damping”: float,

    }

compute_repulsive_ignore()#

Precompute which bead pairs should be repelled.

Repulsion skips immediate neighbors along bonds, stiff triplets, and angled triplets to avoid fighting primary constraints.

add_point(point, name)#

Add a bead if name is new; otherwise reuse the index.

Parameters:

  • point (complex) – Position of the bead.

  • name (Any) – External identifier to map to this bead.

add_angled_triplet(triplet, angle)#

Register an angular constraint.

Parameters:

  • triplet (tuple) – Indices or external names (i, j, k) with angle at j.

  • angle (float) – Ideal angle in radians.

add_connections_from(connections)#

Add multiple connections.

Parameters:

connections (Iterable[tuple[(complex, name), (complex, name)]]) – Each connection includes (point, name) pairs for its endpoints.

add_connection(connection)#

Add a single bond.

Parameters:

connection (tuple) – ((point_a, name_a), (point_b, name_b)).

add_stiff_triplets_from(triplets)#

Add multiple stiffness triplets (i, j, k).

add_stiff_triplet(triplet)#

Add a single stiffness triplet (i, j, k).

average_connection_length()#

Average bond length across all connections.

distances()#

List of bond lengths across all connections.

scale(factor)#

Uniformly scale all bead positions by factor.

compute_forces()#

Compute all forces for the current configuration.

net_force_magnitude()#

Mean magnitude of forces across beads (a stability indicator).

step(dt)#

Advance the simulation by a single time step.

Parameters:

dt (float) – Time step multiplier applied to the velocity (force proxy).

plot_bead_frame(ax, network, show_indices=False)#

Plot a single frame of the bead network onto the provided Axes.

Parameters:

  • ax (matplotlib.axes.Axes) – Target axes.

  • network (Network) – Network to draw.

  • show_indices (bool) – If True, annotate bead indices and names.

plot_force_history(ax, network)#

Plot the history of the mean net force magnitude over time.

Parameters:

  • ax (matplotlib.axes.Axes) – Target axes.

  • network (Network) – Source of stability_history.

plot_static_frame(network, show_indices=False)#

Plot a single static frame of the bead network.

Parameters:

  • network (Network) – The network to draw.

  • show_indices (bool) – If True, annotate bead indices and names.

animate_simulation(network, dt=0.1, show=True)#

Animate the network dynamics with a two-panel view (geometry + force).

Parameters:

  • network (Network) – The network to simulate.

  • dt (float) – Time step used in Network.step.

  • show (bool) – If True, call plt.show() at the end.

simulation(network, dt=0.1, force_constants=None, show=False)#

Run a fixed number of steps and return the stability series.

This helper runs the dynamics for 100 steps and returns the list of mean net force magnitudes at each step. It does not plot.

Parameters:

  • network (Network) – The network to simulate.

  • dt (float) – Time step used in Network.step.

  • force_constants – Unused (reserved for future).

  • show (bool) – Unused (reserved for future).

Returns:

list[float] – Mean net force magnitude per step.