Fields
| Field | Meaning |
|---|---|
ok | true when the run succeeded. A failed run still returns a report, with ok set to false. |
errors | Each error has a code, the key at fault and a message. |
warnings | code, often where and first_frame, and the fix.key to change with a fix.hint. |
artifacts | Every file: kind, width, height, size. |
metrics | Clip metrics: life_s, rise_speed_mps, aspect_at_peak, mean_coverage and loop_seam, plus per-frame lists. |
metrics.leftover_divergence | Worst pressure error of any step, as the solve counts it. |
metrics.stored_divergence | Worst pressure error at the exported frames: leftover_divergence plus rounding from solver.precision. |
metrics.render_redos | Number 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 code | Meaning |
|---|---|
0 | Baked. The report may still carry warnings. |
1 | Invalid spec or arguments. The report lists every error. |
2 | Internal failure, reported as GPU_ERROR. This includes a frame whose lighting still disagrees after 4 tries (metrics.render_redos); that bake writes nothing. |
3 | A file could not be read or written. |
4 | This host cannot run bakes. |
| Code | Meaning | Fix |
|---|---|---|
SPEC_SYNTAX | The spec is not valid TOML | Correct the syntax; the message has the line and the parse error |
UNKNOWN_SECTION | The spec has a section the module does not know | Use the nearest valid section named in the message |
UNKNOWN_KEY | The spec has a key the module does not know | Use the nearest valid key named in the message |
BAD_TYPE | A value has the wrong type | Give the type the message asks for |
BAD_VALUE | A value is not in the allowed set, or is otherwise invalid | Follow the message; it lists the allowed values or the rule |
OUT_OF_RANGE | A number is outside its allowed range | Set it inside the range the message states |
BAD_SET | A field override is malformed or points at a missing list entry | Use section.key or section.index.key, and make sure the entry exists |
BAD_SPEC_NAME | The spec file name does not end in the module's extension | Rename it, for example to .pyro.toml for pyrofx |
GRID_TOO_LARGE | The domain needs more cells than the largest grid allows | Raise domain.voxel_m; the message states the minimum |
GPU_ERROR | A compute job failed, or a frame's lighting disagreed on 4 tries (exit code 2) | Read the message and retry |
FILE_READ | A file could not be read, usually the spec | Check the path and that the file is readable |
FILE_WRITE | A file or directory could not be written | Check the output path and that it is writable |
UNKNOWN_TOOL | No module by that name is registered | Use a name listed in the message |
BAD_ARGS | Arguments are missing or invalid | Follow the message |
BAD_REQUEST | The request body is not a JSON object | Send a JSON object |
Warnings
| Code | Means | First key to change |
|---|---|---|
DOMAIN_CLIPPING | Visible gas reached a side or the top of the box | domain.size_m |
EMPTY_SIM | Nothing visible in any frame | emitters |
TILE_CLIPPING | Content touches the tile edge | views.margin |
NOT_RISING | Hot gas that does not climb | solver.buoyancy |
FLAT_SHAPE | Wider than tall, seen side-on | solver.buoyancy |
PALE_CORE | No flame pixel nears white | look.exposure |
FLAME_CLIPPED | Over a tenth of flame pixels at the encoding limit | look.exposure (lower) |
FLAME_NOT_EXPORTED | There is flame but no sheet carries it | export.channels (add "emissive") |
ENDS_VISIBLE | A one-shot is still visible on its last frame | domain.duration_s |
STARTS_FULL | A one-shot's first frame is already large | export.start_s |
LOOP_SEAM | The loop's wrap shows | export.loop_blend_frames, export.warmup_s |
PRESSURE_LOOSE | The solver missed its accuracy, or 16 bit precision could not hold a tighter one | domain.substeps, or solver.precision = "full" |
SEALED_SPACE | Gas 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 room | domain.open_faces, or carve a vent |
STEP_TOO_LARGE | Gas crosses more than about two cells a step | domain.substeps |
COVERAGE_HIGH | Mean coverage over a half; expensive to draw | solver.smoke_fade |
GRID_REDUCED | Draft quality; expected | none |
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.