From 7937f1acee166b6185ff24a20411ae0397baea6e Mon Sep 17 00:00:00 2001
From: mongibellili <bellilimongi@gmail.com>
Date: Wed, 23 Oct 2024 14:02:10 +0200
Subject: [PATCH] update the docs: internals explanation

---
 docs/src/assets/img/diagram.png | Bin 0 -> 32062 bytes
 docs/src/dependencies.md        |  28 +++
 docs/src/developerGuide.md      |   4 +-
 docs/src/implementation.md      | 406 ++++++++++++++++++++++++++++++++
 4 files changed, 437 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/assets/img/diagram.png
 create mode 100644 docs/src/dependencies.md
 create mode 100644 docs/src/implementation.md

diff --git a/docs/src/assets/img/diagram.png b/docs/src/assets/img/diagram.png
new file mode 100644
index 0000000000000000000000000000000000000000..df2b2bd60a3c6f87798eb4a4a73fa208915fefe0
GIT binary patch
literal 32062
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
KcFC#pH~$wb>mZu|

literal 0
HcmV?d00001

diff --git a/docs/src/dependencies.md b/docs/src/dependencies.md
new file mode 100644
index 0000000..9047a8f
--- /dev/null
+++ b/docs/src/dependencies.md
@@ -0,0 +1,28 @@
+# Dependencies
+
+In addition, the package contains several shared helper functions used during the integration
+process by the algorithm such as the scheduler that organizes which variable of the system to
+update at any specific time of the simulation. The solver uses other packages such as MacroTools for user-code parsing, SymEngine for Jacobian computation and dependencies extraction, and a modified TaylorSeries that uses caching to obtain free Taylor variable operations as the current version of TaylorSeries creates a heap allocated object for every operation. The approximation through Taylor variables transforms any complicated equations to polynomials, which makes root finding cheaper, which the QSS methods relies heavily on it.
+## MacroTools
+MacroTools offers a comprehensive library of tools for manipulating Julia expressions, enabling deep code transformations through features such as 𝑝𝑜𝑠𝑡𝑤𝑎𝑙𝑘 and @𝑐𝑎𝑝𝑡𝑢𝑟𝑒. The 𝑝𝑜𝑠𝑡𝑤𝑎𝑙𝑘 function plays a pivotal role within the NLodeProblem function, particularly for user code parsing.
+By systematically traversing each operation, 𝑝𝑜𝑠𝑡𝑤𝑎𝑙𝑘 allows the code to recognize and differentiate between symbols. For instance, it is crucial for integrating parameters and helper functions directly into the equations. Furthermore, 𝑝𝑜𝑠𝑡𝑤𝑎𝑙𝑘 is used to traverse both the right-hand side of differential equations and zero-crossing functions, facilitating the construction of the Jacobian matrix and identifying variable dependencies. It also transforms specific expressions like 𝑞[1] into 𝑞[1] [0] within events, and converts 𝑞[𝑖] to 𝑞𝑖, making the equations more tractable for differentiation and Jacobian construction. Additionally, the @𝑐𝑎𝑝𝑡𝑢𝑟𝑒 function efficiently handles the case where differential equations are defined as expressions within a for loop, ensuring smooth parsing and processing of these equations. The ability to transform and capture expressions ensures that user-defined code is processed efficiently, making MacroTools an indispensable component in the QSS solver workflow.
+## SymEngine
+SymEngine is a high-performance symbolic manipulation library designed for efficient mathematical computations. A key feature of SymEngine is its ability to convert expressions into a symbolic form using the convert(Basic, m) function, where m is typically an expression, such as the right-hand side of a differential equation. This conversion transforms the expression into a Basic type, which is a fundamental structure in SymEngine for symbolic computation. Once the expression is in Basic form, the diff(basi, symarg) function can be applied to perform symbolic differentiation, where basi is the converted expression and symarg is the symbol with respect to which the derivative is taken. This returns the partial derivative of the expression, making it particularly useful for deriving system Jacobians. SymEngine’s ability to handle symbolic differentiation with speed and accuracy makes it an essential tool in Jacobian computation for the QSS solver.
+## Taylor Variables
+In the quantized system solver, and similar to the Taylor struct from the package TaylorSeries.jl, the Taylor0 struct serves as a convenient representation of Taylor series approximations. Each instance encapsulates an array of coefficients, which correspond to the Taylor series expansion, along with an order indicating the degree of the expansion. This structure allows for efficient storage of state values and their derivatives, as the first coefficient represents the variable value, while subsequent coefficients represent higher-order derivatives. The use of Taylor variables enables the computation of derivatives for complex expressions seamlessly, enhancing the solver’s capability to analyze and simulate dynamic systems. The implementation includes various constructors and methods to manipulate and evaluate the Taylor series, ensuring that users can easily derive the necessary values from the stored Taylor variables, thus facilitating precise calculations
+of system behavior over time.
+New functions are created to match each old function but with a different name and added
+caches in the parameters. These new functions are designed to optimize performance by avoiding memory allocation during their execution. This is achieved through careful design and implementation of the functions, where arithmetic operations and mathematical functions leverage the existing cached data rather than creating new instances of taylor variables. In addition, the old Taylor is kept, with minimum functionalities, as a fallback in case there is an expression that does not use the available cache vector. As a result, this approach enhances the efficiency of the Taylor variable framework, making it more suitable for complex simulations and calculations without sacrificing flexibility or usability.
+
+arithmetic operations: The provided code introduces personalized arithmetic operations
+that optimize performance by eliminating memory allocation during calculations. Functions
+such as addsub, subsub, and mulT are designed to operate directly on existing data structures, utilizing a caching mechanism to store intermediate results. This is in stark contrast to traditional arithmetic operations that typically allocate memory with each computation, creating overhead and potentially slowing down performance in computationally intensive tasks. The previous approach required reallocation for each arithmetic operation, leading to inefficiencies when processing large datasets or performing numerous calculations.
+mathematical functions: Similar to arithmetic operations, new mathematical functions are
+designed to leverage in-place operations, which reduces the overhead associated with creating
+new memory for intermediate results. For instance, functions like exp, log, sin, and cos, sqrt, power iterate over the input Taylor series and apply the corresponding operation without allocating additional arrays.
+By implementing these new methods, the code significantly reduces the number of allocations, improving both execution speed and resource management, while still maintaining the
+flexibility and functionality required for complex mathematical operations.
+transformation of expressions: The transformF function is designed to translate userdefined mathematical expressions into optimized forms that leverage the custom arithmetic and
+function implementations. By traversing the expression tree with the prewalk function, it identifies operations such as addition, subtraction, multiplication, division, and specific mathematical functions (like exponential and logarithmic functions). For each identified operation, the code modifies the expression to call specialized versions (e.g., subT, addT, mulT) that avoid memory allocation, enhancing performance during calculations. Additionally, it tracks the number of caches needed for these operations, which are essential for efficient computation of Taylor series.
+Each time a transformation occurs, a reference to a cache is added, ensuring that a necessary
+cache is available for the optimized functions. This systematic approach effectively restructures the original expressions, maintaining their functionality while improving computational efficiency by reducing unnecessary allocations.
diff --git a/docs/src/developerGuide.md b/docs/src/developerGuide.md
index 4ae0028..ada7e4d 100644
--- a/docs/src/developerGuide.md
+++ b/docs/src/developerGuide.md
@@ -2,7 +2,9 @@
 
 While the package is optimized to be fast, extensibility is not compromised. It is divided into 3 entities that can be extended separately: Problem, Algorithm, and Solution. The package uses other packages such as MacroTools.jl for user-code parsing, SymEngine.jl for Jacobian computation, and a modified TaylorSeries.jl that uses caching to obtain free Taylor variables. The approximation through Taylor variables transforms any complicated equations to polynomials, which makes root finding cheaper.
 
-
+### [Implementation ](@ref)
+### [Dependencies ](@ref)
+### [Algorithm Extension ](@ref)
 ### [Algorithm Extension ](@ref)
 ### [Problem Extension](@ref)
 ### [Solution Extension](@ref)
diff --git a/docs/src/implementation.md b/docs/src/implementation.md
new file mode 100644
index 0000000..2d5eb6e
--- /dev/null
+++ b/docs/src/implementation.md
@@ -0,0 +1,406 @@
+# Implementation
+### Package Structure {#ch5:section:Package-description}
+
+While the package is optimized to be fast, extensibility is not
+compromised. It is divided into 3 entities that can be extended
+separately: Problem, Algorithm, and Solution. The rest of the code is to
+create these entities and glue them together as shown in the Figure.
+
+::: center
+![The QSS Solver Structure.](./assets/img/diagram.png){#fig:qssdiag width="10cm"
+height="6cm"}
+:::
+
+The API was designed to provide an easier way to handle events than the
+approach provided by the classic integration solvers. Inside an
+NLodeProblem function, the user may introduce any parameters, variables,
+equations, and events:
+
+        odeprob = NLodeProblem(quote 
+        name
+        parameters
+        discrete and continous variables
+        helper expressions
+        differential equations
+        if-statments for events)
+
+The output of this function is an object of type Problem, and it is
+passed to the solve function along any other configuration arguments
+such as the algorithm type, the time span and the tolerance. The solve
+function dispatches on the given algorithm and start the numerical
+integration.
+
+        tspan = (start time, end time)
+        sol= solve(odeprob,algorithm,tspan,abstol=...,reltol=...)    
+
+A the end, a solution object is produced that can be queried and
+plotted.
+
+        sol(time,idxs=variable index) 
+        sol.stats
+        plot(sol)    
+
+
+### Internal Code Explained {#ch5:section:code-explained}
+
+The solver structure is designed for modularity, allowing for different
+QSS algorithms and quantizer orders to be used in the simulation. The
+core components of the solver include the NLodeProblem function, the
+solve function, the scheduler, the quantizer, and the solution object.
+These components work together to parse user-provided code, solve the
+system of ODEs using QSS algorithms, and store the results for analysis.
+The following sections provide an in-depth explanation of the key
+components and their interactions within the solver framework.
+
+#### creating the problem
+
+The NLodeProblem function is the entry point for defining a new problem
+to be solved by the QSS solver. It takes user-provided code, which
+includes system parameters, variables, equations, and event logic, and
+constructs a Problem object that encapsulates all the necessary
+information for the solver to simulate the system such as problem
+dimensions, dependencies, and equations. The function works by parsing
+the user code and extracting relevant data to populate the Problem
+object.
+
+*NLODEDiscProblem{PRTYPE,T,Z,Y,CS}:* This is the struct that holds all
+the necessary data for a nonlinear ordinary differential equation (ODE)
+problem with discrete events. The structure includes various fields such
+as initial conditions, discrete variables, Jacobians, event
+dependencies, and other data related to how the problem is formulated.
+This structure serves as the core data holder for the problem and will
+be used in the solver. It is a parametric abstract type that has the
+following parameters:
+
+PRTYPE: The type of the problem (to distinguish between various types,
+and allow future extension of the solver to handle new types).
+
+T: The number of continuous variables (state variables).
+
+Z: The number of zero-crossing functions, which are used to detect
+events.
+
+Y: The actual number of events.
+
+CS: Cache size, which is used to store intermediate operations.
+
+The use of abstract types in this context allows for flexibility and
+extensibility in the solver. By defining these abstract types, the code
+can be easily adapted to handle different types of problems, algorithms,
+and solutions without needing to modify the core solver logic. This
+design choice enhances the maintainability and scalability of the
+solver, making it easier to add new features or support additional
+problem types in the future.
+
+**NLodeProblemFunc:** After an initial preparation performed by the The
+NLodeProblem function, The function NLodeProblemFunc takes the resulting
+expressions to continue constructing an instance of the NLODEDiscProblem
+structure. It works in several key stages:
+
+*Initialization:* The function begins by initializing vectors and
+dictionaries that will hold equations (equs), Jacobian dependencies
+(jac), zero-crossing functions (ZCjac), and event dependencies. These
+serve to store the different types of equations and their relationships.
+
+*Processing ODEs:* It loops through each of the ODE expressions provided
+by the user. Depending on the type of expression (discrete variables,
+differential equations, or loop constructs), it processes the right-hand
+side (RHS) of the equation. For differential equations, it extracts
+dependencies to build the Jacobian and transform the equations into a
+more appropriate form for further use. Special cases are handled, such
+as if the RHS is a number or a symbol.
+
+*Handling Events:* The function also processes event-related constructs
+(if conditions) that correspond to different points where the system
+might undergo discrete changes. It process the RHS of the event
+equations, transforms them into a suitable form, and builds the
+necessary dependency structures. Specifically, it constructs how
+discrete and continuous variables influence one another through the
+events.
+
+*Constructing the Function Code:* After processing all ODEs and events,
+the function dynamically generates a Julia function code needed to store
+the system of ODEs and events. This code is built into a function that
+handles different cases (i.e., which equation to evaluate based on an
+index of a state change or an event).
+
+**Building Dependencies:** Several helper functions that build the
+dependencies between variables, events. They build dependency vectors
+that track how discrete and continous variables influence the system.
+This is used to know what variables to update and determine when
+specific events should be checked. By tracking the relationships between
+variables and events, the solver can determine the appropriate actions
+to take at each time step. The dependencies are stored in the following
+vectors:
+
+\-$jac$: It determines which variables affect a derivative.
+
+\-$ZCjac$: It determines which variables affect a zero-crossing
+function.
+
+\-$SD$: It determines which derivatives that are affected by a given
+variable.
+
+\-$SZ$: It determines which zero-crossing functions that are affected by
+a given variable.
+
+\-$HZ$: It tells which Zero-crossing functions influenced by a given
+event.
+
+\-$HD$: It tells which derivatives influenced by a given event.
+
+Here's a quick summary and what each helper function is doing:
+
+*extractJacDepNormal:* It Extracts the dependencies for normal
+(non-loop) expressions. It updates the Jacobian matrix $jac$ and a
+dictionary $dD$ for tracking dependencies of derivatives to discrete
+variables.
+
+*extractJacDepLoop:* Similar to extractJacDepNormal, but specifically
+for loop expressions. It tracks dependencies across loop iterations.
+
+*extractZCJacDepNormal:* It Extracts zero-crossing Jacobian dependencies
+for discrete variables ($dZ$), and it updates $zcjac$, $SZ$.
+
+*createDependencyToEventsDiscr:* It maps discrete dependencies (dD, dZ)
+to specific events, it and constructs dependency matrices HZ and HD from
+the discrete variables only.
+
+*createDependencyToEventsCont:* Similar to
+createDependencyToEventsDiscr, but for continuous dependencies (SD, sZ),
+and it updates the matrices HZ and HD from the continuous variables
+only.
+
+*unionDependency:* Merges the two previous sets of dependencies
+(continuous and discrete) into the final matrices HZ and HD.
+
+#### The solve function
+
+The solve function is the primary interface for solving non-linear ODE
+problems using various QSS (Quantized State Systems) algorithms. It does
+this by dispatching on the problem and algorithm types to select the
+right solver.
+
+**QSS Algorithm:** The diagram shows three specific algorithms: (QSS
+Algorithm, LiQSS Algorithm, mLiQSS Algorithm). The Algorithm type is
+parametric on the solver name (N) and order (O). When a user doesn't
+provide a solver explicitly, the solve function defaults to using the
+modified second-order implicit algorith (mLiQSS2). This approach allows
+flexibility: the user can select a different algorithm by providing an
+alternative QSS Algorithm without needing to modify the solve function.
+Based on the QSS Algorithm provided, it either selects a basic QSS
+integration method or, in the case of LiQSS, constructs additional data
+structures needed for implicit integration. The method defaults to
+sparse handling as false (Val(false)), tolerances (abstol=1e-4 and
+reltol=1e-3), and a maximum number of iterations (maxiters=1e7). These
+parameters can be adjusted based on the problem's complexity and desired
+accuracy.
+
+**Helper Functions:**
+
+*createCommonData:* This function sets up the common data required by
+the QSS solver. It initializes all necessary vectors (x, q, tx, tq,
+nextStateTime, etc.) used in the integration process, and it
+pre-allocates a cache of Taylor series to avoid repeated memory
+allocation during integration (taylorOpsCache).
+
+*getClosure:* This function creates a closure for the Jacobian and the
+dependency matrices, allowing in a flexible in a way that enables easy
+extension. The closure is used to access the Jacobian matrix during the
+integration process.
+
+*createLiqssData:* For LiQSS solvers, this function sets up additional
+data structures and auxiliary variables used for storing linear
+approximation coefficients.
+
+#### The scheduler function
+
+The scheduler component retrieves the next index (a state change or an
+event) for processing. It determines the next action by comparing three
+types of timing events: state updates, events, and input updates. It
+initializes minimum time variables for each action type to infinity and
+iterates through the provided vectors to find the minimum times and
+their corresponding indices. Based on these comparisons, it decides
+whether the next scheduled action is an input update, an event, or a
+state update. If no valid actions are found (indicated by a zero index),
+the function assigns a default state indicating the next action is a
+state update at time infinity. Finally, it returns a tuple containing
+the index of the next action, its time, and a symbol representing the
+type of action to take next (:STINPUT, :STEVENT, or :STSTATE). This
+structure ensures that the simulation progresses accurately and
+efficiently.
+
+#### The Quantizer functions
+
+The system handles different quantizer orders (Order 1 and Order 2). It
+defines methods for state integration, derivative computation, event
+time computation, updating quantized values, and cycle detection
+updates.
+
+**Utils:** This section contains utility functions like root finding
+that assist in the solution process.
+
+**computeNextTime:** for first-order, the state of the system changes at
+a constant rate. The core calculation takes place when the first
+derivative of the state, represented by $x[i][1]$, is non-zero. In this
+case, the function determines the time to the next event by dividing a
+quantum threshold by this derivative. Additionally, to prevent numerical
+issues, it ensures that this calculated time-step does not fall below a
+predefined minimum value, $absDeltaT$. If the first derivative is
+extremely small or essentially zero, the function adjusts it to avoid
+potential numerical instabilities that could arise from very small time
+increments.
+
+For second-order, the system state evolves with both a rate of change
+(first derivative) and acceleration (second derivative). The core
+calculation occurs when the second derivative of the state, represented
+by $x[i][2]$, is non-zero. In this case, the function computes the time
+to the next event by using the square root of the ratio between a
+quantum threshold and the second derivative. This ensures that the
+time-step reflects the influence of the system's acceleration.
+Additionally, to prevent numerical issues (such as division by zero or
+overly small time-steps), a minimum delta time (absDeltaT) is enforced.
+If the computed time-step is smaller than this threshold, the function
+adjusts the second derivative to maintain stability. If the second
+derivative is zero but the first derivative is non-zero, the time to the
+next event is calculated based on the first derivative. The function
+ensures that the time-step does not drop below absDeltaT, adjusting the
+first derivative if necessary. If both derivatives are zero, the system
+is assumed to have no change, and the next event time is set to infinity
+(Inf).
+
+**recomputeNextTime:** The reComputeNextTime functions are used in the
+explicit QSS algorithms to enable the recalculation of the next time
+after interactions between different variables, such as variable i and
+variable j. These functions determine the time until the system crosses
+the quantum threshold by solving polynomial equations derived from the
+difference between the quantized state and the actual state. In
+situations where the quantum threshold has already been surpassed, they
+promptly return a very small time increment (e.g., simt + 1e-12) to
+trigger an immediate update of the system's state.
+
+**LiqssrecomputeNextTime:** In the LIQSS methods of first-order, the
+recomputeNextTime function calculates the next event time based on the
+current state (x), its first derivative (x1), and the quantized state
+(q). First, if the difference between the current state and the
+quantized state exceeds twice the quantum size, the next event is
+scheduled almost immediately with a small time-step. Otherwise, if the
+derivative is non-zero, the function computes the time-step by dividing
+the state difference by the derivative. If the result is positive, this
+time is added to the current simulation time (simt). If negative, it
+adjusts the time-step by either adding or subtracting twice the quantum
+size based on the direction of change. If the derivative is zero,
+indicating no change, the event time is set to infinity. Lastly, if the
+computed time is in the past, the function resets it to a far future
+time to prevent any premature events. This ensures that the system
+evolves smoothly and accurately.
+
+In the second-order LIQSS method, the recomputeNextTime function
+calculates the next event time by considering both the state (x) and its
+first (x1) and second (x2) derivatives, along with the quantized state
+(q). The function constructs a polynomial using the current state,
+derivative values, and the second derivative, then calculates the next
+event time by finding the smallest positive root of this polynomial.
+
+**computeNextInputTime:** The computeNextInputTime functions focus on
+computing the next action when derivatives depend only on time. They
+assess changes in the derivatives over a specified elapsed time to
+compute the time increment until the next input action. If the
+derivatives are null, the function reverts to handling the system in a
+lower-order thus simplifying the calculation.
+
+**computeNextEventTime:** The computeNextEventTime function calculates
+the next event time based on the zero-crossing function ($ZCFun$) of a
+system. It first checks if a sign change has occurred in the
+zero-crossing function, indicating that the system is leaving zero and
+should be considered an event, provided the previous value is
+significantly different from zero (to prevent duplicate events). If a
+sign change is detected, the function updates the event time to the
+current simulation time. If both the old and new values of the
+zero-crossing function are zero, it sets the next event time to
+infinity, indicating no event should occur. For cases where the old and
+new values have the same sign, it calculates the minimum positive root
+of the zero-crossing function, representing the time of the next event,
+ensuring that this time is not too close to zero to avoid spurious
+events. The function then updates the old sign values for future
+comparisons.
+
+#### The solution
+
+This is where the results of the simulation are stored, including:
+Settings, Time points (times\[\]), Variables (vars\[\]), Statistics
+(stats).
+
+**The solution Struct** The LightSol struct is specifically designed to
+hold the solution of a system of ODEs. It contains several fields,
+including size and order, which denote the number of continuous
+variables and the order of the algorithm used, respectively. The
+savedTimes and savedVars fields are vectors that store the time steps
+and corresponding values of the continuous variables at which they were
+recorded during the simulation. Other fields include algName and
+sysName, which specify the names of the algorithm and system being
+solved, alongside absQ, the absolute tolerance used during the
+simulation. The stats field contains an instance of the Stats struct,
+providing access to the performance metrics, while ft holds the final
+time of the simulation. The Stats struct includes fields for totalSteps,
+which counts the total number of steps taken throughout the simulation,
+simulStepCount, representing the number of simultaneous updates during
+the simulation, and evCount, which tallies the number of events that
+occurred. Additionally, the numSteps vector keeps track of the number of
+steps taken for each continuous variable involved in the simulation,
+allowing for detailed analysis of the performance for individual
+components.
+
+The functions defined in conjunction with these structs enable various
+operations related to the simulation's solutions. The createSol function
+initializes a LightSol instance with the specified parameters, while the
+getindex function provides a helper to access either the saved times or
+variables easily. The evaluateSol function allows for the evaluation of
+the solution at a specified time, supporting linear interpolation
+between saved points. Furthermore, the solInterpolated functions enable
+the generation of interpolated solutions across specified intervals,
+creating new solution objects based on the interpolated values and
+times. The show function is tailored to present the statistics in a
+user-friendly format, offering insights into the performance of the
+simulation. Overall, these constructs provide a robust framework for
+managing and analyzing the outcomes of simulations involving ODEs.
+
+**Plotting the Solution:** The plotSol function is designed to visually
+represent the solution of a system of ODEs stored in the solution
+object. It accepts a variety of optional parameters, allowing users to
+customize their plots significantly. The function takes in a solution
+object sol along with indices for the variables to be plotted (xvars).
+Users can also specify a title, axis limits (xlims and ylims), and
+visual styles, such as marker types and whether to display a legend. If
+a title is not provided, it defaults to a composite of various
+parameters, including the system name, algorithm name, absolute
+tolerance, total steps taken, and more.Within the function, each
+selected variable is plotted against its corresponding saved time,
+utilizing different line styles for better distinction. If no specific
+variables are selected, all variables in the solution are plotted by
+default. After constructing the plot, the function checks for specified
+axis limits and applies them accordingly. Finally, the function returns
+the plot object, which can be further modified or saved. In addition to
+basic plotting, the saveSol function allows users to save their plots as
+PNG files, automatically generating filenames based on relevant
+parameters and timestamps. This functionality is crucial for
+documentation and sharing results in a reproducible manner. This
+comprehensive plotting capability ensures that users can effectively
+visualize the behavior of their systems, making the analysis of results
+intuitive and informative.
+
+**Finding the Error:** The getError function computes the relative error
+of a solution compared to a specified reference function, enabling users
+to assess the accuracy of their numerical results. The function iterates
+over the saved time points, and it calculates the sum of the squares of
+the differences between the numerical solution and the true values
+provided by the reference function, as well as the sum of the squares of
+the true values. The relative error is then derived as the square root
+of the ratio of these sums, providing a quantitative measure of the
+solution's deviation from the expected results. This comprehensive error
+analysis is essential for validating the performance of numerical
+methods and ensuring that the solutions produced are both reliable and
+precise. By comparing the numerical results to known reference values,
+users can gain insights into the accuracy and effectiveness of the
+solver, enabling them to make informed decisions about their simulations
+and analyses.
\ No newline at end of file