dynsim 0.1.0

package/src/simulation.js

@@ -0,0 +1,161 @@
+/**
+ * Pure simulation engine — no DOM, no Plotly.
+ *
+ * Manages state, stepping, and plot data buffering.
+ * The step function is resolved via a stepProvider on each tick,
+ * enabling live code replacement.
+ */
+export class Simulation {
+  /**
+   * @param {object} config
+   * @param {Array} config.params - Parameter definitions [{id, label, min, max, step, value}]
+   * @param {string} config.plotType - 'timeseries' | '3d' | '2d'
+   * @param {object} config.plotConfig - Plotly layout config (title, axes, etc.)
+   * @param {object} config.initialState - Initial state object
+   * @param {number} config.initialX - Initial input/output value
+   * @param {number} config.dt - Time step
+   * @param {number} [config.maxPoints=1000] - Max buffered points (non-timeseries)
+   * @param {number} [config.maxPoints=1000] - Max buffered points (non-timeseries)
+   * @param {number} [config.pauseTime=null] - Pause simulation at this time (null = run forever)
+   * @param {string} [config.spikes=null] - State variable name to check for spikes (e.g. 'z'). Falsy = no spikes.
+   * @param {function} stepProvider - () => stepFunction. Called each tick to get the current step function.
+   */
+  constructor(config, stepProvider) {
+    this.params = config.params;
+    this.plotType = config.plotType || 'timeseries';
+    this.plotConfig = config.plotConfig || {};
+    this.initialState = config.initialState || { t: 0 };
+    this.initialX = config.initialX ?? 0;
+    this.dt = config.dt || 0.01;
+    this.maxPoints = config.maxPoints || 1000;
+    this.pauseTime = config.pauseTime ?? null;
+    this.spikes = config.spikes || null;
+
+    this.stepProvider = stepProvider;
+
+    this.x = this.initialX;
+    this.state = { ...this.initialState };
+    this.time = 0;
+    this.plotData = [];
+    this.spikeTimes = [];
+  }
+
+  /**
+   * Advance one time step.
+   * @param {number} inputValue - Current input from the user (slider)
+   * @param {object} paramValues - Parameter values keyed by param ID
+   * @returns {{ x: number, state: object, dataPoint: Array }} result of the step
+   * @throws if stepProvider returns null or step function throws
+   */
+  step(inputValue, paramValues) {
+    const stepFn = this.stepProvider();
+    if (!stepFn) {
+      throw new Error('No step function available');
+    }
+
+    // Add dt to params
+    const params = { ...paramValues, dt: this.dt };
+
+    const result = stepFn(inputValue, this.state, params);
+    this.x = result[0];
+    this.state = result[1];
+    this.time += this.dt;
+
+    // Record spike if the configured state variable is truthy
+    if (this.spikes && this.state[this.spikes]) {
+      this.spikeTimes.push(this.time);
+    }
+
+    const dataPoint = this._collectDataPoint();
+    this.plotData.push(dataPoint);
+    this._manageBuffer();
+
+    return { x: this.x, state: this.state, dataPoint };
+  }
+
+  /**
+   * Whether the simulation has reached its pause time.
+   * @returns {boolean}
+   */
+  get paused() {
+    return this.pauseTime != null && this.time >= this.pauseTime;
+  }
+
+  /**
+   * Reset simulation to initial conditions.
+   */
+  reset() {
+    this.x = this.initialX;
+    this.state = { ...this.initialState };
+    this.time = 0;
+    this.plotData = [];
+    this.spikeTimes = [];
+  }
+
+  /**
+   * Get current plot data arrays suitable for Plotly.
+   * @returns {object} { x, y, z? } arrays
+   */
+  getPlotArrays() {
+    if (this.plotType === '3d') {
+      return {
+        x: this.plotData.map(d => d[0]),
+        y: this.plotData.map(d => d[1]),
+        z: this.plotData.map(d => d[2])
+      };
+    }
+    return {
+      x: this.plotData.map(d => d[0]),
+      y: this.plotData.map(d => d[1])
+    };
+  }
+
+  /**
+   * Compute the current x-axis range for timeseries plots.
+   * @returns {[number, number]} [min, max]
+   */
+  getTimeseriesRange() {
+    const windowSize = (this.plotConfig.xaxis?.range?.[1] - this.plotConfig.xaxis?.range?.[0]) || 50;
+    const originalEnd = this.plotConfig.xaxis?.range?.[1] || 50;
+
+    if (this.time > originalEnd) {
+      return [this.time - windowSize, this.time];
+    }
+    return this.plotConfig.xaxis?.range || [0, 50];
+  }
+
+  // --- Private ---
+
+  _collectDataPoint() {
+    if (this.plotType === '3d') {
+      return [this.state.x || this.x, this.state.y || 0, this.state.z || 0];
+    } else if (this.plotType === 'timeseries') {
+      return [this.time, this.x];
+    } else {
+      return [this.x, this.state.y || 0];
+    }
+  }
+
+  _manageBuffer() {
+    if (this.plotType === 'timeseries') {
+      const windowSize = this.plotConfig.xaxis?.range?.[1] || 50;
+      const pointsPerWindow = Math.ceil(windowSize / this.dt);
+      const bufferPoints = Math.ceil(pointsPerWindow * 0.5);
+      const targetPoints = pointsPerWindow + bufferPoints;
+
+      if (this.plotData.length > targetPoints * 2) {
+        this.plotData = this.plotData.slice(-targetPoints);
+        // Trim old spike times outside the buffer
+        if (this.spikeTimes.length > 0) {
+          const cutoff = this.plotData[0][0]; // earliest time in buffer
+          const firstKeep = this.spikeTimes.findIndex(t => t >= cutoff);
+          if (firstKeep > 0) this.spikeTimes = this.spikeTimes.slice(firstKeep);
+        }
+      }
+    } else {
+      if (this.plotData.length > this.maxPoints) {
+        this.plotData.shift();
+      }
+    }
+  }
+}

package/src/umd-entry.js

@@ -0,0 +1,22 @@
+/**
+ * UMD entry point — auto-initializes for <script> tag usage.
+ * Exposes everything on the global DynSim namespace and calls autoInit().
+ *
+ * Injects the Python bridge FIRST (synchronously) so that PyScript
+ * processes it before any user <script type="py"> tags.
+ */
+export { Simulation } from './simulation.js';
+export { SimulationView } from './view.js';
+export { SimulationController } from './controller.js';
+export { CodeEditor } from './editor.js';
+export * as registry from './registry.js';
+export { autoInit } from './index.js';
+
+import { injectPythonBridge } from './pybridge.js';
+import { autoInit } from './index.js';
+
+// 1. Inject Python bridge before PyScript runs
+injectPythonBridge();
+
+// 2. Set up JS-side registration and auto-init
+autoInit();

package/src/view.js

@@ -0,0 +1,235 @@
+/**
+ * SimulationView — DOM + Plotly rendering.
+ *
+ * Creates the UI (sliders, buttons, plot area), reads user input,
+ * and updates the Plotly chart. Emits events via callbacks.
+ * Contains no simulation logic.
+ */
+export class SimulationView {
+  /**
+   * @param {object} options
+   * @param {HTMLElement} options.container - DOM element to render into
+   * @param {Array} options.params - Parameter definitions [{id, label, min, max, step, value}]
+   * @param {number} options.initialX - Initial input value
+   * @param {number} options.height - Plot height in pixels
+   * @param {string} options.plotType - 'timeseries' | '3d' | '2d'
+   * @param {object} options.plotConfig - Plotly layout config
+   * @param {object} [options.callbacks] - { onReset, onPauseToggle }
+   */
+  constructor({ container, params, initialX, height, plotType, plotConfig, spikeThreshold, callbacks }) {
+    this.container = container;
+    this.params = params;
+    this.initialX = initialX;
+    this.height = height || 400;
+    this.plotType = plotType || 'timeseries';
+    this.plotConfig = plotConfig || {};
+    this.spikeThreshold = spikeThreshold;
+    this.callbacks = callbacks || {};
+
+    this.plotDiv = null;
+
+    this.createHTML();
+    this.initPlot();
+  }
+
+  createHTML() {
+    this.container.innerHTML = `
+      <div class="dynsim-container" style="font-family: Arial, sans-serif; font-size: 0.9em;">
+        <div class="dynsim-controls" style="background: #f8f9fa; padding: 12px; border-radius: 6px; border: 1px solid #ddd; margin-bottom: 12px; box-sizing: border-box;">
+          <div class="dynsim-params"></div>
+        </div>
+        <div style="width: 100%; height: ${this.height}px; border: 1px solid #ddd; border-radius: 6px; box-sizing: border-box; overflow: hidden;">
+          <div class="dynsim-plot" style="width: 100%; height: 100%;"></div>
+        </div>
+      </div>
+    `;
+
+    this._buildControls();
+    this.plotDiv = this.container.querySelector('.dynsim-plot');
+
+    // Typeset LaTeX in labels if MathJax is available
+    if (typeof MathJax !== 'undefined' && MathJax.typesetPromise) {
+      MathJax.typesetPromise([this.container.querySelector('.dynsim-controls')]);
+    }
+  }
+
+  _buildControls() {
+    const paramsDiv = this.container.querySelector('.dynsim-params');
+
+    // Input slider row
+    let html = `
+      <div style="display: flex; gap: 12px; align-items: center; margin-bottom: 8px;">
+        <label style="font-weight: 600; font-size: 0.85em; color: #0056b3; white-space: nowrap;">Input (x):</label>
+        <input type="range" class="dynsim-input"
+          min="-2" max="2" step="0.1" value="${this.initialX}"
+          style="flex: 1; height: 6px; min-width: 100px;">
+        <span class="dynsim-input-value" style="background: #cfe2ff; padding: 2px 8px; border-radius: 3px; font-size: 0.85em; min-width: 40px; text-align: center; font-family: monospace;">${this.initialX.toFixed(2)}</span>
+        <button class="dynsim-reset" style="background: transparent; border: none; cursor: pointer; padding: 4px; display: flex; align-items: center;" title="Reset">
+          <svg width="20" height="20" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M21 12a9 9 0 1 1-9 -9c2.5 0 4.8 1 6.5 2.5l.5 .5"/>
+            <path d="M21 3v6h-6"/>
+          </svg>
+        </button>
+      </div>
+    `;
+
+    // Parameter sliders row
+    html += `<div style="display: flex; gap: 12px; align-items: center;">`;
+    html += this.params.map(param => `
+      <label style="font-weight: 600; font-size: 0.85em; white-space: nowrap;">${param.label}:</label>
+      <input type="range" class="dynsim-param" data-param="${param.id}"
+        min="${param.min}" max="${param.max}" step="${param.step}" value="${param.value}"
+        style="flex: 1; height: 6px; min-width: 100px;">
+      <span class="dynsim-param-value" style="background: #e9ecef; padding: 2px 8px; border-radius: 3px; font-size: 0.85em; min-width: 40px; text-align: center; font-family: monospace;">${param.value.toFixed(2)}</span>
+    `).join('');
+    html += `
+      <button class="dynsim-pause" style="background: transparent; border: none; cursor: pointer; padding: 4px; display: flex; align-items: center;" title="Pause">
+        ${SimulationView.PAUSE_ICON}
+      </button>
+    </div>`;
+
+    paramsDiv.innerHTML = html;
+
+    // Wire up slider display updates
+    paramsDiv.querySelector('.dynsim-input').addEventListener('input', (e) => {
+      e.target.closest('div').querySelector('.dynsim-input-value')
+        .textContent = parseFloat(e.target.value).toFixed(2);
+    });
+    paramsDiv.querySelectorAll('.dynsim-param').forEach(slider => {
+      slider.addEventListener('input', (e) => {
+        e.target.nextElementSibling.textContent = parseFloat(e.target.value).toFixed(2);
+      });
+    });
+
+    // Wire up button callbacks
+    this.container.querySelector('.dynsim-reset')
+      .addEventListener('click', () => this.callbacks.onReset?.());
+    this.container.querySelector('.dynsim-pause')
+      .addEventListener('click', () => this.callbacks.onPauseToggle?.());
+  }
+
+  initPlot() {
+    if (this.plotType === '3d') {
+      Plotly.newPlot(this.plotDiv, [{
+        x: [], y: [], z: [],
+        mode: 'lines',
+        type: 'scatter3d',
+        line: { color: '#2196f3', width: 4 }
+      }], {
+        title: this.plotConfig.title,
+        scene: {
+          xaxis: { title: this.plotConfig.xaxis?.title || 'X' },
+          yaxis: { title: this.plotConfig.yaxis?.title || 'Y' },
+          zaxis: { title: this.plotConfig.zaxis?.title || 'Z' }
+        },
+        margin: { l: 0, r: 0, t: 30, b: 0 }
+      });
+    } else {
+      const layout = { margin: { l: 50, r: 20, t: 40, b: 50 } };
+      if (this.plotConfig.title) layout.title = this.plotConfig.title;
+      if (this.plotConfig.xaxis) layout.xaxis = this.plotConfig.xaxis;
+      if (this.plotConfig.yaxis) layout.yaxis = this.plotConfig.yaxis;
+
+      Plotly.newPlot(this.plotDiv, [{
+        x: [], y: [],
+        mode: 'lines',
+        line: { color: '#2196f3', width: 2 }
+      }], layout);
+    }
+  }
+
+  /**
+   * Read the current input slider value.
+   * @returns {number}
+   */
+  getInput() {
+    return parseFloat(this.container.querySelector('.dynsim-input').value);
+  }
+
+  /**
+   * Read current parameter slider values as a dict keyed by param ID.
+   * @returns {object}
+   */
+  getParameters() {
+    const result = {};
+    this.container.querySelectorAll('.dynsim-param').forEach(slider => {
+      result[slider.dataset.param] = parseFloat(slider.value);
+    });
+    return result;
+  }
+
+  /**
+   * Update the Plotly chart with new data.
+   * @param {object} plotArrays - { x, y, z? } from Simulation.getPlotArrays()
+   * @param {[number, number]} [xRange] - x-axis range for timeseries
+   * @param {number[]} [spikeTimes] - spike times to render as vertical lines
+   */
+  updatePlot(plotArrays, xRange, spikeTimes) {
+    if (this.plotType === '3d') {
+      Plotly.animate(this.plotDiv, {
+        data: [{ x: plotArrays.x, y: plotArrays.y, z: plotArrays.z }]
+      }, { transition: { duration: 0 }, frame: { duration: 0 } });
+    } else if (this.plotType === 'timeseries') {
+      const layout = {
+        title: this.plotConfig.title,
+        xaxis: { title: this.plotConfig.xaxis?.title || 'Time', range: xRange },
+        yaxis: this.plotConfig.yaxis,
+        margin: { l: 50, r: 20, t: 40, b: 50 }
+      };
+
+      // Render spike markers and threshold line
+      const shapes = [];
+
+      // Spike threshold: horizontal dashed line
+      if (this.spikeThreshold != null) {
+        shapes.push({
+          type: 'line',
+          x0: 0, x1: 1, xref: 'paper',
+          y0: this.spikeThreshold, y1: this.spikeThreshold,
+          line: { color: 'grey', width: 1, dash: 'dash' }
+        });
+      }
+
+      // Spike times: vertical lines
+      if (spikeTimes && spikeTimes.length > 0) {
+        for (const t of spikeTimes) {
+          shapes.push({
+            type: 'line',
+            x0: t, x1: t,
+            y0: 0, y1: 1, yref: 'paper',
+            line: { color: 'rgba(255, 0, 0, 0.4)', width: 1 }
+          });
+        }
+      }
+
+      if (shapes.length > 0) layout.shapes = shapes;
+
+      Plotly.react(this.plotDiv,
+        [{ x: plotArrays.x, y: plotArrays.y, mode: 'lines', line: { color: '#2196f3', width: 2 } }],
+        layout
+      );
+    } else {
+      Plotly.animate(this.plotDiv, {
+        data: [{ x: plotArrays.x, y: plotArrays.y }]
+      }, { transition: { duration: 0 }, frame: { duration: 0 } });
+    }
+  }
+
+  /**
+   * Update the pause button icon.
+   * @param {boolean} isRunning
+   */
+  setPauseState(isRunning) {
+    const btn = this.container.querySelector('.dynsim-pause');
+    btn.title = isRunning ? 'Pause' : 'Play';
+    btn.innerHTML = isRunning ? SimulationView.PAUSE_ICON : SimulationView.PLAY_ICON;
+  }
+
+  destroy() {
+    this.container.innerHTML = '';
+  }
+}
+
+SimulationView.PAUSE_ICON = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle><line x1="10" y1="15" x2="10" y2="9"></line><line x1="14" y1="15" x2="14" y2="9"></line></svg>`;
+
+SimulationView.PLAY_ICON = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle><polygon points="10 8 16 12 10 16 10 8"></polygon></svg>`;