Derives the per-task primer – a length-2 integer vector – from
rlang::hash(params), suitable for the stream argument of
dqrng::dqset.seed(). Together with the scenario seed, the primer fully
specifies a task's RNG starting point:
dqrng::dqset.seed(seed, stream = task_primer(params)). It pairs with
local_dqrng_state(), which installs the (seed, primer) pair under an
active local_dqrng_backend() scope.
Value
An integer vector of length 2 – the per-task primer – to pass as
the stream argument of dqrng::dqset.seed() (via local_dqrng_state()).
Details
The primer packs 64 bits of the rlang::hash() digest (xxhash128) as
c(hi32, lo32). Each 32-bit half is encoded as a signed int32, with the
reserved bit pattern 0x80000000 (INT_MIN, which R cannot represent as a
non-NA integer) mapped to NA_integer_; dqrng accepts NA_integer_ in
stream and treats it as INT_MIN, so the encoding recovers the full 64 bits
of stream entropy.
params may be a plain named list or a single-row data frame (one row of a
{sample,fit,hc}_tasks table). A data-frame row is normalised to a
canonical plain list – the inverse of tibble::tibble_row() – by dropping
all attributes, unwrapping length-1 list-style columns to their element, and
leaving df-style (nested data-frame) columns as data frames, before hashing.
The primer is therefore identical whether derived from the row or from the
equivalent plain list. Note that rlang::hash() is order-sensitive, so the
plain list must use the same name order as the task-table columns to
reproduce the row's primer (assembling params in a canonical column order
is part of the task-tables caller contract below).
task_primer() normalises structure, not meaning: it hashes whatever
params it is given. The canonical, name-keyed representation is a caller
contract assembled where params is built (task-tables, over the
task-lists tables). Per the three-step model the RNG-consuming steps each
take a primer over their task identity:
sample – keyed
(dataset, sim, replace)only.nrowis deliberately absent: everynrowshares onen_max-row draw that thefitstep truncates inline (head(sample, nrow), RNG-free, no separate primer), so excludingnrowis load-bearing for the sub-truncation property (TARGETS-DESIGN.md§5).fit – the parent
sampleidentity plusnrowand the fit-grid row (rescale,computable,at_boundary_ok,min_pmixname,range_shape1,range_shape2).nrowIS part of the fit primer: a fit on a different truncation is a genuinely different computation.hc – the parent
fitidentity plus the hc-grid row (ci,nboot,est_method,ci_method,parametric).
Function-valued parameters (e.g. min_pmix) MUST be referenced by name,
not by function value, so a recompile or JIT does not move a task's primer.
Examples
task_primer(list(dataset = "boron", sim = 1L, replace = FALSE))
#> [1] -310630442 -782239665