Struct BestDoseProblem 

pub struct BestDoseProblem { /* private fields */ }

The BestDose optimization problem

Contains all data needed for the three-stage BestDose algorithm. Create via BestDoseProblem::new(), then call .optimize() to run the full algorithm.

Three-Stage Algorithm

1. Posterior Density Calculation (automatic in new())

   • NPAGFULL11: Bayesian filtering of prior support points
   • NPAGFULL: Local refinement of each filtered point

2. Dual Optimization (automatic in optimize())

   • Optimization with posterior weights (patient-specific)
   • Optimization with uniform weights (population-based)
   • Selection of better result

3. Final Predictions (automatic in optimize())

   • Concentration or AUC predictions with optimal doses

Fields

Input Data

• target: Future dosing template with target observations
• target_type: Target::Concentration or [Target::AUC]

Population Prior

• population_weights: Filtered population probability weights (used for bias term)

Patient-Specific Posterior

• theta: Refined posterior support points (from NPAGFULL11 + NPAGFULL)
• posterior: Posterior probability weights

Model Components

• eq: Pharmacokinetic/pharmacodynamic ODE model
• settings: NPAG configuration settings (used for prediction grid)

Optimization Parameters

• doserange: Min/max dose constraints
• bias_weight (λ): Personalization parameter (0=personalized, 1=population)

Example

use pmcore::bestdose::{BestDoseProblem, Target, DoseRange};

let problem = BestDoseProblem::new(
    &population_theta,
    &population_weights,
    Some(past),                      // Patient history
    target,                          // Dosing template with targets
    eq,
    error_models,
    DoseRange::new(0.0, 1000.0),
    0.5,                             // Balanced personalization
    settings,
    500,                             // NPAGFULL cycles
    Target::Concentration,
)?;

let result = problem.optimize()?;

Implementations

impl BestDoseProblem

pub fn new( population_theta: &Theta, population_weights: &Weights, past_data: Option<Subject>, target: Subject, time_offset: Option<f64>, eq: ODE, doserange: DoseRange, bias_weight: f64, settings: Settings, target_type: Target, ) -> Result<Self>

Create a new BestDose problem with automatic posterior calculation

This is the main entry point for the BestDose algorithm.

Algorithm Structure (Matches Flowchart)

┌─────────────────────────────────────────┐
│ STAGE 1: Posterior Density Calculation  │
│                                         │
│  Prior Density (N points)              │
│      ↓                                 │
│  Has past data with observations?      │
│      ↓ Yes          ↓ No              │
│  Step 1.1:      Use prior             │
│  NPAGFULL11     directly               │
│  (Filter)                              │
│      ↓                                 │
│  Step 1.2:                             │
│  NPAGFULL                              │
│  (Refine)                              │
│      ↓                                 │
│  Posterior Density                     │
└─────────────────────────────────────────┘

Parameters

• population_theta - Population support points from NPAG
• population_weights - Population probabilities
• past_data - Patient history (None = use prior directly)
• target - Future dosing template with targets
• time_offset - Optional time offset for concatenation (None = standard mode, Some(t) = Fortran mode)
• eq - Pharmacokinetic/pharmacodynamic model
• error_models - Error model specifications
• doserange - Allowable dose constraints
• bias_weight - λ ∈ [0,1]: 0=personalized, 1=population
• settings - NPAG settings for posterior refinement
• max_cycles - NPAGFULL cycles (0=skip refinement, 500=default)
• target_type - Concentration or AUC targets

Returns

BestDoseProblem ready for optimize()

pub fn optimize(self) -> Result<BestDoseResult>

Run the complete BestDose optimization algorithm

Algorithm Flow (Matches Diagram!)

┌─────────────────────────────────────────┐
│ STAGE 1: Posterior Calculation          │
│         [COMPLETED in new()]             │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ STAGE 2: Dual Optimization              │
│                                         │
│  Optimization 1: Posterior Weights      │
│    (Patient-specific)                   │
│      ↓                                  │
│  Result 1: (doses₁, cost₁)             │
│                                         │
│  Optimization 2: Uniform Weights        │
│    (Population-based)                   │
│      ↓                                  │
│  Result 2: (doses₂, cost₂)             │
│                                         │
│  Select: min(cost₁, cost₂)             │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ STAGE 3: Final Predictions              │
│                                         │
│  Calculate predictions with             │
│  optimal doses and winning weights      │
└─────────────────────────────────────────┘

Returns

BestDoseResult containing:

• dose: Optimal dose amount(s)
• objf: Final cost function value
• preds: Concentration-time predictions
• auc_predictions: AUC values (if target_type is AUC)
• optimization_method: “posterior” or “uniform”

pub fn with_bias_weight(self, weight: f64) -> Self

Set the bias weight (lambda parameter)

• λ = 0.0 (default): Full personalization (minimize patient-specific variance)
• λ = 0.5: Balanced between individual and population
• λ = 1.0: Population-based (minimize deviation from population mean)

Trait Implementations

impl Clone for BestDoseProblem

fn clone(&self) -> BestDoseProblem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CostFunction for BestDoseProblem

Implement CostFunction trait for BestDoseProblem

This allows the Nelder-Mead optimizer to evaluate candidate doses.

type Param = Vec<f64>

Type of the parameter vector

type Output = f64

Type of the return value of the cost function

fn cost(&self, param: &Self::Param) -> Result<Self::Output>

Compute cost function

fn bulk_cost<P>(&self, params: &[P]) -> Result<Vec<Self::Output>, Error>

where P: Borrow<Self::Param> + SyncAlias, Self::Output: SendAlias, Self: SyncAlias,

Compute cost in bulk. If the rayon feature is enabled, multiple calls to cost will be run in parallel using rayon, otherwise they will execute sequentially. If the rayon feature is enabled, parallelization can still be turned off by overwriting parallelize to return false. This can be useful in cases where it is preferable to parallelize only certain parts. Note that even if parallelize is set to false, the parameter vectors and the problem are still required to be Send and Sync. Those bounds are linked to the rayon feature. This method can be overwritten.

fn parallelize(&self) -> bool

Indicates whether to parallelize calls to cost when using bulk_cost. By default returns true, but can be set manually to false if needed. This allows users to turn off parallelization for certain traits implemented on their problem. Note that parallelization requires the rayon feature to be enabled, otherwise calls to cost will be executed sequentially independent of how parallelize is set.

impl Debug for BestDoseProblem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.