Setup

If you don't have it, download and setup Emscripten:

just install_emsdk

The build script (see below) expects that the Emscripten SDK is available in emsdk/, so if you already have an installation, symlink it there.

Then you need to prepare the hector code:

just setup

Then to compile:

just build

To create a debug build:

DEBUG=true just build

Usage

See main.js for an example.

Webpack

Inclusion in Webpack is a little tricky, but what I've found to work is to include a specific rule targeting hector.wasm so that Webpack loads it in as a regular file. For example, your webpack.config.js would include something like:

module.exports = {
  // ...
  module: {
    rules: [{
      test: /hector\.wasm/,
      type: 'asset'
    }]
  },
  // ...
};

Known Issues

[FIXED] Can't run optimized build

Currently the optimized build runs into an index out of bounds error unless the -s NO_DISABLE_EXCEPTION_CATCHING flag is included, which results in larger file sizes (about 1.1MB total; without that flag its about 600KB) and slower execution.

Update: This is now fixed:

The problem was in this try-catch block in CarbonCycleSolver::run:

try {
    using namespace boost::numeric::odeint;
    typedef runge_kutta_dopri5<std::vector<double> > error_stepper_type;
    integrate_adaptive( make_controlled<error_stepper_type>( eps_abs, eps_rel ),
             odeFunctor, c, t_start, t_target, dt, odeFunctor );
} catch( bad_derivative_exception& e ) {
    stat = e.errorFlag;
}

When exception catching is disabled, the program just crashes here, rather than catching the exception and moving on.

Instead of using the -s NO_DISABLE_EXCEPTION_CATCHING, which enables all exception catching and adds size/performance overhead everywhere, instead the -s EXCEPTION_CATCHING_ALLOWED flag is used to allow exceptions only for that specific method. Since it's C++ we have to get the mangled name to give to Emscripten. This is already in the build.sh script, but for posterity, here's how you get the name:

Compile a debug build or just a regular build but with EMCC_DEBUG=1. Emscripten will output intermediate files to /tmp/emscripten_temp. Then run:

/.emsdk/upstream/bin/llvm-nm /tmp/emscripten_temp/carbon-cycle-solver_5.o | grep run

One of those should be the CarbonCycleSolver::run method.

Compiled in this way the resulting total file size is about 600KB (for both the .js and .wasm files total).

Performance

From the Emscripten documentation:

Emscripten-compiled code can currently achieve approximately half the speed of a native build.

It takes under 1 second to run in both Firefox (92.0a1) and Chrome (91.0.4472.164) (in Chrome I hit under 500ms). This is when using only one observer/output variable; more will add to the runtime. For reference, pyhector (which uses Hector 2.4.0, this WASM build is using 2.5.0) with the three default observers/outputs runs in about 1.5-2 seconds (this is a very rough comparison).

About a quarter of that time is setting the scenario emissions--the overhead is probably from the conversion of JS arrays into vectors.

Before the fix for the exception issue above it took about ~3 seconds to run in Firefox and ~1.5-2 seconds in Chrome.

File sizes

See https://emscripten.org/docs/optimizing/Optimizing-Code.html

Misc notes

This currently compiles to a single .js file with the wasm embedded into it. I was having issues importing the library, where Emscripten hardcodes the path to the .wasm file (e.g. to dist/hector.wasm). If this library is loaded as part of a Webpack project that path is incorrect (when I tested it the browser looked for it at /dist/dist/hector.wasm). Compiling to a single .js file gets around this problem, but it is a fair bit larger (750KB compared to 600KB before).

Citations

The glue C++ code is almost entirely from the excellent pyhector project, with minor modifications (to the namespace and return types, so that it's not using numpy datatypes).

Hartin, C. A., Patel, P., Schwarber, A., Link, R. P., and Bond-Lamberty, B. P.: A simple object-oriented and open-source model for scientific and policy analyses of the global climate system – Hector v1.0, Geosci. Model Dev., 8, 939-955, doi:10.5194/gmd-8-939-2015, 2015.
Willner, Sven, & Gieseke, Robert. (2019, August 6). pyhector (Version v2.4.0.0). Zenodo. http://doi.org/10.5281/zenodo.3361624

frnsys/hector-wasm