WebAssembly Code Generation
===========================
Generate WebAssembly (WASM) for browser-based physics simulations.
Overview
--------
WebAssembly enables near-native performance in web browsers, making it ideal for:
- Interactive physics demonstrations
- Educational web applications
- Browser-based games with realistic physics
- Online simulation tools
.. note::
WebAssembly support is experimental. Basic mechanics simulations work,
but SPH fluid dynamics require additional browser features.
Prerequisites
-------------
To generate and use WebAssembly:
1. **Emscripten SDK**: Install from https://emscripten.org
2. **Modern browser**: Chrome, Firefox, Safari, or Edge (recent versions)
.. code-block:: bash
# Install Emscripten
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
Basic Usage
-----------
.. code-block:: python
from mechanics_dsl import PhysicsCompiler
compiler = PhysicsCompiler()
compiler.compile_dsl(source)
# Generate WebAssembly
compiler.compile_to_wasm("pendulum.wasm")
This generates:
- ``pendulum.wasm``: WebAssembly binary
- ``pendulum.js``: JavaScript glue code
- ``pendulum.html``: Simple test page (optional)
Using in Web Pages
------------------
Basic HTML integration:
.. code-block:: html
JavaScript API
--------------
The generated JavaScript module provides:
.. code-block:: javascript
// Create simulation instance
const sim = Module._create_simulation();
// Set initial conditions
Module._set_state(sim, theta, theta_dot);
// Step forward in time
Module._step_simulation(sim, dt);
// Get current state
const state = Module._get_state(sim);
// Returns: { theta: ..., theta_dot: ..., t: ... }
// Clean up
Module._destroy_simulation(sim);
Performance
-----------
WebAssembly typically achieves:
- 80-90% of native C++ performance
- Much faster than equivalent JavaScript
- Consistent across browsers
For physics simulations, expect:
.. list-table::
:header-rows: 1
* - System
- JavaScript (ms/step)
- WASM (ms/step)
- Speedup
* - Pendulum
- 0.5
- 0.05
- 10x
* - Double pendulum
- 2.0
- 0.15
- 13x
* - N-body (10)
- 15.0
- 1.2
- 12x
Limitations
-----------
Current WebAssembly support has limitations:
1. **No SPH fluids**: Requires SIMD and threading (future)
2. **No file I/O**: Must use JavaScript for data export
3. **Memory limits**: Browser sandbox restricts memory
4. **Debugging**: Limited debugging tools compared to native
Future Plans
------------
Planned WebAssembly enhancements:
- SIMD support for SPH kernels
- Web Workers for parallel simulation
- WebGL integration for visualization
- Interactive parameter controls
Example: Interactive Pendulum
-----------------------------
Complete example with visualization:
.. code-block:: html
MechanicsDSL Pendulum
Interactive Pendulum