Construct the sequence portion of an initial design

Constructs random sequences, or searches for a sequence design with balanced ordered adjacent pairs and well-separated rows using simulated annealing or space-filling threshold accepting (SFTA). A neighbor is generated by selecting one design row and exchanging two component positions, so every candidate remains a valid permutation.

Usage

magp_sequence_design(
  n,
  q,
  pair_weight = 0.2,
  space_weight = 0.8,
  p = 15L,
  maxit = 10000L,
  temp = 0.1,
  tmax = 10L,
  initial = NULL,
  seed = NULL,
  method = c("sann", "random", "sfta"),
  sfta_control = list()
)

Arguments

n: Number of design runs. Must be at least two.
q: Number of components. Must be at least three.
pair_weight: Nonnegative weight for ordered adjacent-pair balance.
space_weight: Nonnegative weight for Hamming-distance space filling.
p: Positive whole-number exponent controlling emphasis on the weakest pair counts and the smallest distances.
maxit: Positive whole number of simulated-annealing iterations, or the total number of Phase-II neighbor proposals for SFTA (across all rounds). Unused by method = "random".
temp: Positive initial temperature passed to stats::optim(). The default is scaled to the sequence-design criterion used here.
tmax: Positive whole number of evaluations at each temperature.
initial: Optional n by q matrix of component positions. Every row must be a permutation of 1:q.
seed: Optional nonnegative whole-number seed. When supplied, the function restores the caller's random-number state before returning.
method: Sequence generation method: "random" samples permutations without optimizing them; "sfta" uses the two-phase search described below; "sann" retains the original simulated annealing and is the default for backward compatibility. With "random", a supplied initial matrix is returned unchanged.
sfta_control: Named list used only with method = "sfta". Positive integer settings are nstarts (default 5 candidate designs in Phase I), ncalibrate (200 trial swaps for threshold calibration), nrounds (min(10, maxit) threshold rounds, at most maxit), and max_proposals (max(1000, 50*n), capped at the integer limit; rejection-sampling budget per Phase-I design). Unknown or duplicated names are errors.

Value

An object of class magp_sequence_design, containing the optimized sequence matrix, the starting matrix, criterion values, and search settings. The sequence matrix is ready to use as the sequence half of a magp input matrix. method_key records the method selector. For SFTA, sfta contains resolved controls, Phase-I criteria and sampling counts, thresholds, accepted moves, best-criterion history, and evaluation counts (including threshold calibration and the final independent check).

Details

This function constructs only the sequence portion of a quantitative- sequence initial design. Use magp_initial_design() to combine it with a quantitative Latin hypercube and improve the pairing of the two portions.

The SFTA option applies threshold accepting to the complete sequence-design criterion returned by magp_sequence_criterion(). It does not require responses and does not change the expected-improvement search used later in Bayesian optimization.

Phase I constructs nstarts complete designs by accepting candidate rows with probability equal to their minimum Hamming distance to already accepted rows divided by q. The best complete design, including the original starting design, enters Phase II. Sampling is bounded; when its budget or all q! permutations are exhausted, remaining rows are sampled uniformly. Repeated sequences are allowed (and unavoidable when n > q!). The diagnostics record these fallback counts.

Phase II swaps two entries of one execution-order row at a time. Thresholds use type-7 empirical quantiles of absolute criterion differences at the fixed Phase-I winner, at probabilities 0.5 * (1 - r/nrounds). The last threshold is explicitly set to zero for a final greedy round; a move is accepted only when its criterion increase is strictly below the threshold. The best visited design is retained, so the result cannot be worse than initial. Adjacent-pair counts and Hamming-distance histograms are updated in C++ after each swap. Sequence columns always contain component positions; execution-order conversion is internal.

temp and tmax only affect "sann". Random generation avoids duplicate rows when n <= q!. Neither optimized method guarantees unique rows or a global optimum.

References

Kirkpatrick, S., Gelatt, C. D., and Vecchi, M. P. (1983). Optimization by Simulated Annealing. Science, 220, 671-680. doi:10.1126/science.220.4598.671 .

Xiao, Q., Wang, Y., Mandal, A., and Deng, X. (2024). Modeling and Active Learning for Experiments with Quantitative-Sequence Factors. Journal of the American Statistical Association. doi:10.1080/01621459.2022.2123335 .

Examples

design <- magp_sequence_design(
  n = 8,
  q = 4,
  maxit = 500,
  seed = 1
)
design$sequence
#>      sequence_1 sequence_2 sequence_3 sequence_4
#> [1,]          4          1          2          3
#> [2,]          3          2          1          4
#> [3,]          1          4          3          2
#> [4,]          1          4          2          3
#> [5,]          3          1          4          2
#> [6,]          1          2          4          3
#> [7,]          4          2          3          1
#> [8,]          3          4          2          1
design$criterion
#> [1] 0.4509175

random <- magp_sequence_design(8, 4, method = "random", seed = 1)
sfta <- magp_sequence_design(
  8, 4, method = "sfta", maxit = 200, seed = 1,
  sfta_control = list(nstarts = 2, ncalibrate = 50)
)
c(random = random$criterion, sfta = sfta$criterion)
#>    random      sfta 
#> 0.4933127 0.4514109