API
PEtab.PEtabModel — TypePEtabModelA Julia-compatible representation of a PEtab-specified problem.
Created by readPEtabModel, this object contains helper functions for setting up cost, gradient, and Hessian computations, as well as handling potential model events (callbacks).
Note1: Several of the functions in PEtabModel are not intended to be accessed by the user. For example, compute_h (and similar functions) require indices that are built in the background to efficiently map parameters between experimental (simulation) conditions. Rather, PEtabModel holds all information needed to create a PEtabODEProblem, and in the future, PEtabSDEProblem, etc.
Note2: ODEProblem.p refers to the parameters for the underlying DifferentialEquations.jl ODEProblem.
Fields
modelName: The model name extracted from the PEtab YAML file.compute_h: Computes the observablehfor a specific time point and simulation condition.compute_u0!: Computes in-place initial values usingODEProblem.pfor a simulation condition;compute_u0!(u0, p).compute_u0: Computes initial values as above, but not in-place;u0 = compute_u0(p).compute_σ: Computes the noise parameterσfor a specific time point and simulation condition.compute_∂h∂u!: Computes the gradient ofhwith respect toODEModelstates (u) for a specific time point and simulation condition.compute_∂σ∂u!: Computes the gradient ofσwith respect toODEModelstates (u) for a specific time point and simulation condition.compute_∂h∂p!: Computes the gradient ofhwith respect toODEProblem.p.compute_∂σ∂p!: Computes the gradient ofσwith respect toODEProblem.p.computeTStops: Computes the event times in case the model hasDiscreteCallbacks(events).convertTspan::Bool: Tracks whether the time span should be converted toDualnumbers forForwardDiff.jlgradients, in case the model hasDiscreteCallbacksand the trigger time is a parameter set to be estimated.dirModel: The directory where the model.xml and PEtab files are stored.dirJulia: The directory where the Julia-model files created by parsing the PEtab files (e.g., SBML file) are stored.odeSystem: AModellingToolkit.jlODE system obtained from parsing the model SBML file.parameterMap: AModellingToolkit.jlparameter map for the ODE system.stateMap: AModellingToolkit.jlstate map for the ODE system describing how the initial values are computed, e.g., whether or not certain initial values are computed from parameters in theparameterMap.parameterNames: The names of the parameters in theodeSystem.stateNames: The names of the states in theodeSystem.pathMeasurements: The path to the PEtab measurements file.pathConditions: The path to the PEtab conditions file.pathObservables: The path to the PEtab observables file.pathParameters: The path to the PEtab parameters file.pathSBML: The path to the PEtab SBML file.pathYAML: The path to the PEtab YAML file.modelCallbackSet: This stores potential model callbacks or events.checkIfCallbackIsActive: Piecewise SBML statements are transformed to DiscreteCallbacks that are activated at a specific time-point. The piecewise callback has a default value at t0 and is only triggered when reaching tactivation. If tactivation ≤ 0 (never reached when solving the model), this function checks whether the callback should be triggered before solving the model.
PEtab.readPEtabModel — FunctionreadPEtabModel(pathYAML::String;
+API · PEtab.jl API
PEtab.PEtabModel — TypePEtabModel
A Julia-compatible representation of a PEtab-specified problem.
Created by readPEtabModel, this object contains helper functions for setting up cost, gradient, and Hessian computations, as well as handling potential model events (callbacks).
Note1: Several of the functions in PEtabModel are not intended to be accessed by the user. For example, compute_h (and similar functions) require indices that are built in the background to efficiently map parameters between experimental (simulation) conditions. Rather, PEtabModel holds all information needed to create a PEtabODEProblem, and in the future, PEtabSDEProblem, etc.
Note2: ODEProblem.p refers to the parameters for the underlying DifferentialEquations.jl ODEProblem.
Fields
modelName: The model name extracted from the PEtab YAML file.compute_h: Computes the observable h for a specific time point and simulation condition.compute_u0!: Computes in-place initial values using ODEProblem.p for a simulation condition; compute_u0!(u0, p).compute_u0: Computes initial values as above, but not in-place; u0 = compute_u0(p).compute_σ: Computes the noise parameter σ for a specific time point and simulation condition.compute_∂h∂u!: Computes the gradient of h with respect to ODEModel states (u) for a specific time point and simulation condition.compute_∂σ∂u!: Computes the gradient of σ with respect to ODEModel states (u) for a specific time point and simulation condition.compute_∂h∂p!: Computes the gradient of h with respect to ODEProblem.p.compute_∂σ∂p!: Computes the gradient of σ with respect to ODEProblem.p.computeTStops: Computes the event times in case the model has DiscreteCallbacks (events).convertTspan::Bool: Tracks whether the time span should be converted to Dual numbers for ForwardDiff.jl gradients, in case the model has DiscreteCallbacks and the trigger time is a parameter set to be estimated.dirModel: The directory where the model.xml and PEtab files are stored.dirJulia: The directory where the Julia-model files created by parsing the PEtab files (e.g., SBML file) are stored.odeSystem: A ModellingToolkit.jl ODE system obtained from parsing the model SBML file.parameterMap: A ModellingToolkit.jl parameter map for the ODE system.stateMap: A ModellingToolkit.jl state map for the ODE system describing how the initial values are computed, e.g., whether or not certain initial values are computed from parameters in the parameterMap.parameterNames: The names of the parameters in the odeSystem.stateNames: The names of the states in the odeSystem.pathMeasurements: The path to the PEtab measurements file.pathConditions: The path to the PEtab conditions file.pathObservables: The path to the PEtab observables file.pathParameters: The path to the PEtab parameters file.pathSBML: The path to the PEtab SBML file.pathYAML: The path to the PEtab YAML file.modelCallbackSet: This stores potential model callbacks or events.checkIfCallbackIsActive: Piecewise SBML statements are transformed to DiscreteCallbacks that are activated at a specific time-point. The piecewise callback has a default value at t0 and is only triggered when reaching tactivation. If tactivation ≤ 0 (never reached when solving the model), this function checks whether the callback should be triggered before solving the model.
sourcePEtab.readPEtabModel — FunctionreadPEtabModel(pathYAML::String;
forceBuildJuliaFiles::Bool=false,
verbose::Bool=true,
ifElseToEvent::Bool=true,
writeToFile::Bool=true,
- jlFilePath::String="")::PEtabModel
Parses a PEtab specified problem with a YAML-file located at pathYAML into a Julia-accessible format.
When parsing a PEtab problem, several things happen under the hood:
- The SBML file is translated into
ModelingToolkit.jl format to allow for symbolic computations of the ODE-model Jacobian. Piecewise and model events are further written into DifferentialEquations.jl callbacks. - The observable PEtab table is translated into a Julia file with functions for computing the observable (
h), noise parameter (σ), and initial values (u0). - To allow gradients via adjoint sensitivity analysis and/or forward sensitivity equations, the gradients of
h and σ are computed symbolically with respect to the ODE model's states (u) and parameters (odeProblem.p).
All of this happens automatically, and resulting files are stored under petabModel.dirJulia assuming writeToFile=true. To save time, forceBuildJlFiles=false by default, which means that Julia files are not rebuilt if they already exist.
In case a Julia model files is provided instead of a SBML file provide file path under jlFilePath.
Arguments
pathYAML::String: Path to the PEtab problem YAML file.forceBuildJuliaFiles::Bool=false: If true, forces the creation of Julia files for the problem even if they already exist.verbose::Bool=true: If true, displays verbose output during parsing.ifElseToEvent::Bool=true: If true, rewrites if-else statements in the SBML model as event-based callbacks.jlFilePath::String="": Path to an existing Julia file. Should only be provided if a Julia model file is availble.
Example
petabModel = readPEtabModel("path/to/petab/problem.yaml")
sourcePEtab.PEtabODEProblem — TypePEtabODEProblem
Everything needed to setup an optimization problem (compute cost, gradient, hessian and parameter bounds) for a PEtab model.
Note The parameter vector θ is always assumed to be on the parameter scale specified in the PEtab parameters file. If needed, θ is transformed to the linear scale inside the function call.
Fields
computeCost: For θ computes the negative likelihood (objective to minimize)computeChi2: For θ compute χ2 valuecomputeGradient!: For θ computes in-place gradient computeGradient!(gradient, θ)computeGradient: For θ computes out-place gradient gradient = computeGradient(θ)computeHessian!: For θ computes in-place hessian-(approximation) computeHessian!(hessian, θ)computeHessian: For θ computes out-place hessian-(approximation) hessian = computeHessian(θ)computeSimulatedValues: For θ compute the corresponding model (simulated) values to the measurements in the same order as in the Measurements PEtab tablecomputeResiduals: For θ compute the residuals (hmodel - hobserved)^2 / σ^2 in the same order as in the Measurements PEtab tablegradientMethod: The method used to compute the gradient (either :ForwardDiff, :ForwardEquations, :Adjoint, or :Zygote).hessianMethod: The method used to compute or approximate the Hessian (either :ForwardDiff, :BlocForwardDiff, or :GaussNewton).nParametersToEstimate: The number of parameters to estimate.θ_estNames: The names of the parameters in θ.θ_nominal: The nominal values of θ as specified in the PEtab parameters file.θ_nominalT: The nominal values of θ on the parameter scale (e.g., log) as specified in the PEtab parameters file.lowerBounds: The lower parameter bounds on the parameter scale for θ as specified in the PEtab parameters file.upperBounds: The upper parameter bounds on the parameter scale for θ as specified in the PEtab parameters file.petabModel: The PEtabModel used to construct the PEtabODEProblem.odeSolverOptions: The options for the ODE solver specified when creating the PEtabODEProblem.odeSolverGradientOptions: The options for the ODE solver gradient specified when creating the PEtabODEProblem.
sourcePEtab.createPEtabODEProblem — FunctioncreatePEtabODEProblem(petabModel::PEtabModel; <keyword arguments>)
Given a PEtabModel creates a PEtabODEProblem with potential user specified options.
The keyword arguments (described below) allow the user to choose cost, gradient, and Hessian methods, ODE solver options, and other tuneable options that can potentially make computations more efficient for some "edge-case" models. Please refer to the documentation for guidance on selecting the most efficient options for different types of models.
If a keyword argument is not set, a suitable default option is chosen based on the number of model parameters.
Note Every problem is unique, so even though the default settings often work well they might not be optimal.
Keyword arguments
odeSolverOptions::ODESolverOptions: Options for the ODE solver when computing the cost, such as solver and tolerances.odeSolverGradientOptions::ODESolverOptions: Options for the ODE solver when computing the gradient, such as the ODE solver options used in adjoint sensitivity analysis. Defaults to odeSolverOptions if not set to nothing.ssSolverOptions::SteadyStateSolverOptions: Options for finding steady-state for models with pre-equilibrium. Steady-state can be found via simulation or rootfinding, which can be set using SteadyStateSolverOptions (see documentation). If not set, defaults to simulation with wrms < 1 termination.ssSolverGradientOptions::SteadyStateSolverOptions: Options for finding steady-state for models with pre-equilibrium when computing gradients. Defaults to ssSolverOptions value if not set.costMethod::Symbol=:Standard: Method for computing the cost (objective). Two options are available: :Standard, which is the most efficient, and :Zygote, which is less efficient but compatible with the Zygote automatic differentiation library.gradientMethod=nothing: Method for computing the gradient of the objective. Four options are available::ForwardDiff: Compute the gradient via forward-mode automatic differentiation using ForwardDiff.jl. Most efficient for models with ≤50 parameters. The number of chunks can be optionally set using chunkSize.:ForwardEquations: Compute the gradient via the model sensitivities, where sensealg specifies how to solve for the sensitivities. Most efficient when the Hessian is approximated using the Gauss-Newton method and when the optimizer can reuse the sensitivities (reuseS) from gradient computations in Hessian computations (e.g., when the optimizer always computes the gradient before the Hessian).:Adjoint: Compute the gradient via adjoint sensitivity analysis, where sensealg specifies which algorithm to use. Most efficient for large models (≥75 parameters).:Zygote: Compute the gradient via the Zygote package, where sensealg specifies which sensitivity algorithm to use when solving the ODE model. This is the most inefficient option and not recommended.
hessianMethod=nothing: method for computing the Hessian of the cost. There are three available options::ForwardDiff: Compute the Hessian via forward-mode automatic differentiation using ForwardDiff.jl. This is often only computationally feasible for models with ≤20 parameters but can greatly improve optimizer convergence.:BlockForwardDiff: Compute the Hessian block approximation via forward-mode automatic differentiation using ForwardDiff.jl. The approximation consists of two block matrices: the first is the Hessian for only the dynamic parameters (parameter part of the ODE system), and the second is for the non-dynamic parameters (e.g., noise parameters). This is computationally feasible for models with ≤20 dynamic parameters and often performs better than BFGS methods.:GaussNewton: Approximate the Hessian via the Gauss-Newton method, which often performs better than the BFGS method. If we can reuse the sensitivities from the gradient in the optimizer (see reuseS), this method is best paired with gradientMethod=:ForwardEquations.
sparseJacobian::Bool=false: When solving the ODE du/dt=f(u, p, t), whether implicit solvers use a sparse Jacobian. Sparse Jacobian often performs best for large models (≥100 states).specializeLevel=SciMLBase.FullSpecialize: Specialization level when building the ODE problem. It is not recommended to change this parameter (see https://docs.sciml.ai/SciMLBase/stable/interfaces/Problems/).sensealg: Sensitivity algorithm for gradient computations. The available options for each gradient method are::ForwardDiff: None (as ForwardDiff takes care of all computation steps).:ForwardEquations: :ForwardDiff (uses ForwardDiff.jl and typicaly performs best) or ForwardDiffSensitivity() and ForwardSensitivity() from SciMLSensitivity.jl (https://github.com/SciML/SciMLSensitivity.jl).:Adjoint: InterpolatingAdjoint() and QuadratureAdjoint() from SciMLSensitivity.jl.:Zygote: All sensealg in SciMLSensitivity.jl.
sensealgSS=nothing: Sensitivity algorithm for adjoint gradient computations for steady-state simulations. The available options are SteadyStateAdjoint(), InterpolatingAdjoint(), and QuadratureAdjoint() from SciMLSensitivity.jl. SteadyStateAdjoint() is the most efficient but requires a non-singular Jacobian, and in the case of a non-singular Jacobian, the code automatically switches to InterpolatingAdjoint().chunkSize=nothing: Chunk-size for ForwardDiff.jl when computing the gradient and Hessian via forward-mode automatic differentiation. If nothing is provided, the default value is used. Tuning chunkSize is non-trivial, and we plan to add automatic functionality for this.splitOverConditions::Bool=false: For gradient and Hessian via ForwardDiff.jl, whether or not to split calls to ForwardDiff across experimental (simulation) conditions. This parameter should only be set to true if the model has many parameters specific to an experimental condition; otherwise, the overhead from the calls will increase run time. See the Beer example for a case where this is needed.reuseS::Bool=false : If set to true, reuse the sensitivities computed during gradient computations for the Gauss-Newton Hessian approximation. This option is only applicable when using hessianMethod=:GaussNewton and gradientMethod=:ForwardEquations. Note that it should only be used when the optimizer always computes the gradient before the Hessian.verbose::Bool=true : If set to true, print progress messages while setting up the PEtabODEProblem.
sourcePEtab.ODESolverOptions — TypeODESolverOptions(solver, <keyword arguments>)
ODE-solver options (solver, tolerances, etc...) to use when computing gradient/cost for a PEtabODEProblem.
More information about the available options and solvers can be found in the documentation for DifferentialEquations.jl (https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/). Recommended settings for which solver and options to use for different problems can be found below and in the documentation.
Arguments
solver: Any of the ODE solvers in DifferentialEquations.jl. For small (≤20 states) mildly stiff models, composite solvers such as AutoVern7(Rodas5P()) perform well. For stiff small models, Rodas5P() performs well. For medium-sized models (≤75 states), QNDF(), FBDF(), and CVODE_BDF() perform well. CVODE_BDF() is not compatible with automatic differentiation and thus cannot be used if the gradient is computed via automatic differentiation or if the Gauss-Newton Hessian approximation is used. If the gradient is computed via adjoint sensitivity analysis, CVODE_BDF() is often the best choice as it is typically more reliable than QNDF() and FBDF() (fails less often).abstol=1e-8: Absolute tolerance when solving the ODE system. Not recommended to increase above 1e-6 for gradients.reltol=1e-8: Relative tolerance when solving the ODE system. Not recommended to increase above 1e-6 for gradients.force_dtmin=false: Whether or not to force dtmin when solving the ODE system.dtmin=nothing: Minimal acceptable step-size when solving the ODE system.maxiters=10000: Maximum number of iterations when solving the ODE system. Increasing above the default value can cause the optimization to take substantial time.
sourcePEtab.SteadyStateSolverOptions — TypeSteadyStateSolverOptions(method::Symbol;
+ jlFilePath::String="")::PEtabModel
Parses a PEtab specified problem with a YAML-file located at pathYAML into a Julia-accessible format.
When parsing a PEtab problem, several things happen under the hood:
- The SBML file is translated into
ModelingToolkit.jl format to allow for symbolic computations of the ODE-model Jacobian. Piecewise and model events are further written into DifferentialEquations.jl callbacks. - The observable PEtab table is translated into a Julia file with functions for computing the observable (
h), noise parameter (σ), and initial values (u0). - To allow gradients via adjoint sensitivity analysis and/or forward sensitivity equations, the gradients of
h and σ are computed symbolically with respect to the ODE model's states (u) and parameters (odeProblem.p).
All of this happens automatically, and resulting files are stored under petabModel.dirJulia assuming writeToFile=true. To save time, forceBuildJlFiles=false by default, which means that Julia files are not rebuilt if they already exist.
In case a Julia model files is provided instead of a SBML file provide file path under jlFilePath.
Arguments
pathYAML::String: Path to the PEtab problem YAML file.forceBuildJuliaFiles::Bool=false: If true, forces the creation of Julia files for the problem even if they already exist.verbose::Bool=true: If true, displays verbose output during parsing.ifElseToEvent::Bool=true: If true, rewrites if-else statements in the SBML model as event-based callbacks.jlFilePath::String="": Path to an existing Julia file. Should only be provided if a Julia model file is availble.
Example
petabModel = readPEtabModel("path/to/petab/problem.yaml")
sourcePEtab.PEtabODEProblem — TypePEtabODEProblem
Everything needed to setup an optimization problem (compute cost, gradient, hessian and parameter bounds) for a PEtab model.
Note The parameter vector θ is always assumed to be on the parameter scale specified in the PEtab parameters file. If needed, θ is transformed to the linear scale inside the function call.
Fields
computeCost: For θ computes the negative likelihood (objective to minimize)computeChi2: For θ compute χ2 valuecomputeGradient!: For θ computes in-place gradient computeGradient!(gradient, θ)computeGradient: For θ computes out-place gradient gradient = computeGradient(θ)computeHessian!: For θ computes in-place hessian-(approximation) computeHessian!(hessian, θ)computeHessian: For θ computes out-place hessian-(approximation) hessian = computeHessian(θ)computeSimulatedValues: For θ compute the corresponding model (simulated) values to the measurements in the same order as in the Measurements PEtab tablecomputeResiduals: For θ compute the residuals (hmodel - hobserved)^2 / σ^2 in the same order as in the Measurements PEtab tablegradientMethod: The method used to compute the gradient (either :ForwardDiff, :ForwardEquations, :Adjoint, or :Zygote).hessianMethod: The method used to compute or approximate the Hessian (either :ForwardDiff, :BlocForwardDiff, or :GaussNewton).nParametersToEstimate: The number of parameters to estimate.θ_estNames: The names of the parameters in θ.θ_nominal: The nominal values of θ as specified in the PEtab parameters file.θ_nominalT: The nominal values of θ on the parameter scale (e.g., log) as specified in the PEtab parameters file.lowerBounds: The lower parameter bounds on the parameter scale for θ as specified in the PEtab parameters file.upperBounds: The upper parameter bounds on the parameter scale for θ as specified in the PEtab parameters file.petabModel: The PEtabModel used to construct the PEtabODEProblem.odeSolverOptions: The options for the ODE solver specified when creating the PEtabODEProblem.odeSolverGradientOptions: The options for the ODE solver gradient specified when creating the PEtabODEProblem.
sourcePEtab.createPEtabODEProblem — FunctioncreatePEtabODEProblem(petabModel::PEtabModel; <keyword arguments>)
Given a PEtabModel creates a PEtabODEProblem with potential user specified options.
The keyword arguments (described below) allow the user to choose cost, gradient, and Hessian methods, ODE solver options, and other tuneable options that can potentially make computations more efficient for some "edge-case" models. Please refer to the documentation for guidance on selecting the most efficient options for different types of models.
If a keyword argument is not set, a suitable default option is chosen based on the number of model parameters.
Note Every problem is unique, so even though the default settings often work well they might not be optimal.
Keyword arguments
odeSolverOptions::ODESolverOptions: Options for the ODE solver when computing the cost, such as solver and tolerances.odeSolverGradientOptions::ODESolverOptions: Options for the ODE solver when computing the gradient, such as the ODE solver options used in adjoint sensitivity analysis. Defaults to odeSolverOptions if not set to nothing.ssSolverOptions::SteadyStateSolverOptions: Options for finding steady-state for models with pre-equilibrium. Steady-state can be found via simulation or rootfinding, which can be set using SteadyStateSolverOptions (see documentation). If not set, defaults to simulation with wrms < 1 termination.ssSolverGradientOptions::SteadyStateSolverOptions: Options for finding steady-state for models with pre-equilibrium when computing gradients. Defaults to ssSolverOptions value if not set.costMethod::Symbol=:Standard: Method for computing the cost (objective). Two options are available: :Standard, which is the most efficient, and :Zygote, which is less efficient but compatible with the Zygote automatic differentiation library.gradientMethod=nothing: Method for computing the gradient of the objective. Four options are available::ForwardDiff: Compute the gradient via forward-mode automatic differentiation using ForwardDiff.jl. Most efficient for models with ≤50 parameters. The number of chunks can be optionally set using chunkSize.:ForwardEquations: Compute the gradient via the model sensitivities, where sensealg specifies how to solve for the sensitivities. Most efficient when the Hessian is approximated using the Gauss-Newton method and when the optimizer can reuse the sensitivities (reuseS) from gradient computations in Hessian computations (e.g., when the optimizer always computes the gradient before the Hessian).:Adjoint: Compute the gradient via adjoint sensitivity analysis, where sensealg specifies which algorithm to use. Most efficient for large models (≥75 parameters).:Zygote: Compute the gradient via the Zygote package, where sensealg specifies which sensitivity algorithm to use when solving the ODE model. This is the most inefficient option and not recommended.
hessianMethod=nothing: method for computing the Hessian of the cost. There are three available options::ForwardDiff: Compute the Hessian via forward-mode automatic differentiation using ForwardDiff.jl. This is often only computationally feasible for models with ≤20 parameters but can greatly improve optimizer convergence.:BlockForwardDiff: Compute the Hessian block approximation via forward-mode automatic differentiation using ForwardDiff.jl. The approximation consists of two block matrices: the first is the Hessian for only the dynamic parameters (parameter part of the ODE system), and the second is for the non-dynamic parameters (e.g., noise parameters). This is computationally feasible for models with ≤20 dynamic parameters and often performs better than BFGS methods.:GaussNewton: Approximate the Hessian via the Gauss-Newton method, which often performs better than the BFGS method. If we can reuse the sensitivities from the gradient in the optimizer (see reuseS), this method is best paired with gradientMethod=:ForwardEquations.
sparseJacobian::Bool=false: When solving the ODE du/dt=f(u, p, t), whether implicit solvers use a sparse Jacobian. Sparse Jacobian often performs best for large models (≥100 states).specializeLevel=SciMLBase.FullSpecialize: Specialization level when building the ODE problem. It is not recommended to change this parameter (see https://docs.sciml.ai/SciMLBase/stable/interfaces/Problems/).sensealg: Sensitivity algorithm for gradient computations. The available options for each gradient method are::ForwardDiff: None (as ForwardDiff takes care of all computation steps).:ForwardEquations: :ForwardDiff (uses ForwardDiff.jl and typicaly performs best) or ForwardDiffSensitivity() and ForwardSensitivity() from SciMLSensitivity.jl (https://github.com/SciML/SciMLSensitivity.jl).:Adjoint: InterpolatingAdjoint() and QuadratureAdjoint() from SciMLSensitivity.jl.:Zygote: All sensealg in SciMLSensitivity.jl.
sensealgSS=nothing: Sensitivity algorithm for adjoint gradient computations for steady-state simulations. The available options are SteadyStateAdjoint(), InterpolatingAdjoint(), and QuadratureAdjoint() from SciMLSensitivity.jl. SteadyStateAdjoint() is the most efficient but requires a non-singular Jacobian, and in the case of a non-singular Jacobian, the code automatically switches to InterpolatingAdjoint().chunkSize=nothing: Chunk-size for ForwardDiff.jl when computing the gradient and Hessian via forward-mode automatic differentiation. If nothing is provided, the default value is used. Tuning chunkSize is non-trivial, and we plan to add automatic functionality for this.splitOverConditions::Bool=false: For gradient and Hessian via ForwardDiff.jl, whether or not to split calls to ForwardDiff across experimental (simulation) conditions. This parameter should only be set to true if the model has many parameters specific to an experimental condition; otherwise, the overhead from the calls will increase run time. See the Beer example for a case where this is needed.reuseS::Bool=false : If set to true, reuse the sensitivities computed during gradient computations for the Gauss-Newton Hessian approximation. This option is only applicable when using hessianMethod=:GaussNewton and gradientMethod=:ForwardEquations. Note that it should only be used when the optimizer always computes the gradient before the Hessian.verbose::Bool=true : If set to true, print progress messages while setting up the PEtabODEProblem.
sourcePEtab.ODESolverOptions — TypeODESolverOptions(solver, <keyword arguments>)
ODE-solver options (solver, tolerances, etc...) to use when computing gradient/cost for a PEtabODEProblem.
More information about the available options and solvers can be found in the documentation for DifferentialEquations.jl (https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/). Recommended settings for which solver and options to use for different problems can be found below and in the documentation.
Arguments
solver: Any of the ODE solvers in DifferentialEquations.jl. For small (≤20 states) mildly stiff models, composite solvers such as AutoVern7(Rodas5P()) perform well. For stiff small models, Rodas5P() performs well. For medium-sized models (≤75 states), QNDF(), FBDF(), and CVODE_BDF() perform well. CVODE_BDF() is not compatible with automatic differentiation and thus cannot be used if the gradient is computed via automatic differentiation or if the Gauss-Newton Hessian approximation is used. If the gradient is computed via adjoint sensitivity analysis, CVODE_BDF() is often the best choice as it is typically more reliable than QNDF() and FBDF() (fails less often).abstol=1e-8: Absolute tolerance when solving the ODE system. Not recommended to increase above 1e-6 for gradients.reltol=1e-8: Relative tolerance when solving the ODE system. Not recommended to increase above 1e-6 for gradients.force_dtmin=false: Whether or not to force dtmin when solving the ODE system.dtmin=nothing: Minimal acceptable step-size when solving the ODE system.maxiters=10000: Maximum number of iterations when solving the ODE system. Increasing above the default value can cause the optimization to take substantial time.
sourcePEtab.SteadyStateSolverOptions — TypeSteadyStateSolverOptions(method::Symbol;
howCheckSimulationReachedSteadyState::Symbol=:wrms,
rootfindingAlgorithm=nothing,
abstol=nothing,
reltol=nothing,
- maxiters=nothing)
Setup options for finding steady-state via either method=:Rootfinding or method=:Simulate.
For method=:Rootfinding, the steady-state u* is found by solving the problem du = f(u, p, t) ≈ 0 with tolerances abstol and reltol via an automatically chosen optimization algorithm (rootfindingAlgorithm=nothing) or via any algorithm in NonlinearSolve.jl.
For method=:Simulate, the steady-state u* is found by simulating the ODE system until du = f(u, p, t) ≈ 0. Two options are available for howCheckSimulationReachedSteadyState:
:wrms : Weighted root-mean square √(∑((du ./ (reltol * u .+ abstol)).^2) / length(u)) < 1:Newton : If Newton-step Δu is sufficiently small √(∑((Δu ./ (reltol * u .+ abstol)).^2) / length(u)) < 1. - Newton often performs better but requires an invertible Jacobian. In case it's not fulfilled, the code switches automatically to :wrms.
maxiters refers to either the maximum number of rootfinding steps or the maximum number of integration steps, depending on the chosen method.
sourcePEtab.remakePEtabProblem — FunctionremakePEtabProblem(petabProblem::PEtabODEProblem, parametersChange::Dict) :: PEtabODEProblem
Fixate model parameters for a given PEtabODEProblem without recompiling the problem.
This function allows you to modify parameters without the need to recompile the underlying code, resulting in reduced latency. To fixate the parameter k1, you can use parametersChange=Dict(:k1 => 1.0).
If model derivatives are computed using ForwardDiff.jl with a chunk-size of N, the new PEtabODEProblem will only evaluate the necessary number of chunks of size N to compute the full gradient for the remade problem.
sourcePEtab.Fides — TypeFides
Fides is a Python Newton-trust region optimizer for box-bounded optimization problems.
It is particularly effective when the full Hessian cannot be computed, but the Gauss-Newton Hessian approximation can be computed. If constructed with Fides(verbose=true), it prints optimization progress during the process.
sourcePEtab.callibrateModel — FunctioncalibrateModel(petabProblem::PEtabODEProblem,
+ maxiters=nothing)
Setup options for finding steady-state via either method=:Rootfinding or method=:Simulate.
For method=:Rootfinding, the steady-state u* is found by solving the problem du = f(u, p, t) ≈ 0 with tolerances abstol and reltol via an automatically chosen optimization algorithm (rootfindingAlgorithm=nothing) or via any algorithm in NonlinearSolve.jl.
For method=:Simulate, the steady-state u* is found by simulating the ODE system until du = f(u, p, t) ≈ 0. Two options are available for howCheckSimulationReachedSteadyState:
:wrms : Weighted root-mean square √(∑((du ./ (reltol * u .+ abstol)).^2) / length(u)) < 1:Newton : If Newton-step Δu is sufficiently small √(∑((Δu ./ (reltol * u .+ abstol)).^2) / length(u)) < 1. - Newton often performs better but requires an invertible Jacobian. In case it's not fulfilled, the code switches automatically to :wrms.
maxiters refers to either the maximum number of rootfinding steps or the maximum number of integration steps, depending on the chosen method.
sourcePEtab.remakePEtabProblem — FunctionremakePEtabProblem(petabProblem::PEtabODEProblem, parametersChange::Dict) :: PEtabODEProblem
Fixate model parameters for a given PEtabODEProblem without recompiling the problem.
This function allows you to modify parameters without the need to recompile the underlying code, resulting in reduced latency. To fixate the parameter k1, you can use parametersChange=Dict(:k1 => 1.0).
If model derivatives are computed using ForwardDiff.jl with a chunk-size of N, the new PEtabODEProblem will only evaluate the necessary number of chunks of size N to compute the full gradient for the remade problem.
sourcePEtab.Fides — TypeFides
Fides is a Python Newton-trust region optimizer for box-bounded optimization problems.
It is particularly effective when the full Hessian cannot be computed, but the Gauss-Newton Hessian approximation can be computed. If constructed with Fides(verbose=true), it prints optimization progress during the process.
sourcePEtab.callibrateModel — FunctioncalibrateModel(petabProblem::PEtabODEProblem,
optimizer;
- <keyword arguments>)
Perform multi-start local optimization for a given PEtabODEProblem and return (fmin, minimizer) for all runs.
Arguments
petabProblem::PEtabODEProblem: The PEtabODEProblem to be calibrated.optimizer: The optimizer algorithm to be used. Currently, we support three different algorithms:Fides(): The Newton trust-region Fides optimizer from Python. Please refer to the documentation for setup examples. This optimizer performs well when computing the full Hessian is not possible, and the Gauss-Newton Hessian approximation can be used.IPNewton(): The interior-point Newton method from Optim.jl. This optimizer performs well when it is computationally feasible to compute the full Hessian.LBFGS() or BFGS() from Optim.jl: These optimizers are suitable when the computation of the Gauss-Newton Hessian approximation is too expensive, such as when adjoint sensitivity analysis is required for the gradient.
nOptimisationStarts::Int: Number of multi-starts to be performed. Defaults to 100.samplingMethod: Method for generating start guesses. Any method from QuasiMonteCarlo.jl is supported, with LatinHypercube as the default.options: Optimization options. For Optim.jl optimizers, it accepts an Optim.Options struct. For Fides, please refer to the Fides documentation and the PEtab.jl documentation for information on setting options.
sourcePEtab.runPEtabSelect — FunctionrunPEtabSelect(pathYAML, optimizer; <keyword arguments>)
Given a PEtab-select YAML file perform model selection with the algorithms specified in the YAML file.
Results are written to a YAML file in the same directory as the PEtab-select YAML file.
Each candidate model produced during the model selection undergoes parameter estimation using local multi-start optimization. Three optimizers are supported: optimizer=Fides() (Fides Newton-trust region), optimizer=IPNewton() from Optim.jl, and optimizer=LBFGS() from Optim.jl. Additional keywords for the optimisation are nOptimisationStarts::Int- number of multi-starts for parameter estimation (defaults to 100) and optimizationSamplingMethod - which is any sampling method from QuasiMonteCarlo.jl for generating start guesses (defaults to LatinHypercubeSample). See also (add callibrate model)
Simulation options can be set using any keyword argument accepted by the createPEtabODEProblem function. For example, setting gradientMethod=:ForwardDiff specifies the use of forward-mode automatic differentiation for gradient computation. If left blank, we automatically select appropriate options based on the size of the problem.
sourcePEtab.solveSBMLModel — FunctionsolveSBMLModel(pathSBML, solver, timeSpan; abstol=1e-8, reltol=1e-8, saveat=Float64[], verbose=true)
Solve an ODE SBML model at the values reported in the SBML file over the specified time span (t0::Float, tend::Float).
Solvers from the OrdinaryDiffEq.jl package are supported. If you want to save the ODE solution at specific time-points, e.g., [1.0, 3.0], provide the saveat argument as saveat=[1.0, 3.0]. The output is provided in the format of OrdinaryDiffEq.jl. The Julia model files are saved in the same directory as the SBML file, in a subdirectory named "SBML".
Note This function is primarily intended for testing the SBML importer.
sourceSettings
This document was generated with Documenter.jl version 0.27.25 on Monday 14 August 2023. Using Julia version 1.8.5.
Perform multi-start local optimization for a given PEtabODEProblem and return (fmin, minimizer) for all runs.
Arguments
petabProblem::PEtabODEProblem: The PEtabODEProblem to be calibrated.optimizer: The optimizer algorithm to be used. Currently, we support three different algorithms:Fides(): The Newton trust-region Fides optimizer from Python. Please refer to the documentation for setup examples. This optimizer performs well when computing the full Hessian is not possible, and the Gauss-Newton Hessian approximation can be used.IPNewton(): The interior-point Newton method from Optim.jl. This optimizer performs well when it is computationally feasible to compute the full Hessian.LBFGS()orBFGS()from Optim.jl: These optimizers are suitable when the computation of the Gauss-Newton Hessian approximation is too expensive, such as when adjoint sensitivity analysis is required for the gradient.
nOptimisationStarts::Int: Number of multi-starts to be performed. Defaults to 100.samplingMethod: Method for generating start guesses. Any method from QuasiMonteCarlo.jl is supported, with LatinHypercube as the default.options: Optimization options. For Optim.jl optimizers, it accepts anOptim.Optionsstruct. For Fides, please refer to the Fides documentation and the PEtab.jl documentation for information on setting options.
PEtab.runPEtabSelect — FunctionrunPEtabSelect(pathYAML, optimizer; <keyword arguments>)Given a PEtab-select YAML file perform model selection with the algorithms specified in the YAML file.
Results are written to a YAML file in the same directory as the PEtab-select YAML file.
Each candidate model produced during the model selection undergoes parameter estimation using local multi-start optimization. Three optimizers are supported: optimizer=Fides() (Fides Newton-trust region), optimizer=IPNewton() from Optim.jl, and optimizer=LBFGS() from Optim.jl. Additional keywords for the optimisation are nOptimisationStarts::Int- number of multi-starts for parameter estimation (defaults to 100) and optimizationSamplingMethod - which is any sampling method from QuasiMonteCarlo.jl for generating start guesses (defaults to LatinHypercubeSample). See also (add callibrate model)
Simulation options can be set using any keyword argument accepted by the createPEtabODEProblem function. For example, setting gradientMethod=:ForwardDiff specifies the use of forward-mode automatic differentiation for gradient computation. If left blank, we automatically select appropriate options based on the size of the problem.
PEtab.solveSBMLModel — FunctionsolveSBMLModel(pathSBML, solver, timeSpan; abstol=1e-8, reltol=1e-8, saveat=Float64[], verbose=true)
Solve an ODE SBML model at the values reported in the SBML file over the specified time span (t0::Float, tend::Float).
Solvers from the OrdinaryDiffEq.jl package are supported. If you want to save the ODE solution at specific time-points, e.g., [1.0, 3.0], provide the saveat argument as saveat=[1.0, 3.0]. The output is provided in the format of OrdinaryDiffEq.jl. The Julia model files are saved in the same directory as the SBML file, in a subdirectory named "SBML".
This function is primarily intended for testing the SBML importer.