Kinetica.jl API

Keyword-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)

allows_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.

setup_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.

has_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.

splice!(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.

splice!(rd, calculator, rids)

Convenience wrapper for deleting reaction data from both a network and its calculator.

PrecalculatedArrheniusCalculator(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.

StaticODESolve(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.

VariableODESolve(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.

solve_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.

RxFilter(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.