Package {rxode2lincmt}

Version:	0.1.0
Title:	Linear Compartment Model Solutions and Gradients for 'rxode2'
Maintainer:	Matthew L. Fidler <matthew.fidler@gmail.com>
Depends:	R (≥ 4.1.0)
Imports:	Rcpp (≥ 1.0.8), checkmate
Suggests:	covr, testthat (≥ 3.0.0)
Description:	Analytic one, two and three compartment linear pharmacokinetic solutions with their parameter gradients from 'stan' automatic differentiation (Carpenter et al (2015) <doi:10.48550/arXiv.1509.07164>), eigen decompositions and derived-parameter conversions used by 'rxode2' (Wang, Hallow and James (2016) <doi:10.1002/psp4.12052>). Split out of 'rxode2' so its installation does not compile 'stan' AD items which made it take too long to compile by itself. The closed-form solutions follow the idea of the 'wnl' package (Bae, https://CRAN.R-project.org/package=wnl), though the implementation here is different.
BugReports:	https://github.com/nlmixr2/rxode2lincmt/issues/
NeedsCompilation:	yes
License:	GPL (≥ 3)
URL:	https://nlmixr2.github.io/rxode2lincmt/, https://github.com/nlmixr2/rxode2lincmt/
Biarch:	true
LinkingTo:	Rcpp (≥ 1.0.8), RcppEigen (≥ 0.3.3.9.2), StanHeaders (≥ 2.21.0.7), BH, RcppParallel
Encoding:	UTF-8
Language:	en-US
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
Packaged:	2026-09-14 19:46:27 UTC; matt-fidler
Author:	Matthew L. Fidler [aut, cre], Richard Upton [ctb]
Repository:	CRAN
Date/Publication:	2026-09-24 14:40:02 UTC

rxode2lincmt: Linear Compartment Model Solutions and Gradients for 'rxode2'

Description

Analytic one, two and three compartment linear pharmacokinetic solutions with their parameter gradients from 'stan' automatic differentiation (Carpenter et al (2015) doi:10.48550/arXiv.1509.07164), eigen decompositions and derived-parameter conversions used by 'rxode2' (Wang, Hallow and James (2016) doi:10.1002/psp4.12052). Split out of 'rxode2' so its installation does not compile 'stan' AD items which made it take too long to compile by itself. The closed-form solutions follow the idea of the 'wnl' package (Bae, https://CRAN.R-project.org/package=wnl), though the implementation here is different.

Details

The closed-form linear compartment solutions follow the idea of the 'wnl' package by Kyun-Seop Bae (https://CRAN.R-project.org/package=wnl); the implementation here is different.

Author(s)

Maintainer: Matthew L. Fidler matthew.fidler@gmail.com (ORCID)

Authors:

• Matthew L. Fidler matthew.fidler@gmail.com (ORCID)

Other contributors:

• Richard Upton [contributor]

See Also

Useful links:

• https://nlmixr2.github.io/rxode2lincmt/

• https://github.com/nlmixr2/rxode2lincmt/

• Report bugs at https://github.com/nlmixr2/rxode2lincmt/issues/

Derived linear compartment parameters (engine for rxode2::rxDerived())

Description

Low-level entry point: rxode2's rxDerived() parses the parameter names and calls this with the compartment count, parameterization and a list of parameter vectors. Use rxode2::rxDerived() instead of calling it directly.

Usage

.calcDerived(ncmt, oral, w2, trans, inp, digits = 0)

Arguments

Value

data frame of derived parameters

Sensitivity methods linCmtB() has used (test hook)

Description

Sensitivity methods linCmtB() has used (test hook)

Usage

.linCmtBSensTypesSeen(reset)

Arguments

Value

integer vector of the sensType codes linCmtB() computed a Jacobian with since the last reset

Number of threads linCmtB() has run on (test hook)

Description

Number of threads linCmtB() has run on (test hook)

Usage

.linCmtBThreadsSeen(reset)

Arguments

Value

integer count of the distinct thread slots linCmtB() ran on since the last reset

Read (and optionally reset) the linCmt() carry-advance fast-path counters

Description

Read (and optionally reset) the linCmt() carry-advance fast-path counters

Usage

.linCmtCarryFastStats(reset = FALSE)

Arguments

Value

named numeric vector: advCalls (every which1=-5 invocation), advFast (subset that took the constant-theta skip)

Drive linCmtB() carry sentinels on a solved subject (test hook)

Description

Replays linCmtB() calls for one subject of the most recent rxode2 solve in the same session, the way that subject's output pass would, so tests can check the carry sentinels. Needs rxode2 to be loaded and a solve to have run.

Usage

.linCmtCarryLiveTest(
  id,
  t,
  tPrior,
  theta,
  ncmt,
  oral0,
  trans,
  which1,
  which2,
  addVal = NULL
)

Arguments

Value

numeric vector of linCmtB() results, one per row

Highest carry sentinel linCmtB(which1 = -k) this build understands

Description

nlmixr2est gates its carry codegen on this: -8 (the fast-path pin an event-modifier jump needs) is only emitted when the loaded rxode2 has it.

Usage

.linCmtCarrySentinelMax()

Value

integer, the magnitude of the most negative carry sentinel

Toggle the linCmt() carry-advance runtime fast path (test/benchmark hook)

Description

Toggle the linCmt() carry-advance runtime fast path (test/benchmark hook)

Usage

.linCmtCarrySetFast(enable)

Arguments

Value

the previous state, invisibly

Force the delta-keyed exponential memo on or off (tests/benchmarks)

Description

Force the delta-keyed exponential memo on or off (tests/benchmarks)

Usage

.linCmtDeltaMemo(on = -1L)

Arguments

Value

the previous setting, invisibly usable to restore it

Read (and optionally reset) the amortized linCmt() sequential counters

Description

Read (and optionally reset) the amortized linCmt() sequential counters

Usage

.linCmtSeqStats(reset = FALSE)

Arguments

Value

named integer vector: windows (window-constant recomputations), seqTailRows (rows evaluated from the window's dt-dependent tail), seqFullRows (rows that fell back to the full forward evaluator), valueCompute (value executions that solved the row), valueRestore (value executions that restored an already-solved row), memoHit (value executions short-circuited by the last-row memo), valueLite (already-solved value re-executions served by the thin fx-plus-scaling path with the Jacobian restore skipped), expBuild (delta-keyed exponential-memo builds: one per distinct row gap per theta window), expHit (rows whose exponentials came from the delta memo; disable with RX_LINCMT_DELTA_MEMO=off), expSolo (of those builds, the ones that went to the within-row slot the guard keeps serving after it stops speculating), dualRows (rows whose tail took one multi-direction pass, linCmtSensType="ADm"), phiAnalyticRows (rows propagated through the closed-form transition matrix; RX_LINCMT_PHI=2)

Host table field names

Description

Test hook: the struct_field names of the offset table in wire order.

Usage

.rxode2lincmtHostFieldNames()

Value

character vector

Examples

head(.rxode2lincmtHostFieldNames())

Inspect the registered host table

Description

Test hook: the struct offsets currently held (-1 before registration) and whether each host function has been bound.

Usage

.rxode2lincmtHostInfo()

Value

list with offsets (integer) and fns (named logical)

Examples

.rxode2lincmtHostInfo()$fns

Register the host table from rxode2

Description

rxode2 calls this from its .onLoad() with the struct offsets and host functions described in inst/include/rxode2lincmtHost.h. Nothing is validated; values are copied with bounds limits only.

Usage

.rxode2lincmtIniHost(host)

Arguments

Value

NULL, invisibly

External pointers to the linear compartment entry points

Description

rxode2 reads this list from its .onLoad() and calls the linear compartment kernels through it; see inst/include/rxode2lincmtPtrs.h for the consumer contract. The list is append-only and its order is fixed.

Usage

.rxode2lincmtPtr()

Value

named list of external pointers

Examples

names(.rxode2lincmtPtr())

Micro-constants of a linear compartment model

Description

Converts one parameter set, in any of the linCmt() parameterizations, to the central volume and micro-constants that the analytic solutions use.

Usage

linCmtMicros(p1, v1, p2 = 0, p3 = 0, p4 = 0, p5 = 0, ncmt, trans = 1L)

Arguments

Details

Supported trans values: one compartment 1 (cl, v), 2 (k, v), 10 (alpha, A with v1 holding A), 11 (alpha, v); two compartments 1 (cl, v, q, vp), 2 (k, v, k12, k21), 3 (cl, v, q, vss), 4 (alpha, beta, k21), 5 (alpha, beta, aob), 10, 11; three compartments 1 (cl, v, q, vp, q2, vp2), 2 (k, v, k12, k21, k13, k31), 10, 11.

Value

named numeric vector: v, k, and for two or more compartments k12, k21, and for three compartments k13, k31

Author(s)

Matthew L. Fidler

Examples

linCmtMicros(p1 = 2, v1 = 20, ncmt = 1)
linCmtMicros(p1 = 2, v1 = 20, p2 = 3, p3 = 40, ncmt = 2)

Advance a linear compartment model by one step

Description

Advances the amounts of a one, two or three compartment linear model by dt and returns the central concentration, optionally with its derivatives. This is the per-row kernel behind rxode2's linCmt().

Usage

linCmtModelDouble(
  dt,
  p1,
  v1,
  p2,
  p3,
  p4,
  p5,
  ka,
  alastNV,
  rateNV,
  ncmt,
  oral0,
  trans,
  deriv,
  type,
  tau,
  tinf,
  amt,
  bolusCmt,
  ndiff,
  sensType = 3L,
  sensH = 0.001
)

Arguments

Value

list with val (central concentration) and Alast (carried state after the step); with deriv = TRUE also J (Jacobian of the amounts) and Jg (gradient of val)

Examples

linCmtModelDouble(1, 2, 20, 0, 0, 0, 0, 0, 100, 0, 1L, 0L, 1L, FALSE,
                  0L, 0, 0, 0, 0L, 0L)

Eigenvalues and coefficients of the two compartment model

Description

Computes the exponents (L) and coefficient matrices (C1, C2) of the two compartment linear system from its micro-constants. The idea comes from the 'wnl' package by Kyun-Seop Bae; the implementation is different.

Usage

solComp2(k10, k12, k21)

Arguments

Value

List with L vector and matrices C1 and C2

Author(s)

Matthew L. Fidler, based on the idea in the 'wnl' package

Examples

solComp2(k10 = 0.1, k12 = 3, k21 = 1)

Eigenvalues and coefficients of the three compartment model

Description

Eigenvalues and coefficients of the three compartment model

Usage

solComp3(k10, k12, k21, k13, k31)

Arguments

Value

List with L vector and matrices C1, C2 and C3

Author(s)

Matthew L. Fidler, based on the idea in the 'wnl' package

Examples

solComp3(k10 = 0.1, k12 = 3, k21 = 1, k13 = 2, k31 = 0.5)