brian2wasm.device module

Module implementing the WASM/JS “standalone” device.

class brian2wasm.device.WASMStandaloneDevice(*args, **kwds)[source]

Bases: CPPStandaloneDevice

The Device used for WASM simulations.

activate(*args, **kwargs)[source]

Activate the WASM standalone device for simulation.

This method overrides template configuration and ensures WASM-specific headers are included in the generated code.

Parameters:

  • *args (tuple) – Positional arguments passed to the parent activate method.

  • **kwargs (dict) – Keyword arguments passed to the parent activate method.

Raises:

None –

Returns:

Configures the device and modifies build templates; does not return a value.

Return type:

None

build(html_file=None, html_content=None, **kwds)[source]

Build the project for the WASM backend.

This method orchestrates the full build pipeline from code generation to Emscripten compilation and optional execution.

Parameters:

  • html_file (str, optional) – Path to a custom HTML template file.

  • html_content (dict, optional) – Dictionary of HTML template variables.

  • directory (str, optional) – Target build directory. Defaults to “output”.

  • results_directory (str, optional) – Sub-folder for runtime results. Defaults to “results”.

  • compile (bool, optional) – Whether to compile sources with emcc. Default is True.

  • run (bool, optional) – Whether to run the generated bundle. Default is True.

  • debug (bool, optional) – Whether to include debug flags. Default is False.

  • clean (bool, optional) – Whether to clear old build artifacts. Default is False.

  • with_output (bool, optional) – Whether to forward stdout/stderr. Default is True.

  • additional_source_files (list of str, optional) – Extra .cpp files to include.

  • run_args (list of str, optional) – Additional runtime arguments.

  • direct_call (bool, optional) – True when called directly; False if triggered automatically.

  • **kwds (dict) – Reserved for future options.

Raises:

  • RuntimeError – If build state is invalid or already executed.

  • TypeError – If results_directory is absolute.

  • ValueError – If invalid options are passed (e.g., negative threads).

Returns:

Produces a build directory with compiled WASM/HTML output.

Return type:

None

copy_source_files(writer, directory)[source]

Copy JavaScript runtime files to the build directory.

This method copies required JavaScript files (worker.js, brian.js) and optionally a custom index.html into the build folder.

Parameters:

  • writer (CodeWriter) – Object containing source file information.

  • directory (str) – Target directory for copied files.

Raises:

IOError – If copying files fails.

Returns:

Populates the build directory with JavaScript runtime files.

Return type:

None

generate_makefile(writer, compiler, compiler_flags, linker_flags, nb_threads, debug)[source]

Generate a platform-specific makefile for Emscripten compilation.

This method configures compiler and linker flags, resolves SDK paths, and writes a makefile tailored for WASM builds.

Parameters:

  • writer (CodeWriter) – Object for writing generated files.

  • compiler (str) – Compiler name (typically emcc).

  • compiler_flags (str) – Compiler flags to apply.

  • linker_flags (str) – Linker flags to apply.

  • nb_threads (int) – Number of threads (unused for WASM).

  • debug (bool) – Whether to include debug symbols.

Raises:

RuntimeError – If Emscripten paths or build options are invalid.

Returns:

Writes the makefile to disk; does not return a value.

Return type:

None

generate_objects_source(writer, arange_arrays, synapses, static_array_specs, networks, timed_arrays)[source]

Generate the main C++ source file for WASM compilation.

This method produces the core simulation code, including objects, arrays, and transfer variables, and writes it to objects.* files.

Parameters:

  • writer (CodeWriter) – Object for writing generated code.

  • arange_arrays (dict) – Specifications for arange arrays.

  • synapses (set) – Set of Synapses objects in the simulation.

  • static_array_specs (dict) – Specifications for static arrays.

  • networks (set) – Set of Network objects in the simulation.

  • timed_arrays (dict) – Specifications for timed arrays.

Raises:

IOError – If writing the generated code to files fails.

Returns:

Generates source files on disk; does not return a value.

Return type:

None

get_report_func(report)[source]

Generate C++ code for simulation progress reporting.

This method produces source code that reports simulation progress to the console or forwards updates to JavaScript via EM_ASM.

Parameters:

report (str or None) – Type of progress reporting: None, ‘text’, ‘stdout’, ‘stderr’, or custom C++ code.

Raises:

ValueError – If the report type is unsupported.

Returns:

The generated C++ source code for progress reporting.

Return type:

str

network_run(net, duration, report=None, report_period=10. * second, namespace=None, profile=None, level=0, **kwds)[source]

Execute a Brian2 network simulation for the WASM backend.

This method organizes network objects, generates C++ execution code, and triggers the build if build_on_run is enabled.

Parameters:

  • net (Network) – The Brian2 network to simulate.

  • duration (Quantity) – Duration of the simulation (must be non-negative).

  • report (str or None, optional) – Progress reporting mode. Default is None.

  • report_period (Quantity, optional) – Interval between progress reports. Default is 10*second.

  • namespace (dict, optional) – Local namespace for variable resolution. Default is None.

  • profile (bool, optional) – Whether to enable profiling. Default is None.

  • level (int, optional) – Stack level for namespace detection. Default is 0.

  • **kwds (dict) – Additional keyword arguments.

Raises:

  • ValueError – If duration is negative.

  • NotImplementedError – If multiple incompatible report functions are used.

  • RuntimeError – If the network was already built and run.

Returns:

Prepares and builds the simulation; does not return a value.

Return type:

None

run(directory, results_directory, with_output, run_args)[source]

Execute the compiled WASM simulation in a browser environment.

This method launches the simulation using emrun and provides browser-based progress reporting and visualization.

Parameters:

  • directory (str) – Build directory containing compiled files.

  • results_directory (str) – Directory to store simulation results.

  • with_output (bool) – Whether to forward stdout/stderr output.

  • run_args (list) – Extra command-line arguments for the execution environment.

Raises:

RuntimeError – If the server cannot be launched or required files are missing.

Returns:

Runs the simulation in a browser; does not return a value.

Return type:

None

transfer_only(variableviews)[source]

Mark variables for transfer from WASM to JavaScript.

This method specifies which simulation variables should be available in JavaScript after the simulation completes.

Parameters:

variableviews (list) – List of VariableView objects to be transferred.

Raises:

AssertionError – If transfer variables are already set before calling this method.

Returns:

Stores the selected variables for later transfer; does not return a value.

Return type:

None