| 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:
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
ncmt |
number of compartments (1-3, double) |
oral |
oral flag (double) |
w2 |
parser weight flag (double) |
trans |
parameterization number (double) |
inp |
list of parameter vectors in parser order |
digits |
significant digits to round to (0 for no rounding) |
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
reset |
logical; when |
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
reset |
logical; when |
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
reset |
logical; when TRUE zero the counters after reading |
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
id |
0-based subject index in the most recent solve |
t |
output time of each row |
tPrior |
time of the preceding row (0 for the first row) |
theta |
numeric matrix with one row per element of |
ncmt |
number of compartments, 1 to 3 |
oral0 |
1 when the model has a depot compartment, otherwise 0 |
trans |
parameterization number |
which1 |
per-row |
which2 |
per-row |
addVal |
for rows with |
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
enable |
logical; new state |
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
on |
integer: 1 forces the memo on, 0 forces it off, -1 (the default) follows the RX_LINCMT_DELTA_MEMO environment latch read at window-fill time |
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
reset |
logical; when TRUE zero the counters after reading |
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
host |
list built by rxode2 (offsets followed by external pointers) |
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
p1 |
first parameter (for example clearance or |
v1 |
central volume (or its parameterization-specific counterpart) |
p2 |
second parameter (two and three compartments) |
p3 |
third parameter (two and three compartments) |
p4 |
fourth parameter (three compartments) |
p5 |
fifth parameter (three compartments) |
ncmt |
number of compartments, 1 to 3 |
trans |
parameterization number (see Details) |
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
dt |
time step |
p1, v1, p2, p3, p4, p5 |
parameters in the |
ka |
absorption rate constant (used when |
alastNV |
amounts at the start of the step (depot first when
|
rateNV |
zero-order rates into each compartment, in the same order |
ncmt |
number of compartments, 1 to 3 |
oral0 |
1 when the model has a depot compartment, otherwise 0 |
trans |
parameterization number |
deriv |
logical; also return the derivatives |
type |
0 for a regular step; 1 and 2 steady-state infusion, 3 steady-state bolus |
tau |
steady-state dosing interval |
tinf |
steady-state infusion duration |
amt |
steady-state bolus amount |
bolusCmt |
steady-state bolus compartment |
ndiff |
differentiation bit mask as used by rxode2 ( |
sensType |
derivative method: 3 or 30 forward-mode automatic
differentiation, 32 all directions in one forward-mode pass, 31
reverse mode, 100 automatic choice, 1 and 2 forward and central
differences with the kernel's own step, 10 and 20 forward and central
differences with step |
sensH |
finite-difference step for |
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
k10 |
elimination rate |
k12 |
rate from central to peripheral compartment |
k21 |
rate from peripheral to central compartment |
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
k10 |
elimination rate |
k12 |
rate from central to peripheral compartment |
k21 |
rate from peripheral to central compartment |
k13 |
rate from central to peripheral compartment #2 |
k31 |
rate from peripheral compartment #2 to central |
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)