Merge pull request #10 from mongibellili/2-not-correctly-matching-the…

…-sciml-interface

update the docs: internals explanation

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.

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)