# References

`EvolutionaryModelingTools.Reaction`

— Type`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.

`EvolutionaryModelingTools.gillespie!`

— Method`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.

`EvolutionaryModelingTools.gillespie`

— Method`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.

In order to update single value state, it must be converted to a `ScalarType`

with `scalar`

.

`EvolutionaryModelingTools.sample`

— Function`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)
```

`EvolutionaryModelingTools.@cfunc`

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

For function definition with other macros, put those macros after this macro.

The argument name `t`

is reserved for time. Don't use those variable names for other usage

`EvolutionaryModelingTools.@quickloop`

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

.

The order of function arguments generated by this macro is undetermined. Thus, it's recommender use this macro inside of `@reaction`

, which detect the order of function arguments automatically.

`EvolutionaryModelingTools.@reaction`

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

If there are global variables, this macro may can not collect arguments correctly. Especially, for functions which accept function and types as arguments, those functions and types may also be collect as an arguments. Thus, these variables must be marked as global variables by `global`

before use them, even functions and types. Besides, type annotation expressions like `x::Vector{Int}`

, types `Vector`

and `Int`

will not be collected. Avoid to defined your reaction with a type arguments for type annotation.

The expression follow the same name preserve rule as `@cfunc`

and `@ufunc`

, don't use those variable names for other usage.

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.

`EvolutionaryModelingTools.@reaction_eq`

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

`EvolutionaryModelingTools.@ufunc`

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

For function definition with other macros, put those macros after this macro.

The argument name `t`

is reserved for time, arguments name `rng`

is reserved for random number generator, and the argument name `ind`

is preserved for index of "reaction". Don't use those variable names for other usage

`EvolutionaryModelingTools.Scalar.ScalarType`

— Type`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!`

.

`EvolutionaryModelingTools.Scalar.scalar`

— Function`scalar(x)`

Convert `x`

to a ScalarType.