StreamsML

StreamsML is a control, modeling, and analysis platform for compressible flow simulations built around the STREAmS solver and a Python/Gymnasium interface. It extends STREAmS with a customizable jet actuator and a workflow for testing control, reduced-order modeling, and analysis methods on high-speed boundary-layer and shock/boundary-layer-interaction simulations.

What StreamsML is for

StreamsML was built to make high-fidelity flow-control experiments more reproducible and easier to modify. It provides a structured environment for:

• running boundary-layer (BL) and shock/boundary-layer-interaction (SBLI) simulations,
• testing open-loop, classical, and learning-based control methods,
• applying reduced-order modeling methods such as POD, DMD, and DMDc, and
• generating analysis and visualization outputs from simulation results.

Repository structure

• streams/ — solver-side code, Python interface, control/modeling/analysis modules, and simulation assets
• streams-utils/ — build, configuration, and execution utilities
• install_dependencies.sh — environment bootstrap script
• README.md — overview and quick-start instructions
• rust-toolchain.toml — Rust toolchain pinning for the utilities

Quick start

For detailed usage beyond a standard run, see the detailed user instructions (PDF).

All commands below are run from the streams-utils/ directory unless noted otherwise.

1. Clone the repository

git clone https://github.com/Fluid-Dynamics-Group/StreamsML.git --depth 1
cd StreamsML

2. Set the required paths

Add the following paths to your shell configuration and reload it:

export STREAMS_DIR="/path/to/your/StreamsML/streams"
export STREAMS_UTILS_DIR="/path/to/your/StreamsML/streams-utils"

For example:

export STREAMS_DIR="/home/username/Desktop/StreamsML/streams"
export STREAMS_UTILS_DIR="/home/username/Desktop/StreamsML/streams-utils"

3. Install dependencies

chmod +x install_dependencies.sh
bash install_dependencies.sh

If Apptainer is not installed successfully by the script, install it separately using the official Apptainer documentation.

4. Build the containerized software stack

From streams-utils/, run:

just nv
just base
just build

This produces the final streams.sif container used to run the software.

Build overview

The build process uses three main layers:

• NVIDIA HPC SDK container — provides the base compiler and CUDA-capable HPC environment
• base.apptainer — installs required software such as Python packages and system dependencies
• build.apptainer — compiles the Fortran and Rust components and assembles the runnable StreamsML environment

Before building, make sure your system satisfies the CUDA/driver requirements for the NVIDIA HPC SDK tag used in this repository, included below:

Configure and run a standard simulation

1. Choose the flow type

In the Justfile, select one of the two flow configurations:

# streams_flow_type := "shock-boundary-layer"
# streams_flow_type := "boundary-layer"

2. Edit the config recipe

The main user interface is the config recipe in the Justfile. This is where you choose:

• simulation parameters,
• control strategy and algorithm,
• actuator settings,
• training and evaluation settings, and
• output/checkpoint locations.

Control strategies are grouped into categories such as open-loop, classical, and learning-based. The README example uses a learning-based DDPG configuration, but the utilities support multiple choices depending on the selected mode.

A shortened example looks like this:

config:
	echo {{config_output}}

	cargo r -- \
		config-generator {{config_output}} {{streams_flow_type}} \
		--steps 6 \
		--reynolds-number 250 \
		--mach-number 2.28 \
		--x-divisions 600 \
		--y-divisions 208 \
		... \
		--use-python \
		learning-based ddpg \
		    --slot-start 100 \
		    --slot-end 149 \
		    --train-episodes 2 \
		    --training-output {{training}} \
		    --eval-episodes 2 \
		    --eval-output {{eval}} \
		    --checkpoint-dir {{checkpoint}}

Use the templates in JustfileExamples/ to quickly assemble valid configurations.

You can also inspect the available flags with:

just help tree

3. Generate the run configuration

just config

4. Launch the simulation

just run

Notes for users

• The README is intentionally a quick-start guide.
• More detailed instructions for modeling, analysis, visualization, and adding new methods are provided in the detailed user instructions (PDF).