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 <head> section of your HTML:
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
<script src="brian.js"></script>
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 <body> for core functionality:
<body>
<h1>My Brian2 Simulation</h1>
<!-- Progress reporting elements -->
<progress id="brian_progress_bar" max="1" value="0"></progress>
<span id="brian_progress_text">Ready to run</span>
<!-- Run button -->
<button id="brian_run_button" onclick="simulation.run()">Run Simulation</button>
<!-- Visualization canvas -->
<div id="brian_canvas" style="width:100%; height:500px;"></div>
</body>
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:
brian_results[owner_name][variable_name]
Variable Access Examples
For a spike monitor named
spikemonitor:// 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
statemonitorrecording voltage:// 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:
<script>
// Configure visualization plots
var result_plots = [
{
type: 'raster',
canvas: 'brian_canvas'
}
];
// Configure progress reporting
var progress_config = {
type: 'bar',
bar_id: 'brian_progress_bar',
text_id: 'brian_progress_text'
};
// Initialize simulation
var simulation = new BrianSimulation(result_plots, progress_config, 'brian_run_button');
simulation.init();
</script>
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:
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:
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:
var result_plots = [
{
type: 'custom',
func: custom_voltage_plot
},
{
type: 'raster',
canvas: 'spikes_canvas'
}
];
Advanced Plotly Features
Multiple Traces
Plot data from multiple neurons:
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:
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:
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:
<!DOCTYPE html>
<html>
<head>
<title>Brian2 Simulation</title>
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
<style>
body { font-family: Arial, sans-serif; margin: 20px; }
.container { max-width: 1200px; margin: 0 auto; }
.plot-container { margin: 20px 0; }
#brian_progress_bar { width: 100%; height: 20px; }
</style>
</head>
<body>
<div class="container">
<h1>Neural Network Simulation</h1>
<div>
<button id="brian_run_button" onclick="simulation.run()">Run Simulation</button>
<progress id="brian_progress_bar" max="1" value="0"></progress>
<span id="brian_progress_text">Ready to run</span>
</div>
<div class="plot-container">
<h2>Spike Raster Plot</h2>
<div id="spikes_canvas" style="width:100%; height:400px;"></div>
</div>
<div class="plot-container">
<h2>Membrane Potential</h2>
<div id="voltage_canvas" style="width:100%; height:400px;"></div>
</div>
</div>
<script src="brian.js"></script>
<script>
function voltage_plot(event) {
var results = event.data.results;
if ('statemonitor' in results) {
var trace = {
x: results['statemonitor'].t,
y: results['statemonitor'].v[0],
type: 'scatter',
mode: 'lines',
name: 'Membrane Potential'
};
var layout = {
title: 'Membrane Potential',
xaxis: { title: 'Time (s)' },
yaxis: { title: 'Voltage (V)' }
};
Plotly.react('voltage_canvas', [trace], layout);
}
}
var result_plots = [
{ type: 'raster', canvas: 'spikes_canvas' },
{ type: 'custom', func: voltage_plot }
];
var progress_config = {
type: 'bar',
bar_id: 'brian_progress_bar',
text_id: 'brian_progress_text'
};
var simulation = new BrianSimulation(result_plots, progress_config, 'brian_run_button');
simulation.init();
</script>
</body>
</html>
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 2script defines monitors with the correct names. Use the browser’s developer console (F12) to inspect thebrian_resultsobject.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_configobject.
Tip
Use the browser’s developer console (F12) to debug JavaScript errors and inspect the structure of the brian_results object for troubleshooting.