Structural Model

The [structural_model] block specifies the pharmacokinetic model used to generate predictions.

Analytical PK models

For standard compartmental models, use the pk keyword with a model function:

pk MODEL_NAME(param=VALUE, param=VALUE, ...)

Named arguments map individual-parameter symbols (from [individual_parameters]) to the model’s PK slots.

Available models

Model function Compartments Route Required parameters
one_cpt_iv_bolus 1 IV bolus cl, v
one_cpt_iv_infusion 1 IV infusion cl, v
one_cpt_oral 1 Oral cl, v, ka
one_cpt_oral_f 1 Oral with bioavailability cl, v, ka, f
two_cpt_iv_bolus 2 IV bolus cl, v1, q, v2
two_cpt_iv_infusion 2 IV infusion cl, v1, q, v2
two_cpt_oral 2 Oral cl, v1, q, v2, ka
two_cpt_oral_f 2 Oral with bioavailability cl, v1, q, v2, ka, f
three_cpt_iv_bolus 3 IV bolus cl, v1, q2, v2, q3, v3
three_cpt_iv_infusion 3 IV infusion cl, v1, q2, v2, q3, v3
three_cpt_oral 3 Oral cl, v1, q2, v2, q3, v3, ka

Examples

One-compartment oral:

[structural_model]
  pk one_cpt_oral(cl=CL, v=V, ka=KA)

Two-compartment IV bolus:

[structural_model]
  pk two_cpt_iv_bolus(cl=CL, v1=V1, q=Q, v2=V2)

Two-compartment oral:

[structural_model]
  pk two_cpt_oral(cl=CL, v1=V1, q=Q, v2=V2, ka=KA)

Bioavailability

For oral models, bioavailability (F) defaults to 1.0. Two ways to estimate it:

  1. Dedicated slot — use the _f model variant and pass f=F:

    pk one_cpt_oral_f(cl=CL, v=V, ka=KA, f=F)

  2. Auto-detected — define F in [individual_parameters]; the oral PK functions pick it up automatically without needing the _f variant.

For logit-normal bioavailability — to constrain F ∈ (0, 1) — see Individual Parameters — Logit-normal bioavailability.

Dose handling

Analytical models support:

  • Bolus doses — instantaneous input (default when RATE=0 in data)
  • Infusions — zero-order input (when RATE>0 in data)
  • Steady-state — pre-computed concentrations (when SS=1 and II>0)
  • Dose superposition — multiple doses summed via superposition

Numerical stability

Analytical solutions include special handling for degenerate cases:

  • Near-equal rate constants — when KA ≈ k, L’Hôpital’s rule avoids division by near-zero
  • Two-compartment eigenvalues — Vieta’s formula (β = d/α) avoids catastrophic cancellation when the discriminant is small

See Structural Model — ferx-core book for the full mathematical reference.

ODE models

For non-standard kinetics (e.g. saturable elimination, TMDD), use the ODE specification:

[structural_model]
  ode(obs_cmt=COMPARTMENT_NAME, states=[state1, state2, ...])
  • obs_cmt — the compartment whose amount is compared to DV
  • states — list of state variable names (compartments), 1-indexed in data

See ODE Models for the full ODE syntax and solver reference.