Inheritable GUI Network

Author: C-Earl

bindsnet/network/network.py

@@ -534,6 +534,12 @@ class GUINetwork(Network):
 
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
+        # GUI-tunable model parameters (name -> current value), declared by a subclass
+        # via set_parameters(). The control panel renders these as editable rows and
+        # passes the edited values back to rebuild() on "Apply & Reload". Empty for a
+        # network assembled imperatively (no build() override).
+        self.parameters = {}
+        self._built = False
         self.opengl_vbos = {'connections': {}, 'layers': {}}
         # name -> dict describing a CUDA-registered GL buffer holding that layer's
         # FULL spike history, (T, batch, n) one byte/spike. Populated lazily by a
@@ -552,6 +558,96 @@ def __init__(self, *args, **kwargs) -> None:
         # Resolved from the layers' device on first use (see _resolve_backend).
         self._use_cuda = None
 
+    # --- inheritable model definition ------------------------------------------
+    # A GUINetwork subclass defines its model by overriding build() (and usually
+    # make_input()), storing its parameters as constructor arguments via
+    # set_parameters(). The Application then drives the lifecycle: it calls build()
+    # to assemble the network, make_input() to generate the stimulus, and -- when the
+    # user edits the parameters and clicks "Apply & Reload" -- rebuild() to reassemble
+    # the model in place from the new values. Example:
+    #
+    #   class MyNet(GUINetwork):
+    #       def __init__(self, device="cuda", in_size=100, exc_size=20_000):
+    #           super().__init__()
+    #           self.device = device
+    #           self.set_parameters(in_size=in_size, exc_size=exc_size)
+    #       def build(self):
+    #           self.add_layer(Input(self.in_size), name="I")
+    #           self.add_layer(LIFNodes(self.exc_size), name="EXC")
+    #           self.add_connection(..., source="I", target="EXC")
+    #           self.to(self.device)
+    #       def make_input(self, runtime):
+    #           return {"I": torch.rand(runtime, self.batch_size, self.in_size,
+    #                                   device=self.device) > 0.9}
+
+    def set_parameters(self, **params) -> None:
+        # language=rst
+        """
+        Declare the GUI-tunable model parameters. Each is stored in ``self.parameters``
+        (so the control panel can render and edit it) AND set as an attribute, so
+        :meth:`build` / :meth:`make_input` can read it as ``self.<name>``. Call from the
+        subclass constructor; :meth:`rebuild` re-calls it with the edited values.
+        """
+        self.parameters = dict(params)
+        for name, value in params.items():
+            setattr(self, name, value)
+
+    def build(self) -> None:
+        # language=rst
+        """
+        Assemble the network: a subclass overrides this to call :meth:`add_layer` /
+        :meth:`add_connection` (and ``self.to(self.device)``) using the parameters
+        stored by :meth:`set_parameters`. Called by the Application -- not the
+        constructor -- so a live reload can re-run it.
+        """
+        raise NotImplementedError(
+            "GUINetwork subclasses must implement build() to assemble the model "
+            "(call self.add_layer / self.add_connection using the stored parameters).")
+
+    def make_input(self, runtime: int) -> Dict[str, torch.Tensor]:
+        # language=rst
+        """
+        Produce the stimulus for a ``runtime``-step run as a ``{layer_name: tensor}``
+        dict (tensors shaped ``[runtime, batch, n]``). A subclass overrides this so the
+        stimulus tracks the parameters (e.g. an input layer sized by a parameter) on
+        every reload. Optional: a network may instead be driven by a fixed dict passed
+        to ``Application.run(inputs=...)``.
+        """
+        raise NotImplementedError(
+            "This GUINetwork does not implement make_input(); either override it or "
+            "pass a fixed `inputs` dict to Application.run().")
+
+    def rebuild(self, **params) -> None:
+        # language=rst
+        """
+        Live model reload: free this network's GL history buffers, tear down its
+        layers/connections, apply the edited parameters, and re-run :meth:`build` -- all
+        on the SAME instance, so the Application's widgets simply re-bind to it. Calling
+        with no params (the initial build) just assembles the model from the parameters
+        already set in the constructor.
+        """
+        self.release_gl()          # free the old run's history buffers (no-op if none)
+        self._clear_structure()    # drop layers/connections/modules + GL bookkeeping
+        if params:
+            self.set_parameters(**{**self.parameters, **params})
+        self.build()
+        self._built = True
+
+    def _clear_structure(self) -> None:
+        # Reset the network to an empty shell so build() can reassemble it from scratch.
+        # Drops the layer/connection registries AND the nn.Module submodule entries they
+        # were added under (add_layer/add_connection call add_module), plus the per-run
+        # GL bookkeeping. Plain attributes (device, parameters, dt, ...) are preserved.
+        self.layers = {}
+        self.connections = {}
+        self.monitors = {}
+        self._modules.clear()
+        self.opengl_vbos = {'connections': {}, 'layers': {}}
+        self._spike_history = {}
+        self._voltage_history = {}
+        self._step_t = 0
+        self._use_cuda = None      # re-resolve GPU/CPU backend after the rebuild
+
     def _resolve_backend(self) -> bool:
         # language=rst
         """
@@ -923,6 +1019,35 @@ def reset_history(self) -> None:
             h['vmax'].fill_(float('-inf'))
         self._step_t = 0
 
+    def release_gl(self) -> None:
+        # language=rst
+        """
+        Free the spike/voltage history GL buffers (and their CUDA registrations) owned
+        by this network. Called when the Application swaps this network out for a freshly
+        built one (live model reload) so the large per-run history buffers -- e.g.
+        ``T*batch*n`` float32 voltage, tens of MB each -- don't leak on every rebuild.
+
+        Best-effort: every step is guarded so a cleanup failure can never abort the
+        reload (the GL context is being reused, not destroyed). The legacy per-layer
+        ``opengl_vbos`` buffers from :meth:`migrate` are intentionally left alone (unused
+        by the renderer; documented legacy).
+        """
+        gpu = self._resolve_backend()
+        for h in list(self._spike_history.values()) + list(self._voltage_history.values()):
+            if gpu and driver is not None and h.get('res') is not None:
+                try:
+                    driver.cuGraphicsUnregisterResource(h['res'])
+                except Exception:
+                    pass
+            vbo = h.get('vbo')
+            if vbo:
+                try:
+                    gl.glDeleteBuffers(1, [int(vbo)])
+                except Exception:
+                    pass
+        self._spike_history = {}
+        self._voltage_history = {}
+
     def _upload_spike_row(self, layer_name: str, t: int) -> None:
         # CPU path: copy this timestep's spikes from the layer's host tensor into row
         # `t` of the spike-history GL buffer (R8UI, one byte/spike). Past the capacity

bindsnet/rendering/app.py

@@ -15,16 +15,29 @@
 
 
 class Application():
-  def __init__(self, network: GUINetwork, width=1400, height=900, title="BindsNET GUI",
+  def __init__(self, network: GUINetwork,
+               width=1400, height=900, title="BindsNET GUI",
                header: str | None = None,
                max_steps_per_second: int | float | str | None = None,
                draw_fps: float | None = None,
                parameters: dict | None = None):
     self.width, self.height = width, height
+
+    # `network` is a GUINetwork. If it OVERRIDES build() (an inheritable model
+    # definition), the Application drives its lifecycle: build() assembles it,
+    # make_input() supplies the stimulus, network.parameters feeds the editable panel,
+    # and the "Apply & Reload" button rebuilds it in place (see reload_model). A plain
+    # GUINetwork assembled imperatively (no build() override) is used as-is with no
+    # reload, driven by the `inputs` dict passed to run().
     self.network = network
-    # Optional {label: value} map surfaced as editable rows in the control panel's
-    # Parameters section (for future model-rebuild support).
-    self.parameters = parameters
+    self._buildable = type(network).build is not GUINetwork.build
+    self._has_make_input = type(network).make_input is not GUINetwork.make_input
+    self.can_reload = self._buildable
+    if self._buildable:
+      self.network.rebuild()                    # initial build() from constructor params
+      self.parameters = dict(network.parameters)
+    else:
+      self.parameters = parameters              # legacy: cosmetic-only panel rows
     self.widgets = []
     self.inputs = None      # Set when run() is called; Inputs into network during runtime
     self.runtime = None     # Set when run() is called; Total runtime of network simulation
@@ -89,7 +102,7 @@ def __init__(self, network: GUINetwork, width=1400, height=900, title="BindsNET
     self.grid = self.layout.add_grid(row=next_row, col=0, margin=10)
 
     # Migrate network tensors to shared OpenGL buffers
-    network.migrate()
+    self.network.migrate()
 
     # Build the control surface (a separate Qt window). It calls back into
     # toggle_play/step_once/run_n and reads back via set_time etc.
@@ -165,6 +178,98 @@ def reset(self):
     self.panel.on_reset()
     self.canvas.update()
 
+  def reload_model(self):
+    # language=rst
+    """
+    Rebuild the network from the control panel's current parameters and re-bind the
+    plots in place, WITHOUT recreating the canvas / control window (that is what causes
+    the black-screen/lag we avoid). Driven by the panel's "Apply & Reload" button, which
+    fires on the main GL thread during panel.pump() -- the same path reset() uses to
+    touch GL, so the context is current and these calls are safe.
+
+    The network's :meth:`GUINetwork.rebuild` reassembles the model IN PLACE (frees the
+    old GL buffers, tears down the layers, re-runs build() with the edited parameters),
+    so the same network object is kept and the widgets simply re-bind to it.
+    """
+    if not self.can_reload:
+      return
+    if self.runtime is None:
+      self.panel.show_status("Start the run before reloading.", error=True)
+      return
+
+    # Coerce the edited fields first; a bad value aborts before the model is touched.
+    try:
+      values = self.panel.get_parameter_values()
+    except Exception as exc:
+      self.panel.show_status(f"Invalid parameter: {exc}", error=True)
+      return
+
+    self.canvas.set_current()   # ensure GL calls below target the plot context
+    try:
+      self.network.rebuild(**values)   # free GL, clear, set params, re-run build()
+      self.network.migrate()           # allocate the rebuilt net's shared GL buffers
+    except Exception as exc:
+      # build() failed (e.g. an invalid size). The network is now an empty shell, but
+      # rebuild() always clears-then-builds, so a subsequent reload with good values
+      # fully recovers. Leave the sim paused and report.
+      self.panel.show_status(f"Build failed: {exc}", error=True)
+      return
+
+    # Re-bind every plot to the rebuilt network (releases old visuals, allocates fresh
+    # history buffers). Done before regenerating inputs so a (rare) input mismatch can't
+    # leave widgets pointing at freed buffers.
+    for widget in self.widgets:
+      widget.reload(self.network)
+    self.parameters = dict(self.network.parameters)
+
+    # Regenerate the stimulus for the rebuilt model. make_input() tracks the parameters
+    # so it always fits; a fixed dict is only warned about if it no longer matches.
+    input_warning = None
+    if self._has_make_input:
+      self.inputs = self.network.make_input(self.runtime)
+    else:
+      try:
+        self._validate_inputs(self.inputs, self.network)
+      except Exception as exc:
+        input_warning = f"Reloaded, but inputs no longer fit: {exc}"
+
+    # Re-arm the run-state machine at t=0 (the rebuilt net + its history buffers are
+    # already fresh/zeroed, so no reset_state_variables/reset_history needed).
+    self.running = False
+    self.step_budget = 0
+    self._was_active = None
+    self._last_draw = None
+    self._sps_count = 0
+    self._sps_t0 = None
+    self.current_time = 0
+    self._set_active(False)
+    if hasattr(self, "timer") and not self.timer.running:
+      self.timer.start()
+
+    self.panel.on_reset()
+    self.panel.set_parameter_values(self.network.parameters)
+    if input_warning is not None:
+      self.panel.show_status(input_warning, error=True)
+    else:
+      self.panel.show_status("Model reloaded.")
+    self.canvas.update()
+
+  def _validate_inputs(self, inputs: dict, network: GUINetwork):
+    # Ensure the (possibly regenerated) inputs match the rebuilt network before swapping
+    # anything in: each input tensor's last dim must equal its target layer's n, and a
+    # time-major tensor must cover the whole runtime. Raises ValueError on a mismatch.
+    for name, tensor in inputs.items():
+      if name not in network.layers:
+        continue
+      n = int(network.layers[name].n)
+      if int(tensor.shape[-1]) != n:
+        raise ValueError(
+          f"input '{name}' last dim {int(tensor.shape[-1])} != layer '{name}' n {n}. "
+          f"Pass `inputs` to run() as a builder function so it tracks the parameters.")
+      if tensor.dim() >= 2 and int(tensor.shape[0]) < self.runtime:
+        raise ValueError(
+          f"input '{name}' has {int(tensor.shape[0])} timesteps < runtime {self.runtime}.")
+
   def _set_active(self, active: bool):
     # Fire on each play<->pause transition: lock the cameras (and resume the
     # follow window) while advancing, hand them back for zoom/pan while idle.
@@ -244,9 +349,21 @@ def _should_draw(self):
       return True
     return False
 
-  def run(self, inputs: dict[str, torch.Tensor], runtime: int):
-    self.inputs = inputs
+  def run(self, inputs: dict[str, torch.Tensor] | None = None, runtime: int = None):
+    # The stimulus comes from the network's make_input(runtime) when it implements one
+    # (regenerated on every reload so its shape tracks the parameters); otherwise a fixed
+    # `inputs` dict must be supplied here. `runtime` sizes the full-history GL buffers.
+    if runtime is None:
+      raise ValueError("Application.run() requires `runtime`.")
     self.runtime = runtime
+    if self._has_make_input:
+      self.inputs = self.network.make_input(runtime)
+    elif inputs is not None:
+      self.inputs = inputs
+    else:
+      raise ValueError(
+        "Application.run() needs an `inputs` dict unless the network implements "
+        "make_input().")
     # Prime widgets now that runtime is known (full-history buffers need it).
     for widget in self.widgets:
       widget.prime(self.network, runtime)