Skip to content

Commit

Permalink
Merge pull request #10 from mongibellili/2-not-correctly-matching-the…
Browse files Browse the repository at this point in the history
…-sciml-interface

update the docs: internals explanation
  • Loading branch information
mongibellili authored Oct 23, 2024
2 parents 34934e5 + 7937f1a commit 8470f91
Show file tree
Hide file tree
Showing 4 changed files with 437 additions and 1 deletion.
Binary file added docs/src/assets/img/diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
28 changes: 28 additions & 0 deletions docs/src/dependencies.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 3 additions & 1 deletion docs/src/developerGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading

0 comments on commit 8470f91

Please sign in to comment.