SIMD algorithms are complex to design, implement and tests as a lot of care has to be put into details like correct tail handling, alignment handling or unrolling.
EVE's algorithms and views module is designed to simplify such design while:
@@ -137,24 +137,24 @@
All those features are usable through generic interfaces to allow for reuse of similar loops structure at the cost of some idiosyncrasies.
For a in-depth discussion about those issues, you can take a look at the Algorithms section of our CppCon talk.
-
+
Basic Components
-
+
Reusable loops
Many algorithms require some form of while(f != l) loop. However, with SIMD, even this simple operation is non trivial. EVE algorithm building-blocks provide implementation for the most frequent loop structure. Those loops can then customized and reused without having to care about the actual range type used. For example, eve::mismatch is implemented as a customized call to eve::find.
-
+
Ranges or Iterators
-
+
General concepts
Iterators are more fundamental than ranges. However, ranges can have some extra information like, for example, that instead of begin() it has aligned_begin() and the algorithm can use that. So the interfaces are range based. We don't generally accept iterator in interfaces just because it increases the maintenance. The eve::algo::as_range can be used to turn iterators pair into a EVE compatible range.
One case where it can be very awkward to use ranges instead of iterators is in multi-range algorithms , like transform_to. In this case, unless we have some reason no to, we allow for passing anything that zips to range, i.e. range, iterator or iterator,range. Exceptions are documented and have static_asserts that will tell you it's not supported.
-
+
Relaxed concepts
Many things that we want to accept in the interfaces as range and/or iterator are not ideal for writing code against. We also need to strip things like vector::iterator to pointers. What also we want is to associate a cardinal with iterator.
This is why we have two layers: relaxed_range/relaxed_iterator and iterator. There are a few things that relaxed_* should be able to do but the main one is preprocess_range(traits, f, l) which returns enhanced traits and iterator pair.
-
+
Customization
-
+
Algorithms traits
EVE allows to customize algorithms with traits. Traits are passed via [] and can be combined.
The proba module as been removed. (See #1490) It will be reworked as a separate project later on with a proper API.
-
+
Architectures/Compilers Support & Fixes
-
+
The One Big News for this release: SVE
SVE with fixed size, power of 2 cardinal is now supported for most of our API. Some more optimizations are on the way but the support is functional. (See #1432, #1435, #1436, #1437, #1438, #1448, #1453, #1455, #1456, #1463, #1464, #1472, #1473, #1474,#1487, #1489, #1491, #1494, #1533, #1556)
-
+
Other Fixes
EVE now compiles on ARM M1 with Homebrew g++. (See #1471)
@@ -152,7 +152,7 @@
Integral sign/signnz functions are now more efficient on x86 (See #1499)
Implementation for X86 AVX2/AVX512 gather and masked gather are now optimized. (See #1526)
-
+
Features
jtlap implemented a large amount of new functions for eve::complex.
@@ -161,7 +161,7 @@
The minmax function is now available. (See #1507)
DenisYaroshevskiy implemented new traits for algorithms to take care of costly kernels, no alignment and to support fused operations. (See #1535, #1543)
-
+
Bug Fixes
Convert is now more efficient and don't generate piecewise evaluation in some scenario involving logicals. (See #1447, #1428)
@@ -171,15 +171,15 @@
Fix issue with dynamic SIMD extension detection that were broken by accident. (See #1504)
A lot. The main non-code changes is our move from MIT License to the BOOST SOFTWARE License. Next to that, support for more algorithms and complex numbers has been added.
Starting this fall, we will also try to provide more regular release.
@@ -242,17 +242,17 @@
-
+
New Contributors
Thanks to all our new contributor for this release!
Simran-B made their first contribution in (See #1303)
justend29 made their first contribution in (See #1338)
This release is an API/ABI breaking changes release.
A lot of improvements in QoL, QoI, and API have been made. Some more breaking ABI changes are planned, including a passive move toward an include file layout more amenable to future modularization.
@@ -345,7 +345,7 @@
-
+
New Contributors
Thanks to all our new contributor for this release!
When you call a function on one or more SIMD values, you expect the computation to be performed on every elements of its parameters. Sometimes, you may want to make the application of a given function dependent on some condition.
Let's explore the functionalities EVE provides for achieving those results.
-
+
Explicit Selection
Let's say the function we want to write computes the product of two values a and b if a is equal to b and their difference otherwise.
The scalar code is looking like:
@@ -164,7 +164,7 @@
the value to use whenever an element of said condition evaluates to false, here the difference of a and b
Warning
Contrary to a if ... else statement, eve::if_else will evaluates all its arguments before performing its selection even if potential short-cut can be applied later on.
-
+
Conditional Function Syntax
Let's define a sqrt_positive function that computes the square root of its argument if it's positive or returns it unchanged otherwise. One can write:
If passing a simple logical expression is the most common use-case of the conditional syntax, one may requires more flexibility. To do so, EVE provides various objects to express more elaborated conditions.
-
+
Mask with alternative
One may want to use the conditional syntax to call a function but instead of returning the first argument if the condition is false, one may want to return an arbitrary value. This use case is handled by the eve::if_ helper by wrapping logical expression so that an alternative value can be specified.
Let's modify sqrt_positive so that, if the argument is not positive, 0 is returned instead.
Some algorithms require conditional function calls but use logical expression relative to the element index inside a eve::simd_value rather than its value. One may want for example to not compute an expression on the first and last element of such eve::simd_value.
A frequent example is trying to load data from memory while ignoring trailing garbage or out of bounds values:
@@ -320,7 +320,7 @@
std::cout << load_between(&data[0] - 1) << "\n";
}
The output is obviously the same.
-
+
Conclusion
Conditional operations on SIMD values is a good way to keep a high level code over some complex computations. EVE provides different levels of abstraction for such operations as well as various helpers to specify how the conditions can be computed based either on values or indexes.
From now on, we make the assumption your Docker instance is running and that you're logged into its interactive shell as per the protocol previously defined. In this tutorial, we will go over the process to configure the tests and run them properly.
-
+
CMake setup
First, you'd need to create a build directory and cd into it
mkdir build_arch && cd build_arch
@@ -167,7 +167,7 @@
Once run, your build folder should contain all the necessary artifact to compile and run EVE test suite.
-
+
Compiling EVE Unit Tests
EVE provides a large number of test targets that are grouped by theme. Each of these themes and tests with a theme can be compiled with a proper target.
In term of options, we encourage you to use the -DEVE_NO_FORCEINLINE macro that prevents costly optimization to be used during the compilation of tests.
@@ -223,7 +223,7 @@
Once compiled, the test executable are located in the unit folder and can be run via:
./unit/unit.core.abs.exe
The unit.exe target is very large and requires a comfortable amount of CPUs to be compiled in parallel.
-
+
Compiling EVE Random Tests
Random tests run a given function over a samples of random values to test its relative precision. The following table list the main high-level random target.
EVE provides a lot of function that operates on similar premises. This page gather the general behaviors EVE types and functions can exhibit.
-
+
Property of EVE types
-
+
Cardinal
For any value type, the cardinal is the number of elements it contains. This information is retrieved via the eve::cardinal type trait.
For any SIMD typeT, eve::cardinal<T>::type evaluates to eve::fixed<N>, where N is the number of lanes of the underlying SIMD register.
Two types are said to be cardinal compatible if they have the same cardinal or at least one of them is a scalar type.
-
+
Element type
For any value type, its underlying element type is the type used to represent its internal values. This information is retrieved via the eve::element_type type trait.
SIMD type internals depend on the actual architecture and instruction set available. This information is retrieved via the eve::abi_of type trait.
@@ -150,9 +150,9 @@
When the type uses an emulated SIMD register, the resulting type is eve::emulated_.
When the type elements are tuple-like, the resulting type is eve::bundle_.
-
+
Operations Classification
-
+
Generalized Element Access
EVE functions' semantics rely on a generic way to access an element of a value, be it scalar or SIMD.
To do so, we define a synthetic function get(v,i) that retrieve the ith element of a value v.
@@ -176,7 +176,7 @@
For any SIMD valuex of type T, a Callable Object f returning a scalar value of type R is said to be a Reduction if the expression R r = f(x) is semantically equivalent to:
R r = f(get(x,0), ..., get(x,cardinal_v<T>-1));
Most reduction operations are not defined on scalar values unless their definition is required by the internal implementation.
EVE constant generator are Callable Object that takes a single argument of type eve::as. This argument provides the information about the type used to generate the constant. E.g:
auto z = eve::zero(as<int>()); // equivalent to auto z = static_cast<int>(0);
auto vp = eve::half(as<wide<float>>()); // equivalent to auto vp = wide<float>(0.5);
Some constants are exactly representable in IEEE754 types. However, some mathematical constants can be under-represented on a given type while simultaneously be over-represented on other. For example, \(\pi\) in float is greater than its mathematical value. Meanwhile \(\pi\) in double is less than its mathematical value.
The constant implementation is so that, for any constant generator g:
A Callable Object performing the same kind of operation but gives the correct result in \([-\pi/4, +\pi/4]\) only and Nan outside. (respectively \([-45, +45]\) if the input in in degrees, \([-0.25, +0.25]\) if the input in in \(\pi\) multiples)
A Callable Object performing the same kind of operation but gives the correct result in \([-\pi, +\pi]\) only and Nan outside. (respectively \([-180, +180]\) if the input in in degrees, \([-1.0, +1.0]\) if the input in in \(\pi\) multiples)
-
full_circle is currently supported only by direct trigonometric object functions This decorator leads to the fastest algorithm at full precision.
A Callable Object performing the same kind of operation, but gives the correct result for \([-\pi/2, +\pi/2]\) only and Nan outside. (respectively \([-90, +90]\) if the input in in degrees, \([-0.5, +0.5]\) if the input in in \(\pi\) multiples)
EVE is a new implementation of the previous EVE SIMD library by Falcou et al. which for a while was named Boost.SIMD. It's a C++20 and onward implementation of a type based wrapper around SIMD extensions sets for most current architectures. It aims at showing how C++20 can be used to design and implement efficient, low level, high abstraction library suited for high performances.
It's a research project first and an open source library second. We reserve the right to change API and baseline compiler required until the first official 0.1 release. However, we'll try to minimize disruption. Semantic versioning will ensure API retro-compatibility if anything huge needs to change.
-
+
Video materials
SIMD in C++20: EVE of a new Era - CppCon 2021
@@ -135,7 +135,7 @@
-
+
Bibliographic References
If you want to refers to EVE, you can currently use those papers (by order of preference in citation). A new, more up-to-date EVE specific journal paper is in the work atm.
diff --git a/index.js b/index.js
index 3e3aaf764d..d9f69a58cb 100644
--- a/index.js
+++ b/index.js
@@ -1,5 +1,5 @@
var index =
[
- [ "Video materials", "index.html#autotoc_md68", null ],
- [ "Bibliographic References", "index.html#autotoc_md69", null ]
+ [ "Video materials", "index.html#autotoc_md63", null ],
+ [ "Bibliographic References", "index.html#autotoc_md64", null ]
];
\ No newline at end of file
diff --git a/inter-with-native.html b/inter-with-native.html
index b98504260d..dff4dfeae7 100644
--- a/inter-with-native.html
+++ b/inter-with-native.html
@@ -164,7 +164,7 @@
If the number is less than the one that can be natively represented, it's internally still represented as a full register. For example wide<int, eve::fixed<2>> on x86 is still __m128i. The relevant data just occupy the first 2 elements, the others can be garbage.
If the cardinal is larger than the one that can be natively represented, you can use slice to get to the half the wide size.
Let's say we want to convert 2D cartesian coordinates to 2D polar coordinates. This is a rather common exercise and will only require basic arithmetic and trigonometric functions.
Cartesian coordinates are usually represented by a pair of floating point values \((x,y)\). In a similar way, polar coordinate can be represented as a pair \((\rho,\theta)\) where \(\rho\) represents the length of the ray and \(\theta\) represents the angle with the X axis.
@@ -142,7 +142,7 @@
return std::atan2(y, x);
}
As expected, the code only requires arithmetic operations and some trigonometry. Fellow mathematicians in the audience may have some remarks on this code. For now, we will deal with the fact that it requires \(\theta\) to be in radians and that the accuracy of computing \(\rho\) this way is maybe sub-optimal. We will address those concerns later.
-
+
From scalar to SIMD using eve::wide
The next step is to work a SIMD version of those functions. When dealing with SIMD data types, one has to remember that a single operation has to be performed on multiple values. There, we will be working on multiple xand y to computes multiple \(\rho\) and \(\theta\).
SIMD instructions sets provides architecture-specific types for SIMD register along with ISA specific functions. Of course, handling such types and functions is highly non-portable. To overcome this issue, EVE provides a generic, architecture agnostic type for SIMD computation: eve::wide.
As expected, EVE code scales naturally with the selected architecture at compile time.
-
+
Mathematical Epilogue
As stated earlier, we are currently using a slightly brutal computation for \(\rho\). Indeed, if the magnitudes of x and y vary greatly, we may end up with overflow or cancellation, both classic IEEE 754 floating-point issues.
Computing the square root of the sum of the squares of x and y, without undue overflow or underflow at intermediate stages of the computation is the job of a very specific function: std::hypot. Quite handily, EVE also proposes a SIMD implementation via eve::hypot.
In the previous tutorial, we managed to convert a sequential function into a function using SIMD types and functions. In general, such function is meant to be applied to a large set of data instead of a single register.
As for usual sequential computation, we want to lift ourselves from raw loops and think using algorithms. EVE provides such ready-to-use SIMD aware algorithms and this tutorial will take a look at how to handle them.
-
+
Initial problem
Let's try to apply our sequential conversion function over data stored in std::vector using standard algorithms.
#include <cmath>
@@ -163,7 +163,7 @@
}
}
Very similar code, except for the fact the input data are passed directly without using iterators.
-
+
Toward SIMD Algorithms
We can turn this range-based code into a SIMD-aware call to one of the algorithms defined in eve::algo. All algorithms in EVE are range-based thus simplifying the transition from code using standard algorithms.
#include <vector>
@@ -193,7 +193,7 @@
eve::algo::transform_to takes a single input range. To pass multiple parallel ranges, we use eve::views::zip that constructs a view over them.
as we consume a zipped range, the data passed to the lambda function behaves like a tuple. We will dive into details of this tuple later but for now just remember you can retrieve the data member exactly like with a regular tuple (using get or structured bindings).
-
+
Tuning algorithms
In SIMD algorithms we by default assume that the provided operation is simple (a few instructions), since this is the common case. This means we use aligned reads and do unrolling, which is an important optimisation. However, for a complex case, like here, it is beneficial to opt out.
EVE provides various traits to customize algorithms behavior. The traits we're interested in are:
NOTE: equivalent to no_aligning + no_unrolling + single_pass By default eve algorithms will assume th...
Definition: traits.hpp:267
Best strategy is always to benchmark your code and tune algorithms accordingly.
Note that this kind of tuning is not reserved to algorithms. The callable eve::hypot can also be tuned (here as eve::hypot[eve::pedantic]) to enforce some behaviors regarding accuracy or standard compliance).
In the previous tutorials, we built a SIMD function to compute those cartesian-polar conversions and we used them in the context of a SIMD algorithm to apply them over an arbitrary set of data. While doing so, we introduced the eve::views::zip component that helped us gather multiple ranges into a single one. This worked by feeding eve::algo::transform_to's lambda a tuple of eve::wide.
This interaction between SIMD registers and tuple-like types is very interesting and EVE provides different ways to take advantage of these interactions. In this tutorial, we'll go over how EVE can help you design SIMD-aware tuple to write higher level SIMD code.
-
+
Tuple of SIMD registers
If we go back to the initial scalar conversion functions, we can actually merge both rho and theta functions in a single to_polar function that will return a tuple of float containing both results of the conversion.
This version of the code just works out of the box. eve::wide is just a C++ type and thus interacts normally with other standard components.
-
+
SIMD register of tuples
If the previous code is fine, it has the disadvantage of not being compatible to the general SIMD principle of EVE. Indeed, std::tuple is not a eve::simd_value even when it contains eve::wide.
A better model should allow us to use eve::wide of tuples. To do so, we use kumi::tuple instead of std::tuple. This change is due to the higher flexibility of kumi::tuple and its system of extension. kumi, as a library is integrated within EVE through the eve/product_type.hpp header file and does not need any special setup.
In the previous tutorial, we laid out how EVE can use SIMD-aware tuples to handle more complex cases. In this tutorial, we'll go over how we can design semantically equivalent user-defined types.
-
+
Adapting UDT to SIMD processing
Using tuples as a random bag of values returned from functions is somewhat lackluster. Indeed, one would prefer names over field numbers, thus rising the level of abstraction.
Following this trend, we can rewrite our scalar to_polar function to return a proper structure.
Note how the semantic improved by being able to explicitly states we return a SIMD register made of instance of polar_coords.
-
+
Creating SIMD-aware UDT
All this boilerplate can be overwhelming so instead of adapting existing code, you may want to build a new user-defined type directly usable as a SIMD type. EVE provides an intrusive protocol to do just that via the use of the eve::struct_support helper.
#include <eve/traits/product_type.hpp>
@@ -232,7 +232,7 @@
We then define friend functions to assign names to numbered fields. As the structure thus defined will be usable in both scalar and SIMD contexts, we use the eve::like concept to overload them. eve::like<polar_coords> used as a parameters concept means that the function accepts any type that behaves like a polar_coords, i.e polar_coords and eve::wide<polar_coords>. Such function can also be defined as regular function, but this form is easier and safer.
This is the bare minimum we can do with eve::struct_support. Additional operators can be added along with stream insertion. Check eve::struct_support documentation for more informations.
-
+
Storage and Processing
The last step in this situation is now to process multiples udt::polar_coords using algorithms. The most efficient way to do so is to use eve::soa_vector as a container for SIMD-aware types, either adapted or created using eve::struct_support.
eve::soa_vector provides a std::vector-like interface but perform automatic Structure of Array storage optimisation, ensures the best alignment possible for each sub-members and is directly usable as EVE algorithm input or output.
The EVE library uses compile-time code generation process to ensure a high-level of performance. However, there can be many reasons why your application or library might run on unknown systems. Thus, you may want to be able to write your SIMD kernel once and yet be able to adapt to your end-user's hardware.
A first solution could be to just recompile a given kernel with different architecture settings and link everything. Then, at runtime, use eve::is_supported to choose the correct implementation between the available ones. However, in attempting to solve the problem in this way, you'll face issues as the core of EVE is based on templated callable object, you may end up violating the One Definition Rule and end up with a binary containing the incorrect symbols and implementations.
-
+
From static to dynamic dispatch
A more successful approach is to isolate the various versions of a given kernel into separate dynamic libraries. In this case, no multiple definition can happen. This means to use dynamic libraries to store your code and dynamic loading.
Dynamic loading in itself is a large topic mostly due to its OS specific components so a good read on the subject is maybe in order. Once you are acquainted with dynamic loading, let's start building our own SIMD dynamic system.
-
+
Writing the kernel
Let's write a small function that will consume a pointer to a data block containing float values and the size of the data block to process. Inside this kernel, we'll use some algorithms to vectorise this process.
#include <eve/module/algo.hpp>
@@ -159,7 +159,7 @@
Inside compute_kernel, we display some information about the SIMD API we are using and proceed to the computation. As a quick way to handle the data, we pass a std::span to our algorithm.
Nothing special is required except for the extern "C" attribute. If we want to get around this limitation and have a function taking arbitrary C++ types as parameters, there are different strategies. One such strategy is to use the mangled name to export a function returning an array or structure containing all the pre-computed functions pointers from the .so library.
-
+
Writing the dynamic function hub
We now need to write an actual compute function that our users will call. This is the place where most of the OS-dependent code will be written. The example we give is made to work on Linux. For a more OS-independent way to handle dynamic loading, you can have a look at libltdl or use your preferred OS API.
The code looks like this:
@@ -205,7 +205,7 @@
Once everything is loaded and setup, we call the function pointer with the appropriate parameters.
Obviously, in realistic settings you would actually care about runtime issues, check that every pointer are non-null, and use functions like dlerror to find out what would have caused an issue. This is left as an exercice for the reader.
-
+
Compiling and Using Dynamic Kernels
The next part is much more down-to-earth. We need to compile the kernel function inside multiple dynamic libraries with different set of options. Then, we need to compile the main binary. To simplify this process, EVE provides a CMake function named eve_build_variants that you can access directly when using find_package or that can be included manually in your CMake after installing the library via include(eve-multiarch).
The complete project is available as in the examples/multi-arch folder. As an exercise, try to modify the code to handle AVX512 and check everything still works.
-
+
Conclusion
Handling multiple architecture within a single application is not trivial. It requires some scaffolding, much of those being provided by EVE itself at both the CMake and C++ level.
EVE requires a C++20 compliant compiler. Here is the current minimal compiler version supported:
@@ -168,15 +168,15 @@
-
+
Retrieving the source
-
+
Github
EVE is available on GitHub and can be retrieved via the following command:
git clone https://github.com/jfalcou/eve.git
This retrieves the main branch which contains the latest stable version. Development happens live on main so if you need stability, use a tagged versions.
Don't forget the --std=c++20 option to be sure to activate C++20 support. If you use a different compiler, check your compiler user's manual to use the proper option.
You can notice we use the -O3 -DNEDBUG options. This is required if you want to be sure to get the best performance out of EVE.
The -DNDEBUG setting can be omitted but then asserts will be inserted into the code to prevent logic errors.
-
+
Instruction Set Selection
The SIMD instruction sets that EVE uses is decided at compile time. You can use -march=native if you're sure your code won't be executed anywhere else.
You can also select a specific instructions set by using the proper option(s) from your compiler. For example, let's compile for exactly SSE4.1.
That's it, EVE is properly installed and ready to use.
-
+
Use with CMake
Once installed, EVE may be consumed through its config-file CMake package. Simply find and link against EVE'sCMake target, as you would any other CMake library, and then configure and build your CMake project.
add_executable(use-eve main.cpp)
find_package(eve CONFIG REQUIRED)
target_link_libraries(use-eve PRIVATE eve::eve)
If a custom installation prefix was used, ensure your EVE installation is within CMake's search path with the use of the CMake variables eve_ROOT, eve_DIR, or CMAKE_PREFIX_PATH.
-
+
Advanced options
If you want to dig a bit further, you can pass additional options to cmake to activate additional features.
By default, instances of eve::wide<T> where T is an User-Defined Product Type supports ordering. However, one can specialize eve::supports_ordering for a given type to evaluates to false in order to disable ordering for this type.
Alternatively, any type T providing an internal eve_disable_ordering type will be treated as if eve::supports_ordering<T>::value evaluates to false, thus disabling ordering operators for eve::wide<T>.
- -
- -- - - - - - - - - - diff --git a/group__math__trig_ga582ee61bd6909c6b95af359339d32c2b.html b/group__math__trig_ga582ee61bd6909c6b95af359339d32c2b.html deleted file mode 100644 index 4bc13633c6..0000000000 --- a/group__math__trig_ga582ee61bd6909c6b95af359339d32c2b.html +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - - - --- - --- ------ --Loading...-Searching...-No Matches-- --