Writing HTML Files for Brian2WASM Scripts
========================================
This guide explains how to create custom HTML files to integrate with ``brian2wasm`` scripts, enabling tailored user interfaces, dynamic variable access, and interactive data visualizations.
Overview
--------
When you run a ``Brian 2`` script (e.g., ``my_simulation.py``) with ``brian2wasm``, it automatically detects an HTML file with the same name (e.g., ``my_simulation.html``) in the same directory. This HTML file serves as the web interface for your simulation.
.. note::
If no matching HTML file is found, ``brian2wasm`` uses a default template with basic progress reporting and visualization features.
.. tip::
Ensure the HTML file has the same name as your Python script and is located in the same directory to avoid issues with detection.
Basic HTML Structure
-------------------
Your HTML file should include the following key components to ensure compatibility with ``brian2wasm``:
Required JavaScript Libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Include these libraries in the ```` section of your HTML:
.. code-block:: html
.. note::
The ``brian.js`` file is generated by ``brian2wasm`` and must be in the same directory as your HTML file. The Plotly library enables interactive visualizations.
Essential HTML Elements
~~~~~~~~~~~~~~~~~~~~~~
Include these elements in the ```` for core functionality:
.. code-block:: html
My Brian2 Simulation
Ready to run
.. tip::
Customize the styling (e.g., CSS) of these elements to match your desired interface design.
Accessing Script Variables
-------------------------
After the simulation completes, variables from your ``Brian 2`` script are accessible via the ``brian_results`` JavaScript object in the following structure:
.. code-block:: javascript
brian_results[owner_name][variable_name]
Variable Access Examples
~~~~~~~~~~~~~~~~~~~~~~~
- For a spike monitor named ``spikemonitor``:
.. code-block:: javascript
// Access spike times
var spike_times = brian_results['spikemonitor'].t;
// Access neuron indices
var neuron_indices = brian_results['spikemonitor'].i;
- For a state monitor named ``statemonitor`` recording voltage:
.. code-block:: javascript
// Access recorded voltages
var voltages = brian_results['statemonitor'].v;
// Access time points
var times = brian_results['statemonitor'].t;
.. warning::
Ensure your ``Brian 2`` script defines monitors with the correct names, as these are used to access data in ``brian_results``. Misnamed monitors will result in undefined variables.
Setting Up the BrianSimulation Class
-----------------------------------
Initialize the simulation interface in your HTML with JavaScript:
.. code-block:: html
.. note::
The ``BrianSimulation`` class links your HTML elements to the simulation logic, enabling interaction and visualization.
Built-in Plot Types
------------------
Raster Plots
~~~~~~~~~~~
For visualizing spike trains:
.. code-block:: javascript
var result_plots = [{
type: 'raster',
canvas: 'my_canvas_id'
}];
.. note::
Raster plots automatically use ``brian_results['spikemonitor'].t`` (spike times) and ``brian_results['spikemonitor'].i`` (neuron indices) for visualization.
Custom Visualizations with Plotly
--------------------------------
Creating Custom Plot Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Define custom visualization functions for tailored plots:
.. code-block:: javascript
function custom_voltage_plot(event) {
var results = event.data.results;
var times = results['statemonitor'].t;
var voltages = results['statemonitor'].v;
var trace = {
x: times,
y: voltages[0], // First neuron's voltage
type: 'scatter',
mode: 'lines',
name: 'Membrane Potential'
};
var layout = {
title: 'Neuron Voltage Over Time',
xaxis: { title: 'Time (s)' },
yaxis: { title: 'Voltage (V)' }
};
Plotly.react('voltage_canvas', [trace], layout);
}
Registering Custom Plots
~~~~~~~~~~~~~~~~~~~~~~~
Include custom functions in the ``result_plots`` configuration:
.. code-block:: javascript
var result_plots = [
{
type: 'custom',
func: custom_voltage_plot
},
{
type: 'raster',
canvas: 'spikes_canvas'
}
];
Advanced Plotly Features
~~~~~~~~~~~~~~~~~~~~~~~
Multiple Traces
^^^^^^^^^^^^^^^
Plot data from multiple neurons:
.. code-block:: javascript
function multi_neuron_plot(event) {
var results = event.data.results;
var times = results['statemonitor'].t;
var voltages = results['statemonitor'].v;
var traces = [];
for (let i = 0; i < 5; i++) { // Plot first 5 neurons
traces.push({
x: times,
y: voltages[i],
type: 'scatter',
mode: 'lines',
name: `Neuron ${i}`
});
}
var layout = {
title: 'Multi-Neuron Voltages',
xaxis: { title: 'Time (s)' },
yaxis: { title: 'Voltage (V)' }
};
Plotly.react('multi_canvas', traces, layout);
}
Interactive Features
^^^^^^^^^^^^^^^^^^^
Add interactive elements like a range slider:
.. code-block:: javascript
var layout = {
title: 'Interactive Simulation Results',
xaxis: {
title: 'Time (s)',
rangeslider: {} // Enable range slider
},
yaxis: { title: 'Value' }
};
Progress Reporting
-----------------
The progress system provides real-time feedback during simulation execution.
Progress Bar Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
Configure a progress bar:
.. code-block:: javascript
var progress_config = {
type: 'bar',
bar_id: 'my_progress_bar',
text_id: 'my_progress_text'
};
.. warning::
Currently, only the ``bar`` progress type is supported. Custom progress handlers are not yet available.
Complete Example
---------------
Below is a complete example of an HTML file for a ``brian2wasm`` simulation:
.. code-block:: html
Brian2 Simulation
Neural Network Simulation
Ready to run
Spike Raster Plot
Membrane Potential
Troubleshooting
---------------
Common Issues
~~~~~~~~~~~~~
- **HTML file not detected**:
Ensure the HTML file has the same name as your Python script (e.g., ``simulation.py`` → ``simulation.html``) and is in the same directory.
- **Variables not accessible**:
Verify that your ``Brian 2`` script defines monitors with the correct names. Use the browser's developer console (F12) to inspect the ``brian_results`` object.
- **Plotly not loading**:
Check the Plotly CDN link (``https://cdn.plot.ly/plotly-latest.min.js``) for accessibility. For offline use, download Plotly and reference it locally.
- **Progress bar not updating**:
Confirm that the progress bar and text elements have the correct IDs as specified in the ``progress_config`` object.
.. tip::
Use the browser's developer console (F12) to debug JavaScript errors and inspect the structure of the ``brian_results`` object for troubleshooting.