Kinetica.jl API
Simulation Parameters
Kinetica.ODESimulationParams
— TypeKeyword-defined container for ODE-driven simulation parameters.
Contains fields for:
- Simulation timespan (must match time unit used in an attached calculator) (
tspan
) - Initial concentrations of species, either as a Dict of certain species or a Vector of all species (
u0
) - DifferentialEquations ODE solver (
solver
) - Whether to use ModelingToolkit to formulate an analytical Jacobian (
do_jac=true
) - Whether to use ModelingToolkit to formulate a sparse problem (
do_sparse=true
) - Absolute tolerance of ODE solver (
abstol=1e-10
) - Relative tolerance of ODE solver (
reltol=1e-8
) - Whether to use adaptive solver tolerance (
adaptive_tols=true
) - Whether to update solver tolerances after successful solve with adaptive tolerance (
update_tols=false
) - Whether to break solution into chunks of size
solve_chunkstep
to avoid floating point underflow (solve_chunks=true
) - Global timestep at which solution should be reinitialised when
solve_chunks=true
(solve_chunkstep=1e-3
) - Maximum number of ODE solver iterations (
maxiters=1e5
) - Whether to explicitly disallow negative values in the solver (
ban_negatives=false
) - Whether to display progress bars - requires
TerminalLogger
initialisation (progress=false
) - Time interval to interpolate solution data on (
save_interval=nothing
) - Cutoff below which reactions with low rate constants are removed from the network (
low_k_cutoff=:auto
) - Maximum species concentrationto multiply maximum reaction rates by un low rate cutoff (
low_k_maxconc=2.0
) - Whether to allow a vector
u0
to be shorter than the number of species in the network (allow_short_u0=false
)
Kinetic Calculators (Kinetica.jl)
Kinetica.allows_continuous
— Functionallows_continuous(calculator<:AbstractKineticCalculator)
Indicates whether a calculator
is allowed to function in continuous variable rate constant simulations.
Should only ever return true
for calculators with analytic expressions for rate constants, as only these can be encoded within Symbolics and MTK.
Calculators relying on external function calls should therefore return false
, as these calls cannot be encoded. These calculators will only be functional for discrete rate constant update simulations.
Kinetica.setup_network!
— Functionsetup_network!(sd::SpeciesData, rd::RxData, calculator<:AbstractKineticCalculator)
Sets up a network for calculation with the provided calculator
.
Must be implemented for each calculator
. Called at the start of a kinetic simulation to check compatibility of network with calculator, and to populate network-dependent fields within the calculator.
Kinetica.has_conditions
— Functionhas_conditions(calculator<:AbstractKineticCalculator, symbols::Vector{Symbol})
Checks if the provided calculator
permits calculations with the conditions in symbols
.
Implemented as a method for every calculator type. If any of the symbolic experimental conditions in symbols
are not listed in the calculator
's method, this returns false
.
Base.splice!
— Methodsplice!(calculator, rids)
Removes all information from the reactions at rids
from calculator
.
Useful in conjunction with splice!(rd, rids)
for removing e.g. low-rate reactions that have been removed from a network from that network's calculator.
Relies on a calculator-specific implementation, as it directly modifies fields of that calculator.
Base.splice!
— Methodsplice!(rd, calculator, rids)
Convenience wrapper for deleting reaction data from both a network and its calculator.
Kinetica.PrecalculatedArrheniusCalculator
— TypePrecalculatedArrheniusCalculator(Ea, A[, k_max=nothing, t_unit="s"])
Arrhenius theory kinetic calculator for precalculated reactions.
Kinetic calculator that uses the Arrhenius equation to determine rates of reaction. Requires prior specification of reaction activation energies (Ea
) and Arrhenius prefactors (A
), will not calculate/predict these internally.
Implemented conditions:
- Temperature (
T
, unit: K)
Requires:
- Activation energies (
Ea
, unit: J/mol) - Arrhenius prefactors (
A
, unit: mol dm^-3 s^-1 assuming bimolecular reactions)
Has support for dispatching with/without a maximum rate constant k_max
and scaling by time unit t_unit
(assuming rates are provided in units of /s).
(calc::PrecalculatedArrheniusCalculator)(; T)
Calculate rates with precalculated Arrhenius theory kinetic calculator.
Requires temperature (T
) as a keyword argument.
Automatically dispatches to a method with correct formula for k_max
-aware calculation if this is defined in the underlying PrecalculatedArrheniusCalculator
.
The ASENEBCalculator
ASE-driven NEB-based calculator also implemented in Kinetica.jl is significantly more complex, and has its own API page here.
Solvers
Kinetica.StaticODESolve
— TypeStaticODESolve(pars::ODESimulationParams, conditions::ConditionSet, calculator<:AbstractKineticCalculator[, filter::RxFilter])
Static kinetic CRN solver type.
Combines all parameter inputs, conditions, a calculator and a set of reaction filters into a single type to be passed to the solver.
All conditions in the provided ConditionSet
must be static (defined as a single number), and also must be compatible with the provided calculator.
Allows for optional specification of RxFilter
. If not defined, creates a filter that allows all reactions.
Kinetica.VariableODESolve
— TypeVariableODESolve(pars::ODESimulationParams, conditions::ConditionSet, calculator<:AbstractKineticCalculator[, filter::RxFilter])
Variable kinetic CRN solver type.
Combines all parameter inputs, conditions, a calculator and a set of reaction filters into a single type to be passed to the solver.
Conditions in the provided ConditionSet
must be compatible with the calculator and can be a combination of static and variable. However, this will throw an error if all conditions are static, as a StaticODESolve
should be used instead.
Allows for optional specification of RxFilter
. If not defined, creates a filter that allows all reactions.
Kinetica.solve_network
— Functionsolve_network(method::StaticODESolve, sd::SpeciesData, rd::RxData[, copy_network=true, return_integrator=false])
Solve a network with static kinetics.
Automatically dispatches to the correct method based on the value of method.pars.solve_chunks
, as chunkwise solution requires a significantly different approach.
Setting copy_network=true
generates a deepcopy
of the original network in rd
and sd
and uses these in the solution, to avoid side effects from calculators modifying the original network that is passed in. The copied (modified) network is returned as part of the resulting ODESolveOutput
.
Setting return_integrator=true
sets up and returns the underlying integrator without solving (i.e. at t = method.pars.tspan[1]
), allowing for manual stepping through the solution. Note that chunkwise solutions implement many reinitialisations of this integrator, which will have to be mirrored in the calling script to get the same results.
solve_network(method::VariableODESolve, sd::SpeciesData, rd::RxData[, copy_network=true, return_integrator=false])
Solve a network with variable kinetics.
Automatically dispatches to the correct method based on the value of method.pars.solve_chunks
and method.conditions.ts_update
, as chunkwise and discrete solutions require significantly different approaches.
Setting copy_network=true
generates a deepcopy
of the original network in rd
and sd
and uses these in the solution, to avoid side effects from calculators modifying the original network that is passed in. The copied (modified) network is returned as part of the resulting ODESolveOutput
.
Setting return_integrator=true
sets up and returns the underlying integrator without solving (i.e. at t = method.pars.tspan[1]
), allowing for manual stepping through the solution. Note that chunkwise solutions implement many reinitialisations of this integrator, which will have to be mirrored in the calling script to get the same results.
Reaction Filtering
Kinetica.RxFilter
— TypeRxFilter(filters[, keep_filtered=false])
Data container for CRN filters.
Defines a set of functions which can be used on a network to construct a set of masks of reactions. These reactions can then be excluded from a network, or their inverse can be taken to exclude all other reactions form a network.
Contains fields for:
- Array of filter functions, each taking a tuple of
::SpeciesData
and::RxData
as arguments (filters
) - Whether to remove or keep masked reactions (
keep_filtered
)
Can be constructed blank (rf = RxFilter()
) to obtain a mask of all reactions, which are then kept. Can also be constructed as rf = RxFilter(filters)
to default to removing the filtered reactions.