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.759 s ±  0.075 s    [User: 23.868 s, System: 0.888 s]
  Range (min … max):   24.706 s … 24.812 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     24.741 s ±  0.051 s    [User: 23.867 s, System: 0.871 s]
  Range (min … max):   24.704 s … 24.777 s    2 runs
 
Summary
  hyper_threading_pr threads: 1 ran
    1.00 ± 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.484 s ±  0.018 s    [User: 24.026 s, System: 0.884 s]
  Range (min … max):   13.471 s … 13.497 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     13.487 s ±  0.056 s    [User: 23.933 s, System: 0.871 s]
  Range (min … max):   13.448 s … 13.527 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.390 s ±  0.043 s    [User: 36.465 s, System: 1.054 s]
  Range (min … max):   10.360 s … 10.421 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):      9.976 s ±  0.168 s    [User: 36.982 s, System: 1.071 s]
  Range (min … max):    9.857 s … 10.095 s    2 runs
 
Summary
  hyper_threading_pr threads: 4 ran
    1.04 ± 0.02 times faster than hyper_threading_main 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.120 s ±  0.012 s    [User: 36.405 s, System: 1.092 s]
  Range (min … max):   10.112 s … 10.128 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):     10.318 s ±  0.253 s    [User: 36.618 s, System: 1.071 s]
  Range (min … max):   10.139 s … 10.497 s    2 runs
 
Summary
  hyper_threading_main threads: 6 ran
    1.02 ± 0.03 times faster than hyper_threading_pr 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.911 s ±  0.149 s    [User: 37.103 s, System: 1.089 s]
  Range (min … max):    9.806 s … 10.016 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):      9.953 s ±  0.138 s    [User: 37.381 s, System: 1.127 s]
  Range (min … max):    9.856 s … 10.050 s    2 runs
 
Summary
  hyper_threading_main threads: 8 ran
    1.00 ± 0.02 times faster than hyper_threading_pr 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.153 s ±  0.192 s    [User: 37.054 s, System: 1.213 s]
  Range (min … max):   10.017 s … 10.288 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):     10.113 s ±  0.111 s    [User: 37.147 s, System: 1.194 s]
  Range (min … max):   10.035 s … 10.192 s    2 runs
 
Summary
  hyper_threading_pr threads: 16 ran
    1.00 ± 0.02 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.015	2.070	2.112	1.00 ± 0.01
head big_factorial	2.081 ± 0.020	2.057	2.114	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.033 ± 0.016	2.012	2.060	1.00 ± 0.01
head big_fibonacci	2.024 ± 0.018	1.996	2.055	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	7.230 ± 0.160	7.034	7.620	1.00
head blake2s_integration_benchmark	7.278 ± 0.121	7.078	7.543	1.01 ± 0.03

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.138 ± 0.011	2.117	2.156	1.00
head compare_arrays_200000	2.150 ± 0.026	2.118	2.195	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.408 ± 0.010	1.388	1.429	1.00
head dict_integration_benchmark	1.421 ± 0.008	1.408	1.437	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.198 ± 0.018	1.180	1.237	1.00
head field_arithmetic_get_square_benchmark	1.212 ± 0.040	1.185	1.288	1.01 ± 0.04

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	7.349 ± 0.080	7.181	7.473	1.00 ± 0.02
head integration_builtins	7.336 ± 0.084	7.182	7.415	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	7.406 ± 0.095	7.225	7.494	1.00 ± 0.02
head keccak_integration_benchmark	7.382 ± 0.088	7.253	7.493	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.159 ± 0.034	2.115	2.240	1.01 ± 0.02
head linear_search	2.144 ± 0.017	2.121	2.169	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.498 ± 0.013	1.476	1.514	1.00 ± 0.01
head math_cmp_and_pow_integration_benchmark	1.496 ± 0.010	1.483	1.512	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.439 ± 0.011	1.419	1.449	1.00
head math_integration_benchmark	1.446 ± 0.020	1.424	1.487	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.199 ± 0.017	1.180	1.233	1.00
head memory_integration_benchmark	1.206 ± 0.013	1.186	1.229	1.01 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.525 ± 0.006	1.516	1.534	1.00
head operations_with_data_structures_benchmarks	1.534 ± 0.007	1.525	1.548	1.01 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	527.0 ± 7.1	522.5	546.9	1.00
head pedersen	527.4 ± 2.3	525.1	532.9	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	608.0 ± 4.5	603.9	616.1	1.00
head poseidon_integration_benchmark	612.7 ± 6.5	603.7	627.5	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	1.761 ± 0.008	1.752	1.771	1.00
head secp_integration_benchmark	1.774 ± 0.010	1.764	1.798	1.01 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	643.7 ± 2.4	639.8	647.4	1.00
head set_integration_benchmark	645.3 ± 2.7	641.6	651.1	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.115 ± 0.072	4.057	4.286	1.00
head uint256_integration_benchmark	4.131 ± 0.037	4.075	4.180	1.00 ± 0.02

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.68%. Comparing base (a3f1ae9) to head (5356ae3).

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