docs: add documentation for assertions functionality

Author: AayushSabharwal

docs/src/basics/Debugging.md

@@ -35,6 +35,23 @@ dsol = solve(dprob, Tsit5());
 Now we see that it crashed because `u1` decreased so much that it became negative and outside the domain of the `√` function.
 We could have figured that out ourselves, but it is not always so obvious for more complex models.
 
+Suppose we also want to validate that `u1 + u2 >= 2.0`. We can do this via the assertions functionality.
+
+```@example debug
+@mtkbuild sys = ODESystem(eqs, t; defaults, assertions = [(u1 + u2 >= 2.0) => "Oh no!"])
+```
+
+The assertions must be an iterable of pairs, where the first element is the symbolic condition and
+the second is the message to be logged when the condition fails.
+
+```@repl debug
+dsys = debug_system(sys; functions = []);
+dprob = ODEProblem(dsys, [], (0.0, 10.0));
+dsol = solve(dprob, Tsit5());
+```
+
+Note the messages containing the failed assertion and corresponding message.
+
 ```@docs
 debug_system
 ```

src/debugging.jl

@@ -43,6 +43,13 @@ function debug_sub(ex, funcs; kw...)
     maketerm(typeof(ex), f, args, metadata(ex))
 end
 
+"""
+    $(TYPEDSIGNATURES)
+
+A function which takes a condition `expr` and returns `NaN` if it is false,
+and zero if it is true. In case the condition is false and `log == true`,
+`message` will be logged as an `@error`.
+"""
 function _debug_assertion(expr::Bool, message::String, log::Bool)
     expr && return 0.0
     log && @error message
@@ -51,9 +58,19 @@ end
 
 @register_symbolic _debug_assertion(expr::Bool, message::String, log::Bool)
 
+"""
+Boolean parameter added to models returned from `debug_system` to control logging of
+assertions.
+"""
 const ASSERTION_LOG_VARIABLE = only(@parameters __log_assertions_ₘₜₖ::Bool = false)
 
-function get_assertions_expr(assertions::Dict{BasicSymbolic, String})
+"""
+    $(TYPEDSIGNATURES)
+
+Get a symbolic expression as per the requirement of `debug_system` for all the assertions
+in `assertions`. `is_split` denotes whether the corresponding system is a split system.
+"""
+function get_assertions_expr(assertions::Dict{BasicSymbolic, String}, is_split::Bool)
     term = 0
     for (k, v) in assertions
         term += _debug_assertion(k, "Assertion $k failed:\n$v", ASSERTION_LOG_VARIABLE)

src/systems/abstractsystem.jl

@@ -2297,6 +2297,14 @@ ERROR: Function /(1, sin(P(t))) output non-finite value Inf with input
   1 => 1
   sin(P(t)) => 0.0
 ```
+
+Additionally, all assertions in the system are validated in the equations. If any of
+the conditions are false, the right hand side of at least one of the equations of
+the system will evaluate to `NaN`. A new parameter is also added to the system which
+controls whether the message associated with each assertion will be logged when the
+assertion fails. This parameter defaults to `true` and can be toggled by
+symbolic indexing with `ModelingToolkit.ASSERTION_LOG_VARIABLE`. For example,
+`prob.ps[ModelingToolkit.ASSERTION_LOG_VARIABLE] = false` will disable logging.
 """
 function debug_system(
         sys::AbstractSystem; functions = [log, sqrt, (^), /, inv, asin, acos], kw...)