# API Documentation

## High Level

PumasQSP.QSPCostType
QSPCost(model, trials; search_space)

The QSPCost stores the information needed to setup a virtual population simulation. The model is an MTK ODESystem describing the particular case of interest. The trials are a trial collection that groups the individual trials according to their interpretation, such as IndependentTrials (there is no link between trials) or SteadyStateTrials (the first trial computes a steady state that other trials may continue to solve from). The search_space defines the parameters (or initial conditions) to be optimized during the virtual population simulation and their bounds.

The resulting object is callable, taking as a single argument the states of the OptimizationProblem that describes one virtual patient of the simulation.

source
PumasQSP.solve_trialFunction
solve_trial(trial, x, cost)

Solve the given trial corresponding to the cost object with the optimization state given by x.

source
PumasQSP.VpopResultType
VpopResult

The structure that contains virtual population results. You can export these results to a DataFrame with DataFrame(vp), or you can plot them using plot(vp, trial), where vp is your VpopResult and trial is the AbstractTrial that you want to use for the default parameter (or initial condition) values.

source
PumasQSP.vpop_ensembleFunction
vpop_ensemble(vp, trial; ss_trial=nothing)

Create an EnsembleProblem descrbing the patients in the virtual population vp and using trial for the parameter and initial condition values. If the trial depends on a steady state trial, it can be specified with ss_trial.

source
Missing docstring.

Missing docstring for vpop. Check Documenter's build log for details.

## Trial Types

PumasQSP.TrialType
Trial(data, model; kwargs...)

The Trial describes one instance in which data was obtained for the specified model. The trial will then be used to compute the cost function of the optimization problem that corresponds to a virtual population simulation or to a global sensitivity analysis (GSA). In the case of GSA, the data is not needed, so it can be assigned to nothing.

A trial describes what happens with the model in a certain situation that corresponds to parameter (or initial condition) values that differ from the defaults of the model. In order to specify the modifications, you can use the u0 keyword argument for initial conditions (e.g. u0 = [statename => custominitialvalue]) and params for the parameters (e.g. params = [p1 => specificvalue, p2 => other_value]).

A required keyword of the Trial constructor is tspan, which indicates the timespan for which we solve the model equations.

In order to specify what states are saved in the data, the save_names keyword argument can be used.

The cost contribution for the trial is computed using the L2 loss function by default, but this can be changed by using the err keyword argument (e.g. err = (sol, data) -> compute_error). The function will be passed 2 arguments, the solution of the trial and the data and is expected to return a scalar value that will represent the cost contribution of the respective trial.

In the case of GSA, a reduction function will be used instead, and that will correspond to what we are computing the sensitivity against.

If the trial is part of a collection of SteadyStateTrials, then forward_u0=true should be passed for the trial to continue solving from the steady state.

If additional keywords are passed, they will be forwarded to the solve call. For example, one can pass alg=Tsit5() to specify what solver will be used. More information about supported arguments can be found here.

source
PumasQSP.IndependentTrialsType
IndependentTrials(trials...)

This trial collection type indicates that each trial can be solved individualy and that there is no interaction between them. This trial type is automatically created it the trials are passed as a Vector (i.e. [trial1, trial2])

source
PumasQSP.SteadyStateTrialsType
SteadyStateTrials(ss_trial, trials...; postprocess=last)

SteadyStateTrials are a trial collection that describes a steady state trial (specified as the first argument) followed by subsequent trials that can continue using the steady state by setting forward_u0=true. The steady state solution that is passed on can be modified using the postprocess keyword argument, which accepts a function with a single argument that represents the solution of the first trial and returns the state to be further passed on.

source

## Virtual Population Methods

PumasQSP.StochGlobalOptType
StochGlobalOpt(; maxiters, parallel_type=EnsembleSerial(), solver=BBO_adaptive_de_rand_1_bin_radiuslimited())

A stochastic global optimization method for computing virtual populations. The keyword maxiters is required and represents the maximum number of iterations taken by the global optimization method (chosen via the solver keyword).

The keyword parallel_type can be used to pass a parallelization method. The ensemble types from SciML are supported.

source