Batch Mode

From BurnSim Wiki
Jump to navigation Jump to search

BurnSim 4 can run a simulation with no window at all: give it a motor file and somewhere to put the results, and it loads the motor, simulates it, writes the burn data as CSV and exits with a status code a script can test. This is how you sweep a parameter, re-run a set of designs after changing a propellant, or check motors from a build script.

It requires an activated personal or commercial license. It is not available on an educational license, or in trial/unlicensed mode.

Which program to run

There are two executables in the install folder, and for anything scripted you want BurnSimCLI.exe.

Program Use it for
BurnSimCLI.exe Scripts, build steps, sweeps - anything where you need to wait for the run or read its exit code. Added in 4.0.0.23.
BurnSim.exe The program itself. It still accepts the same batch options, but a shell will not wait for it (see below).

Both take exactly the same options and produce byte-identical output. BurnSimCLI.exe contains no simulation logic of its own - it starts BurnSim, waits for it, and passes the exit code back - so there is no behaviour to learn twice.

Why there are two programs

BurnSim is a windowed program, and Windows shells do not wait for a windowed program to finish: the prompt comes back immediately. That is fixed in the executable's header when it is built, so BurnSim cannot change it from the inside. BurnSimCLI.exe is a small console-mode launcher that exists purely to be waitable.

Measured on the same motor: BurnSim.exe returned in 49 ms with no exit code set and no CSV yet; BurnSimCLI.exe returned in 414 ms with exit code 0 and the CSV written.

Note what that does not mean. The CSV is never half-written - BurnSim finishes writing it before the process ends. The problem is purely that the shell stopped waiting, so a script that reads the file immediately may find it missing or still absent, not truncated.

BurnSimCLI.exe will not open the window. Given no options, or only a file path, it prints an error and exits 2 rather than launching a GUI that a build agent would then wait on for ever. To open a motor normally, run BurnSim.exe.

Usage

BurnSimCLI -infile <motor.bsx> -outfile <results.csv> [-units metric|imperial]
Option What it does
-infile The .bsx motor file to simulate. Required.
-outfile Where to write the CSV. Required. This is the same time-step table File → Export CSV writes, minus the imported-test-data columns - a batch run has no way to supply a measured trace.
-units metric or imperial. Optional; without it the run uses your saved display-units setting.
-machineid Print this machine's ID and exit. Useful when arranging activation on a machine with no screen.
-help (or -?) Print the usage text and exit.

Both -infile and -outfile must be given. Supplying only one is an error rather than a silent fall-back to opening the window - a typo in one flag would otherwise leave a windowless BurnSim running on a build machine having written nothing.

A bare file path on its own does not trigger batch mode in BurnSim.exe: that is how a double-clicked .bsx arrives, and it still opens normally in the GUI.

Exit codes

Code Meaning
0 Success - the CSV was written.
1 The simulation or file access failed. The input file was missing, or the design has a problem serious enough to stop the run. No CSV is written.
2 A usage error - a missing or unrecognized option, or a -units value that is neither metric nor imperial.
3 The license does not cover batch mode (educational, trial, or unlicensed).

Any design messages BurnSim would have shown in the Results panel are written to standard error, prefixed burnsim:. Warnings do not stop the run; a critical message does, and is the usual reason for exit code 1.

Testing the exit code

In PowerShell, $LASTEXITCODE holds the result of the last external program: 

& "C:\Program Files\BurnSim 4\BurnSimCLI.exe" -infile motor.bsx -outfile results.csv
if ($LASTEXITCODE -ne 0) {
    Write-Error "BurnSim failed with exit code $LASTEXITCODE"
    exit $LASTEXITCODE
}

This is the part that did not work before 4.0.0.23: with BurnSim.exe the shell returns before the run finishes, so $LASTEXITCODE reflects nothing useful.

A worked sweep

Sweeping one dimension means writing one motor file per step and running BurnSim on each. The .bsx format is XML, so a script can edit a single value and save a copy.

This example sweeps nozzle throat diameter and collects the peak pressure from each run: 

$throats = 0.40, 0.45, 0.50, 0.55, 0.60
$cli = "C:\Program Files\BurnSim 4\BurnSimCLI.exe"

foreach ($t in $throats) {
    $xml = [xml](Get-Content motor.bsx)
    $xml.Motor.Nozzle.ThroatDia = "$t"
    $xml.Save("sweep-$t.bsx")

    & $cli -infile "sweep-$t.bsx" -outfile "sweep-$t.csv"
    if ($LASTEXITCODE -ne 0) { Write-Warning "throat $t failed ($LASTEXITCODE)"; continue }

    $peak = (Import-Csv "sweep-$t.csv" | Measure-Object -Property "Pc psi" -Maximum).Maximum
    "{0,5:N2}  {1,8:N0} psi" -f $t, $peak
}

The CSV's columns are Time, Kn, Kn Eff, Pc <unit>, Thrust <unit>, Mass Flux, Mass Flow, Cf, Surface Area, Nozzle Erosion, Erosive Model. Note that the pressure and thrust headings carry their unit - Pc psi in imperial, Pc KPa in metric - so a script that names a column has to agree with the units the run used. Passing -units explicitly is the safe way to be sure.

One caveat worth knowing before you trust a sweep

Batch mode uses the saved settings of the machine it runs on. Sliced (erosive) burning, the slice count and the time step all come from your appsettings.json, not from the motor file and not from the command line. That is deliberate - it is what makes a batch run agree with what you see in the window on the same machine - but it has a consequence worth stating plainly:

The same command, on the same motor file, can produce different numbers on two different machines.

If a sweep has to be reproducible across machines, or checked into a build, make sure the settings match on each one. There is currently no per-run override for these.

See also

Retrieved from "https://wiki.burnsim.com/index.php?title=Batch_Mode&oldid=343"