diff --git a/README.md b/README.md index f6dffcd90b..b18709ab03 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,22 @@ # Reactant.jl -[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://enzymead.github.io/Reactant.jl/stable) -[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://enzymead.github.io/Reactant.jl/dev) -[![Build Status](https://github.com/EnzymeAD/Reactant.jl/workflows/CI/badge.svg)](https://github.com/EnzymeAD/Reactant.jl/actions) +
+ +[![Latest Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://enzymead.github.io/Reactant.jl/dev) +[![Stable Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://enzymead.github.io/Reactant.jl/stable) + +[![CI](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/CI.yml) [![Coverage](https://codecov.io/gh/EnzymeAD/Reactant.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/EnzymeAD/Reactant.jl) +[![Benchmarks](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/benchmark.yml/badge.svg?branch=main)](https://enzymead.github.io/Reactant.jl/benchmarks/) + +[![Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Fmonthly_downloads%2FReactant&query=total_requests&suffix=%2Fmonth&label=Downloads)](https://juliapkgstats.com/pkg/Reactant) +[![Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Ftotal_downloads%2FReactant&query=total_requests&&label=Total%20Downloads)](https://juliapkgstats.com/pkg/Reactant) -> [!WARNING] -> This package is under active development at the moment and may change its API and supported end systems at any time. End-users are advised to wait until a corresponding release with broader availability is made. Package developers are suggested to try out Reactant for integration, but should be advised of the same risks. +[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl) +[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) +[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/JuliaDiff/BlueStyle) + +
Reactant takes Julia function and compile it into MLIR and run fancy optimizations on top of it, including using EnzymeMLIR for automatic differentiation, and create relevant executables for CPU/GPU/TPU via XLA. It presently operates as a tracing system. Compiled functions will assume the same control flow pattern as was originally taken by objects used at compile time, and control flow (e.g. if, for) as well as any type instabilities will be removed. The benefits of this approach is immediately making all such code available for advanced optimization with little developer effort. This system and corresponding semantics is subject to change to a (potentially partial) source rewriter in the future. @@ -16,7 +26,7 @@ Reactant provides two new array types at its core, a ConcreteRArray and a Traced using Reactant julia_data = ones(2, 10) -reactant_data = Reactant.ConcreteRArray(julia_data) +reactant_data = Reactant.to_rarray(julia_data) ``` You can also create a ConcreteRArray-version of an arbitrary data type by tracing through the structure, like below. This method will automatically handle recursive data structures or shared objects. @@ -30,13 +40,13 @@ end pair = Pair(ones(3), ones(10)) reactant_pair = Reactant.to_rarray(pair) -``` +``` To compile programs using ConcreteRArray's, one uses the compile function, like as follows: ```julia -input1 = Reactant.ConcreteRArray(ones(10)) -input2 = Reactant.ConcreteRArray(ones(10)) +input1 = Reactant.to_rarray(ones(10)) +input2 = Reactant.to_rarray(ones(10)) function sinsum_add(x, y) return sum(sin.(x) .+ y) diff --git a/docs/src/introduction/FAQs.md b/docs/src/introduction/FAQs.md index 1505b954f6..89b9887455 100644 --- a/docs/src/introduction/FAQs.md +++ b/docs/src/introduction/FAQs.md @@ -19,6 +19,7 @@ When you encounter OOM (Out of Memory) errors, you can try to clear the cache by Julia's builtin `GC.gc()` between memory-intensive operations. !!! note + This will only free memory which is not currently live. If the result of compiled function was stored in a vector, it will still be alive and `GC.gc()` won't free it. @@ -85,7 +86,7 @@ After using Julia's built-in `GC.gc()`: ## Benchmark results feel suspiciously fast If you see benchmark results that are suspiciously fast, it's likely because the benchmark -was executed with compiled functions where `sync=false` was used (the default). In this case, the compiled +was executed with compiled functions where `sync=false` was used (the default). In this case, the compiled function will be executed asynchronously, and the benchmark results will be the time it takes for the function to schedule the computation on the device. Compile functions with `sync=true` to get the actual runtime. You can also use the `Reactant.synchronize` on the result of the computation to block until the computation is complete. @@ -106,13 +107,13 @@ y = Reactant.to_rarray(rand(Float32, 1000)) @benchmark f($x, $y) setup=(f = @compile sync=false myfunc($x, $y)) ``` -``` +```julia BenchmarkTools.Trial: 199 samples with 9 evaluations per sample. Range (min … max): 2.926 μs … 14.333 μs ┊ GC (min … max): 0.00% … 0.00% Time (median): 3.607 μs ┊ GC (median): 0.00% Time (mean ± σ): 4.210 μs ± 1.968 μs ┊ GC (mean ± σ): 0.00% ± 0.00% - █▅▄▂ + █▅▄▂ ▇█████▇█▅▅▃▃▂▃▄▂▂▁▁▂▁▁▂▁▁▁▁▁▂▁▁▁▁▂▁▁▁▃▁▁▁▁▁▂▁▁▁▁▁▁▁▂▃▁▂▁▁▃ ▂ 2.93 μs Histogram: frequency by time 12.5 μs < @@ -123,13 +124,13 @@ BenchmarkTools.Trial: 199 samples with 9 evaluations per sample. @benchmark f($x, $y) setup=(f = @compile sync=true myfunc($x, $y)) ``` -``` +```julia BenchmarkTools.Trial: 221 samples with 8 evaluations per sample. Range (min … max): 8.974 μs … 42.443 μs ┊ GC (min … max): 0.00% … 0.00% Time (median): 11.688 μs ┊ GC (median): 0.00% Time (mean ± σ): 12.264 μs ± 3.070 μs ┊ GC (mean ± σ): 0.00% ± 0.00% - █▃ ▅▇██▃▄ ▄█▃▄▂▅ ▇ ▂ ▂ + █▃ ▅▇██▃▄ ▄█▃▄▂▅ ▇ ▂ ▂ ▇▆████████████████▇███▇▃▆▆██▅▅▅▆▆▅▇▁▆▁▁▃▁▃▁▆▁▁▃▁▁▁▁▃▁▁▁▅▁▁▅ ▅ 8.97 μs Histogram: frequency by time 20.2 μs < @@ -137,21 +138,31 @@ BenchmarkTools.Trial: 221 samples with 8 evaluations per sample. ``` ```julia -@benchmark begin - result = f($x, $y); - Reactant.synchronize(result) +@benchmark begin + result = f($x, $y); + Reactant.synchronize(result) end setup=(f = @compile sync=false myfunc(x, y)) ``` -``` +```julia BenchmarkTools.Trial: 233 samples with 8 evaluations per sample. Range (min … max): 8.911 μs … 19.609 μs ┊ GC (min … max): 0.00% … 0.00% Time (median): 12.479 μs ┊ GC (median): 0.00% Time (mean ± σ): 12.758 μs ± 2.219 μs ┊ GC (mean ± σ): 0.00% ± 0.00% - ▁▄▄▄▃▂▁ ▃ ▄█▂ ▆▄▂ ▃ ▁ ▃ ▁ + ▁▄▄▄▃▂▁ ▃ ▄█▂ ▆▄▂ ▃ ▁ ▃ ▁ ▄▃▄▆▆████████▆██▆▇███▆███▇█▄▄▆██▇▇█▇▆▄██▇▁▆▄▃▃▁▁▁▁▃▁▁▁▁▄▁▁▃ ▄ 8.91 μs Histogram: frequency by time 19.3 μs < Memory estimate: 400 bytes, allocs estimate: 14. -``` \ No newline at end of file +``` + +## XLA verbosity flags + +XLA has special logging flags that can be used to get more information about the compilation +process. These flags are: + +1. `TF_CPP_MAX_VLOG_LEVEL`: This set the max verbosity level for XLA, i.e. all logging + for `VLOG(level)` where `level <= TF_CPP_MAX_VLOG_LEVEL` will be printed. +2. `TF_CPP_MIN_VLOG_LEVEL`: This set the min verbosity level for XLA, i.e. all logging + for `VLOG(level)` where `level >= TF_CPP_MIN_VLOG_LEVEL` will be printed.