Adaptive-Barrier-Monitor/webapp.md

Webapp Reference

The web application is a focused Monte Carlo comparison built with FastAPI, vanilla JavaScript, and Plotly.js.

Purpose

For each simulated price path, the backend constructs an adaptive schedule using the current distance to the nearer log-price barrier and the local symmetric-endpoint Brownian-bridge proxy. The fixed baseline has two modes:

1. Equal budget: use exactly the adaptive schedule's sample count on each path, distributed uniformly.
2. Fixed cadence: sample at an independently selected interval in minutes, with the start and end of the window included.

Lower and upper barrier events are evaluated independently. A detection must occur within the configured number of simulation-grid steps and the sampled price must still be beyond the relevant barrier.

Routes

GET /

Serves the single-page frontend and replaces static asset query strings with mtime/size cache-busting values.

GET /api/health

Returns runtime readiness, package version, and default model parameters.

POST /api/simulate

Validated request fields include:

• initial price, annual drift, and annual volatility;
• simulation horizon, number of paths, and grid resolution;
• lower and upper barrier percentages;
• local diffusion parameter eps;
• hard maximum polling interval;
• detection deadline in grid steps;
• comparison mode and fixed cadence in minutes;
• optional Merton jump parameters;
• optional random seed.

The response contains path data, both schedules, direction-specific breach and detection fields, exact sample totals, detection-lag summaries, and an explicit model-scope warning.

Important interpretation

eps is not an unconditional probability guarantee. The exact Brownian bridge formula conditions on two endpoints, whereas an online scheduler does not know the future endpoint. The implementation substitutes the current barrier distance for both endpoint distances. Jumps are outside that diffusion calculation entirely.

The demo therefore presents a controlled scheduling comparison, not a promise that adaptive sampling always outperforms fixed sampling.

Frontend

The interface provides controls for all main simulation and detector parameters. It displays:

• simulated paths and both barriers;
• adaptive observations as open cyan circles;
• equal-budget or fixed-cadence observations as grey dots;
• first lower and upper breach markers;
• direction-specific detection counts;
• exact adaptive/fixed sample totals;
• adaptive and fixed mean detection lags;
• raw run statistics and model-scope warnings.

Pure GBM is the default. Merton jump diffusion is an optional stress mode and triggers an on-screen warning about the limits of the Brownian proxy.

Local development

pip install -e ".[webapp]"
uvicorn webapp.app:app --reload --host 127.0.0.1 --port 8055

API smoke test

curl -s http://127.0.0.1:8055/api/health