Add docs/SPECS.md

[DiegoCivi]

Add docs/SPECS.md

Closes #2188

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.627 s ±  0.030 s    [User: 23.768 s, System: 0.857 s]
  Range (min … max):   24.606 s … 24.649 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     24.673 s ±  0.015 s    [User: 23.832 s, System: 0.839 s]
  Range (min … max):   24.662 s … 24.684 s    2 runs
 
Summary
  hyper_threading_main threads: 1 ran
    1.00 ± 0.00 times faster than hyper_threading_pr 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.427 s ±  0.010 s    [User: 23.936 s, System: 0.867 s]
  Range (min … max):   13.420 s … 13.435 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     13.457 s ±  0.011 s    [User: 24.020 s, System: 0.871 s]
  Range (min … max):   13.449 s … 13.464 s    2 runs
 
Summary
  hyper_threading_main threads: 2 ran
    1.00 ± 0.00 times faster than hyper_threading_pr 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 ± σ):     10.255 s ±  0.238 s    [User: 36.641 s, System: 1.096 s]
  Range (min … max):   10.087 s … 10.424 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):     10.365 s ±  0.423 s    [User: 36.476 s, System: 1.043 s]
  Range (min … max):   10.065 s … 10.664 s    2 runs
 
Summary
  hyper_threading_main threads: 4 ran
    1.01 ± 0.05 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 ± σ):     10.110 s ±  0.132 s    [User: 36.756 s, System: 1.068 s]
  Range (min … max):   10.017 s … 10.203 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):     10.039 s ±  0.086 s    [User: 36.522 s, System: 1.053 s]
  Range (min … max):    9.978 s … 10.101 s    2 runs
 
Summary
  hyper_threading_pr threads: 6 ran
    1.01 ± 0.02 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 ± σ):     10.240 s ±  0.133 s    [User: 36.865 s, System: 1.095 s]
  Range (min … max):   10.146 s … 10.334 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):     10.062 s ±  0.224 s    [User: 36.981 s, System: 1.086 s]
  Range (min … max):    9.904 s … 10.220 s    2 runs
 
Summary
  hyper_threading_pr threads: 8 ran
    1.02 ± 0.03 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 ± σ):      9.891 s ±  0.070 s    [User: 37.635 s, System: 1.159 s]
  Range (min … max):    9.841 s …  9.940 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):      9.981 s ±  0.148 s    [User: 37.428 s, System: 1.158 s]
  Range (min … max):    9.877 s … 10.086 s    2 runs
 
Summary
  hyper_threading_main threads: 16 ran
    1.01 ± 0.02 times faster than hyper_threading_pr threads: 16

[github-actions]

Benchmark Results for unmodified programs 🚀

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_factorial	2.103 ± 0.021	2.071	2.127	1.00
head big_factorial	2.109 ± 0.022	2.079	2.133	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.036 ± 0.021	2.006	2.064	1.00
head big_fibonacci	2.053 ± 0.014	2.035	2.076	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	7.322 ± 0.124	7.101	7.551	1.00 ± 0.02
head blake2s_integration_benchmark	7.305 ± 0.079	7.141	7.360	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.183 ± 0.025	2.141	2.218	1.00 ± 0.02
head compare_arrays_200000	2.183 ± 0.023	2.152	2.221	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.446 ± 0.014	1.426	1.471	1.01 ± 0.01
head dict_integration_benchmark	1.429 ± 0.013	1.414	1.445	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.210 ± 0.011	1.192	1.228	1.01 ± 0.01
head field_arithmetic_get_square_benchmark	1.201 ± 0.007	1.190	1.215	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	7.428 ± 0.244	7.236	8.090	1.01 ± 0.03
head integration_builtins	7.390 ± 0.042	7.327	7.446	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	7.458 ± 0.153	7.254	7.848	1.00
head keccak_integration_benchmark	7.495 ± 0.220	7.229	7.878	1.00 ± 0.04

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.153 ± 0.017	2.125	2.182	1.00 ± 0.01
head linear_search	2.142 ± 0.013	2.117	2.162	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.517 ± 0.015	1.502	1.544	1.00 ± 0.01
head math_cmp_and_pow_integration_benchmark	1.515 ± 0.012	1.499	1.537	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.480 ± 0.019	1.448	1.518	1.01 ± 0.02
head math_integration_benchmark	1.460 ± 0.020	1.435	1.495	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.210 ± 0.012	1.192	1.227	1.00
head memory_integration_benchmark	1.216 ± 0.016	1.199	1.250	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.544 ± 0.015	1.527	1.576	1.00 ± 0.01
head operations_with_data_structures_benchmarks	1.539 ± 0.011	1.531	1.560	1.00

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	526.6 ± 2.2	523.0	530.6	1.00
head pedersen	526.8 ± 2.4	522.9	530.4	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	628.6 ± 7.2	621.9	645.7	1.01 ± 0.02
head poseidon_integration_benchmark	624.2 ± 6.5	615.5	639.8	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	1.776 ± 0.017	1.761	1.814	1.00
head secp_integration_benchmark	1.787 ± 0.021	1.762	1.833	1.01 ± 0.02

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	652.2 ± 2.4	647.2	656.1	1.00 ± 0.01
head set_integration_benchmark	651.1 ± 3.1	646.4	657.1	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.175 ± 0.072	4.091	4.323	1.02 ± 0.02
head uint256_integration_benchmark	4.105 ± 0.022	4.077	4.136	1.00

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.68%. Comparing base (8d716b7) to head (9f53fc3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2105   +/-   ##
=======================================
  Coverage   96.68%   96.68%           
=======================================
  Files         104      104           
  Lines       44027    44027           
=======================================
  Hits        42566    42566           
  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