improve callback docs

Author: hexaeder

docs/make.jl

@@ -8,9 +8,9 @@ using ModelingToolkit
 using DocumenterInterLinks
 
 links = InterLinks(
-    "diffeq" => "https://diffeq.sciml.ai/stable/",
-    "mtk" => "https://mtk.sciml.ai/stable/",
-    "sii" => "https://docs.sciml.ai/SymbolicIndexingInterface/stable/",
+    "DiffEq" => "https://docs.sciml.ai/DiffEqDocs/stable/",
+    "MTK" => "https://docs.sciml.ai/ModelingToolkit/stable/",
+    "SymbolicIndexingInterface" => "https://docs.sciml.ai/SymbolicIndexingInterface/stable/",
 )
 
 # generate examples

docs/src/API.md

@@ -127,7 +127,7 @@ set_bounds!
 ## Callbacks API
 ### Define Callbacks
 ```@docs
-ComponentCallback
+NetworkDynamics.ComponentCallback
 ContinousComponentCallback
 VectorContinousComponentCallback
 ComponentCondition

docs/src/callbacks.md

@@ -1,14 +1,13 @@
-# Callbacks and Events (@id Callbacks)
+# [Callbacks and Events](@id Callbacks)
 
 Callback-functions are a way of handling discontinuities in differential equations.
 In a nutshell, the solver checks for some "condition" (i.e. a zero crossing of some variable)
 and calls some "affect" if the condition is fulfilled.
-In the affect it is safe to modify the integrator, e.g. changing some state or some parameter.
+Within the affect function, it is safe to modify the integrator, e.g. changing some state or some parameter.
 
 Since `NetworkDynamics.jl` provides nothing more than a RHS for DifferentialEquations.jl, please check
 [their docs on event handling](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/)
 as a general reference.
-
 This page at introducing the general concepts, for a hands on example of a simulation with callbacks
 refer to the [Cascading Failure](@ref) example.
 
@@ -84,7 +83,7 @@ add_callback!(vert, vccb)
 
 
 ### Extracting the Callback
-In order to use the callback during simulation, we need to generate a [`SciMLBase.CallbackSet`](@extref) which contains the conditions and affects of all the component based callbacks in the network. For that we use [`get_callbacks(::Network)`](@ref `get_callbacks(::NetworkDynamics.Network)`):
+In order to use the callback during simulation, we need to generate a [`SciMLBase.CallbackSet`](@extref) which contains the conditions and affects of all the component based callbacks in the network. For that we use [`get_callbacks(::Network)`](@ref):
 ```julia
 u0 = NWState(u0)
 cbs = get_callbacks(nw)
@@ -105,7 +104,7 @@ To access states and parameters of specific components, we havily rely on the [S
 using SymbolicIndexingInterface as SII
 nw = Network(#= some network =#)
 
-condition = let getvalue = SII.getu(nw, VIndex(1:5, :some_state))
+condition = let getvalue = SII.getsym(nw, VIndex(1:5, :some_state))
     function(out, u, t, integrator)
         s = NWState(integrator, u, integrator.p, t)
         some_state = getvalue(s)
@@ -115,7 +114,7 @@ end
 ```
 Please not a few important things here:
  - Symbolic indexing can be costly, and the condition function gets called very
-   often. By using [`SII.getu`](@extref `SymbolicIndexingInterface.getu`) we did
+   often. By using [`SII.getsym`](@extref `SymbolicIndexingInterface.getsym`) we did
    some of the work *before* the callback by creating the accessor function.
    When handling with "normal states" and parameters consider using
    [`SII.variable_index`](@ref `SymbolicIndexingInterface.variable_index`) and
@@ -150,4 +149,4 @@ Once the `condition` and `affect!` is defined, you can use the [`SciMLBase.Conti
     To extract or plot timeseries of observed states under *time variant
     parameters* (i.e. parameters that are changed in a callback), those changes
     need to be recorded using the [`save_parameters!`](@ref) function whenever `p` is changed.
-    When using [ComponentCallback](@ref), NetworkDynamics will automaticially check for changes in `p` and save them if necessary.
+    When using [ComponentCallback](@ref NetworkDynamics.ComponentCallback), NetworkDynamics will automaticially check for changes in `p` and save them if necessary.

src/NetworkDynamics.jl

@@ -77,7 +77,7 @@ include("metadata.jl")
 
 export ComponentCondition, ComponentAffect
 export ContinousComponentCallback, VectorContinousComponentCallback
-export SymbolicView, get_callbacks
+export SymbolicView
 include("callbacks.jl")
 
 using NonlinearSolve: AbstractNonlinearSolveAlgorithm, NonlinearFunction

src/callbacks.jl

@@ -66,7 +66,7 @@ Creates a callback condition for a [`ComponentCallback`].
     - `event_idx`: The current event index, i.e. which `out` element triggerd in case of [`VectorContinousComponentCallback`](@ref).
     - `ctx::NamedTuple` a named tuple with context variables.
        - `ctx.model`: a referenc to the ocmponent model
-       - `ctx.vidx`/ctx.eidx: The index of the vertex/edge model.
+       - `ctx.vidx`/`ctx.eidx`: The index of the vertex/edge model.
        - `ctx.src`/`ctx.dst`: src and dst indices (only for edge models).
        - `ctx.integrator`: The integrator object.
        - `ctx.t=ctx.integrator.t`: The current simulation time.
@@ -155,6 +155,7 @@ Returns a `CallbackSet` composed of all the "component-based" callbacks in the m
 Network components.
 """
 function get_callbacks(nw::Network)
+    aliased_changed(nw; warn=true)
     cbbs = collect_callbackbatches(nw)
     if isempty(cbbs)
         return nothing
@@ -432,7 +433,8 @@ _sym_to_int(x::SymbolicView, idx) = _sym_to_int.(Ref(x), idx)
 ####
 assert_cb_compat(comp::ComponentModel, t::Tuple) = assert_cb_compat.(Ref(comp), t)
 function assert_cb_compat(comp::ComponentModel, cb)
-    all_obssym = Set(sym(comp)) ∪ Set(comp.obssym) ∪ insym_all(comp) ∪ outsym_flat(comp)
+    insym = hasinsym(comp) ? insym_all(comp) : []
+    all_obssym = Set(sym(comp)) ∪ Set(comp.obssym) ∪ insym ∪ outsym_flat(comp)
     pcond = s -> s in comp.psym
     ucond_cond = s -> s in all_obssym
     ucond_affect = s -> s in comp.sym