# Daybreak Neural Dynamics Explorer

An open-source, browser-based laboratory for one-population recurrent dynamics
and a Wilson–Cowan-style excitatory–inhibitory pair. Change coupling, external
drive, time constants, and initial states; inspect trajectories, nullclines,
fixed points, and Jacobian eigenvalues; export displayed samples as CSV.

Public application: https://daybreak-neural.org/neural-dynamics

Source ZIP: https://daybreak-neural.org/open-source/neural-dynamics-explorer.zip

Release: 1.0.0, November 10, 2026. License: MIT; see `LICENSE`.

## Run locally

Extract the source ZIP. From the extracted folder, serve these files with a
local HTTP server; ES modules should be opened over HTTP rather than `file://`:

```sh
python3 -m http.server 8000
```

On Windows, `py -m http.server 8000` is an equivalent option. Open
http://localhost:8000/index.html in a current browser. There is no build step,
package installation, account, or API key. The application has no third-party
JavaScript dependencies. Simulations and CSV generation run in the browser;
the application does not upload simulation parameters or results.

## Source map

| File | Purpose |
| --- | --- |
| `index.html` | Semantic interface, model notes, and reference link |
| `styles.css` | Responsive styling and chart presentation |
| `app.mjs` | Controls, SVG plots, time inspection, and CSV export |
| `models.mjs` | Model definitions, RK4 integration, roots, Jacobians, nullclines |
| `models.test.mjs` | Numerical and preset regression checks |
| `mark.svg` | Daybreak mark used by this interface |
| `LICENSE` | MIT terms for the files in this release |

`models.mjs` is independent of the DOM and can also be imported in Node.js or
another JavaScript application. Source files are readable and unminified.

## Equations and units

The sigmoid is `S(z) = 1 / (1 + exp(-z))`.

One recurrent population:

```text
tau * dr/dt = -r + S(w*r + P)
```

Excitatory–inhibitory pair:

```text
tauE * dE/dt = -E + S(wEE*E - wEI*I + P)
tauI * dI/dt = -I + S(wIE*E - wII*I + Q)
```

Internal states `r`, `E`, and `I` are fractions of a 100 Hz reference rate.
Plots and CSVs show rates in Hz. Integration time and time constants are in
milliseconds; displayed Jacobian eigenvalues are in inverse seconds. Weights
and drives are dimensionless. `wEI` denotes inhibitory input to E and `wIE`
denotes excitatory input to I; inhibitory signs are explicit in the equations.

The presets illustrate a single attractor, bistability, damped oscillations,
sustained rhythms, and a stable node. These are educational population rate
models, not fits to measured recordings or a validated clinical system.

## Numerical interpretation

- Integration uses fixed-step fourth-order Runge–Kutta with steps no larger
  than 0.5 ms by default. The module permits a smaller maximum step for checks.
- Plotting samples are decimated for display. CSV export contains those same
  displayed samples, not every internal solver step.
- Fixed points are found using bisection and a finite search for residual
  extrema. Near tangencies and bifurcations, finite numerical resolution can
  miss closely spaced roots; the display is not a formal bifurcation analysis.
- Jacobian eigenvalues describe local behavior near each fixed point. A
  positive real part does not, by itself, prove a stable limit cycle, and a
  finite-time trajectory does not prove asymptotic behavior.
- The model functions assume valid, finite parameters within the interface's
  supported ranges. Callers importing the module should validate inputs and
  check numerical convergence for their own use.

## Run the checks

With a current Node.js installation (Node 20 or later):

```sh
node --test models.test.mjs
```

The checks cover known preset behavior, finite bounded trajectories, analytic
Jacobians against central finite differences, and RK4 step-halving convergence.
They are regression checks, not empirical validation of the models.

## Embed

Serve the files on the same origin as the host page and embed
`index.html?embed=1`. Embed mode hides the standalone heading and footer and
uses the available width. The frame posts
`{ type: "daybreak-explorer-height", height: <pixels> }` to its own origin when
the natural content height changes. A host should accept this message only
when both `event.origin` matches its origin and `event.source` matches the
iframe's `contentWindow`, then validate the numeric height before applying it.

## Contribute and reuse

You may use, modify, and redistribute this release under the MIT license,
including commercial use, provided the license notice is retained. This
license applies to the explorer files in this release, not the rest of the
Daybreak website, research papers, or datasets. Feedback and proposed changes
can be shared at https://daybreak-neural.org/contact.

Scientific background: Wilson, H. R. and Cowan, J. D. (1972), *Excitatory and
inhibitory interactions in localized populations of model neurons*.
https://pubmed.ncbi.nlm.nih.gov/4332108/

The implementation uses a simplified sigmoid rate model inspired by that
framework; it is not a reproduction of every term or assumption of the paper.