Getting Started with npRmpi

This vignette is intentionally conservative. The goal is to provide a package-side overview of the modern npRmpi workflow without making routine vignette builds depend on live MPI startup.

The full install matrix, platform-specific notes, and longer mode comparisons belong on the gallery site rather than in a shipped package vignette:

The main practical point is simple: on platforms where spawning is supported, the recommended interactive route is now session mode (the spawn code path), where the estimator calls look like ordinary np code once MPI has been initialized with npRmpi.init(nslaves = ...).

Which mode should I use?

Use session / spawn for ordinary interactive work on platforms where spawning is supported.
Use attach when the MPI world is already launched with mpiexec and you still want npRmpi.init(mode = "attach") to manage the worker loop.
Use profile / manual-broadcast mode when startup and broadcast logic need to be explicit, especially on larger or heterogeneous clusters.

For teaching and troubleshooting, it is usually better to be explicit than to rely on mode = "auto".

Recommended starting point: session mode

library(npRmpi)

npRmpi.init(nslaves = 1)

set.seed(1)
x <- runif(200)
y <- sin(2 * pi * x) + rnorm(200, sd = 0.2)

bw <- npregbw(y ~ x, regtype = "ll", bwmethod = "cv.ls")
fit <- npreg(bws = bw)
summary(fit)

new_points <- data.frame(x = c(0.25, 0.5, 0.75))
predict(fit, newdata = new_points)

# Reuse the bandwidth: no second bandwidth search is performed.
fit_inference <- npreg(bws = fit$bws, gradients = TRUE, se = TRUE)
head(se(fit_inference))
head(gradients(fit_inference))
head(gradients(fit_inference, se = TRUE))
prediction <- predict(fit, newdata = new_points, se.fit = TRUE)
prediction$fit
prediction$se.fit

npRmpi.quit()

The examples in this vignette are alternative session layouts, not one script to concatenate after MPI has finalized. Keep the original training data available when refitting or predicting with a retained bandwidth object.

Uncertainty and migration from 0.70-5

Statistical requests follow the same conventions as np:

Request	Purpose
`se = TRUE` in an estimator call	Compute its supported fit-time uncertainty.
`gradients = TRUE` in an estimator call	Compute supported derivatives or categorical contrasts. Add `se = TRUE` for their standard errors.
`se(fit)` or `gradients(fit, se = TRUE)`	Read stored standard errors; do not refit or repeat search.
`predict(fit, newdata = ..., se.fit = TRUE)`	Evaluate predictions and their supported standard errors.
`vcov(fit)`	Read coefficient covariance for families such as `npindex` and `npplreg`, not a universal covariance of the fitted surface.
`plot(fit, errors = "bootstrap")` or `errors = "asymptotic"`	Request plot-time uncertainty through that family’s plot method.

Fit-time standard errors are opt-in across the principal families. The intentional exception is npindex, whose default se = TRUE, se.type = "asymptotic" includes coefficient covariance; se = FALSE requests a point-only fit. Gradients remain a separate request. The example above shows the no-search refit used when stored results are absent.

Consult each estimator’s help for supported kernels, bandwidth types and derivative orders. Missing stored uncertainty, unsupported inference and an undefined evaluation row are different conditions; do not interpret NA as zero uncertainty. Asymptotic results condition on the selected smoothing settings, without bandwidth or polynomial-degree selection uncertainty. Supported plot targets provide asymptotic simultaneous variability bands over the finite evaluation grid within each panel, conditional on the selected smoothing settings. They do not provide joint coverage across separate panels. See ?np.plot for supported targets, working-covariance assumptions and unavailability conditions.

For plot calls, use snake_case names such as gradient_order, data_overlay and data_rug, and B for bootstrap replication counts. Estimator and control constructor arguments retain their documented names, including gradient.order. With output = "data" or "plot-data", the returned np_plot_data object stores the evaluation grid, target values and absolute interval endpoints. For example, as.data.frame(out, panel = 1L, band = "simultaneous") returns one row per evaluation point for the selected target; its lower and upper columns are grid-aligned vectors, not scalar critical values. See ?np_plot_data. Unknown named arguments are rejected with a spelling hint where available. The full package NEWS (news(package = "npRmpi")) lists the replacements and family-specific changes. The Gallery FAQ provides further troubleshooting guidance.

Joint polynomial-order and bandwidth selection

The same joint polynomial-order and bandwidth selection route is also available here for local-polynomial-capable methods via search.engine = "nomad+powell", but this package-side vignette stays operational rather than methodological.

If you want the recommended route without spelling out all of the LP tuning arguments, use nomad = TRUE. This is a documented convenience preset, not a generic optimizer alias: it fills only missing LP degree-search controls and leaves compatible explicit overrides in place. This route uses the NOMAD backend supplied by the required crs dependency (version 0.15-46 or later), installed with npRmpi.

if (requireNamespace("crs", quietly = TRUE) &&
    utils::packageVersion("crs") >= package_version("0.15-46")) {
  npRmpi.init(nslaves = 1)

  set.seed(7)
  n <- 120
  x <- runif(n, -1, 1)
  y <- x + 0.4 * x^2 + rnorm(n, sd = 0.18)

  fit_nomad <- npreg(y ~ x, nomad = TRUE, degree.max = 1L, nmulti = 1L)
  fit_nomad$bws$nomad.shortcut

  bw_nomad_only <- npregbw(
    y ~ x,
    nomad = TRUE,
    search.engine = "nomad",
    degree.max = 1L,
    nmulti = 1L
  )
  bw_nomad_only$nomad.shortcut

  npRmpi.quit()
}

The same convenience entry point is available for the other LP-capable families: npcdens, npcdist, npplreg, npscoef, and npindex, together with their corresponding *bw constructors.

On current package sources, spawn is not the Windows entry path. There the practical starting point is attach mode under mpiexec.

Attach mode

Use attach mode when the MPI world is already launched via mpiexec and you want npRmpi.init(mode = "attach") to be the startup entry point.

library(npRmpi)
npRmpi.init(mode = "attach")

if (mpi.comm.rank(0L) == 0L) {
  set.seed(1)
  x <- runif(200)
  y <- sin(2 * pi * x) + rnorm(200, sd = 0.2)

  bw <- npregbw(y ~ x, regtype = "ll", bwmethod = "cv.ls")
  fit <- npreg(bws = bw)
  summary(fit)

  npRmpi.quit(mode = "attach")
}

For attach mode, keep R_PROFILE_USER and R_PROFILE cleared at launch time. Profile startup belongs to a different mode and should not be mixed into attach launches.

Profile / manual-broadcast mode

Use profile mode when explicit startup and broadcast control are needed, especially on larger or heterogeneous clusters. In this route, npRmpi.init() is not the startup entry point; instead, ranks are launched with inst/Rprofile (or R_PROFILE_USER) and then initialized explicitly inside the script.

mpi.bcast.cmd(np.mpi.initialize(), caller.execute = TRUE)

set.seed(1)
x <- runif(200)
y <- sin(2 * pi * x) + rnorm(200, sd = 0.2)
dat <- data.frame(y, x)

mpi.bcast.Robj2slave(dat)
mpi.bcast.cmd(
  bw <- npregbw(y ~ x, regtype = "ll", bwmethod = "cv.ls", data = dat),
  caller.execute = TRUE
)
mpi.bcast.cmd(
  fit <- npreg(bws = bw, data = dat),
  caller.execute = TRUE
)

summary(fit)
mpi.bcast.cmd(mpi.quit(), caller.execute = TRUE)

For profile mode, use exactly one startup profile source via R_PROFILE_USER or a local .Rprofile, clear R_PROFILE, and avoid --vanilla.

Practical guidance

Start with session / spawn mode first on macOS and Linux.
Start with attach mode first on Windows.
Treat attach and profile as standard advanced workflows.
Use attach when you want npRmpi.init(mode = "attach") to manage the worker loop for an already-launched MPI world.
Use profile when you want startup and broadcasts to be explicit and script-controlled.
Keep the attach and profile launch contracts distinct rather than mixing them.
Keep the package-side vignette light; use longer website documentation for platform-specific install notes and cluster recipes.