id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc
4436	Improve how equations are shown in the declarative debugger when tearing is applied	Francesco Casella	Adeel Asghar	"When tearing is applied to systems of equations, the way they are shown in the Equations windows of the declarative debugger is not immediately clear (understatement). Unfortunately, the [https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/debugger.html user's guide] does not explain how this works at all.

After some investigation through examples, I understood that:
- when you click on the system of equations, only the tearing variables
  are shown in the {{{Defines}}} window
- the first equations shown when you open the system are the torn equations
  and when you click on one, the {{{Defines}}} window shows the corresponding
  torn variable
- then, the residual equations are shown, which are marked with a {{{(residual)}}} indication after the body of the equation. If you click on them, no equation shows up in the ""Defines"" section
- in some cases, after the residual equations some other equations
  appear, defining variables such as {{{$pDERLSJac18.dummyVarLSJac18}}}
  which seem to be related to analytical Jacobian computations

Eventually, the whole thing makes sense, but it can be extremely puzzling at first sight, particularly since there is no documentation at all on this topic.

My first suggestion is to make this clearer at first sight, by:
- adding some indication that tearing has been applied to the description of the equation that represents the whole system, e.g., {{{nonlinear, size 8, tearing applied}}}
- moving the {{{(residual)}}} marker ''before'' the body of the equation, otherwise it is not seen immediately if the equation lenght exceeds the (small) window width. For example, change {{{x + y - z (residual)}}} into {{{(residual) x + y - z = 0}}}. Note the addition of {{{= 0}}} which, IMHO, makes  the whole thing clearer
- adding a {{{(torn)}}} marker before the body of torn equations
- adding a {{{(Jacobian)}}} marker before the equations to compute Jacobian
  terms showing up after the residual equations
- adding the indication {{{Tearing variables}}} to the list of equations shown in the {{{Define}}} window when clicking on the system of equations, so it is immmediately clear why not all the unknowns of the system are shown
- showing some meaningful message, e.g., {{{Part of an implicit system of equations}}} in the {{{Define}}} window when clicking on a residual equations, so that one does not have the impression that nothing is shown because of a bug

My second suggestion is to add some documentation of this thing to the user's guide. I can volunteer to write this once the GUI is updated."	enhancement	closed	high	1.12.0	OMEdit		fixed		Martin Sjölund Lennart Ochel Patrick Täuber