Merge pull request #28 from JuliaMath/rename

VML replaced with IntelVectorMath

Author: aminya

.travis.yml

@@ -24,6 +24,6 @@ before_script:
 
 script:
   # 
-  - export JL_PKG=VML
-  - julia --color=yes -e "if VERSION < v\"0.7.0-DEV.5183\"; Pkg.clone(pwd()); Pkg.build(\"VML\"); else using Pkg; if VERSION >= v\"1.1.0-rc1\"; Pkg.build(\"VML\"; verbose=true); else Pkg.build(\"VML\"); end; end"
-  - julia --check-bounds=yes --color=yes -e "if VERSION < v\"0.7.0-DEV.5183\"; Pkg.test(\"VML\", coverage=true); else using Pkg; Pkg.test(coverage=true); end"
+  - export JL_PKG=IntelVectorMath
+  - julia --color=yes -e "if VERSION < v\"0.7.0-DEV.5183\"; Pkg.clone(pwd()); Pkg.build(\"IntelVectorMath\"); else using Pkg; if VERSION >= v\"1.1.0-rc1\"; Pkg.build(\"IntelVectorMath\"; verbose=true); else Pkg.build(\"IntelVectorMath\"); end; end"
+  - julia --check-bounds=yes --color=yes -e "if VERSION < v\"0.7.0-DEV.5183\"; Pkg.test(\"IntelVectorMath\", coverage=true); else using Pkg; Pkg.test(coverage=true); end"

LICENSE.md

@@ -1,4 +1,4 @@
-The VML.jl package is licensed under the MIT "Expat" License:
+The IntelVectorMath.jl package is licensed under the MIT "Expat" License:
 
 > Copyright (c) 2014: Simon Kornblith.
 >

Project.toml

@@ -1,4 +1,4 @@
-name = "VML"
+name = "IntelVectorMath"
 uuid = "c8ce9da6-5d36-5c03-b118-5a70151be7bc"
 version = "0.2.0"
 

README.md

@@ -1,42 +1,47 @@
-# VML 
-[![Build Status](https://travis-ci.com/Crown421/VML.jl.svg?branch=master)](https://travis-ci.com/Crown421/VML.jl)
-[![Build status](https://ci.appveyor.com/api/projects/status/btdduqfsxux8fhsr?svg=true)](https://ci.appveyor.com/project/Crown421/vml-jl)
+# IntelVectorMath.jl (formerly VML.jl)
+[![Build Status](https://travis-ci.com/JuliaMath/IntelVectorMath.jl.svg?branch=master)](https://travis-ci.com/JuliaMath/IntelVectorMath.jl)
+[![Build status](https://ci.appveyor.com/api/projects/status/btdduqfsxux8fhsr?svg=true)](https://ci.appveyor.com/project/Crown421/IntelVectorMath-jl)
 
-This package provides bindings to the Intel Vector Math Library for
-arithmetic and transcendental functions. Especially for large vectors it is often substantially faster than broadcasting Julia's built-in functions.
+This package provides bindings to the Intel MKL [Vector Mathematics Functions](https://software.intel.com/en-us/node/521751).
+This is often substantially faster than broadcasting Julia's built-in functions, especially when applying a transcendental function over a large array. 
+Until Julia 0.6 the package was registered as `VML.jl`.
 
 ## Basic install
 
-To use VML.jl, you must have the shared libraries of the Intel Vector Math Library avilable on your system.
-The easiest option is to use [MKL.jl](https://github.com/JuliaComputing/MKL.jl) via 
+To use IntelVectorMath.jl, you must have the shared libraries of the Intel Vector Math Library available on your system.
+The easiest option is to use [MKL.jl](https://github.com/JuliaComputing/MKL.jl) via
 ```julia
 julia> ] add https://github.com/JuliaComputing/MKL.jl.git
 ```
 Alternatively you can install MKL directly [from intel](https://software.intel.com/en-us/mkl/choose-download).
 
 Note that intel MKL has a separate license, which you may want to check for commercial projects (see [FAQ]( https://software.intel.com/en-us/mkl/license-faq)).
 
-To install VML.jl run 
+To install IntelVectorMath.jl run
 ```julia
-julia> ] add https://github.com/JuliaMath/VML.jl
+julia> ] add https://github.com/JuliaMath/IntelVectorMath.jl
 ```
 
-## Using VML
-After loading `VML`, you have the supported function listed below available to call, i.e. `VML.sin(rand(100))`. This should provide a significant speed-up over broadcasting the Base functions.
+## Using IntelVectorMath
+After loading `IntelVectorMath`, you have the supported function listed below, for example `IntelVectorMath.sin(rand(100))`. These should provide a significant speed-up over broadcasting the Base functions.
+Since the package name is quite long, an alias `IVM` is also exported to allow `IVM.sin(rand(100))` after `using` the package. 
+If you `import` the package, you can add this alias via `const IVM = IntelVectorMath`. Equally, you can replace `IVM` with another alias of your choice. 
+
+#### Example
 ```julia
-julia> using VML, BenchmarkTools
+julia> using IntelVectorMath, BenchmarkTools
 
 julia> a = randn(10^4);
 
 julia> @btime sin.($a);     # apply Base.sin to each element
   102.128 μs (2 allocations: 78.20 KiB)
 
-julia> @btime VML.sin($a);  # apply VML.sin to the whole array
+julia> @btime IVM.sin($a);  # apply IVM.sin to the whole array
   20.900 μs (2 allocations: 78.20 KiB)
 
 julia> b = similar(a);
 
-julia> @btime VML.sin!(b, a);  # in-place version 
+julia> @btime IVM.sin!(b, a);  # in-place version
   20.008 μs (0 allocations: 0 bytes)
 ```
 
@@ -50,7 +55,7 @@ julia> @btime sin($a);
 julia> ans ≈ sin.(a)
 true
 ```
-Calling `sin` on an array now calls the a VML function, while its action on scalars is unchanged. 
+Calling `sin` on an array now calls the a IntelVectorMath function, while its action on scalars is unchanged.
 
 #### Note:
 
@@ -61,47 +66,47 @@ julia> exp(ones(2,2))
  4.19453  3.19453
  3.19453  4.19453
 
-julia> VML.exp(ones(2,2))
+ julia> IVM.exp(ones(2,2))
 2×2 Array{Float64,2}:
  2.71828  2.71828
  2.71828  2.71828
 
 julia> ans == exp.(ones(2,2))
 true
 ```
-If your code, or any code you call, uses matrix exponentiation, then `@overload exp` may silently lead to incorrect results. This caution applies to all trigonometric functions, too, since they have matrix forms defined by matrix exponential.
+If your code, or any code you call, uses matrix exponentiation, then `@overload exp` may silently lead to incorrect results. This caution applies to all trigonometric functions, too, since they have matrix forms defined by matrix exponentials.
 
 ### Accuracy
 
-By default, VML uses `VML_HA` mode, which corresponds to an accuracy of
+By default, IntelVectorMath uses `VML_HA` mode, which corresponds to an accuracy of
 <1 ulp, matching the accuracy of Julia's built-in openlibm
 implementation, although the exact results may be different. To specify
 low accuracy, use `vml_set_accuracy(VML_LA)`. To specify enhanced
 performance, use `vml_set_accuracy(VML_EP)`. More documentation
 regarding these options is available on
-[Intel's website](http://software.intel.com/sites/products/documentation/hpc/mkl/vml/vmldata.htm).
+[Intel's website](http://software.intel.com/sites/products/documentation/hpc/mkl/IntelVectorMath/vmldata.htm).
 
 ## Performance
 (These results are currently outdated and will be updated in due course)
-![VML Performance Comparison](/benchmark/performance.png)
+![IntelVectorMath Performance Comparison](/benchmark/performance.png)
 
-![VML Complex Performance Comparison](/benchmark/performance_complex.png)
+![IntelVectorMath Complex Performance Comparison](/benchmark/performance_complex.png)
 
 Tests were performed on an Intel(R) Core(TM) i7-3930K CPU. Error bars
 are 95% confidence intervals based on 25 repetitions of each test with
 a 1,000,000 element vector. The dashed line indicates equivalent
-performance for VML versus the implementations in Base. Both Base and
-VML use only a single core when performing these benchmarks.
+performance for IntelVectorMath versus the implementations in Base. Both Base and
+IntelVectorMath use only a single core when performing these benchmarks.
 
 ## Supported functions
 
-VML.jl supports the following functions, most for Float32 and
+IntelVectorMath.jl supports the following functions, most for Float32 and
 Float64, while some also take complex numbers.
 
 ### Unary functions
 
 Allocating forms have signature `f(A)`. Mutating forms have signatures
-`f!(A)` (in place) and `f!(out, A)` (out of place). The last 9 functions have been moved from Base to `SpecialFunctions.jl` or have no Base equivalent. 
+`f!(A)` (in place) and `f!(out, A)` (out of place). The last 9 functions have been moved from Base to `SpecialFunctions.jl` or have no Base equivalent.
 
 Allocating | Mutating
 -----------|---------
@@ -143,7 +148,7 @@ Allocating | Mutating
 ### Binary functions
 
 Allocating forms have signature `f(A, B)`. Mutating forms have
-signature `f!(out, A, B)`. 
+signature `f!(out, A, B)`.
 
 Allocating | Mutating
 -----------|---------
@@ -154,21 +159,21 @@ Allocating | Mutating
 
 
 ## Next steps
-Next steps for this package 
+Next steps for this package
 * [x] Windows support
 * [x] Basic Testing
 * [x] Avoiding overloading base and optional overload function
-* [ ] Updating Benchmarks
 * [x] Travis and AppVeyor testing
 * [x] Adding CIS function
+* [ ] Updating Benchmarks
 * [ ] Add tests for mutating functions
+* [ ] Add test for using standalone MKL
 
 
+## Advanced
+IntelVectorMath.jl works via Libdl which loads the relevant shared libraries. Libdl automatically finds the relevant libraries if the location of the binaries has been added to the system search paths.
+This already taken care of if you use MKL.jl, but the stand-alone may require you to source `mklvars.sh`. The default command on Mac and Ubuntu is `source /opt/intel/mkl/bin/mklvars.sh intel64`. You may want to add this to your `.bashrc`.
+Adding a new `*.conf` file in `/etc/ld.so.conf.d` also works, as the `intel-mkl-slim` package in the AUR does automatically.
 
-## Advanced 
-VML.jl works via Libdl which loads the relevant shared libraries. Libdl automatically finds the relevant libraries if the location of the binaries has been added to the system search paths. 
-This already taken care of if you use MKL.jl, but the stand-alone may require you to source `mklvars.sh`. The default command on Mac and Ubuntu is `source /opt/intel/mkl/bin/mklvars.sh intel64`. You may want to add this to your `.bashrc`. 
-Adding a new `*.conf` file in `/etc/ld.so.conf.d` also works, as the `intel-mkl-slim` package in the AUR does automatically. 
-
-Further, VML.jl uses [CpuId.jl](https://github.com/m-j-w/CpuId.jl) to detect if your processor supports the newer `avx2` instructions, and if not defaults to `libmkl_vml_avx`. If your system does not have AVX this package will currently not work for you.
-If the CPU feature detection does not work for you, please open an issue. 
+Further, IntelVectorMath.jl uses [CpuId.jl](https://github.com/m-j-w/CpuId.jl) to detect if your processor supports the newer `avx2` instructions, and if not defaults to `libmkl_vml_avx`. If your system does not have AVX this package will currently not work for you.
+If the CPU feature detection does not work for you, please open an issue.

benchmark/benchmark.jl

@@ -1,4 +1,4 @@
-using VML
+using IntelVectorMath
 using Distributions, Statistics, BenchmarkTools # for benchmark
 using Plots # for plotting
 using JLD2, FileIO # to save file
@@ -32,7 +32,7 @@ fns = [[x[1:2] for x in base_unary_real];
 """
     bench(fns, input)
 
-benchmark function for VML.jl. Calls both Base and VML functions and stores the benchmarks in two nested Dict. First layer specifies type, and second layer specifies the function name. The result is a Tuple, 1st element being benchmark for Base/SpecialFunctions and 2nd element being for VML.
+benchmark function for IntelVectorMath.jl. Calls both Base and IntelVectorMath functions and stores the benchmarks in two nested Dict. First layer specifies type, and second layer specifies the function name. The result is a Tuple, 1st element being benchmark for Base/SpecialFunctions and 2nd element being for IntelVectorMath.
 
 # Examples
 ```julia
@@ -41,14 +41,14 @@ input = Dict( Float64 => [(rand(1000)); (rand(1000), rand(1000)); (rand(1000))])
 times = bench(fns, input)
 
 times[Float64][:acos][1] # Base.acos benchmark for Float64
-times[Float64][:acos][2] # VML.acos benchmark for Float64
+times[Float64][:acos][2] # IntelVectorMath.acos benchmark for Float64
 ```
 """
 function bench(fns, input)
     Dict(t => begin
         Dict( fn[2] => begin
             base_fn = eval(:($(fn[1]).$(fn[2])))
-            vml_fn = eval(:(VML.$(fn[2])))
+            vml_fn = eval(:(IntelVectorMath.$(fn[2])))
             println("benchmarking $vml_fn for type $t")
             timesBase = @benchmark $base_fn.($inp...)
             timesVML = @benchmark $vml_fn($inp...)
@@ -137,8 +137,8 @@ function plotBench()
     # end
     xlims!(0, length(fns) + 1)
     xticks!(1:length(fns)+1, fname, rotation = 70, fontsize = 10)
-    title!("VML Performance for array of size $NVALS")
-    ylabel!("Relative Speed (VML/Base)")
+    title!("IntelVectorMath Performance for array of size $NVALS")
+    ylabel!("Relative Speed (IntelVectorMath/Base)")
     hline!([1], line=(4, :dash, 0.6, [:green]), labels = 1)
     savefig("performance$(complex ? "_complex" : "").png")
 

src/VML.jl renamed to src/IntelVectorMath.jl

@@ -1,6 +1,9 @@
 __precompile__()
 
-module VML
+module IntelVectorMath
+
+export IVM
+const IVM = IntelVectorMath
 
 # import Base: .^, ./
 using SpecialFunctions
@@ -88,7 +91,7 @@ for t in (Float32, Float64)
     def_unary_op(Complex{t}, t, :abs, :abs!, :Abs)
     def_unary_op(Complex{t}, t, :angle, :angle!, :Arg)
 
-    ### cis is special, vml function is based on output
+    ### cis is special, IntelVectorMath function is based on output
     def_unary_op(t, Complex{t}, :cis, :cis!, :CIS; vmltype = Complex{t})
 
     # Binary, complex-only. These are more accurate but performance is
@@ -104,37 +107,37 @@ end
 """
     @overload exp log sin
 
-This macro adds a method to each function in `Base` (or perhaps in `SpecialFunctions`), 
-so that when acting on an array (or two arrays) it calls the `VML` function of the same name.
+This macro adds a method to each function in `Base` (or perhaps in `SpecialFunctions`),
+so that when acting on an array (or two arrays) it calls the `IntelVectorMath` function of the same name.
 
 The existing action on scalars is unaffected. However, `exp(M::Matrix)` will now mean
-element-wise `VML.exp(M) == exp.(M)`, rather than matrix exponentiation.
+element-wise `IntelVectorMath.exp(M) == exp.(M)`, rather than matrix exponentiation.
 """
 macro overload(funs...)
     out = quote end
     say = []
     for f in funs
         if f in _UNARY
             if isdefined(Base, f)
-                push!(out.args, :( Base.$f(A::Array) = VML.$f(A) ))
+                push!(out.args, :( Base.$f(A::Array) = IntelVectorMath.$f(A) ))
                 push!(say, "Base.$f(A)")
             elseif isdefined(SpecialFunctions, f)
-                push!(out.args, :( VML.SpecialFunctions.$f(A::Array) = VML.$f(A) ))
+                push!(out.args, :( IntelVectorMath.SpecialFunctions.$f(A::Array) = IntelVectorMath.$f(A) ))
                 push!(say, "SpecialFunctions.$f(A)")
             else
-                @error "function VML.$f is not defined in Base or SpecialFunctions, so there is nothing to overload"
+                @error "function IntelVectorMath.$f is not defined in Base or SpecialFunctions, so there is nothing to overload"
             end
         end
         if f in _BINARY
             if isdefined(Base, f)
-                push!(out.args, :( Base.$f(A::Array, B::Array) = VML.$f(A, B) ))
+                push!(out.args, :( Base.$f(A::Array, B::Array) = IntelVectorMath.$f(A, B) ))
                 push!(say, "Base.$f(A, B)")
             else
-                @error "function VML.$f is not defined in Base, so there is nothing to overload"
+                @error "function IntelVectorMath.$f is not defined in Base, so there is nothing to overload"
             end
         end
         if !(f in _UNARY) && !(f in _BINARY)
-            error("there is no function $f defined by VML.jl")
+            error("there is no function $f defined by IntelVectorMath.jl")
         end
     end
     str = string("Overloaded these functions: \n  ", join(say, " \n  "))

src/setup.jl

@@ -46,9 +46,9 @@ function vml_check_error()
             # Singularity, overflow, or underflow
             # I don't think Base throws on these
         elseif vml_error == 1000
-            warn("VML does not support $(vml_get_accuracy); lower accuracy used instead")
+            warn("IntelVectorMath does not support $(vml_get_accuracy); lower accuracy used instead")
         else
-            error("an unexpected error occurred in VML ($vml_error)")
+            error("an unexpected error occurred in IntelVectorMath ($vml_error)")
         end
     end
 end

test/complex.jl

@@ -18,11 +18,11 @@ fns = [x[1:2] for x in base_unary_complex]
   for t in (ComplexF32, ComplexF64), i = 1:length(fns)
 
     base_fn = eval(:($(fns[i][1]).$(fns[i][2]))) 
-    vml_fn = eval(:(VML.$(fns[i][2])))
+    vml_fn = eval(:(IntelVectorMath.$(fns[i][2])))
 
-    Test.@test which(vml_fn, typeof(input[t][i])).module == VML
+    Test.@test which(vml_fn, typeof(input[t][i])).module == IntelVectorMath
 
-    # Test.test_approx_eq(output[t][i], fn(input[t][i]...), "Base $t $fn", "VML $t $fn")
+    # Test.test_approx_eq(output[t][i], fn(input[t][i]...), "Base $t $fn", "IntelVectorMath $t $fn")
     Test.@test vml_fn(input[t][i]...) ≈ base_fn.(input[t][i]...)
 
   end

test/real.jl

@@ -19,12 +19,12 @@ fns = [[x[1:2] for x in base_unary_real]; [x[1:2] for x in base_binary_real]]
   for t in (Float32, Float64), i = 1:length(fns)
 
     base_fn = eval(:($(fns[i][1]).$(fns[i][2]))) 
-    vml_fn = eval(:(VML.$(fns[i][2])))
-    # vml_fn! = eval(:(VML.$(fns[i][2])!))
+    vml_fn = eval(:(IntelVectorMath.$(fns[i][2])))
+    # vml_fn! = eval(:(IntelVectorMath.$(fns[i][2])!))
 
-    Test.@test which(vml_fn, typeof(input[t][i])).module == VML
+    Test.@test which(vml_fn, typeof(input[t][i])).module == IntelVectorMath
 
-    # Test.test_approx_eq(output[t][i], fn(input[t][i]...), "Base $t $fn", "VML $t $fn")
+    # Test.test_approx_eq(output[t][i], fn(input[t][i]...), "Base $t $fn", "IntelVectorMath $t $fn")
     Test.@test vml_fn(input[t][i]...) ≈ base_fn.(input[t][i]...)
 
   end
@@ -34,8 +34,8 @@ end
 @testset "Error Handling and Settings" begin
 
   # Verify that we still throw DomainErrors
-  Test.@test_throws DomainError VML.sqrt([-1.0])
-  Test.@test_throws DomainError VML.log([-1.0])
+  Test.@test_throws DomainError IntelVectorMath.sqrt([-1.0])
+  Test.@test_throws DomainError IntelVectorMath.log([-1.0])
 
   # Setting accuracy
   vml_set_accuracy(VML_LA)
@@ -48,7 +48,7 @@ end
 
 @testset "@overload macro" begin
 
-    @test VML.exp([1.0]) ≈ exp.([1.0])
+    @test IntelVectorMath.exp([1.0]) ≈ exp.([1.0])
     @test_throws MethodError Base.exp([1.0])
     @test (@overload log exp) isa String
     @test Base.exp([1.0]) ≈ exp.([1.0])

test/runtests.jl

@@ -1,5 +1,5 @@
 using Test
-using VML
+using IntelVectorMath
 
 include("common.jl")
 include("real.jl")