add docs on low level acces to state ordering

Author: hexaeder

docs/src/symbolic_indexing.md

@@ -1,6 +1,6 @@
 # Symbolic Indexing
 
-Using SciML's [`SymblicIndexingInterface.jl`](https://github.com/SciML/SymbolicIndexingInterface.jl), `ND.jl` provides lots of methods to access and change variables and Parameters.
+Using SciML's [`SymbolicIndexingInterface.jl`](https://github.com/SciML/SymbolicIndexingInterface.jl), `ND.jl` provides numerous methods to access and change variables and parameters.
 
 !!! details "Setup code to make following examples work"
     ```@example si
@@ -11,7 +11,7 @@ Using SciML's [`SymblicIndexingInterface.jl`](https://github.com/SciML/SymbolicI
     ```
 
 ## Provide Symbol Names
-When construction component models, you can pass symbolic names using the `sym` and `psym` keywords.
+When constructing component models, you can pass symbolic names using the `sym` and `psym` keywords.
 ```@example si
 function _edgef!(e, v_s, v_d, (K,), t)
     e .= K * (v_s[1] .- v_d[1])
@@ -28,9 +28,9 @@ vertexf = VertexModel(f=_vertexf!, g=1, sym=[:storage])
 ```
 
 
-## Fundamental Symblic Indices
+## Fundamental Symbolic Indices
 The default types for this access are the types [`VIndex`](@ref), [`EIndex`](@ref), [`VPIndex`](@ref) and [`EPIndex`](@ref).
-Each of those symbolic indices consists of 2 elements: a reference to the network componen and a reference to the symbol within that component.
+Each of those symbolic indices consists of 2 elements: a reference to the network component and a reference to the symbol within that component.
 As such, `VIndex(2, :x)` refers to variable with symbolic name `:x` in vertex number 2.
 `EPIndex(4, 2)` would refer to the *second* parameter of the edge component for the 4th edge.
 
@@ -56,7 +56,7 @@ Often, you need many individual symbolic indices. For that there are the helper
 With the help of those methods you can generate arrays of symbolic indices:
 
 ```@example si
-vidxs(nw, :, :storage) # get variable "storage" for all nodes
+vidxs(nw, :, :storage) # get variable "storage" for all vertices
 ```
 ```@example si
 plot(sol; idxs=vidxs(nw, :, :storage))
@@ -70,7 +70,7 @@ p = NWParameter(nw)
 ```
 creates a `NWParameter` object for the network `nw`.
 It essentially creates a new flat parameter array and fills it with the default parameter values define in the component.
-The parameters in the `NWParameter` object can be accessed using the symbolic indices.
+The parameters in the `NWParameter` object can be accessed using symbolic indices.
 ```@example si
 p[EPIndex(5, :K)] = 2.0 # change the parameter K of the 5th edge
 nothing #hide
@@ -79,20 +79,20 @@ Similarly, you can create a `NWState` object for the network `nw` using
 ```@example si
 s = NWState(nw)
 ```
-No default values were provided in the network components, so the state array is filled with `NaN`s.
+No default values were provided in the network components, so the state array is filled with `NaN` values.
 ```@example si
-s[VIndex(:, :storage)] .= randn(5) # set the (initial) storage for alle nodes 
+s[VIndex(:, :storage)] .= randn(5) # set the (initial) storage for all vertices 
 s #hide
 ```
-For both `NWState` and `NWParameter` objects, the there is a more convenient way to access the variables and parameters.
+For both `NWState` and `NWParameter` objects, there is a more convenient way to access the variables and parameters.
 ```@example si
 @assert s.v[1, :storage] == s[VIndex(1, :storage)] # s.v -> access vertex states
 @assert s.e[1, :flow]    == s[EIndex(1, :flow)]    # s.e -> access edge states
 @assert s.p.e[1,:K]      == p[EPIndex(1, :K)]      # s.p -> access parameters
 ```
 
 The `NWState` and `NWParameter` objects are mutable, thus changing them will also change the underlying wrapped flat arrays.
-You can allways access the flat representations by calling [`uflat`](@ref) and [`pflat`](@ref).
+You can always access the flat representations by calling [`uflat`](@ref) and [`pflat`](@ref).
 
 !!! note
     The `NWState` and `NWParameter` wrappers can be constructed from various objects.
@@ -101,8 +101,8 @@ You can allways access the flat representations by calling [`uflat`](@ref) and [
 
 ## Observables
 Sometimes, the "states" you're interested in aren't really states in the DAE sense but rather
-algebraic derivations from DAE states, parameters and time -- in accordance with the naming in 
-the `SciML`-ecosystem those states are called Observables.
+algebraic derivations from DAE states, parameters, and time -- in accordance with the naming in 
+the `SciML` ecosystem, these values are called Observables.
 
 A prime example of Observables are edge/vertex-outputs, such as the `flow` in the edge model defined above.
 It is also possible to define additional Observables manually by using the `obssym` and `obsf` keyword
@@ -117,17 +117,43 @@ plot(sol; idxs=eidxs(nw, :, :flow))
 
 ## Derived `ObservableExpressions` using `@obsex`
 
-Sometimes it is usefull to plot or observe some simple derived quantity.For that,
-one can used the [`@obsex`](@ref) macro, to define simple derived quantities.
+Sometimes it is useful to plot or observe simple derived quantities. For that,
+one can use the [`@obsex`](@ref) macro to define simple derived quantities.
 
 For example, we can directly plot the storage difference with respect to storage of node 1.
 
 ```@example si
 plot(sol; idxs=@obsex(vidxs(nw,:,:storage) .- VIndex(1,:storage)))
 ```
 
-Other examples are the calculation of magnitude and argument of complex values which are modeld in real and imaginary part.
+Other examples include calculating the magnitude and argument of complex values that are modeled using real and imaginary parts.
 ```
 @obsex mag = sqrt(VIndex(1, :u_r)^2 + VIndex(2, :u_i)^2)
 ```
 
+## Low-level accessors for flat array indices
+Sometimes, you want to know the indices of your states in the flat arrays.
+For that, you can use the low-level methods defined in `SymbolicIndexingInterface.jl`:
+
+```@example si
+using NetworkDynamics: SII # SII = SymbolicIndexingInterface
+idxs = SII.variable_index(nw, vidxs(1:2, :storage))
+```
+```@example si
+uflat(s)[idxs] == s.v[1:2, :storage]
+```
+Analogous with parmeters:
+```@example si
+idxs = SII.parameter_index(nw, eidxs(1:2, :K))
+pflat(s)[idxs] == s.p.e[1:2, :K]
+```
+
+If you need the symbols of all the states/parameters in order, you can use
+```@example si
+SII.variable_symbols(nw)
+```
+and
+```@example si
+SII.parameter_symbols(nw)
+```
+All above examples also work on other "symbolic containers", e.g. `SII.variable_symbols(::NWState)`.

src/symbolicindexing.jl

@@ -239,7 +239,7 @@ end
 function SII.variable_index(nw::Network, sni)
     if _hascolon(sni)
         SII.variable_index(nw, _resolve_colon(nw,sni))
-    elseif SII.symbolic_type(sni) === SII.ArraySymbolic()
+    elseif sni isa AbstractVector || SII.symbolic_type(sni) === SII.ArraySymbolic()
         SII.variable_index.(nw, sni)
     else
         _variable_index(nw, sni)
@@ -289,7 +289,7 @@ end
 function SII.parameter_index(nw::Network, sni)
     if _hascolon(sni)
         SII.parameter_index(nw, _resolve_colon(nw,sni))
-    elseif SII.symbolic_type(sni) === SII.ArraySymbolic()
+    elseif sni isa AbstractVector || SII.symbolic_type(sni) === SII.ArraySymbolic()
         SII.parameter_index.(nw, sni)
     else
         _parameter_index(nw, sni)