API Documentation

Create a model

ReactiveDynamics.@ReactionNetworkMacro

Macro 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 acs
source

Modify a model

We list common transition attributes. When being specified using the @ReactionNetwork macro they can be conveniently referred to using their shorthand description.

attributeshorthandinterpretation
transPriorityprioritypriority of a transition (influences resource allocation)
transProbOfSuccessprobability prob posprobability that a transition terminates successfully
transCapacitycap capacitymaximum number of concurrent instances of the transition
transCycleTimect cycletimeduration of a transition's instance (adjusted by resource allocation)
transMaxLifeTimelifetime maxlifetime maxtime timetolivemaximal duration of a transition's instance
transPostActionpostAction postaction to be executed once a transition's instance terminates
transNamename interpretationname of a transition, either a string or unquoted text

We list common species attributes:

attributeshorthandinterpretation
specInitUncertaintyuncertainty stoch stochasticityuncertainty about variable's initial state (modelled as Gaussian standard deviation)
specInitValinitial 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.@akaMacro

Alias object name in an acs.

Default names

nameshort name
speciesS
transitionT
actionA
eventE
paramP
metaM

Examples

@aka acs species = resource transition = reaction
source
ReactiveDynamics.@modeMacro

Set 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 conserved
source
ReactiveDynamics.@name_transitionMacro

Set 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"
source

Resource costs

Add reactions

ReactiveDynamics.@pushMacro

Add 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
end
source
ReactiveDynamics.@jumpMacro

Add a jump process (with specified Poisson intensity per unit time step) to a model.

Examples

@jump acs λ Z += rand(Poisson(1.0))
source

Set initial values, uncertainty, and solver arguments

ReactiveDynamics.@prob_metaMacro

Set model metadata (e.g. solver arguments)

Examples

@prob_meta acs tspan = (0, 100.0) schedule = schedule_weighted!
@prob_meta sir_acs tspan = 250 tstep = 1
source

Model unions

ReactiveDynamics.@joinMacro
@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)
source

Model import and export

ReactiveDynamics.@import_networkMacro

Import 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"
source
ReactiveDynamics.@export_networkMacro

Export 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 CSV
source

Solution import and export

ReactiveDynamics.@import_solutionMacro
@import_solution "sol.jld2"
@import_solution "sol.jld2" sol

Import a solution from a file.

Examples

@import_solution "sir_acs_sol/serialized/sol.jld2"
source

Problematize,sSolve, and plot

ReactiveDynamics.@solveMacro

Solve the problem. Solverargs passed at the calltime take precedence.

Examples

@solve prob
@solve prob tspan = 1:100
@solve prob tspan = 100 trajectories = 20
source
ReactiveDynamics.@plotMacro

Plot 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!
source

Optimization and fitting

ReactiveDynamics.@optimizeMacro
@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 =
    min
source
ReactiveDynamics.@fitMacro
@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 A
source
ReactiveDynamics.@fit_and_plotMacro
@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 A
source
ReactiveDynamics.@build_solverMacro
@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, α, β])
source