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

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 ± σ):     25.898 s ±  0.018 s    [User: 25.106 s, System: 0.789 s]
  Range (min … max):   25.885 s … 25.911 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     25.625 s ±  0.046 s    [User: 24.846 s, System: 0.776 s]
  Range (min … max):   25.592 s … 25.657 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 ± σ):     14.501 s ±  0.024 s    [User: 25.326 s, System: 0.846 s]
  Range (min … max):   14.484 s … 14.517 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     14.336 s ±  0.034 s    [User: 25.048 s, System: 0.766 s]
  Range (min … max):   14.312 s … 14.360 s    2 runs
 
Summary
  hyper_threading_pr threads: 2 ran
    1.01 ± 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 ± σ):     10.671 s ±  0.328 s    [User: 37.753 s, System: 0.987 s]
  Range (min … max):   10.439 s … 10.902 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):     10.526 s ±  0.598 s    [User: 37.798 s, System: 1.006 s]
  Range (min … max):   10.103 s … 10.949 s    2 runs
 
Summary
  hyper_threading_pr threads: 4 ran
    1.01 ± 0.07 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.351 s ±  0.213 s    [User: 38.045 s, System: 1.051 s]
  Range (min … max):   10.200 s … 10.502 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):     10.445 s ±  0.134 s    [User: 37.832 s, System: 1.013 s]
  Range (min … max):   10.350 s … 10.539 s    2 runs
 
Summary
  hyper_threading_main threads: 6 ran
    1.01 ± 0.02 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 ± σ):     10.357 s ±  0.026 s    [User: 38.305 s, System: 1.054 s]
  Range (min … max):   10.339 s … 10.376 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):     10.268 s ±  0.178 s    [User: 38.241 s, System: 1.001 s]
  Range (min … max):   10.142 s … 10.393 s    2 runs
 
Summary
  hyper_threading_pr threads: 8 ran
    1.01 ± 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.351 s ±  0.193 s    [User: 38.672 s, System: 1.120 s]
  Range (min … max):   10.215 s … 10.488 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):     10.262 s ±  0.051 s    [User: 38.775 s, System: 1.085 s]
  Range (min … max):   10.226 s … 10.299 s    2 runs
 
Summary
  hyper_threading_pr threads: 16 ran
    1.01 ± 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.147 ± 0.055	2.100	2.282	1.01 ± 0.03
head big_factorial	2.123 ± 0.030	2.091	2.178	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.060 ± 0.016	2.041	2.097	1.00 ± 0.01
head big_fibonacci	2.051 ± 0.017	2.024	2.078	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	7.803 ± 0.049	7.711	7.873	1.00
head blake2s_integration_benchmark	7.861 ± 0.109	7.744	8.098	1.01 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.203 ± 0.025	2.170	2.239	1.00 ± 0.01
head compare_arrays_200000	2.199 ± 0.015	2.177	2.232	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.434 ± 0.019	1.413	1.462	1.00 ± 0.02
head dict_integration_benchmark	1.427 ± 0.018	1.410	1.469	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.236 ± 0.005	1.229	1.245	1.00
head field_arithmetic_get_square_benchmark	1.237 ± 0.004	1.233	1.244	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	7.923 ± 0.042	7.846	7.990	1.00 ± 0.01
head integration_builtins	7.917 ± 0.040	7.844	7.971	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	8.146 ± 0.081	8.056	8.285	1.00 ± 0.01
head keccak_integration_benchmark	8.133 ± 0.043	8.083	8.218	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.189 ± 0.023	2.160	2.230	1.01 ± 0.02
head linear_search	2.171 ± 0.030	2.139	2.223	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.498 ± 0.014	1.481	1.531	1.00
head math_cmp_and_pow_integration_benchmark	1.501 ± 0.014	1.487	1.534	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.448 ± 0.011	1.434	1.475	1.00 ± 0.01
head math_integration_benchmark	1.444 ± 0.006	1.433	1.455	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.205 ± 0.005	1.199	1.215	1.00
head memory_integration_benchmark	1.218 ± 0.008	1.205	1.230	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.571 ± 0.013	1.558	1.602	1.00
head operations_with_data_structures_benchmarks	1.574 ± 0.011	1.562	1.597	1.00 ± 0.01

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	533.5 ± 6.4	527.5	549.6	1.01 ± 0.01
head pedersen	530.4 ± 1.3	528.7	533.3	1.00

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	619.7 ± 3.2	615.6	625.1	1.00
head poseidon_integration_benchmark	622.2 ± 4.6	617.7	634.2	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	1.827 ± 0.019	1.802	1.856	1.00
head secp_integration_benchmark	1.837 ± 0.024	1.812	1.880	1.01 ± 0.02

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	631.1 ± 1.5	628.6	632.9	1.00 ± 0.00
head set_integration_benchmark	628.2 ± 1.2	626.3	630.2	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.314 ± 0.027	4.273	4.348	1.00 ± 0.01
head uint256_integration_benchmark	4.307 ± 0.047	4.273	4.433	1.00

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.67%. Comparing base (e339ab7) to head (23f4a13).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2105      +/-   ##
==========================================
+ Coverage   96.65%   96.67%   +0.01%     
==========================================
  Files         103      103              
  Lines       43544    43568      +24     
==========================================
+ Hits        42089    42118      +29     
+ Misses       1455     1450       -5     

☔ 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