API Documentation

Create a model

ReactiveDynamics.@ReactionNetwork — Macro

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

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.

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 — Macro

Add new species to a model.

Examples

@add_species acs S I R

ReactiveDynamics.@aka — Macro

Alias 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 = reaction

ReactiveDynamics.@mode — Macro

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

ReactiveDynamics.@name_transition — Macro

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"

Resource costs

ReactiveDynamics.@cost — Macro

Set cost.

Examples

@cost model experimental1=2 experimental2=3

ReactiveDynamics.@valuation — Macro

Set valuation.

Examples

@valuation model experimental1=2 experimental2=3

ReactiveDynamics.@reward — Macro

Set reward.

Examples

@reward model experimental1=2 experimental2=3

Add reactions

ReactiveDynamics.@push — Macro

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

ReactiveDynamics.@jump — Macro

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

Examples

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

ReactiveDynamics.@periodic — Macro

Add a periodic callback to a model.

Examples

@periodic acs 1.0 X += 1

Set initial values, uncertainty, and solver arguments

ReactiveDynamics.@prob_init — Macro

Set 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 — Macro

Set 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 — Macro

Set parameter values in an acset.

Examples

@prob_params acs α = 1.0 β = 2.0

ReactiveDynamics.@prob_meta — Macro

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

Model 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 — Macro

Identify (collapse) a set of species in a model.

Examples

@join acs acs1.A = acs2.A B = C

Model import and export

ReactiveDynamics.@import_network — Macro

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"

ReactiveDynamics.@export_network — Macro

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

Solution import and export

ReactiveDynamics.@import_solution — Macro

@import_solution "sol.jld2"
@import_solution "sol.jld2" sol

Import a solution from a file.

Examples

@import_solution "sir_acs_sol/serialized/sol.jld2"

ReactiveDynamics.@export_solution_as_table — Macro

@export_solution_as_table sol

Export a solution as a DataFrame.

Examples

@export_solution_as_table sol

ReactiveDynamics.@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 — Macro

Convert a model to a DiscreteProblem. If passed a problem instance, return the instance.

Examples

@problematize acs tspan = 1:100

ReactiveDynamics.@solve — Macro

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

Examples

@solve prob
@solve prob tspan = 1:100
@solve prob tspan = 100 trajectories = 20

ReactiveDynamics.@plot — Macro

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!

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 =
    min

ReactiveDynamics.@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 A

ReactiveDynamics.@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 A

ReactiveDynamics.@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, α, β])