The Complexity Profiler and Routing

Purpose

The Complexity Profiler is a static analysis pass within the ARES compiler. It is a system that predicts how fast your program will be before it even runs. It uses this prediction to drive the Heuristic Routing Engine, which automatically picks the best language (C++, Python, or TypeScript) to handle your specific logic.

Why it exists

Different languages are good at different things. C++ is incredibly fast for difficult math, while Python is excellent for data science, and TypeScript is perfect for web services. The Profiler exists to make this choice for you. Instead of you needing to decide which language is best for your algorithm, ARES analyzes the mathematical complexity of your code and routes it to the most efficient environment. This ensures that you always get the best possible performance without needing to be an expert in every language.

How it works

The Profiler categorizes every part of your code into specific "complexity tiers."

1. Tier assignment. Every algorithm in the ARES library has a pre-defined complexity rank, from $O(1)$ (very fast) to $O(2^N)$ (very slow).
2. Loop weighting. The system identifies loops in your code. A simple command inside a loop automatically becomes more complex in the eye of the Profiler.
3. Efficiency Scoring. After identifying all the tiers, the system calculates an "Efficiency Score." It considers things like how much data you are processing and whether you are using specialized web or data science tools.
4. Language Routing. Based on the score, the system makes a final decision:
   • C++ is chosen for complex math and large datasets (Competitive Programming).
   • Python is chosen for data science or tasks involving graphs.
   • TypeScript is chosen for any task that involves setting up a web server.

Intuition

Think of the Complexity Profiler like a professional travel agent. You tell the agent where you want to go (your ARES logic) and how much luggage you have (your data size). The agent then decides whether it's best for you to take a bicycle (Python for small tasks), a high-speed train (C++ for heavy math), or a commercial airplane (TypeScript for web connectivity). You just need to provide the destination, and the agent ensures you take the most efficient path to get there.

Implementation details

The logic for profiling is contained in src/semantics/profiler.ts. It performs a single pass over your code tree to calculate the final complexity score.

• Complexity Merging: When you have multiple statements, the Profiler focuses on the "worst-case" scenario (the slowest part of your code).
• Performance Overrides: If the system detects that you have over 100,000 data points, it will almost always choose C++ regardless of how simple the logic is, just to ensure maximum speed.

Trace example

This is what happens when the Profiler sees a sort command on a large list:

1. Categorization: The system identifies that sort belongs to the $O(N \log N)$ tier.
2. Data check: It sees that your list has $200,000$ items.
3. Decision: Because the task is mathematically difficult and the data is large, the Routing Engine chooses C++ as the target language.
4. Final step: The compiler activates the C++ Emitter to write the final code.

Related entities

• 01_pipeline.md: Phase 4 and 5 of the pipeline are where the Profiler and Router perform their work.
• src/semantics/profiler.ts: The actual code that implements the complexity analysis logic.