TSDHN

TSDHN runs tsunami simulations from earthquake source parameters. The repository contains one shared tsdhn simulation engine and CLI for researchers, a FastAPI service, a Procrastinate worker, a SvelteKit web app, and the generated TypeScript API client used by the web server.

Documentation

Area	Docs	Covers
Python engine + CLI	packages/tsdhn	Calculations, runtime paths, model assets, pipeline execution
API service	packages/api	FastAPI routes, service-token auth, worker entry point
Web app	apps/web	SvelteKit app, auth, database, and server-side backend configuration
API client	libs/api-client	OpenAPI schema and generated TypeScript types

Tip

Start with the component README for the package or app you are changing. The root README gives orientation and shared commands; component READMEs carry the exact usage details for their own layer.

Architecture

flowchart LR
    Browser[Browser] --> Web[SvelteKit web app]
    Web -->|server-side Bearer token| API[FastAPI /api/v1]
    API -->|create job + defer task| PG[(Compute Postgres)]
    Worker[Procrastinate worker] -->|claim task + update status| PG
    Worker --> Engine[tsdhn engine]
    CLI[tsdhn CLI] --> Engine
    Engine --> Model[versioned model assets]
    Engine --> Tools[Fortran, GMT, TTT]
    Worker --> MinIO[(MinIO artifacts)]
    Worker --> Jobs[(temporary jobs directory)]
    Web --> DB[(SQLite/libSQL)]

Loading

The browser talks to the SvelteKit app. The SvelteKit server calls the FastAPI backend with BACKEND_SERVICE_TOKEN; that token is never sent to browser code. Long simulations run in the Procrastinate worker, which calls the shared tsdhn engine, updates compute_jobs in Postgres, and writes artifacts and metadata to MinIO.

Quick start

The backend stack is self-hosted because the simulation runtime needs the Fortran/GMT/TTT toolchain. Compose uses the images and Dockerfiles under deploy/. Podman is the default local engine; docker compose works identically and is what CI uses.

Install podman plus the docker-compose-plugin package, then enable the rootless socket once per machine:

systemctl --user enable --now podman.socket

cp .env.example .env
mise run dev-up

Set BACKEND_SERVICE_TOKEN and BETTER_AUTH_SECRET in .env before running the web profile:

mise run dev-web

Rootless containers stop when you log out. Run loginctl enable-linger $(whoami) once if you want the stack to survive logout or reboot.

For local development, install the pinned tools with mise, then install the Python workspace:

mise install
mise run install
mise run test

The repository uses uv for Python packages and Bun for the web workspace. Windows users run the scientific backend under WSL 2; Microsoft documents the setup in the WSL install guide.

Common commands

Command	Purpose
mise run install	Install all Python workspace packages with dev and build groups
mise run test	Run the Python test suite with pytest -n auto
mise run lint	Run Ruff and mypy for Python packages
mise run api	Start the FastAPI service with tsdhn-api
mise run worker	Start the Procrastinate worker with tsdhn-worker
mise run web-dev	Start the SvelteKit dev server
mise run gen-client	Export FastAPI OpenAPI JSON and regenerate TypeScript types
mise run dev-up	Run Postgres, MinIO, libSQL, API, and worker (Podman)
mise run dev-web	Run the backend stack plus the SvelteKit web app
mise run dev-down	Stop the local stack
mise run dev-logs	Follow logs for the local stack

Workspace

picv-2025/
├── apps/
│   └── web/                  # SvelteKit app and server-side web routes
├── deploy/                   # Dockerfiles for toolchain, API, and web images
├── libs/
│   └── api-client/           # Generated TypeScript client from FastAPI OpenAPI
├── model/                    # TSDHN model assets and legacy Fortran sources
├── packages/
│   ├── api/                  # FastAPI compute service and Procrastinate worker
│   └── tsdhn/                # Shared engine, runtime, assets, and CLI
├── scripts/
│   ├── export_openapi.py     # FastAPI schema export
│   └── gen-client.ts         # OpenAPI TypeScript generation
├── docker-compose.yml
├── mise.toml                 # Tool versions and repo tasks
├── package.json              # Bun workspaces for apps/* and libs/*
├── pyproject.toml            # uv workspace for packages/*
└── uv.lock

Runtime notes

tsdhn validates model and tool paths before running simulations. Non-container backend runs need:

• TSDHN_MODEL_DIR pointing at the model asset directory.
• TSDHN_TOOLS_DIR pointing at prebuilt fault_plane, deform, and tsunami executables when command pipeline steps are active.
• TSDHN_JOBS_DIR for temporary simulation workspaces when running the API worker.

The API container image sets these paths to /app/model, /app/tools, and /app/jobs.

Scientific runtime dependencies for non-container backend runs

The containerized path is the maintained setup for the backend runtime. Non-container runs must provide the same external tools:

• Intel Fortran compiler (ifx) from Intel oneAPI Fortran Essentials
• Generic Mapping Tools
• Ghostscript (gs), required by PyGMT when finalizing plots
• TTT SDK, including ttt_client
• ps2eps and csh

License

This project is licensed under the terms declared in pyproject.toml.