Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Automate a simulation with a shell script

Use this script when your complete simulation request already exists as JSON and you need to submit it, follow its status, and download its result. For a request constructed in code, use Automate a simulation with Python.

Prepare the shell

Complete Set up API access so VANELLUS_API_KEY is available in your terminal. The script requires curl and jq; ensure both commands are available in your environment.

Download run-simulation.sh beside your request.

Provide your request

Save the complete request as request.json, or pass another JSON path as the first argument. The request itself controls dry_run, streaming, solver settings, and every physical input.

The script does not modify the request. This makes the same JSON suitable for the shell script, dashboard, or another API client.

Run the simulation

Make the script executable and run it:

chmod +x run-simulation.sh
./run-simulation.sh

Pass request and result paths when they differ from the defaults:

./run-simulation.sh enclosure.json enclosure-results.zip

The script refuses to submit if the request is missing or the result file already exists. It then:

  1. submits the JSON request;
  2. prints any API warnings;
  3. polls status until the run finishes;
  4. applies a terminal-state policy; and
  5. downloads the result ZIP.

dry_run, residual_converged, and monitor_converged are treated as normal downloadable outcomes. The script downloads max_iterations_reached and canceled results with a warning, while error, diverged, and killed stop without attempting a download.

Download only the required artifacts

Repeat the items query parameter when a downstream task needs only part of the bundle:

# Download fields, residual history, and the submitted request in one ZIP archive.
curl --fail-with-body --silent --show-error \
  -H "X-API-Key: $VANELLUS_API_KEY" \
  "https://api.vanellus.tech/simulations/$simulation_id/download?items=fluid_vtu&items=iteration_info&items=request" \
  --output "$result_file"

Available selections cover fluid and solid VTU fields, the combined iteration history, and the request. iteration_info.csv contains residuals, monitors, CTM junction temperatures, iteration timings, and linear-solver diagnostics. Every archive also contains simulation_manifest.json.

The fluid and solid VTU fields are usually the largest files in the archive. If you do not need to visualize the fields, leave fluid_vtu and solid_vtu out of the selection to greatly reduce the download size and time for large simulations.

Omit items to download every available artifact, as the main script does.

See also