DOCS // pyrofx

Report

Every command prints the same JSON report to stdout and writes it to bake_report.json: ok, errors, warnings with a fix key and hint, artifacts and metrics. A failed run still returns a report with ok set to false. Exit codes and error codes are listed under Errors.

Contents4 sections
  1. Fields
  2. Errors
  3. Warnings
  4. Questions

Fields

FieldMeaning
oktrue when the run succeeded. A failed run still returns a report, with ok set to false.
errorsEach error has a code, the key at fault and a message.
warningscode, often where and first_frame, and the fix.key to change with a fix.hint.
artifactsEvery file: kind, width, height, size.
metricsClip metrics: life_s, rise_speed_mps, aspect_at_peak, mean_coverage and loop_seam, plus per-frame lists.
metrics.leftover_divergenceWorst pressure error of any step, as the solve counts it.
metrics.stored_divergenceWorst pressure error at the exported frames: leftover_divergence plus rounding from solver.precision.
metrics.render_redosNumber of frames rendered again. The renderer computes each frame's light volume twice and renders the frame again when the two disagree. After 4 failed tries the bake (the compile) fails (see Errors).

Errors

A failed run still returns a report, with ok set to false and errors filled.

Exit codeMeaning
0Baked. The report may still carry warnings.
1Invalid spec or arguments. The report lists every error.
2Internal failure, reported as GPU_ERROR. This includes a frame whose lighting still disagrees after 4 tries (metrics.render_redos); that bake writes nothing.
3A file could not be read or written.
4This host cannot run bakes.
CodeMeaningFix
SPEC_SYNTAXThe spec is not valid TOMLCorrect the syntax; the message has the line and the parse error
UNKNOWN_SECTIONThe spec has a section the module does not knowUse the nearest valid section named in the message
UNKNOWN_KEYThe spec has a key the module does not knowUse the nearest valid key named in the message
BAD_TYPEA value has the wrong typeGive the type the message asks for
BAD_VALUEA value is not in the allowed set, or is otherwise invalidFollow the message; it lists the allowed values or the rule
OUT_OF_RANGEA number is outside its allowed rangeSet it inside the range the message states
BAD_SETA field override is malformed or points at a missing list entryUse section.key or section.index.key, and make sure the entry exists
BAD_SPEC_NAMEThe spec file name does not end in the module's extensionRename it, for example to .pyro.toml for pyrofx
GRID_TOO_LARGEThe domain needs more cells than the largest grid allowsRaise domain.voxel_m; the message states the minimum
GPU_ERRORA compute job failed, or a frame's lighting disagreed on 4 tries (exit code 2)Read the message and retry
FILE_READA file could not be read, usually the specCheck the path and that the file is readable
FILE_WRITEA file or directory could not be writtenCheck the output path and that it is writable
UNKNOWN_TOOLNo module by that name is registeredUse a name listed in the message
BAD_ARGSArguments are missing or invalidFollow the message
BAD_REQUESTThe request body is not a JSON objectSend a JSON object

Warnings

CodeMeansFirst key to change
DOMAIN_CLIPPINGVisible gas reached a side or the top of the boxdomain.size_m
EMPTY_SIMNothing visible in any frameemitters
TILE_CLIPPINGContent touches the tile edgeviews.margin
NOT_RISINGHot gas that does not climbsolver.buoyancy
FLAT_SHAPEWider than tall, seen side-onsolver.buoyancy
PALE_CORENo flame pixel nears whitelook.exposure
FLAME_CLIPPEDOver a tenth of flame pixels at the encoding limitlook.exposure (lower)
FLAME_NOT_EXPORTEDThere is flame but no sheet carries itexport.channels (add "emissive")
ENDS_VISIBLEA one-shot is still visible on its last framedomain.duration_s
STARTS_FULLA one-shot's first frame is already largeexport.start_s
LOOP_SEAMThe loop's wrap showsexport.loop_blend_frames, export.warmup_s
PRESSURE_LOOSEThe solver missed its accuracy, or 16 bit precision could not hold a tighter onedomain.substeps, or solver.precision = "full"
SEALED_SPACEGas grows in a space it cannot leave (no open side, or a room sealed by obstacles). The growth is removed evenly, like pressure in a closed roomdomain.open_faces, or carve a vent
STEP_TOO_LARGEGas crosses more than about two cells a stepdomain.substeps
COVERAGE_HIGHMean coverage over a half; expensive to drawsolver.smoke_fade
GRID_REDUCEDDraft quality; expectednone

Warnings are advice. Flat or cold elements avoid some through their settings; the examples show how. Ship when warnings is empty.

Questions

What does bake_report.json contain when a pyrofx run fails?

Even on failure, bake_report.json sets ok to false and lists each error code, key at fault and message.

What causes a pyrofx bake to exit with code 2 and GPU_ERROR?

It happens on a compute failure or when a frame's lighting disagrees four times in render_redos.

How do pyrofx warnings help fix issues like DOMAIN_CLIPPING?

Each warning includes a fix.key and fix.hint, such as adjusting domain.size_m when visible gas reaches a box edge.