Performing Parameter Sweeps

CHAMPS+ includes a built-in macro substitution engine that allows you to modify input parameters directly from the command line. This eliminates the need to create dozens of separate .sdf files when performing sensitivity analyses or parameter sweeps (e.g., varying Mach number, Angle of Attack, or Reynolds number).

Variable Substitution Syntax

To parameterize your simulation, you can replace any static value in your input file with a variable placeholder using the syntax $(variable_name).

When the code runs, it looks for these placeholders and replaces them with values provided via the -D command-line flag.

Example: Mach Number Sweep

Consider a standard input file (see the dictionary section for details on this section) for a blunt cone simulation:

Dictionary
{
    Tref     = 100.0
    gamma    = 1.4
    Rgas     = 287.15
    mach     = 6.0              // Static value
    aoa      = 12.5
    umag     = mach*sqrt(gamma*Rgas*Tref)
}

To sweep the Mach number, replace the static value 6.0 with a variable, for example $(mach_input):

Dictionary
{
    // ... constants ...
    mach     = $(mach_input)    // Parameterized value
    // ...
}

Running the Simulation

You can now define mach_input at runtime using the -D flag:

./champs+ input.sdf -Dmach_input=6.0

The engine performs a string substitution before parsing the file. This means derived variables (like umag in the example above) will automatically calculate the correct velocity based on the injected Mach number.

Automating with Scripts

This feature is designed to be used with shell scripts or Python wrappers. Below is a simple Bash example that sweeps Mach numbers from 5 to 8:

#!/bin/bash
for m in 5 6 7 8; do
    echo "Running Mach $m..."
    ./champs+ input.sdf -Dmach_input=$m
done

Managing Output Directories

Preventing Data Overwrite

If you run a sweep as shown above, each simulation will likely write to the default output directory, overwriting the results of the previous run.

To prevent this, you should also parameterize the Output Directory in the IO section of your input file.

1. Modify the IO Section:

Change your output path to use a variable, such as $(out_dir) (see the I/O section):

IO
{
    output_directory = $(out_dir)
    Outputs
    {
        // ... output definitions ...
    }
}

2. Update the Command Line:

Pass a unique directory name for each run. For example:

./champs+ input.sdf -Dmach_input=6.0 -Dout_dir=results_mach_6

Or, in a loop:

for m in 5 6 7 8; do
    ./champs+ input.sdf -Dmach_input=$m -Dout_dir=data/run_mach_$m
done