Consolidate VM documentation

[JulianGCalderon]

Consolidate documentation

This PR consolidates documentation from other repositories into the docs directory.

Description

• Adds tooling section to documentation, linking to the auxiliary crates
• Adds How does the VM work? section, explaining core VM concepts. It was taken from https://github.com/lambdaclass/cairo-vm_in_go, but modified to be more generic.

Next Steps

• Consider which parts of the main README.md can be moved to the docs directory
• Consider how to structure the docs: md book? rust docs?
• Review code examples and CLI flags
• Review auxiliary crates documentation

[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 ± σ):     32.084 s ±  0.111 s    [User: 31.360 s, System: 0.721 s]
  Range (min … max):   32.006 s … 32.162 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     31.571 s ±  0.040 s    [User: 30.807 s, System: 0.762 s]
  Range (min … max):   31.543 s … 31.600 s    2 runs
 
Summary
  hyper_threading_pr threads: 1 ran
    1.02 ± 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 ± σ):     17.996 s ±  0.116 s    [User: 31.409 s, System: 0.744 s]
  Range (min … max):   17.914 s … 18.078 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     17.664 s ±  0.051 s    [User: 30.880 s, System: 0.749 s]
  Range (min … max):   17.628 s … 17.700 s    2 runs
 
Summary
  hyper_threading_pr threads: 2 ran
    1.02 ± 0.01 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 ± σ):     12.090 s ±  0.389 s    [User: 43.111 s, System: 0.889 s]
  Range (min … max):   11.815 s … 12.365 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):     12.196 s ±  0.586 s    [User: 43.642 s, System: 0.872 s]
  Range (min … max):   11.782 s … 12.610 s    2 runs
 
Summary
  hyper_threading_main threads: 4 ran
    1.01 ± 0.06 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 ± σ):     12.282 s ±  0.038 s    [User: 43.198 s, System: 0.936 s]
  Range (min … max):   12.255 s … 12.309 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):     12.086 s ±  0.241 s    [User: 43.372 s, System: 0.914 s]
  Range (min … max):   11.916 s … 12.257 s    2 runs
 
Summary
  hyper_threading_pr threads: 6 ran
    1.02 ± 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 ± σ):     11.696 s ±  0.212 s    [User: 43.622 s, System: 0.918 s]
  Range (min … max):   11.546 s … 11.846 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):     11.965 s ±  0.531 s    [User: 43.955 s, System: 0.931 s]
  Range (min … max):   11.590 s … 12.340 s    2 runs
 
Summary
  hyper_threading_main threads: 8 ran
    1.02 ± 0.05 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 ± σ):     11.770 s ±  0.241 s    [User: 43.919 s, System: 1.064 s]
  Range (min … max):   11.600 s … 11.941 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):     11.970 s ±  0.171 s    [User: 44.128 s, System: 1.078 s]
  Range (min … max):   11.849 s … 12.091 s    2 runs
 
Summary
  hyper_threading_main threads: 16 ran
    1.02 ± 0.03 times faster than hyper_threading_pr threads: 16

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.33%. Comparing base (3f3df3e) to head (f112a3e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1866   +/-   ##
=======================================
  Coverage   96.33%   96.33%           
=======================================
  Files         102      102           
  Lines       40751    40751           
=======================================
  Hits        39259    39259           
  Misses       1492     1492           

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

[github-actions]

Benchmark Results for unmodified programs 🚀

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_factorial	2.516 ± 0.087	2.445	2.719	1.02 ± 0.04
head big_factorial	2.465 ± 0.022	2.442	2.495	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.444 ± 0.088	2.373	2.613	1.02 ± 0.04
head big_fibonacci	2.401 ± 0.018	2.376	2.421	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	9.109 ± 0.208	8.918	9.437	1.01 ± 0.02
head blake2s_integration_benchmark	8.992 ± 0.020	8.959	9.026	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.581 ± 0.052	2.509	2.679	1.01 ± 0.02
head compare_arrays_200000	2.554 ± 0.036	2.512	2.615	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.682 ± 0.016	1.662	1.703	1.01 ± 0.01
head dict_integration_benchmark	1.672 ± 0.011	1.658	1.694	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.422 ± 0.047	1.393	1.551	1.00
head field_arithmetic_get_square_benchmark	1.432 ± 0.025	1.405	1.479	1.01 ± 0.04

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	9.245 ± 0.291	9.041	10.051	1.00
head integration_builtins	9.347 ± 0.419	9.037	10.098	1.01 ± 0.06

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	9.358 ± 0.143	9.250	9.739	1.00
head keccak_integration_benchmark	9.361 ± 0.164	9.257	9.805	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.554 ± 0.029	2.518	2.593	1.00
head linear_search	2.566 ± 0.073	2.516	2.767	1.00 ± 0.03

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.725 ± 0.013	1.709	1.753	1.00
head math_cmp_and_pow_integration_benchmark	1.749 ± 0.034	1.722	1.831	1.01 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.725 ± 0.060	1.675	1.835	1.02 ± 0.04
head math_integration_benchmark	1.690 ± 0.022	1.671	1.740	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.406 ± 0.018	1.390	1.438	1.00
head memory_integration_benchmark	1.435 ± 0.047	1.394	1.537	1.02 ± 0.04

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.790 ± 0.014	1.775	1.821	1.00
head operations_with_data_structures_benchmarks	1.802 ± 0.028	1.780	1.869	1.01 ± 0.02

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	582.7 ± 5.0	576.8	590.2	1.00
head pedersen	588.0 ± 12.7	579.3	622.6	1.01 ± 0.02

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	690.2 ± 5.2	681.5	698.1	1.00
head poseidon_integration_benchmark	690.6 ± 9.0	679.8	707.1	1.00 ± 0.02

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	2.041 ± 0.020	2.021	2.077	1.00
head secp_integration_benchmark	2.072 ± 0.027	2.045	2.133	1.01 ± 0.02

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	657.1 ± 7.9	651.6	677.1	1.00
head set_integration_benchmark	660.7 ± 4.6	654.9	671.9	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.950 ± 0.036	4.908	5.015	1.00
head uint256_integration_benchmark	5.060 ± 0.130	4.976	5.417	1.02 ± 0.03

[fmoletta]

🚀