MathWizard Extension for ODC (v1.0)

MathWizard is a high-performance External Logic library built for OutSystems Developer Cloud (ODC).

It extends the native low-code capabilities of OutSystems by providing advanced mathematical operations that are either computationally expensive or natively unavailable in logic flows. This library bridges the gap for Computer Engineering concepts, enabling high-speed processing for Linear Algebra, Cryptography (Bitwise), Combinatorics, Physics simulations, and Numerical Analysis directly within your ODC server actions.

🚀 Features

• Linear Algebra & Matrices: Comprehensive matrix manipulation toolkit, including addition, multiplication, transposition, and determinant calculation (via Gaussian Elimination).
• Geometry & Physics: 3D Vector mathematics including Euclidean distance and Cross Products, essential for game logic and spatial calculations.
• Numerical Methods: Algorithms for solving complex equations, including a Polynomial Root Finder using the Newton-Raphson method.
• Combinatorics & Probability: Efficient calculation of Permutations ($nPr$) and Combinations ($nCr$), optimized for large numbers to avoid overflow.
• Bitwise Toolkit: A complete set of low-level bit manipulation tools (AND, OR, XOR, NOT, Shifts) essential for implementing flags, permissions, and binary protocols.
• High-Precision Algorithms: Financial calculations using decimal precision and highly optimized algorithms for number theory (Primes, Factorials).

---

📦 Installation & Deployment

1. Build: Run dotnet publish -c Release -r linux-x64 --self-contained false to generate the binaries.
2. Package: Zip the contents of the publish folder (ensure the DLL is at the root of the zip).
3. Upload: Go to the ODC Portal > Assets > External Logic and upload MathWizard.zip.
4. Use: In ODC Studio, go to Manage Dependencies, search for "MathWizard", and select the actions.

---

🧩 Data Structures

1. MatrixModel

OutSystems does not support multi-dimensional arrays (like Decimal[][]) natively in Structures. To bypass this limitation while maintaining performance, this extension uses a Row-Major Flattened List approach.

Attribute	Type	Description
Rows	Integer	The number of rows in the matrix.
Columns	Integer	The number of columns in the matrix.
Values	List of Decimal	The flattened data stream containing all matrix cells.

💡 Concept: How to Save & Flatten a Matrix

When you work with matrices in your head, you see a grid. When you send it to this extension, you must send a single line of numbers.

The Rule (Row-Major Order): Read the matrix from left to right, top to bottom.

Example: A 2x3 Matrix

Imagine you want to process this grid:

$$ \begin{bmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \end{bmatrix} $$

1. Before Flattening (The Conceptual View)

• Rows: 2
• Columns: 3
• Data:
  • Row 0: [1, 2, 3]
  • Row 1: [4, 5, 6]

2. After Flattening (The MatrixModel Structure) To create this in OutSystems logic, you will append values to the Values list in this exact order:

• Rows: 2
• Columns: 3
• Values: [1, 2, 3, 4, 5, 6]

3. Retrieving a Value (The Math) If the extension needs to find the value at Row 1, Column 2 (which is 6), it uses this formula:

$$\text{Index} = (\text{Row} \times \text{TotalColumns}) + \text{Column}$$

$$\text{Index} = (1 \times 3) + 2 = 5$$

Checking the list [1, 2, 3, 4, 5, 6], index 5 is indeed 6.

2. VectorModel

Represents a point or vector in 3D space.

Attribute	Type	Description
X	Decimal	The X coordinate.
Y	Decimal	The Y coordinate.
Z	Decimal	The Z coordinate.

---

📚 Action Reference

1. Matrix Operations (Linear Algebra)

Namespace: Linear Algebra

MatrixAdd

Adds two matrices together cell-by-cell.

• Input: MatrixA, MatrixB
• Output: ResultMatrix
• Rule: Dimensions must match ($Rows_A = Rows_B$ and $Cols_A = Cols_B$).
• Logic: $C_{ij} = A_{ij} + B_{ij}$

MatrixMultiply

Performs the Dot Product of two matrices.

• Input: MatrixA ($N \times M$), MatrixB ($M \times P$)
• Output: ResultMatrix ($N \times P$)
• Rule: The number of Columns in Matrix A must equal the number of Rows in Matrix B.
• Complexity: $O(N \cdot M \cdot P)$

MatrixTranspose

Flips a matrix over its main diagonal, swapping rows and columns.

• Input: Matrix ($R \times C$)
• Output: TransposedMatrix ($C \times R$)
• Example: The vector [1, 2, 3] ($1 \times 3$) becomes a vertical column ($3 \times 1$).

MatrixDeterminant

Calculates the scalar Determinant of a square matrix.

• Input: Matrix ($N \times N$)
• Output: Determinant (Decimal)
• Method: Uses Gaussian Elimination to convert the matrix to Upper Triangular form ($O(N^3)$), avoiding the factorial complexity of recursive expansion.
• Use Case: Essential for checking if a matrix is invertible (non-singular).

---

2. Geometry & Physics

Namespace: Spatial Logic

CalculateDistance

Calculates the Euclidean distance between two 3D points.

• Input: Point1, Point2 (VectorModel)
• Output: Distance (Decimal)
• Formula: $\sqrt{(x_2-x_1)^2 + (y_2-y_1)^2 + (z_2-z_1)^2}$

CalculateCrossProduct

Calculates the vector perpendicular to two input vectors.

• Input: VectorA, VectorB
• Output: ResultVector
• Use Case: Determining surface normals in 3D graphics or torque in physics.
• Visual:

[Image of vector cross product right hand rule]

---

3. Numerical Methods

Namespace: Analysis

SolvePolynomialRoot

Finds a root ($x$ where $y=0$) for any polynomial equation using the Newton-Raphson method.

• Inputs:
  • Coefficients: A list of decimals representing the polynomial formula.
    • Example: [-16, 0, 1] represents $-16 + 0x + 1x^2$ (or $x^2 - 16$).
  • InitialGuess: Where to start looking (e.g., 10).
  • MaxIterations: Safety break (default 100).
• Output: Root (Decimal)
• Method: Iteratively approximates the root using derivatives: $x_{new} = x_{old} - \frac{f(x)}{f'(x)}$.

---

4. Combinatorics & Probability

Namespace: Statistics

CalculatePermutation ($nPr$)

Calculates the number of ordered arrangements of $r$ items from a set of $n$.

• Formula: $P(n,r) = \frac{n!}{(n-r)!}$
• Optimization: Uses iterative multiplication to prevent overflow for large $n$.

CalculateCombination ($nCr$)

Calculates the number of ways to choose $r$ items from $n$ (order irrelevant).

• Formula: $C(n,r) = \frac{n!}{r!(n-r)!}$
• Optimization: Includes symmetry optimization ($C(n, r) == C(n, n-r)$) for speed.

---

5. Bitwise Operations

Namespace: Low-Level Logic Note: All inputs/outputs are 64-bit Long Integers.

Action	Description	Logic Example
BitwiseAnd	Returns 1 if both bits are 1.	101 & 011 = 001
BitwiseOr	Returns 1 if either bit is 1.	101 | 011 = 111
BitwiseXor	Returns 1 if bits are different.	101 ^ 011 = 110
BitwiseNot	Inverts all bits (One's Complement).	~101 = ...111010
BitwiseShiftLeft	Shifts bits left (Multiply by $2^N$).	10 << 1 = 20
BitwiseShiftRight	Shifts bits right (Divide by $2^N$).	10 >> 1 = 5

---

6. Basic Mathematics

Namespace: Algorithms

CalculateFactorial

Calculates the product of an integer and all integers below it.

• Input: Number (Integer)
• Output: Result (Long Integer)
• Note: Uses an iterative approach to prevent Stack Overflow exceptions. Validates for non-negative inputs.

IsPrime

Determines if a number is prime using an optimized trial division.

• Input: Number (Integer)
• Output: IsPrime (Boolean)
• Optimization: Loop runs only up to $\sqrt{N}$, making it efficient for large integers.

CalculateCompoundInterest

Calculates the future value of an investment.

• Inputs:
  • Principal (Decimal): Initial amount.
  • Rate (Decimal): Annual interest rate (e.g., 0.05 for 5%).
  • Years (Integer): Duration.
• Output: TotalAmount (Decimal)
• Formula: $A = P(1 + r)^t$

---

💻 Usage Example (ODC Logic)

Scenario: Verifying the Determinant of a Matrix

1. Create Variables: Define MyMatrix of type MatrixModel and DetValue (Decimal).
2. Initialize Matrix:
   • Set MyMatrix.Rows = 2
   • Set MyMatrix.Columns = 2
   • Use ListAppend to add values 4, 6, 3, 8.
   • (This represents $\begin{bmatrix} 4 & 6 \ 3 & 8 \end{bmatrix}$).
3. Call Action: Drag MatrixDeterminant to the flow.
4. Map Inputs: Set Matrix = MyMatrix.
5. Assert Result: The output should be 14 ($4 \times 8 - 6 \times 3 = 32 - 18 = 14$).

---

🛠 Tech Stack

• Framework: .NET 8.0
• SDK: OutSystems.ExternalLibraries.SDK (v1.5.0)
• Architecture: Server-side C# Library running in Linux Containers (ODC standard).

👤 Author

Developed by Fabian as a component for High-Code Extensions in OutSystems.