References

Reaction{C,U}

Contain a "calculate" function and an "update" function. The "calculate" function calculates the a "rate" of reaction with the system state, which determines the probability weight of the reaction be selected, and the "update" function updates the system state, when this reaction were selected randomly.

gillespie!(hook!, rng::AbstractRNG, c::ContinuousClock, ps::NamedTuple, rs::Tuple)

Simulate the system using the Gillespie algorithm with the given parameters, and return a tuple of end time and the terminate state :finnish, :zero or any other state returns by the hook!. The terminate state :finnish means that simulation reach to the end time, and :zero means the simulation break because the total "reaction rate" is zero, besides, hook! should return a symbol terminate state like :break. if the return value of hook! is not :finnish, the simulation will be terminated. The clock c and parameters ps will be updated during the simulation.

Arguments

• hook!: a function with similar arguments to "update" functions, and it's recommended to create hook! with @ufunc macro; unlike "update" functions, hook will be called after each reaction and should return a terminate state used to terminate the simulation if it is not :finnish.
• rng: a random number generator for generate random numbers;
• c: a clock recording time, which must be the reference clock of recorded variables in ps;
• ps: a NamedTuple contains state, parameters even args used by hook! of the system;
• rs: a tuple contains reactions, all parameters required by reactions must be in ps with same name.

gillespie([hook!, rng::AbstractRNG,] c, ps::NamedTuple, rs::Tuple)

Simulate the system using the Gillespie algorithm with the given parameters, and return a tuple of updated ps, end time and terminate state. More about terminate state, see gillespie!.

Arguments

• hook!: a function with similar arguments to "update" functions and recommended to created with @ufunc macro; unlike "update" functions, hook will be called after each reaction and should return a terminate state used to terminate the simulation if it is not :finnish.
• rng: a random number generator for generate random numbers;
• c: a ContinuousClock, a end time or a tuple of a begin and a end time;
• ps: a NamedTuple contains state, parameters even args used by hook! of the system;
• rs: a tuple contains reactions, all parameters required by reactions must be in ps with same name.

sample(A::AbstractArray{<:Real,N}, rn::Real) -> CartesianIndex{N}

Select a cartesian index of given weight array A and random number rn, where A should be an AbstractArray with element type of Real.

Example

julia> A = reshape(1:4, 2, 2)
2×2 reshape(::UnitRange{Int64}, 2, 2) with eltype Int64:
 1  3
 2  4

julia> EvolutionaryModelingTools.sample(A, 1)
CartesianIndex(1, 1)

julia> EvolutionaryModelingTools.sample(A, 2)
CartesianIndex(2, 1)

julia> EvolutionaryModelingTools.sample(A, 4)
CartesianIndex(1, 2)

julia> EvolutionaryModelingTools.sample(A, 7)
CartesianIndex(2, 2)

@cfunc ex

Define a "calculation" function with an "adapter" methods used to parse args from model. "calculate" functions take arguments from system state and calculate "rate"s determining the probability weight of the reaction be selected.

Example

For function definition:

@cfunc @inline growth_c(r, x::Vector) = r * x # function to calculate "growth rate"

This macro creates two methods, an "adapter" method

growth_c(args::NamedTuple) = growth_c(args.r, args.x)

and the origin method

@inline growth_c(r, x::Vector) = r * x

@quickloop ex opts...

Generate a function to calculate given expression with nested loops.

Example

@quickloop x[i] * m[i, j] * y[j]

will generate a function

(m, y, x)->begin
    ret = Array{...}(undef, size(m, 1), size(m, 2)) # expression for type inference is omitted
    @fastmath @inbounds for j = axes(m, 2), i = axes(m, 1)
        ret[i, j] = x[i] * m[i, j] * y[j]
    end
    return ret
end

where the size of return array is determined automatically. The size can be specified by

@quickloop z[j, i] := x[i] * m[i, j] * y[j]

which will generate a function

(m, y, x)->begin
    z = Array{...}(undef, size(m, 2), size(m, 1)) # expression for type inference is omitted
    @fastmath @inbounds for i = axes(m, 1), j = axes(m, 2)
        z[j, i] = x[i] * m[i, j] * y[j]
    end
    return z
end

where the return value is named by z and the size of return array is (size(m, 2), size(m, 1)) instead of (size(m, 1), size(m, 2)).

Options

Options should be specified like @quickloop ex opt=true/false or @quickloop ex opt, if the value of option is omitted, it will be treated as true.

• avx or turbo: use LoopVectorization to accelerate the loop, default is false, unless LoopVectorization have be loaded.
• inbounds: use @inbounds to accelerate the loop, default is true, this option is ignored if avx or turbo is enabled.
• fastmath: use @fastmath to accelerate the loop, default is true, this option is ignored if avx or turbo is enabled.
• offset: if true, input arrays will be treat as offset arrays, default is false.

@reaction name ex

Define a Reaction with the given name and ex.

@reaction growth begin
    r * x # "calculate" expression
    begin
        i = ind[1]
        x[i] += 1 # "update" expression
    end
end

will create a Reaction with a "calculation" function:

@cfunc Base.@propagate_inbounds growth_c(r, x) = r * x

and an "update" function:

@ufunc Base.@propagate_inbounds growth_u!(ind, x) = begin
    i = ind[1]
    x[i] += 1
end

where arguments of functions were collected from given expression automatically.

This macro cannot parse macro expression. Thus in some cases, arguments of expression with macro may not be collected correctly. To avoid this, define reaction with anonymous functions may helpfully:

@reaction reaction begin
    (A, B) -> @einsum C[i, k] := A[i, j] * B[j, k] # where C, i, j, k should not be collected
    begin
        # do something
    end
end

in this case, only arguments of anonymous function (A and B) will be collected.

Besides, there are another macro @quickloop, which is similar to @einsum, but it don't follow the einstein convenience which just generate nest loops out of the expression. Because the @quickloop generate a function and arguments are provided, indexing variables and return variable will not be collected.

@reaction_eq name param eq [opts...]

Generate a reaction with the given name, parameters and equation.

Example

@reaction growth r X[i] --> 2X[i]

is equivalent to

@reaction growth begin
    r * X
    begin
        i = ind[1]
        X[i] += 1
    end
end

@ufunc ex

Define a "update" function with an "adapter" methods used to parse args from model. "update" functions take arguments from system state and update system state.

Example

For function definition:

@ufunc Base.@propagate_inbounds growth_u!(ind::CartesianIndex{1}, x) = x[ind] += 1

This macro creates two methods, an "adapter" method

growth_u!(ind, args::NamedTuple) = growth_u(ind, args.x)

and the origin method

Base.@propagate_inbounds growth_u!(ind::CartesianIndex{1}, x) = x[ind] += 1

ScalarType{T}

ScalarType is a type of number used to represent a scalar value in a model. Its value is accessible via getindex and can be updated via setindex!.

scalar(x)

Convert x to a ScalarType.