90 lines
2.9 KiB
Markdown
90 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pip install -e ".[webapp]"
|
|
uvicorn webapp.app:app --reload --host 127.0.0.1 --port 8055
|
|
```
|
|
|
|
## API smoke test
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8055/api/health
|
|
```
|