SimulationVuer

SimulationVuer is a Vue 3 component used in the SPARC portal to run some simulation-based datasets that include a JSON file. That JSON file is used by SimulationVuer to create a user interface (Fig. 1) which can then be used by someone to configure a simulation before running it.

The simulation is run either on oSPARC or in a user's browser, depending on how the simulation-based dataset is referenced (see the id property below). In the oSPARC case, SimulationVuer relies on the SPARC API to ask oSPARC to run the model and to retrieve the simulation results, which can then be visualised and interacted with using the interface.

Figure 1: user interface for dataset 135.

How to use

To install the package in your Vue application:

npm install @abi-software/simulationvuer

To include the package in your script:

import { SimulationVuer } from "@abi-software/simulationvuer";

To register the package as a Vue component:

export default {
  ...
  components: {
    ...,
    SimulationVuer,
    ...
  }
  ...
}

The above registers the SimulationVuer component into the global scope. You can now use SimulationVuer in your Vue template as follows:

<SimulationVuer :apiLocation="apiLocation" :id="123" />

where:

• apiLocation is the URL of a running copy of the SPARC API; and
• id is:
  • the id of a SPARC simulation-based dataset (as a Number, e.g., 135);
  • the PMR path to an OMEX file (as a String, e.g., workspace/b7c/rawfile/e0ae8d2d56aaaa091e23e1ee7e84cacbda1dfb6b/135.omex);
  • the direct URL to an OMEX file (as a String, e.g., https://raw.githubusercontent.com/opencor/webapp/refs/heads/main/tests/models/ui/135.omex); or
  • a raw OMEX file (as a Uint8Array).

Note that a simulation will be run on oSPARC if the id references a SPARC simulation-based dataset, in a user's browser otherwise.

Deployment

SimulationVuer uses @opencor/opencor, which relies on libOpenCOR's threaded WebAssembly (WASM) to run simulations in the browser. Threaded WASM requires SharedArrayBuffer, which in turn requires the page to be served with cross-origin isolation headers.

When deploying an application that uses SimulationVuer, your Web server must must send the following headers with the HTML document:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Without these headers, @opencor/opencor will fail to initialise libOpenCOR and will not function.

The exact steps to set these headers depend on your Web server. Here are the steps for Apache:

1. Enable mod_headers. Ensure the headers module is enabled (e.g., a2enmod headers or add it to your modules list).

2. Set headers on the HTML path. In your virtual host config, add:

   <Location "/app">
       Header set Cross-Origin-Opener-Policy "same-origin"
       Header set Cross-Origin-Embedder-Policy "require-corp"
   </Location>

   Adjust the Location path to match the URL prefix where the Web app is served (here, we use /app assuming the Web app is served from https://your-domain.com/app).

3. Reload Apache. Apply the changes with sudo apachectl reload or the equivalent for your distribution.

4. Verify. Check the response headers on your deployed HTML page using:

   curl -I https://your-domain.com/app/

   You should see:

   cross-origin-opener-policy: same-origin
   cross-origin-embedder-policy: require-corp

Project setup

Clone the respository

git clone https://github.com/ABI-Software/simulationvuer.git

Vue component

Setup

npm install

Run the sample application

npm run serve

Compile and minify for production

npm run build-bundle

Vue 2 vs. Vue 3

SimulationVuer is now being developed as a Vue 3 component only. The Vue 2 version of SimulationVuer is not maintained anymore.

Documentation

The documentation is written using VitePress and vuese, and it can be found in the docs folder.

To run in local development mode

npm run docs:watch

This will start the documentation server with VitePress on port 5173: http://localhost:5173/simulationvuer/.