widening vars and array based turbo mode working as delegates in ScalarTurboEvaluator.java to provide robustness and versatility

Author: gbenroscience

BENCHMARK_RESULTS.md

@@ -1,4 +1,16 @@
-# ParserNG 1.0.0 Official Benchmarks
+# ParserNG 1.0.2 Official Benchmarks
+
+
+### **ParserNG vs. The Giants: Master Performance Matrix**
+
+| Battleground | Expression Type | Janino (ns/op) | **ParserNG (Turbo)** | **ParserNG Advantage** |
+| :--- | :--- | :--- | :--- | :--- |
+| **Pure Arithmetic** | `x + y + z...` | 251.08 | **119.95** | **2.1x Faster** |
+| **Structural Scale** | `500+ Variables` | **CRASH** | **SUCCESS** | **Only Survivor** |
+| **Functional Heavy** | `20+ sin() calls` | 471.43 | **362.89** | **1.3x Faster** |
+
+---
+
 
 The following data represents high-concurrency performance and memory allocation benchmarks for **ParserNG**, compared against **Janino** (Bytecode Compiler) and **exp4j** (Interpreted).
 

TECHNICAL.md

@@ -0,0 +1,76 @@
+# **ParserNG: Performance & Memory Manifesto**
+
+ParserNG is a high-performance mathematical expression engine for Java, designed for systems where **nanoseconds matter** and **Garbage Collection (GC) is unacceptable.**
+
+
+### **ParserNG vs. The Giants: Master Performance Matrix**
+
+| Battleground | Expression Type | Janino (ns/op) | **ParserNG (Turbo)** | **ParserNG Advantage** |
+| :--- | :--- | :--- | :--- | :--- |
+| **Pure Arithmetic** | `x + y + z...` | 251.08 | **119.95** | **2.1x Faster** |
+| **Structural Scale** | `500+ Variables` | **CRASH** | **SUCCESS** | **Only Survivor** |
+| **Functional Heavy** | `20+ sin() calls` | 471.43 | **362.89** | **1.3x Faster** |
+
+---
+
+
+## **1. Performance: Beyond the "Gold Standard"**
+For years, Janino has been considered the speed leader because it compiles expressions to bytecode. ParserNG’s **Turbo** engine shatters this benchmark.
+
+In head-to-head testing using a complex trigonometric and power-based expression, ParserNG consistently beats both Janino and Parsii.
+
+### **Benchmark Results (Complex Expression)**
+*Expression: `(sin(x) + 2 + ((7-5) * (3.14159 * x^(14-10)) + sin(-3.141) + (0%x)) * x/3 * 3/sqrt(x+12))`*
+
+| Library | Speed (ns/op) | Performance Gap |
+| :--- | :--- | :--- |
+| **ParserNG Turbo (Widening)** | **119.95 ns** | **1.0x (Winner)** |
+| **ParserNG Turbo (Array)** | **133.26 ns** | 1.1x Slower |
+| **Janino** | 251.08 ns | **2.1x Slower** |
+| **Parsii** | 370.29 ns | 3.1x Slower |
+
+**The Verdict:** ParserNG is **2x faster than Janino** and **3x faster than Parsii**, all while operating under the same JVM constraints.
+
+---
+
+## **2. Memory Profile: Zero Allocation, Zero Disturbance**
+High-performance Java isn't just about raw speed; it's about **predictability**. Most parsers create object "noise" that forces the Garbage Collector to pause your application.
+
+### **The "Zero-Allocation" Guarantee**
+ParserNG achieves a steady-state execution with **zero object churn**. 
+* **GC Allocation Rate:** **0.007 MB/sec** (effectively zero).
+* **GC Count:** **0** during the entire measurement period.
+
+### **Metaspace Safety**
+Unlike Janino, which creates a new Java class for every expression (risking **Metaspace OutOfMemoryErrors**), ParserNG uses a reusable, high-density architecture. You can compile millions of unique expressions without bloating the JVM's permanent memory or requiring a restart.
+
+---
+
+## **3. Architecture: Hybrid Variable Passing**
+ParserNG intelligently optimizes how data reaches the CPU.
+
+### **Widening Strategy (The "Register" Path)**
+For expressions within the JVM’s method slot limits (up to 63 variables), ParserNG uses **Widening**. This passes values directly through registers and the stack, achieving the absolute lowest possible latency.
+* **Winner for:** Standard formulas, physics engines, and real-time signals.
+
+### **Array-Based Strategy (The "Unlimited" Path)**
+When expressions grow into hundreds or thousands of variables, ParserNG seamlessly switches to an **Array-Based** approach. This bypasses the JVM’s 255-slot limit, allowing for massive high-dimensional data processing that would crash a standard compiler.
+
+---
+
+## **4. Scalability: Linear Performance**
+ParserNG scales predictably. As you increase variable counts, the "tax" per variable remains under **1 nanosecond** per op, allowing you to build complex models without hitting a performance wall.
+
+| Variables | Array-Based | Widening |
+| :--- | :--- | :--- |
+| **1 Var** | 5.65 ns | 6.17 ns |
+| **20 Vars** | 15.11 ns | 15.34 ns |
+| **63 Vars** | 52.07 ns | **51.60 ns** |
+
+---
+
+## **Summary**
+If you are building high-frequency trading platforms, real-time simulation software, or cloud-native microservices with tight memory budgets, **ParserNG** provides the deterministic speed you need without the Garbage Collection or Metaspace risks of traditional tools.
+
+---
+ 

maven-central-3-month-data.png

@@ -12,9 +12,11 @@
     -->
 
     <name>ParserNG</name>
-    <description>Rich and Performant, Cross Platform Java Library(100% Java)...Version 1.0.0 explodes even higher in execution speed.
-        Version 1.0.1 retains the wild speeds of Version 1.0.0 and brings the memory usage of the turbo mode down to 0.001 B/op(same as for the normal mode)
-        but at nanosecond speeds.Matrix Algebra and other rich features have been optimized in Turbo mode also.
+    <description>Rich and Performant, Cross Platform Java Library(100% Java)...Version 1.0.2 explodes even higher in execution speed.
+        Version 1.0.2 retains the wild speeds of Version 1.0.1. Adds an extra widening technique of variable passing to the Turbo mode,
+        in addition to the current method of array based passing. The widening technique can be sometimes faster than the array based methods,
+        but their speed profiles and memory profiles are similar. Its weakness though is that it cannot use more than 63 variables per expression,
+        whereas the array based approach allows in theory any number up to the max integer size.
         </description>
     <url>https://github.com/gbenroscience/ParserNG</url>
 

pom.xml

@@ -30,10 +30,12 @@ public class ScalarTurboEvaluator implements TurboExpressionEvaluator {
      * {@link ScalarTurboEvaluator#MIN_VAR_COUNT_FOR_ARRAY_BASED_EVALUATOR}, the
      * Array based evaluator will be used
      */
-    public static final int MIN_VAR_COUNT_FOR_ARRAY_BASED_EVALUATOR = 12;
+    public static final int MIN_VAR_COUNT_FOR_ARRAY_BASED_EVALUATOR = 15;
+
+    public static final int MAX_ALLOWED_METHOD_ARGS_BY_JVM = 63;
 
     public ScalarTurboEvaluator(MathExpression me) {
-        this(me, countVariables(me.getCachedPostfix()) < MIN_VAR_COUNT_FOR_ARRAY_BASED_EVALUATOR);
+        this(me, useWidening(me.getCachedPostfix()));
     }
 
     /**
@@ -56,8 +58,8 @@ public ScalarTurboEvaluator(MathExpression me, boolean useWideningVars) {
     public FastCompositeExpression compile() throws Throwable {
         return delegate.compile();
     }
-    
-    public String getDelegateClass(){
+
+    public String getDelegateClass() {
         return delegate.getClass().getSimpleName();
     }
 
@@ -74,4 +76,13 @@ private static int countVariables(MathExpression.Token[] postfix) {
         }
         return maxIndex + 1;
     }
+
+    private static boolean useWidening(MathExpression.Token[] postfix) {
+        int varCount = countVariables(postfix);
+        if (varCount > MAX_ALLOWED_METHOD_ARGS_BY_JVM) {//use array based if more than 63 unique variables are in expression
+            return false;
+        }
+        return varCount < MIN_VAR_COUNT_FOR_ARRAY_BASED_EVALUATOR;
+    }
+
 }

src/main/java/com/github/gbenroscience/parser/turbo/tools/ScalarTurboEvaluator.java

@@ -34,6 +34,7 @@ public class TurboEvaluatorFactory {
      * Intelligently selects and returns the best Turbo engine for the
      * expression.
      * @param me The {@linkplain MathExpression} 
+     * @return A {@link TurboExpressionEvaluator} that can be used to evaluate expressions at turbo speed
      */
     public static TurboExpressionEvaluator getCompiler(MathExpression me) {
         MathExpression.Token[] postfix = me.getCachedPostfix();
@@ -46,7 +47,29 @@ public static TurboExpressionEvaluator getCompiler(MathExpression me) {
                 break;
             }
         }
-        return involvesMatrices ? new MatrixTurboEvaluator(me) : new ScalarTurboEvaluator2(me);
+        return involvesMatrices ? new MatrixTurboEvaluator(me) : new ScalarTurboEvaluator(me);//defaults to an array based approach
+    }
+    /**
+     * 
+     * @param me The root MathExpression
+     * @param useWideningVarsPassing If true, will create a turbo evaluator that uses widening to pass variables, 
+     * else it uses an array based approach. If you are not sure, if your expression has more than 63 unique variables,
+     * definitely set this variable to false. Else test with true or false for your particular expression and see which has higher performance.
+     * They usually give performances within 1-20ns of each other.
+     * @return A {@link TurboExpressionEvaluator} that can be used to evaluate expressions at turbo speed
+     */
+        public static TurboExpressionEvaluator getCompiler(MathExpression me, boolean useWideningVarsPassing) {
+        MathExpression.Token[] postfix = me.getCachedPostfix();
+        boolean involvesMatrices = false;
+
+        // Scan tokens for Matrix indicators
+        for (MathExpression.Token t : postfix) {
+            if (isMatrixToken(t)) {
+                involvesMatrices = true;
+                break;
+            }
+        }
+        return involvesMatrices ? new MatrixTurboEvaluator(me) : new ScalarTurboEvaluator(me, useWideningVarsPassing);//defaults to an array based approach
     }
 
     private static boolean isMatrixToken(MathExpression.Token t) {

src/main/java/com/github/gbenroscience/parser/turbo/tools/TurboEvaluatorFactory.java

@@ -26,8 +26,7 @@ public interface TurboExpressionEvaluator {
 
     /**
      * Compile a postfix token array into a fast-executing expression.
-     *
-     * @param postfix The compiled postfix (RPN) token array 
+     * 
      * @return A FastCompositeExpression ready for evaluation
      * @throws Throwable if compilation fails
      */