Profiler Architecture (alnoms.core.profiler)
The Profiler is the "Stopwatch" of the Alnoms Performance Intelligence Engine. It provides the precision timing and statistical rigor required to transform raw execution data into Empirical Truth.
🧭 1. Philosophy: Precision & Purity
Performance data is notoriously noisy due to CPU frequency scaling, background processes, and Garbage Collection (GC). The Alnoms Profiler is designed to isolate the algorithm from the operating system to ensure Deterministic Benchmarking.
Core Pillars of Purity:
- GC Isolation: Garbage collection is temporarily disabled during benchmarking to prevent "jitter" in the data.
- Warmup Cycles: Every test includes untimed warmup runs to prime the CPU cache and branch predictors.
- Argument Deep-Copying: Input data is copied before every run to ensure that in-place mutations (e.g., sorting a list) do not impact subsequent trials.
🔄 2. The Doubling Test (Asymptotic Analysis)
The most powerful feature of the Profiler is the Doubling Test. This mechanism allows Alnoms to prove Big-O complexity through observation rather than just static analysis.
How it Works:
- \(T(N)\): Run the function with input size \(N\) and record the time.
- \(T(2N)\): Double the input size and record the new time.
- Calculate Ratio: Compute \(R = T(2N) / T(N)\).
The Complexity Map:
The Profiler uses the following mathematical thresholds to categorize performance:
| Ratio (\(R\)) | Complexity Class | Scaling Behavior |
|---|---|---|
| \(< 1.4\) | \(O(1) / O(\log N)\) | Near-instant scaling. |
| \(1.4 - 2.8\) | \(O(N)\) | Linear growth; time roughly doubles with data. |
| \(2.8 - 5.5\) | \(O(N^2)\) | Quadratic growth; time quadruples with data. |
| \(5.5 - 10.0\) | \(O(N^3)\) | Cubic growth; time octuples with data. |
| \(> 10.0\) | Exponential | High Growth; dangerous for production. |
⚙️ 3. Internal Mechanics
3.1 Statistical Aggregation Modes
Depending on the environment, you can configure how the Profiler selects the final "score" from multiple repeats:
* min (Default): Captures the "perfect" run, assuming all other variations are OS-level noise.
* median: Most robust for long-running tests with occasional spikes.
* mean: Standard average, useful for high-frequency low-latency tests.
3.2 The Precision Timer
Alnoms utilizes timeit.default_timer, which automatically selects the highest resolution clock available on your platform (e.g., QueryPerformanceCounter on Windows or clock_gettime on Linux).
🧪 4. Example: Doubling Analysis Output
When running a run_doubling_test on a nested loop function, the Profiler produces a report like this:
```text 🔬 ANALYSIS: slow_membership_sum (Mode: min) N | Time (s) | Ratio | Est. Complexity
100 | 0.00012 | - | Initial Round
200 | 0.00047 | 3.92 | O(N^2)
400 | 0.00192 | 4.08 | O(N^2)