API Documentation
Create a model
ReactiveDynamics.@ReactionNetwork — MacroMacro that takes an expression corresponding to a reaction network and outputs an instance of TheoryReactionNetwork that can be converted to a DiscreteProblem or solved directly.
Most arrows accepted (both right, left, and bi-drectional arrows). Use 0 or ∅ for annihilation/creation to/from nothing.
Custom functions and sampleable objects can be used as numeric parameters. Note that these have to be accessible from ReactiveDynamics's source code.
Examples
acs = @ReactionNetwork begin
+ 1.0, X ⟶ Y
+ 1.0, X ⟶ Y, priority => 6.0, prob => 0.7, capacity => 3.0
+ 1.0, ∅ --> (Poisson(0.3γ)X, Poisson(0.5)Y)
+ (XY > 100) && (XY -= 1)
+end
+@push acs 1.0 X ⟶ Y
+@prob_init acs X = 1 Y = 2 XY = α
+@prob_params acs γ = 1 α = 4
+@solve_and_plot acsModify a model
We list common transition attributes. When being specified using the @ReactionNetwork macro they can be conveniently referred to using their shorthand description.
| attribute | shorthand | interpretation |
|---|---|---|
transPriority | priority | priority of a transition (influences resource allocation) |
transProbOfSuccess | probability prob pos | probability that a transition terminates successfully |
transCapacity | cap capacity | maximum number of concurrent instances of the transition |
transCycleTime | ct cycletime | duration of a transition's instance (adjusted by resource allocation) |
transMaxLifeTime | lifetime maxlifetime maxtime timetolive | maximal duration of a transition's instance |
transPostAction | postAction post | action to be executed once a transition's instance terminates |
transName | name interpretation | name of a transition, either a string or unquoted text |
We list common species attributes:
| attribute | shorthand | interpretation |
|---|---|---|
specInitUncertainty | uncertainty stoch stochasticity | uncertainty about variable's initial state (modelled as Gaussian standard deviation) |
specInitVal | initial value of a variable |
Moreover, it is possible to specify the semantics of the "rate" term. By default, at each time step n ~ Poisson(rate * dt) instances of a given transition will be spawned. If you want to specify the rate in terms of a cycle time, you may want to use @ct(cycle_time), e.g., @ct(ex), A --> B, .... This is a shorthand for 1/ex, A --> B, ....
For deterministic "rates", use @per_step(ex). Here, ex evaluates to a deterministic number (ceiled to the nearest integer) of a transition's instances to spawn per a single integrator's step. However, note that in this case, the number doesn't scale with the step length! Moreover
ReactiveDynamics.@add_species — MacroAdd new species to a model.
Examples
@add_species acs S I RReactiveDynamics.@aka — MacroAlias object name in an acs.
Default names
| name | short name |
|---|---|
| species | S |
| transition | T |
| action | A |
| event | E |
| param | P |
| meta | M |
Examples
@aka acs species = resource transition = reactionReactiveDynamics.@mode — MacroSet species modality.
Supported modalities
- nonblock
- conserved
- rate
Examples
@mode acs (r"proj\w+", r"experimental\w+") conserved
+@mode acs (S, I) conserved
+@mode acs S conservedReactiveDynamics.@name_transition — MacroSet name of a transition in the model.
Examples
@name_transition acs 1 = "name"
+@name_transition acs name = "transition_name"
+@name_transition acs "name" = "transition_name"Resource costs
ReactiveDynamics.@cost — MacroSet cost.
Examples
@cost model experimental1=2 experimental2=3ReactiveDynamics.@valuation — MacroSet valuation.
Examples
@valuation model experimental1=2 experimental2=3ReactiveDynamics.@reward — MacroSet reward.
Examples
@reward model experimental1=2 experimental2=3Add reactions
ReactiveDynamics.@push — MacroAdd reactions to an acset.
Examples
@push sir_acs β * S * I * tdecay(@time()) S + I --> 2I name => SI2I
+@push sir_acs begin
+ ν * I, I --> R, name => I2R
+ γ, R --> S, name => R2S
+endReactiveDynamics.@jump — MacroAdd a jump process (with specified Poisson intensity per unit time step) to a model.
Examples
@jump acs λ Z += rand(Poisson(1.0))ReactiveDynamics.@periodic — MacroAdd a periodic callback to a model.
Examples
@periodic acs 1.0 X += 1Set initial values, uncertainty, and solver arguments
ReactiveDynamics.@prob_init — MacroSet initial values of species in an acset.
Examples
@prob_init acs X = 1 Y = 2 Z = h(α)
+@prob_init acs [1.0, 2.0, 3.0]ReactiveDynamics.@prob_uncertainty — MacroSet uncertainty in initial values of species in an acset (stderr).
Examples
@prob_uncertainty acs X = 0.1 Y = 0.2
+@prob_uncertainty acs [0.1, 0.2]ReactiveDynamics.@prob_params — MacroSet parameter values in an acset.
Examples
@prob_params acs α = 1.0 β = 2.0ReactiveDynamics.@prob_meta — MacroSet model metadata (e.g. solver arguments)
Examples
@prob_meta acs tspan = (0, 100.0) schedule = schedule_weighted!
+@prob_meta sir_acs tspan = 250 tstep = 1Model unions
ReactiveDynamics.@join — Macro@join models... [equalize...]Performs join of models and identifies model variables, as specified.
Model variables / parameter values and metadata are propagated; the last model takes precedence.
Examples
@join acs1 acs2 @catchall(A) = acs2.Z @catchall(XY) @catchall(B)ReactiveDynamics.@equalize — MacroIdentify (collapse) a set of species in a model.
Examples
@join acs acs1.A = acs2.A B = CModel import and export
ReactiveDynamics.@import_network — MacroImport a model from a file: this can be either a single TOML file encoding the entire model, or a batch of CSV files (a root file and a number of files, each per a class of objects).
See tutorials/loadsave for an example.
Examples
@import_network "model.toml"
+@import_network "csv/model.toml"ReactiveDynamics.@export_network — MacroExport model to a file: this can be either a single TOML file encoding the entire model, or a batch of CSV files (a root file and a number of files, each per a class of objects).
See tutorials/loadsave for an example.
Examples
@export_network acs "acs_data.toml" # as a TOML
+@export_network acs "csv/model.csv" # as a CSVSolution import and export
ReactiveDynamics.@import_solution — Macro@import_solution "sol.jld2"
+@import_solution "sol.jld2" solImport a solution from a file.
Examples
@import_solution "sir_acs_sol/serialized/sol.jld2"ReactiveDynamics.@export_solution_as_table — Macro@export_solution_as_table solExport a solution as a DataFrame.
Examples
@export_solution_as_table solReactiveDynamics.@export_solution_as_csv — Macro@export_solution_as_csv sol
+@export_solution_as_csv sol "sol.csv"Export a solution to a file.
Examples
@export_solution_as_csv sol "sol.csv"ReactiveDynamics.@export_solution — Macro@export_solution sol
+@export_solution sol "sol.jld2"Export a solution to a file.
Examples
@export_solution sol "sol.jdl2"Problematize,sSolve, and plot
ReactiveDynamics.@problematize — MacroConvert a model to a DiscreteProblem. If passed a problem instance, return the instance.
Examples
@problematize acs tspan = 1:100ReactiveDynamics.@solve — MacroSolve the problem. Solverargs passed at the calltime take precedence.
Examples
@solve prob
+@solve prob tspan = 1:100
+@solve prob tspan = 100 trajectories = 20ReactiveDynamics.@plot — MacroPlot the solution (summary).
Examples
@plot sol plot_type = summary
+@plot sol plot_type = allocation # not supported for ensemble solutions!
+@plot sol plot_type = valuations # not supported for ensemble solutions!
+@plot sol plot_type = new_transitions # not supported for ensemble solutions!Optimization and fitting
ReactiveDynamics.@optimize — Macro@optimize acset objective <free_var=[init_val]>... <free_prm=[init_val]>... opts...Take an acset and optimize given functional.
Objective is an expression which may reference the model's variables and parameters, i.e., A+β. The values to optimized are listed using their symbolic names; unless specified, the initial value is inferred from the model. The vector of free variables passed to the NLopt solver has the form [free_vars; free_params]; order of vars and params, respectively, is preserved.
By default, the functional is minimized. Specify objective=max to perform maximization.
Propagates NLopt solver arguments; see NLopt documentation.
Examples
@optimize acs abs(A - B) A B = 20.0 α = 2.0 lower_bounds = 0 upper_bounds = 100
+@optimize acss abs(A - B) A B = 20.0 α = 2.0 upper_bounds = [200, 300, 400] maxeval = 200 objective =
+ minReactiveDynamics.@fit — Macro@fit acset data_points time_steps empiric_variables <free_var=[init_val]>... <free_prm=[init_val]>... opts...Take an acset and fit initial values and parameters to empirical data.
The values to optimized are listed using their symbolic names; unless specified, the initial value is inferred from the model. The vector of free variables passed to the NLopt solver has the form [free_vars; free_params]; order of vars and params, respectively, is preserved.
Propagates NLopt solver arguments; see NLopt documentation.
Examples
t = [1, 50, 100]
+data = [80 30 20]
+@fit acs data t vars = A B = 20 A α # fit B, A, α; empirical data is for variable AReactiveDynamics.@fit_and_plot — Macro@fit acset data_points time_steps empiric_variables <free_var=[init_val]>... <free_prm=[init_val]>... opts...Take an acset, fit initial values and parameters to empirical data, and plot the result.
The values to optimized are listed using their symbolic names; unless specified, the initial value is inferred from the model. The vector of free variables passed to the NLopt solver has the form [free_vars; free_params]; order of vars and params, respectively, is preserved.
Propagates NLopt solver arguments; see NLopt documentation.
Examples
t = [1, 50, 100]
+data = [80 30 20]
+@fit acs data t vars = A B = 20 A α # fit B, A, α; empirical data is for variable AReactiveDynamics.@build_solver — Macro@build_solver acset <free_var=[init_val]>... <free_prm=[init_val]>... opts...Take an acset and export a solution as a function of free vars and free parameters.
Examples
solver = @build_solver acs S α β # function of variable S and parameters α, β
+solver([S, α, β])