Merge pull request #23 from JuliaPerf/MPI-integration

New paper version

Author: Dvegrod

Project.toml

@@ -10,6 +10,7 @@ CountFlops = "1db9610d-79e1-487a-8d40-77f3295c7593"
 CpuId = "adafc99b-e345-5852-983c-f28acb93d879"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MLStyle = "d8e11817-5142-5d16-987a-aa16d5891078"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"

README.md

@@ -1,14 +1,99 @@
-# PerfTest
+# PerfTest.jl - A performance unit testing framework
+
+NOTE: This package is under active development, bugs may lurk around, if a bug is found please raise an issue so it can be adressed. Thanks :)
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaPerf.github.io/PerfTest.jl/stable)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaPerf.github.io/PerfTest.jl/dev)
 [![CI](https://github.com/JuliaPerf/PerfTest.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/JuliaPerf/PerfTest.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JuliaPerf/PerfTest.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaPerf/PerfTest.jl)
 
-> :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: This repository is under construction :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction:
+The package PerfTest provides the user with a performance regression unit testing framework. This package is focused on providing a simple and fast way to develop performance suites, with additional features to customise them for more comprehensice use cases.
+
+## Basic performance evaluation
+
+PerfTest.jl provides a set of macros to provide declarative instructions to the performance testing suit generator. A simple case will be shown here.
+
+```julia
+module VecOps
+function innerProduct(A , B)
+    @assert length(A) == length(B)
+
+    r = 0.
+
+    for i in eachindex(A)
+        r += A[i] * B[i]
+    end
+
+    return r
+end
+end
+```
+
+In this basic example, we are implementing a inner product function as part of a bigger vector operation package. We are interested in evaluating the performance of that product, the following test file is a recipe to do so:
+
+
+```julia
+using Test, PerfTest
+
+# Disable regression enable verbosity to see successful tests
+@perftest_config "
+[general]
+verbose = true
+"
+
+@testset "Simple test" begin
+
+    N = 1000
+    A,B = rand(N), rand(N)
+
+    @perfcompare :median_time < (0.000005 * N)
+    @perftest VecOps.innerProduct(A,B)
+
+end
+
+```
+
+Where:
+    @perftest sets the computation to target for the tests.
+    @perfcompare sets the testing methodology which is comparing the median time elapsed against a reference that is dependent on the size of the vectors.
+    @perftest_config sets the configuration in a TOML format, in this case to disable automatic regression testing
+
+
+PertTest.jl relies on a configuration file written in TOML to refer for settings that are not specified anywhere else. In case no file is present, it will be made with the default configuration enabled. Please see the documentation for more information.
+
+## Dependencies
+
+```
+BenchmarkTools
+CountFlops
+CpuId
+JLD2
+JSON
+MLStyle
+MacroTools
+STREAMBenchmark
+Suppressor
+UnicodePlots
+Dates
+ LinearAlgebra
+Pkg
+Printf
+TOML
+Test
+```
+
+## Installation
+ImplicitGlobalGrid may be installed directly with the [Julia package manager](https://docs.julialang.org/en/v1/stdlib/Pkg/index.html) from the REPL:
+```julia-repl
+julia>]
+  pkg> add https://github.com/JuliaPerf/PerfTest.jl
+  pkg> test PerfTest
+```
 
+## Questions, comments and discussions
 
-This is the source repository of the Julia package `PerfTest.jl`. Please head to the [-> documentation website <-](https://JuliaPerf.github.io/PerfTest.jl) to learn about its usage.
+Please email: [email protected] or raise an issue.
 
+## Your contributions
 
-> :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: This repository is under construction :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction: :construction:
+Help is more than welcome! If you have an idea/contribution that could benefit from this project, please share!

docs/src/api.MD

@@ -33,6 +33,6 @@ Order = [:function, :macro]
 ```
 #### Documentation
 ```@autodocs
-Modules = [PerfTest, PerfTest.Configuration]
+Modules = [PerfTest, PerfTest.Configuration, PerfTest.BencherInterface]
 Order   = [:function, :macro]
 ```

examples/example-paper-implicitglobalgrid/EXP_test_halo_thr.jl

@@ -13,8 +13,13 @@ import ImplicitGlobalGrid: @require, longnameof
 using ThreadPinning
 pinthreads(:compact)
 threadinfo()
-NTHREADS = 8
+NTHREADS = 16
 
+# 256M Elements on STREAM Benchmark (2GB)
+@perftest_config "
+[machine_benchmarking]
+memory_bandwidth_test_buffer_size = 536870912
+"
 
 array_types          = ["CPU"]
 gpu_array_types      = []
@@ -31,7 +36,8 @@ MPI.Init();
 nprocs = MPI.Comm_size(MPI.COMM_WORLD); # NOTE: these tests can run with any number of processes.
 ndims_mpi = GG.NDIMS_MPI;
 nneighbors_per_dim = GG.NNEIGHBORS_PER_DIM; # Should be 2 (one left and one right neighbor).
-nx = Int(round(sqrt(1024^3/4/16*NTHREADS/nprocs)));
+# 256M Elements (2GB)
+nx = Int(round(sqrt(536870912/16*NTHREADS/nprocs)));
 ny = nx;
 nz = 5;
 dx = 1.0
@@ -56,7 +62,6 @@ dz = 1.0
 		ranges = [1:size(P,1), 1:size(P,2), 1:1];
 
 		i = 0
-               	@export_vars i nx ny MPI
 		@define_eff_memory_throughput begin
                     (nx * ny * 8) * 3 * MPI.Comm_size(MPI.COMM_WORLD) / :median_time
                 end
@@ -69,7 +74,7 @@ dz = 1.0
                 for i in 1:1
                     GG.write_h2h!(buf, P, ranges, 3);
                 end
-                @perftest samples=100 begin
+                @perftest begin
              	   GG.read_h2h!(buf, P2, ranges, 3);
                 end
                 finalize_global_grid(finalize_MPI=false);