This repository is under active development. It aims to bring up meta-modeling functionality in an interactive, user-friendly, guided step-by-step way.
It uses Vite (and React) for the front-end, and Python (via Flask) for the backend. Additionally, it connects to the OSPARC backend through its API (which is actively being expanded with "Functions" and related content to allow for meta-modeling functionality).
CI uploads unit-test coverage to Codecov with separate node and flaskapi flags, plus Chromium browser coverage from the Playwright suite under the e2e flag.
Run Node coverage locally with:
cd node && npm ci && npm run test:coverageRun the Playwright browser coverage locally with:
make test-e2eRun backend coverage locally with:
make test-flaskapiCI combines regular and analytical backend coverage before uploading it.
To setup your development environment, you need to fill it with the API access data from your oSPARC's account. Login on a deployment with your account and create a New API Key and use that data to fill out the generated .env file:
make .envMake sure your images have been build (since they are used as a base for mounting the loca source folders)
make buildInstall and run the repository hooks before opening a PR:
uvx prek install
make prekStart for development mode with (pick the mode × permissions variant you need, see the run matrix below)
make run-develop-sumo-readNOTE: code will be running inside docker containers.
The app ships as 3 service modes × 2 permission levels, each with a development launcher (live source mounts, debug logging) and a production-local launcher (built images, validation mount only). There are 12 targets in total:
| Mode | Purpose | Dev (live mounts) | Prod-local (built images) |
|---|---|---|---|
| SuMo | surrogate metamodeling (fit/validation of AI models) | make run-develop-sumo-read |
make run-prod-local-sumo-read |
| SuMo | same, writable (run sampling, persist collections) | make run-develop-sumo-write |
make run-prod-local-sumo-write |
| UQ | uncertainty quantification (histograms, correlation, Sobol indices) | make run-develop-uq-read |
make run-prod-local-uq-read |
| UQ | same, writable | make run-develop-uq-write |
make run-prod-local-uq-write |
| MOGA | multi-objective genetic algorithm optimization (preview) | make run-develop-moga-read |
make run-prod-local-moga-read |
| MOGA | same, writable | make run-develop-moga-write |
make run-prod-local-moga-write |
Target naming: make run-{develop|prod-local}-{sumo|uq|moga}-{read|write} — mode/perm are passed to the backend as SERVICE_MODE/PERMISSIONS (§ SPEC.md §I env contract).
Notes:
- The app (Caddy proxy) publishes on host port
8888by default; if busy,scripts/resolve-app-port.shpicks the next free port (fallbacks 8889-8892) and the launcher prints the actual URL(s). - Under WSL2 the printed output distinguishes the shell-local
http://localhost:<port>from the Windows-browserhttp://<WSL-IP>:<port>; if Windowslocalhostfails on a fallback port while the WSL-IP URL works, see the portproxy workaround in the next section. - Dev launchers bind-mount
flaskapi/andnode/(container runs as your host UID/GID), so edits are served live — Vite HMR for the frontend, Flask debug reload for the backend.
Under WSL2, Windows localhost forwarding may already make the selected app port accessible, including fallback ports (8889-8892); it is not limited to 8888. If http://localhost:<port> fails from a Windows browser but the launcher's http://<WSL-IP>:<port> URL works, the manual netsh interface portproxy workaround below can forward the port into WSL. Adding or deleting these rules requires an elevated Command Prompt (cmd.exe "Run as administrator"; unprivileged add/delete is refused).
Manual flow in an elevated Command Prompt — show, delete stale, add, show — with <WSL-IP> set to the current WSL IP (the one the launcher prints, or the first address of hostname -I inside WSL):
netsh interface portproxy show v4tov4
for /L %p in (8889,1,8892) do netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=%p
for /L %p in (8889,1,8892) do netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=%p connectaddress=<WSL-IP> connectport=%p
netsh interface portproxy show v4tov4Or run scripts/setup-windows-portproxy.sh inside WSL: it detects the current WSL IP (same detection as the launcher banner) and prints this block pre-filled, ready to paste. To tear the rules down, run only the delete line.
Warning — stale rules after an IP change: the WSL IP is reassigned after wsl --shutdown or a Windows reboot. Existing portproxy rules keep forwarding to the OLD address, so localhost:<fallback-port> from Windows silently fails even while http://<WSL-IP>:<port> still works. Re-run scripts/setup-windows-portproxy.sh (or repeat delete + add with the new IP) after every restart. If the rules look correct but connections are still refused, Windows Defender Firewall may be blocking them; an inbound allow rule fixes it (run once): netsh advfirewall firewall add rule name="mmux-vite WSL fallback ports" dir=in action=allow protocol=TCP localport=8889-8892.
When done editing always validate the production build of the app with the below command (pick your variant), since it's the only one giving some minor guarantee on the corectness of your changes.
make run-prod-local-sumo-readPer-variable sampling limits are auto-derived by convention, not hand-set per study: there is no Sobol' bounds window in the UI — the Sobol' box is derived backend-side, in itis-sumo (the editable Sobol' bounds editor and the frontend box-derivation were deliberately removed as a DOMAIN↔DISTRIBUTION conflation; decision record: JavierGOrdonnez/mmux_vite#84). Two different boxes exist in the stack and they need not coincide:
| Box | Used by | Derived from | Rule |
|---|---|---|---|
| Sampling box | surrogate training/validation runs (LHS, grid search) | the modeller's input distributions | uniform → [min, max], normal → mean ± 2.5σ, constant → pinned value; these derived ranges seed the Start/End fields of the sampling forms, where they may still be adjusted before launching a run |
| Sobol' domain box | Sobol' sensitivity ensemble | the surrogate's observed training samples | per-variable min/max of the samples; a column constant in the samples becomes a fixed factor; draws are uniform over the box (log-uniform under a log-scale flag); no UI to edit it |
What this means in practice:
- ±2.5σ covers ≈98.8% of a normal distribution. The remaining ≈1.2% of the mass lies outside the sampled/validated domain — there the surrogate is extrapolating, not interpolating.
- Sobol' indices describe the surrogate's own exploration ensemble, not your distribution. The engine draws uniformly across the domain box, so the indices answer "how does the surrogate's output vary across this box?" — they are not your input distributions pushed through the surrogate (the Correlation panel is the distribution-shaped view; Sobol' ignores distribution shape entirely).
- Everything Sobol'-side is engine-owned.
itis_sumo.api.evaluate_soboltakes optionaldomains/fixedmaps; anything omitted is auto-inferred from the observed sample bounds, and the Saltelli sample count is fixed inside the engine. The FE sends no domain or distribution keys on the Sobol' request — a contract test (node/src/utils/sobolIndices.test.ts) locks that. Engine docstrings, verbatim: modeller distributions are "NOT an input here; they driveevaluate_uncertainty" and "no box is ever re-derived from a distribution's mean ± 3σ". Whether the two boxes should be reconciled is an engine decision, tracked in itis-sumo#55.
Note
Engine pin: this behavior ships with itis-sumo==0.1.0a10 (pinned in flaskapi/pyproject.toml). The auto-infer contract above — optional domains/fixed, observed-bounds inference, constant column → fixed factor, uniform draws, and both docstring quotes — was verified against that pin (itis_sumo/api/_session.py in the published 0.1.0a10 wheel), not only against newer a11+ documentation.
Performance is measured continuously with CodSpeed in CPU simulation mode; every pull request gets a report through .github/workflows/codspeed.yml.
- Frontend benchmarks:
node/src/**/*.bench.ts(vitest bench) — job-collection CSV import, sampling bounds, and the session response-cache request key. - Backend benchmarks:
flaskapi/benchmarks/(pytest-codspeed) — the Flask API boundary only (request/response key case conversion on production-shaped payloads, pydantic validation and the Flask JSON round trip). The Dakota data-processing internals will be benchmarked where they live, in itis-sumo; the move is tracked in itis-sumo#56.
Run them locally (requires the CodSpeed CLI):
make bench-flaskapi
make bench-nodeThe backend relies on the osparc package to interact with the oSPARC's API server. If he API server specs change, you would most likley need to create a new release of this service.
Instructions:
Fork https://github.com/ITISFoundation/osparc-simcore-clients and clone your fork locally
cd api
make openapi-osparc-simore-master-branch
git commit -am "updated specs form osparc-simcore master branch"Push your changes and create a PR which needs to be merged.
After the PR is merged, the CI will automatically publish a new version of this client which can be found here https://pypi.org/project/osparc/0.8.3.post0.dev27/#history
Get the latest version and repalce it in falskapi/Dockerfile. At the time of writing this it was osparc==0.8.3.post0.dev27.