Add docs/SPECS.md

[DiegoCivi]

Add docs/SPECS.md

Description

Adds the SPECS.md which serves as a detailed guide to understand the projects requirements and design

Co-authored-by: @JulianGCalderon

Checklist

• Linked to Github Issue
• Unit tests added
• Integration tests added.
• This change requires new documentation.
  • Documentation has been added/updated.
  • CHANGELOG has been updated.

[github-actions]

**Hyper Thereading Benchmark results**




hyperfine -r 2 -n "hyper_threading_main threads: 1" 'RAYON_NUM_THREADS=1 ./hyper_threading_main' -n "hyper_threading_pr threads: 1" 'RAYON_NUM_THREADS=1 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 1
  Time (mean ± σ):     24.348 s ±  0.079 s    [User: 23.519 s, System: 0.826 s]
  Range (min … max):   24.292 s … 24.404 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     24.214 s ±  0.005 s    [User: 23.378 s, System: 0.834 s]
  Range (min … max):   24.211 s … 24.218 s    2 runs
 
Summary
  hyper_threading_pr threads: 1 ran
    1.01 ± 0.00 times faster than hyper_threading_main threads: 1




hyperfine -r 2 -n "hyper_threading_main threads: 2" 'RAYON_NUM_THREADS=2 ./hyper_threading_main' -n "hyper_threading_pr threads: 2" 'RAYON_NUM_THREADS=2 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 2
  Time (mean ± σ):     13.204 s ±  0.006 s    [User: 23.521 s, System: 0.860 s]
  Range (min … max):   13.199 s … 13.208 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     13.185 s ±  0.013 s    [User: 23.482 s, System: 0.869 s]
  Range (min … max):   13.176 s … 13.194 s    2 runs
 
Summary
  hyper_threading_pr threads: 2 ran
    1.00 ± 0.00 times faster than hyper_threading_main threads: 2




hyperfine -r 2 -n "hyper_threading_main threads: 4" 'RAYON_NUM_THREADS=4 ./hyper_threading_main' -n "hyper_threading_pr threads: 4" 'RAYON_NUM_THREADS=4 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 4
  Time (mean ± σ):      9.871 s ±  0.016 s    [User: 36.028 s, System: 1.051 s]
  Range (min … max):    9.860 s …  9.882 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):      9.945 s ±  0.347 s    [User: 35.782 s, System: 1.047 s]
  Range (min … max):    9.700 s … 10.190 s    2 runs
 
Summary
  hyper_threading_main threads: 4 ran
    1.01 ± 0.04 times faster than hyper_threading_pr threads: 4




hyperfine -r 2 -n "hyper_threading_main threads: 6" 'RAYON_NUM_THREADS=6 ./hyper_threading_main' -n "hyper_threading_pr threads: 6" 'RAYON_NUM_THREADS=6 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 6
  Time (mean ± σ):      9.979 s ±  0.070 s    [User: 36.151 s, System: 1.076 s]
  Range (min … max):    9.930 s … 10.028 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):      9.814 s ±  0.104 s    [User: 36.633 s, System: 1.050 s]
  Range (min … max):    9.741 s …  9.888 s    2 runs
 
Summary
  hyper_threading_pr threads: 6 ran
    1.02 ± 0.01 times faster than hyper_threading_main threads: 6




hyperfine -r 2 -n "hyper_threading_main threads: 8" 'RAYON_NUM_THREADS=8 ./hyper_threading_main' -n "hyper_threading_pr threads: 8" 'RAYON_NUM_THREADS=8 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 8
  Time (mean ± σ):      9.840 s ±  0.141 s    [User: 36.594 s, System: 1.104 s]
  Range (min … max):    9.741 s …  9.939 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):      9.796 s ±  0.069 s    [User: 36.628 s, System: 1.124 s]
  Range (min … max):    9.747 s …  9.845 s    2 runs
 
Summary
  hyper_threading_pr threads: 8 ran
    1.00 ± 0.02 times faster than hyper_threading_main threads: 8




hyperfine -r 2 -n "hyper_threading_main threads: 16" 'RAYON_NUM_THREADS=16 ./hyper_threading_main' -n "hyper_threading_pr threads: 16" 'RAYON_NUM_THREADS=16 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 16
  Time (mean ± σ):     10.169 s ±  0.027 s    [User: 36.539 s, System: 1.186 s]
  Range (min … max):   10.149 s … 10.188 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):      9.984 s ±  0.103 s    [User: 36.718 s, System: 1.151 s]
  Range (min … max):    9.911 s … 10.056 s    2 runs
 
Summary
  hyper_threading_pr threads: 16 ran
    1.02 ± 0.01 times faster than hyper_threading_main threads: 16

[github-actions]

Benchmark Results for unmodified programs 🚀

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_factorial	2.089 ± 0.018	2.077	2.130	1.00
head big_factorial	2.104 ± 0.052	2.074	2.248	1.01 ± 0.03

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.034 ± 0.026	2.014	2.098	1.00 ± 0.01
head big_fibonacci	2.029 ± 0.009	2.014	2.047	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	7.186 ± 0.038	7.147	7.262	1.00 ± 0.01
head blake2s_integration_benchmark	7.174 ± 0.075	7.119	7.375	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.141 ± 0.006	2.131	2.149	1.00
head compare_arrays_200000	2.163 ± 0.024	2.118	2.216	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.415 ± 0.019	1.394	1.455	1.00
head dict_integration_benchmark	1.417 ± 0.009	1.403	1.434	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.198 ± 0.021	1.181	1.249	1.01 ± 0.02
head field_arithmetic_get_square_benchmark	1.188 ± 0.007	1.179	1.198	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	7.256 ± 0.040	7.188	7.331	1.00
head integration_builtins	7.276 ± 0.108	7.194	7.568	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	7.385 ± 0.180	7.295	7.896	1.01 ± 0.03
head keccak_integration_benchmark	7.316 ± 0.048	7.233	7.405	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.119 ± 0.027	2.096	2.178	1.00
head linear_search	2.119 ± 0.023	2.100	2.180	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.493 ± 0.015	1.480	1.529	1.00 ± 0.01
head math_cmp_and_pow_integration_benchmark	1.492 ± 0.011	1.479	1.515	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.445 ± 0.014	1.431	1.481	1.00 ± 0.01
head math_integration_benchmark	1.441 ± 0.008	1.428	1.458	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.206 ± 0.018	1.195	1.254	1.00 ± 0.02
head memory_integration_benchmark	1.203 ± 0.006	1.189	1.211	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.514 ± 0.004	1.511	1.523	1.00
head operations_with_data_structures_benchmarks	1.521 ± 0.007	1.511	1.532	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	524.8 ± 3.1	521.4	532.8	1.00
head pedersen	526.0 ± 2.9	521.7	531.8	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	615.1 ± 3.7	609.1	622.3	1.01 ± 0.01
head poseidon_integration_benchmark	611.5 ± 2.2	608.5	614.3	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	1.765 ± 0.009	1.753	1.780	1.00
head secp_integration_benchmark	1.770 ± 0.013	1.760	1.806	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	663.8 ± 8.4	654.4	675.1	1.00
head set_integration_benchmark	668.0 ± 5.0	658.9	676.1	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.129 ± 0.014	4.109	4.154	1.00
head uint256_integration_benchmark	4.147 ± 0.021	4.126	4.187	1.00 ± 0.01

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.68%. Comparing base (7d0cb7e) to head (2c35b4c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2105   +/-   ##
=======================================
  Coverage   96.68%   96.68%           
=======================================
  Files         104      104           
  Lines       44026    44026           
=======================================
  Hits        42565    42565           
  Misses       1461     1461           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gabrielbosio]

Is Operations a subsection of Instructions?

[DiegoCivi]

Yes! Did the correction here b282b86