https://github.com/trick-17/fmath
Math library for operations on fields
https://github.com/trick-17/fmath
c-plus-plus c-plus-plus-17 etl expression-template header-only math-library openmp-backend parallelisation
Last synced: 11 months ago
JSON representation
Math library for operations on fields
- Host: GitHub
- URL: https://github.com/trick-17/fmath
- Owner: Trick-17
- License: mit
- Created: 2017-12-31T17:14:43.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2022-04-01T20:33:52.000Z (almost 4 years ago)
- Last Synced: 2025-01-13T03:44:48.136Z (about 1 year ago)
- Topics: c-plus-plus, c-plus-plus-17, etl, expression-template, header-only, math-library, openmp-backend, parallelisation
- Language: C++
- Size: 1.31 MB
- Stars: 3
- Watchers: 4
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
FMath: Field Math library
=========================
**Efficient and expressive use of abstract Fields**
[](https://travis-ci.com/github/Trick-17/FMath)
[](https://codecov.io/gh/trick-17/fmath/branch/master)
[](https://fmath.readthedocs.io)
**Requirements:**
- C++17
- OpenMP 4.5 (optional)
- (later maybe a CUDA version which supports C++17 features)
General Ideas
-------------
The library revolves around the `Field` template class, which is a convenience
wrapper around `std::vector` with added operators and functions. The Eigen library
is used for vector operations.
Expression templates ensure that mathematical operations are used efficiently,
avoiding temporaries.
The library provides convenience `typedef`s:
- `FMath::scalar` = default is `double`, can be defined differently by `FMATH_SCALAR_TYPE`
- `FMath::ScalarField` = `FMath::Field`
- `FMath::Vector3` = `Eigen::Vector3`
- `FMath::VectorX` = `Eigen::VectorX`
- `FMath::VectorField` = `FMath::Field`
Parallelisation
---------------
Since almost all operations on `Field`s, defined in this library, are either trivially parallelizable
or typical reductions, both CPU and GPU could and should be used to speed up operations.
OpenMP 4.5 can easily be used to parallelize everything on CPU and also supports usage of devices.
However, due to the lack of unified memory abstractions, GPU parallelisation does not yet come as
naturally.
Incorporation into your project
-------------------------------
Adding this library to your project should be trivial.
You can do it manually:
- copy the `FMath` folder into your directory of choice
- copy the `thirdparty/Eigen` folder or provide your own
- make sure the `FMath` and `Eigen` folders are in your include-directories
- optionally define `FMATH_SCALAR_TYPE`
- optionally add OpenMP compiler flags to activate parallelisation
or using CMake:
- copy the entire repository folder into your directory of choice
- TODO...
Usage Examples
--------------
### Reductions
```C++
#include
// Single field reduction
FMath::VectorField vf(N);
FMath::scalar mean = vf.mean();
// N-dimensional dot-product
FMath::ScalarField sf1(N), sf2(N);
sf1 *= sf2;
FMath::scalar dot = sf1.sum();
```
### Operators
```C++
#include
FMath::VectorField vf1(N), vf2(N);
FMath::ScalarField sf1(N);
// This will produce an expression object, due to auto
auto vf = vf1 + vf2*vf2;
// This will actually evaluate the expression
FMath::ScalarField sf_result = vf.dot(vf1);
```
### Convenience math functions
```C++
#include
FMath::VectorField vf1(N), vf2(N);
// Element-wise dot product
FMath::ScalarField sf_dot = vf1.dot(vf2);
// Element-wise cross product
FMath::VectorField vf_cross = vf1.cross(vf2);
```
### Other convenience functions
Copying or re-interpreting a `Field` as an `Eigen::VectorX`
```C++
#include
FMath::ScalarField sf(N);
FMath::VectorField vf(N);
// Copy a scalar field to a new N-dimensional vector
FMath::VectorX vec1 = sf.asRef();
// Copy a vector field to a new 3N-dimensional vector
FMath::VectorX vec2 = vf.asRef();
// Interpret a scalar field as a N-dimensional vector without copying
Eigen::Ref vecRef1 = sf.asRef();
// Interpret a vector field as a 3N-dimensional vector without copying
Eigen::Ref vecRef2 = vf.asRef();
```
Extracting and operating on an indexed subset of a `Field`
```C++
#include
// A Field of size N1 and an index list of size N2