Skip to content

Contracts

What each query of the engine (crates/llevant) guarantees, and the tests that hold it to that. A change that breaks one of these is a bug, unless this page changes with it. The semantics themselves (what a cell is, the problem box, lattices) come from MCNP and are checked against it by mcnp-oracle (docs/internals/engine.md, "Checks"); the deliberate departures are in docs/internals/engine.md, "Deliberate semantics".

The reference for the fast paths is llevant::reference: brute force, every cell of each universe a candidate, with no boxes, BVH or octrees.

Query Guarantee Enforced by
Model::classify(points, depth) Exactly the labels of reference::classify, for any GridMode, with or without residual programs, at every Depth. tests/properties.rs (fast_path_equals_brute_force, octree_path_equals_brute_force), tests/levels.rs (points_to_a_level), tests/submodel.rs, tests/big_model.rs (ignored; reference model), llevant-bench verify
The cell MCNP reports for the golden points of the zoo models. tests/mcnp_golden.rs; mcnp-oracle check regenerates them
Model::trace(lines, depth) Agrees with reference::trace as reference::traces_agree says: segment by segment the same labels, ends within the tolerance. Where several surfaces lie within the tolerance of an end, which one is named may differ, and on-surface slivers up to 1e-6 cm may appear in one and not the other. tests/properties.rs (tracing_equals_brute_force_and_points, tracing_with_octrees_equals_brute_force_and_points), tests/levels.rs (tracing_to_a_level), tests/mcnp_golden.rs, tests/big_model.rs, llevant-bench compare-trace (octrees on vs off)
Segments cover [t_min, t_max] without gaps between them; a point inside a segment classifies to its label, except on-surface where the line runs within the tolerance of a surface. tests/tracing.rs (segments_cover_the_line_with_exact_ends, segment_labels_match_point_labels), the property tests above
Model::first_hits(rays, vis, skip) The first visible segment trace gives: the same label and surface, t within the tolerance (a ray traced in windows can round a crossing one ULP away). With a Skip built for the same visibility, the same hits as without it. With ghosts, the ghost record of each ray is the boundaries trace crosses before the hit, the first named as the GPU names it; with veils, which gaps and overlaps shown come before it. tests/properties.rs (first_hit_is_the_first_visible_segment, skipped_first_hits_are_the_first_hits), tests/levels.rs (with ghosts and veils, at levels), tests/hits.rs, tests/big_model.rs
Model::slice, Model::render, Model::pixel_hits A slice pixel holds the label of the point at its centre; a render pixel is the first hit of the camera's ray through it. Cutaways only remove what they say. tests/views.rs
Rules by label (label, $) The cells whose $ comments (not c lines, not FCn text) contain the text, any case; the same cells from a model read from the cache (labels read from the input); an error, not an empty set, when no labels were given. Rules round-trip through their text. llevant-scene (labels, query, hiding tests), tests/cli.rs (label_rules), tests/test_api.py (test_label_rules), the viewer's labels_select_and_isolate
Visibility::problem_cells First hits show a gap or problem only where it belongs to a masked cell (Visibility::owns_problem), and are otherwise what tracing says (random masks among the random visibilities). tests/levels.rs (first_hits_at_a_level_with_ghosts), tests/hits.rs (problem_cells_keep_only_their_problems), llevant-scene hiding tests
Bounding boxes (cells, nodes, problem box) Conservative: padded outward; a failed refinement keeps the previous box. A box that cut into its cell would change labels, which the fast-path tests above would catch. bbox.rs unit tests, the fast-path tests
Every query Results are identical for any number of threads. tests/properties.rs (results_do_not_depend_on_thread_count, tracing_does_not_depend_on_thread_count), tests/volumes.rs, tests/fingerprints.rs (precision_and_threads), llevant-bench trace (one thread vs all)
Bad arguments An Error, never a panic: non-finite lines, non-unit directions, a visibility of the wrong size, degenerate cameras and grids, missing files. tests/errors.rs
Model::placed_boxes Every point of a cell, at every level, is inside one of its instances' boxes (TRCL fills, lattices, level 0); each cell once, in the order asked. tests/volumes.rs (placed_boxes_hold_every_point_of_their_cells), llevant-scene bounds tests, tests/cli.rs (bbox_and_isolated_framing)
Model::cells_kept (the viewer's shown rule) Conservative: a cell with any point, at any level, that the cutaway does not remove is kept (planes, wedges, kept and removed boxes; TRCL fills, lattices); a cell wholly cut away by its boxes is not. tests/volumes.rs (cells_kept_by_cuts), the viewer's shown_rule_follows_the_view
Model::volumes_within, instance_boxes Over the whole region as one box, the same volumes as volumes; within a cell's instance boxes, the cell's whole volume and the problems the whole check finds there (rotated fills and lattices too). tests/volumes.rs (a_check_within_boxes_finds_what_the_whole_check_finds_there, instance_boxes_cover_every_instance)
Model::volumes, volumes_to, instance_volumes Deterministic for a given grid. The standard error is honest (the exact volume is within a few sigma at the rate a normal distribution says). Gaps and overlaps planted in a model are found. Progress is reported and cancelling stops the call with Error::Cancelled. tests/volumes.rs (sigma_is_an_honest_standard_error, planted_gaps_and_overlaps_are_found, volumes_do_not_depend_on_thread_count), tests/errors.rs
Model::fingerprints The same for inputs that compile to the same geometry (renumbering, card order, equivalent rewritings); different for any change, and only for the cells that contain it. tests/fingerprints.rs
Model::instances Every place a cell occupies has one id; ids and paths map to each other; the instance of a point's label is its path's. tests/instances.rs
Model::universe A universe opened on its own answers as brute force does on it, and as the whole model does inside it. tests/submodel.rs
Model::save / Model::read A model read back answers exactly as the compiled one. Bytes with another magic, format version or engine build, or cut short, are refused with Error::Format. tests/saved.rs
Model::compile_staged / Model::complete A staged model (octrees pending) answers as the complete one: the same labels for points, traces that agree. Completing it gives a model whose saved bytes are exactly those of Model::compile, in every GridMode. A staged model cannot be saved. tests/staged.rs
Model::recompile A model recompiled from an older one (complete or staged) and then completed saves exactly the bytes of Model::compile of the new input, for any edit (surfaces, transforms, cells added, removed or renumbered, fills). An unchanged input reuses every universe; other Options reuse none. tests/recompile.rs; the reference model in tests/big_model.rs (--ignored)
Draft::set, Draft::snapshot After any sequence of steps, the draft's model classifies points exactly as reference::classify of a fresh compile of the edited input, its traces agree with that compile's (reference::traces_agree), and its cell boxes contain that compile's. It cannot be saved. A refused step changes nothing. Draft::begin refuses what it cannot follow, with the reason. A draft of a universe cut out on its own answers as that universe cut, to the same box, from a fresh compile. tests/draft.rs
GpuModel::patch A draft's patch written into its base's upload renders as an upload of a fresh compile of the edited input (with the skip widened by Draft::widen_skip). The revert patch gives back the base, and the shader stays the same. llevant-gpu/tests/draft.rs
export (format EXPORT_VERSION) Indices, programs and boxes as the module documents them; any change to the layout or meaning raises the version, and llevant-gpu refuses to build against another one. the compile-time check in llevant-gpu, llevant-gpu tests

The command line's output

Output Guarantee Enforced by
--format json A label, a surface and a box have one shape in every command (crates/llevant-cli/src/json.rs, the fields of Python's Label and Surface; docs/guide/cli.md, "Scripting and agents"): numbers are numbers, none is null. tests/cli.rs (json_outputs_share_one_vocabulary)
trace --lines Each line traced as a single --from/--to run traces it. tests/cli.rs (trace_many_lines)
Exit status 1 when the answer is "no" (check found problems, volume --rel-sigma fell short, bbox found nothing, fingerprint --diff found differences); 2 on errors, which with JSON output are also {"error": ...} on stdout. tests/cli.rs (check_finds_the_one_real_overlap_of_the_zoo, bad_arguments_are_errors, trace_many_lines, fingerprint_diff_as_json, stdin_and_json_errors)

The GPU renderer

llevant-gpu is approximate by design (f32, a bounded number of steps): it is held to agreement with Model::first_hits, not to equality. tests/vs_cpu.rs and llevant-bench gpu-check <model> 150 compare ray by ray over nine views and report the share of pixels whose cell differs and where; the thresholds are in those tests (docs/internals/rendering.md). Gaps seen through (veils) are held to the CPU's on a model with holes at every level, with octrees and BVHs (gaps_seen_through); rays that meet an overlap, stopping at it or seeing through it, are not compared.

Editing the input

llevant_scene::source::Source keeps an input's migjorn tree and changes one card of it in place (Source::edit; edit_card on text): every other byte stays as written (the comment lines just above a card are part of its text), and the cards and lines it gives after edits are those of a parse of the text (source.rs tests). An edit that cannot be made (no such card, one in a READ file, text that does not read as a card of that kind, a line over 128 columns) is an error and changes nothing; restore and redo take an edit back and make it again exactly. The viewer compiles an edit with Model::recompile_parsed from the tree, which gives the bytes of Model::compile of its text (tests/recompile.rs, tests/big_model.rs), so the model shown after it is the one compile would give; the app test cards_edited_undone_and_saved edits, takes back, saves, edits from the inspector, edits a TRn card and saves as. A drag in the inspector (surfaces_dragged_live) has these guarantees:

  • each step is previewed by a draft;
  • the release writes the card through Source::surface_with_coeffs (migjorn's set_coeffs: everything else as written) and compiles it as any edit;
  • a drag cancelled, or taken back to where it began, edits nothing and shows the model again.

Cards edited by fields (Source::cell_with, material_with, surface_retyped) are changed by migjorn on the card alone, so only the words changed differ and the input itself is touched only by the edit that follows (source/fields.rs tests, with the app test cell_fields_edited: a parameter added leaves the rest of the card byte for byte). A geometry with as many terms keeps the card's line breaks; any other is written again within 128 columns (geometry_written_term_by_term). Many cards are written as one edit with Source::edit_many (all or none: on an error the cards written are put back) and taken back with restore_all; cells_with gives the cards of many cells with the same changes (many_cards_all_or_none, cell_changes_keep_the_card). Source::renumber changes numbers in every card that uses them through migjorn's renumber, and records each card it changed, before and after: it snapshots the cards in which one of the old numbers appears as a run of digits (every card a renumbering can change), so restore_all gives the input back byte for byte (numbers_changed_everywhere_and_taken_back). Numbers in use, numbers not defined, two cells given one number and numbers outside MCNP's range are refused and change nothing (renumbering_refused). The app test cells_edited_together edits three cells from the selection, takes it back with one Undo, renumbers two and takes that back to the same text. Model::point_in_unit gives a point in the frame of a universe through the fills above it (tests/surfaces.rs), which the slice's marks of a cell's surfaces use (marks.rs test: a sphere's trace within a grid step of it). The cell as edited is compiled alone from Source::cell_alone (cells_alone_for_the_preview) and asked with Model::cell_holds, its own program in its universe's frame (tests/surfaces.rs); the marks.rs test finds the edge of a moved cell within a grid step, and the app test cell_geometry_edited waits for it on the slice before Apply, and for its shell traced for the 3D view. Model::unit_frame gives the same map as a transform and Model::shape_record a surface written in the problem's frame through it (points_in_a_universe_frame); the 3D view's marks pass (view3d/edits.rs) draws a marked plane within a pixel or two of where it cuts the faces seen, lays a shell with its outline over them, and leaves the image unchanged, pixel for pixel, when nothing is marked (tests/images.rs, edit_marks_drawn). Source::add_card adds a card at the end of its block, with one more value in each data card given per cell, and restore_all takes it out (found by its number) and gives the input back byte for byte; a number in use, or a card that does not read, changes nothing (cards_added_and_taken_out). Source::cell_cut refuses cells with a TRCL or LIKE (cells_cut). The app test new_cards_added adds a surface and a cell inside it cut out of the cell around, finds the point in the new cell, and takes both back to the same text. A surface moved in the inspector writes nothing until Apply (surfaces_dragged_live: released, the card is as it was and the drag held).

Property tests

The property tests run with a fixed seed in CI and with random seeds nightly (.github/workflows/nightly.yml). A failing seed goes into the test's .proptest-regressions file, so it is replayed from then on.