Index Handlers
The task of an index handler is to provide a mapping between the system state and the way it is stored in memory, usually as a multidimensional array. The standard approach is to represent the states of a system with $s$ reactions as an $s$-dimensional array and have the index $(i_1, \ldots, i_s)$ correspond to the state $(n_1 = i_1, \ldots, n_s = i_s)$. This is implemented by the class DefaultIndexHandler, which accepts an offset argument to deal with Julia's 1-based indexing (so the Julia index $(1,\ldots,1)$ corresponds to the state with no molecules).
Extending Index Handlers
To define a custom index handler, subtype AbstractIndexHandler and import the extension functions before adding methods:
import Base: LinearIndices, vec
import FiniteStateProjection: build_rhs_header, getsubstitutions, pairedindices, singleindicesImplement getsubstitutions, plus array and dimension-tuple methods for singleindices and pairedindices. Implement LinearIndices and vec as well when the handler supports sparse-matrix conversions. Override build_rhs_header only when generated RHS functions need parameters arranged differently from the default vector form.
FiniteStateProjection.AbstractIndexHandler — Type
AbstractIndexHandlerAbstract supertype for index handlers used by FSPSystem.
Extension Rules
To implement a custom handler, subtype AbstractIndexHandler and extend the documented index-handler interface described in the manual. Matrix-capable handlers must implement both forms of singleindices and pairedindices, LinearIndices, and vec; all handlers must implement getsubstitutions.
FiniteStateProjection.DefaultIndexHandler — Type
DefaultIndexHandler{N}()
DefaultIndexHandler{N}(offset, perm)Default index handler for an FSP system with N species.
Fields
offset: Julia index corresponding to a molecular count of zero.perm: Mapping from state-array dimensions to Catalyst species order.
It represents the state as an N-dimensional array, maps a molecule count of zero to offset, and uses perm to map state-array dimensions to Catalyst's species order.
The zero-argument constructor uses Julia's one-based indexing and preserves the species order. This representation is appropriate when every state in the truncated array is reachable; reduce conserved species before construction when possible.
Examples
julia > DefaultIndexHandler{2}()
DefaultIndexHandler{2}(1, (1, 2))FiniteStateProjection.NaiveIndexHandler — Function
NaiveIndexHandlerDeprecated constructor forwarding to DefaultIndexHandler.
Arguments
args...: Positional arguments accepted byDefaultIndexHandler.
Keyword Arguments
kwargs...: Keyword arguments accepted byDefaultIndexHandler.
Use DefaultIndexHandler directly instead.
FiniteStateProjection.singleindices — Function
singleindices(idxhandler::AbstractIndexHandler, arr)Returns the indices of the finite state space represented by arr.
Arguments
idxhandler: The index handler that defines the state-space layout.arr: Either the state array or its tuple of dimensions.
Returns
- An iterator of Cartesian indices. The default implementation returns
CartesianIndices(arr).
Extension Rules
Custom index handlers must import and extend this function. Implement both the state-array and dimension-tuple forms when supporting matrix conversions.
FiniteStateProjection.pairedindices — Function
pairedindices(idxhandler::AbstractIndexHandler, arr, shift::CartesianIndex)Returns pairs (I .- shift, I) for state transitions that remain within arr.
Arguments
idxhandler: The index handler that defines the state-space layout.arr: Either the state array or its tuple of dimensions.shift: The reaction stoichiometry as a Cartesian index in Catalyst species order.
Returns
- An iterator of source and destination Cartesian-index pairs.
Extension Rules
Custom index handlers must import and extend this function. Implement both the state-array and dimension-tuple forms when supporting matrix conversions.
FiniteStateProjection.getsubstitutions — Function
getsubstitutions(idxhandler::AbstractIndexHandler, rs::ReactionSystem; state_sym::Symbol)Returns a dictionary S_i => f_i(state_sym), where each f_i computes a species abundance from the symbolic state variable.
Arguments
idxhandler: The index handler that defines the state-space layout.rs: Catalyst reaction system whose species require substitutions.
Keyword Arguments
state_sym: Symbol naming the generated RHS state variable.
Returns
- A dictionary mapping each Catalyst species to a symbolic abundance expression.
Extension Rules
Custom index handlers must import and extend this function.
FiniteStateProjection.build_rhs_header — Function
build_rhs_header(sys::FSPSystem)Returns initialization code for the generated RHS function. The default implementation unpacks the vector parameter p supplied by DifferentialEquations.jl.
Arguments
sys: FSP system whose parameter ordering determines the generated code.
Returns
- An expression evaluated at the start of the generated RHS function.
Extension Rules
Custom index handlers with a different parameter representation may import and extend this function for their corresponding FSPSystem specialization.
See also: unpackparams, build_rhs
Base.LinearIndices — Type
LinearIndices(idxhandler::AbstractIndexHandler, arr)Returns an object lind converting the Cartesian indices produced by singleindices and pairedindices to the linear indices of vec. The required invariant is
arr[idx_cart] == vec(idxhandler, arr)[idx_lin]Arguments
idxhandler: The index handler that defines the vector ordering.arr: Either the state array or its tuple of dimensions.
Returns
- An indexable object mapping Cartesian indices to vector positions.
Extension Rules
Custom index handlers that support matrix conversions must import and extend this Base function, preserving the documented indexing invariant.
See also: vec