flowcast

Fluid and environmental models often start as clear equations and then become slow inner loops once they are embedded in simulations, notebooks, route screening jobs, robotics tools, games, or local planning services.

That creates a practical gap. Teams want fast predictions, portable artifacts, repeatable examples, and visual feedback, but they do not always need a full physics engine in every call site.

That is a surrogate-modeling problem, not just a numerical-methods problem.

flowcast is a Python package and local web app for generating environmental flow-field examples, training compact tree-based surrogate models, evaluating model quality, and exporting ONNX artifacts for local inference.

The default workflow starts from analytical reference solvers, writes CSV feature and label data, trains XGBoost regressors, validates the trained model, and exports portable ONNX files. Generated datasets and trained artifacts stay out of git by default.

It is designed for developers who want a small, inspectable lab for surrogate models before applying the same pattern to larger solvers, measured data, or application-specific simulation workloads.

Quick Start

Install the package in editable mode with the development and ONNX extras:

make install-dev

Run the local dashboard:

make serve

Open:

http://127.0.0.1:8080

The dashboard samples lightweight reference fields directly. It does not need trained models, so it is the fastest way to inspect the plume, wave, and vortex fields.

Build and run the container demo instead:

make demo

The Makefile uses Docker when docker is available and falls back to Podman otherwise.

Sample the reference solvers from the CLI:

make sample

Generate training data for every domain:

SAMPLES=1000 make generate

Train a small smoke model:

ALLOW_LOW_QUALITY=1 make train

Evaluate the trained model against generated reference data:

make evaluate

Export trained models to ONNX and validate ONNX output against the XGBoost model output:

make export-onnx

Run the test suite:

make test

The generated data goes under:

data/

Trained models and exported ONNX files go under:

models/

Both directories are ignored by git except for .gitkeep placeholders.

What It Does

flowcast handles a compact surrogate-modeling workflow:

• Provides analytical reference solvers for simple flow-field examples.
• Serves a local dashboard for interactive field inspection.
• Generates reproducible CSV feature and label data.
• Uses Latin hypercube sampling and domain-focused sampling over bounded parameter ranges.
• Trains XGBoost regressors for single-output and multi-output fields.
• Applies per-domain training configuration, label transforms, and filters.
• Saves model metadata with features, outputs, metrics, transforms, and hyperparameters.
• Evaluates trained models against generated reference data.
• Runs local inference through a Python API or CLI.
• Exports one ONNX file per output for portable local inference.
• Validates exported ONNX files against the trained XGBoost model.
• Writes artifact manifests with hashes for generated model and ONNX files.

The project is intentionally small. It is meant to make the surrogate-modeling loop inspectable before a team applies the same pattern to larger solvers or real measured data.

Surrogate Models and ONNX

The reference solver remains the source of labeled examples. The surrogate model is a fast approximation over bounded input ranges. For each domain, flowcast records the original feature names, internal model feature names, output names, target transforms, training metrics, and artifact hashes.

ONNX export is treated as a deployable artifact path, not just a file conversion step. The exporter writes model metadata, exports one ONNX file per output, and compares ONNX Runtime predictions with the source XGBoost model on generated reference rows.

Public background:

• XGBoost
• ONNX
• ONNX Runtime
• scikit-learn

Typical Pattern

Browser dashboard or CLI
        |
        | samples
        v
 Analytical reference solver
        |
        | generated parameter sweep
        v
 CSV features and labels
        |
        | train and evaluate
        v
 XGBoost surrogate model
        |
        | export and validate
        v
 ONNX model artifact
        |
        | local inference
        v
 application, simulation, visualization, or notebook

For local development:

flowcast repo
  Python package
  analytical solvers
  local dashboard
  generated data in data/
  trained models in models/
  tests and examples

For a downstream application:

application
  ONNX Runtime
  flowcast model metadata
  one or more exported ONNX files
  input validation for the trained feature ranges

Dashboard

The dashboard is a local tool for exploring flow fields before training a surrogate.

• Plume: downwind concentration footprint.
• Wave: velocity magnitude and vector direction for a simple wave/current field.
• Vortex: compact vortex velocity magnitude and vector direction.

The browser calls the Python HTTP server. The server owns the reference solvers and field sampling logic.

Run it:

make serve

Use a different local port:

ADDR=127.0.0.1:5082 make serve

Then open:

http://127.0.0.1:5082

Flow Fields

Plume

The plume example estimates concentration over a crosswind slice using a simple Gaussian plume equation.

Features:

emission_rate, stability, wind_speed, y, z, dist_from_center,
abs_y, y_norm, z_norm, norm_radius_sq,
log_emission_rate, log_stability, log_wind_speed

Output:

concentration

Wave

The wave example estimates linear-wave orbital velocity plus a steady current.

Features:

wave_height, wavelength, current_speed, depth, x, y, z, sin_phase, cos_phase

Outputs:

velocity_u, velocity_v, velocity_w

Vortex

The vortex example estimates a compact Gaussian vortex velocity field.

Features:

strength, radius, x, y, dist_from_center, sin_theta, cos_theta

Outputs:

velocity_u, velocity_v

Model Quality

The default training configuration lives at:

config/flowcast.yaml

Default gates:

Domain	Quality Metric	Default Gate	Transform and Filtering
plume	transformed_r_squared	0.95	log transform, labels at or below 1e-8 filtered
wave	r_squared	0.98	no target transform
vortex	r_squared	0.95	no target transform

The plume field spans a large dynamic range. The training path uses a log target transform, filters near-zero labels, adds normalized plume-shape features, and uses focused sampling near the plume core so the model learns meaningful plume shape instead of spending most of its capacity on values that are effectively zero.

Small smoke datasets are useful for checking the workflow, not for judging model quality. Use larger sample counts before treating the metrics as useful:

SAMPLES=10000 make generate
make train
make evaluate

Use the smoke override only when you want to verify plumbing with too little data:

ALLOW_LOW_QUALITY=1 SAMPLES=200 make generate train evaluate

CLI

The flowcast command is the package entrypoint. Running through python -m flowcast uses the same implementation.

Sample a plume point:

python -m flowcast sample plume \
  --emission-rate 2 \
  --stability 0.8 \
  --wind-speed 5 \
  --y 10 \
  --z 8

Generate wave data:

python -m flowcast generate --domain wave --samples 10000

Train a vortex model:

python -m flowcast train --domain vortex

Evaluate a trained model:

python -m flowcast evaluate --domain vortex

Run local model inference:

python -m flowcast predict \
  --domain vortex \
  --features 'strength=6,radius=15,x=8,y=5,dist_from_center=9.43,sin_theta=0.53,cos_theta=0.85'

Export all trained models to ONNX:

python -m flowcast export-onnx --domain all

Run the dashboard:

python -m flowcast serve --addr 127.0.0.1:8080

HTTP API

The local server exposes JSON routes for the dashboard and for integration smokes:

GET   /api/health
GET   /api/domains
POST  /api/sample
POST  /api/grid

Health check:

curl http://127.0.0.1:8080/api/health

Sample a point:

curl -s http://127.0.0.1:8080/api/sample \
  -H 'Content-Type: application/json' \
  -d '{"domain":"vortex","params":{"strength":6,"radius":15,"x":8,"y":5}}'

Generate a compact field grid:

curl -s http://127.0.0.1:8080/api/grid \
  -H 'Content-Type: application/json' \
  -d '{"domain":"plume","width":40,"height":30,"params":{"emission_rate":2,"stability":0.8,"wind_speed":5}}'

The API is local-lab oriented today. Production use would need authentication, authorization, audit logging, TLS, rate limits, and deployment-specific model policy.

Configuration

The Makefile defaults are:

PYTHON=python3
PYTHONPATH=src
SAMPLES=10000
DOMAIN=all
DATA_DIR=data
MODELS_DIR=models
CONFIG=config/flowcast.yaml
ADDR=127.0.0.1:8080

Generate only one domain:

DOMAIN=wave SAMPLES=5000 make generate

Train only one domain:

DOMAIN=vortex make train

Use separate generated-data and model directories:

DATA_DIR=/tmp/flowcast-data MODELS_DIR=/tmp/flowcast-models make generate train evaluate

What You Can Build With It

Environmental Visualization Demo

Use the plume field to show how an analytical reference model can become an interactive visualization and a portable inference artifact.

Water Motion Prototype

Use the wave model to generate fast local velocity estimates for visualizations, robotics tests, or educational notebooks.

Flow-Field Inference Lab

Use the vortex model to test ONNX inference paths against known vector-field behavior before replacing the reference solver with a larger one.

Surrogate Model Template

Use the project structure as a template for turning another deterministic solver into generated training data, a trained regressor, and an ONNX artifact.

What an Integration Needs

For a flowcast-style integration, the deployment needs:

1. A reference solver or trusted source of labeled samples.
2. Bounded input ranges that describe where the surrogate is valid.
3. Generated feature and label data.
4. A training configuration with quality gates.
5. Exported model artifacts, metadata, and hashes.
6. Runtime checks that reject inputs outside the trained range.
7. Monitoring that compares surrogate output with trusted reference data over time.

The surrogate should be treated as an approximation. The reference solver or measured data remains the source of truth.

What It Is Not

flowcast is not a CFD solver, weather model, hydrodynamics package, air quality compliance tool, or replacement for validated scientific software.

That is intentional.

It is a focused surrogate-modeling lab. It shows how small analytical models can produce training data, metrics, model artifacts, and a local dashboard in a way that is easy to inspect and repeat.

Main Files

• src/flowcast/solvers.py: analytical reference solvers.
• src/flowcast/fields.py: field sampling API used by the dashboard.
• src/flowcast/server.py: local HTTP API and static dashboard server.
• src/flowcast/generate.py: CSV data generation.
• src/flowcast/train.py: XGBoost training and model metadata.
• src/flowcast/evaluate.py: trained-model evaluation.
• src/flowcast/predict.py: local XGBoost and ONNX inference helpers.
• src/flowcast/export_onnx.py: ONNX export and validation.
• src/flowcast/cli.py: command-line entrypoint.
• src/flowcast/static/: local dashboard assets.
• config/flowcast.yaml: default model-quality and training configuration.
• tests/: unit, CLI, field API, training, and optional ONNX tests.
• examples/quickstart.sh: small sampling script.
• data/: ignored generated datasets.
• models/: ignored trained models and ONNX files.

Verification

Run the unit tests:

make test

Run the example solver samples:

make sample

Run a small end-to-end smoke workflow:

SAMPLES=200 make generate
ALLOW_LOW_QUALITY=1 make train
make evaluate
make export-onnx

Run the dashboard smoke:

make serve

The optional training and ONNX tests are skipped when the optional ML stack is not installed. Install the full local development set with:

make install-dev

Container

Build the default image:

make container-build

Build and run the local dashboard demo:

make demo

Run with Docker explicitly:

CONTAINER_RUNTIME=docker make demo

Run with Podman explicitly:

CONTAINER_RUNTIME=podman make demo

Use a different local port:

PORT=5082 make demo

Then open:

http://127.0.0.1:5082

The Makefile defaults are:

CONTAINER_RUNTIME=docker when available, otherwise podman
CONTAINER_BUILD_FLAGS=empty for Docker, --pull=missing for Podman
IMAGE=flowcast:latest
CONTAINER_NAME=flowcast-demo
HOST=127.0.0.1
PORT=8080

Tested Environments

flowcast is expected to run on standard Python-supported Unix-like systems. The local workflow is intended for:

• macOS with Python 3.10 or newer.
• Linux with Python 3.10 or newer.
• CPU-only XGBoost training for small generated datasets.
• ONNX Runtime CPU inference in downstream applications.

The dashboard is plain HTML, CSS, and JavaScript served by the Python package.

Security

This repository is intended for transparent examples, repeatable local tests, and surrogate-modeling integration work.

Do not commit private datasets, sensitive measurements, proprietary solver outputs, production model artifacts, API tokens, or deployment-specific policy.

For production use, add authentication, authorization, audit logging, rate limits, TLS, input range enforcement, model provenance, artifact signing, model registry policy, monitoring, and domain-specific validation against trusted reference data.

License

Apache License 2.0. See LICENSE.

Summary

flowcast makes small ONNX surrogate models concrete.

It gives developers one place to visualize environmental flow examples, generate training data, train compact regressors, evaluate model quality, export ONNX artifacts, and test the pattern before applying it to larger simulation or environmental workloads.