103 lines
5.1 KiB
Markdown
103 lines
5.1 KiB
Markdown
# ROTGEN - Runtime Overlay for EIGEN
|
|
|
|
**ROTGEN** is a C++20 library that wraps EIGEN and adds some *Quality of Life* options :
|
|
+ Limitation of compile-time by forcing the library to use precompiled code and dynamic settings.
|
|
+ Limitation of compile-time by de-activating the Expression Template layer.
|
|
+ Limitation of unrolling by forcing containers to fall back to dynamic storage above a given static size.
|
|
+ Free function versions of some member function from Eigen to promote a more generic programming approach.
|
|
|
|
**ROTGEN** depends on [Eigen v3.4.0](https://eigen.tuxfamily.org/index.php?title=Main_Page).
|
|
Documentation for Eigen v3.4.0 is available here: https://libeigen.gitlab.io/eigen/docs-3.4/.
|
|
|
|
## Installation
|
|
After cloning this repository, you can setup **ROTGEN** via CMake using the following options:
|
|
|
|
+ `-DROTGEN_FORCE_DYNAMIC=ON` that will precompile the wrapped Eigen functions and types into a shared library - `librotgen`.
|
|
+ `-DROTGEN_MAX_SIZE=n` that will limit the total static size of any container to `n`. So, for example, if the library is setup with `-DROTGEN_MAX_SIZE=9`, `rotgen::matrix<float,3,4>` will use a dynamic size Eigen container under the hood while `rotgen::matrix<flaot,2,3>` will still be using static sizes. In this mode, all Eigen expression templates systems are disabled, elmading to all operations ot generate intermediate data.
|
|
+ `-DROTGEN_ENABLE_EXPRESSION_TEMPLATES=ON` will re-enable Eigen expression templates systems when paired with `ROTGEN_MAX_SIZE`. If used without `ROTGEN_MAX_SIZE`, `ROTGEN_MAX_SIZE` willbe set to 0, thus forcing all containers to be allocated dynamically.
|
|
|
|
At configuration time, **ROTGEN** wil display a summary of options used and how they'll affect compialtion flags. For example, the command `cmake . -DROTGEN_MAX_SIZE=16 -DROTGEN_ENABLE_EXPRESSION_TEMPLATES` will output:
|
|
|
|
```bash
|
|
-- ==================== Rotgen Configuration Summary ====================
|
|
-- Configuration mode: STATIC
|
|
-- Expression Templates: ON
|
|
-- Preprocessor flags: -DROTGEN_MAX_SIZE=16 -DROTGEN_ENABLE_EXPRESSION_TEMPLATES
|
|
-- ======================================================================
|
|
-- Configuring done (0.0s)
|
|
-- Generating done (0.0s)
|
|
```
|
|
|
|
While the command `cmake -DROTGEN_FORCE_DYNAMIC=ON` will output:
|
|
|
|
```bash
|
|
-- ==================== Rotgen Configuration Summary ====================
|
|
-- Configuration mode: DYNAMIC
|
|
-- Reason : No static size options were provided
|
|
-- Preprocessor flags: -DROTGEN_FORCE_DYNAMIC
|
|
-- ======================================================================
|
|
-- Configuring done (0.0s)
|
|
-- Generating done (0.1s)
|
|
```
|
|
|
|
Once setup, you can run:
|
|
+ `make rotgen` to compile the rotgen library. This is required in all above scenarios.
|
|
+ `make install` to install the library binary and headers. Use [CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) to select where you want it to be installed.
|
|
+ `make rotgen-test` to run our unit test suite.
|
|
|
|
## Suppported Features
|
|
|
|
### Types
|
|
The following containers are provided
|
|
+ `rotgen::matrix`, which wraps `Eigen::Matrix`.
|
|
+ `rotgen::block`, which wraps `Eigen::Block`.
|
|
+ `rotgen::map`, which wraps `Eigen::Map`.
|
|
+ `rotgen::quaternion`, which wraps `Eigen::Quaternion`.
|
|
+ `rotgen::ref`, which wraps `Eigen::Ref`.
|
|
|
|
In dynamic mode, `rotgen::matrix`,`rotgen::block` and `rotgen::map` use a PIMPL based implementation to garantee ABI stability.
|
|
Proper move semantic support is provided to minimize overhead in most non-Expression Templates situations.
|
|
|
|
Supported scalar types are `float` and `double`.
|
|
|
|
### Operations
|
|
+ Arithmetic operations on containers/scalars.
|
|
+ Block extractions.
|
|
+ Data generation interface (i.e `matrix::Zero`, etc...)
|
|
+ Reductions (sum, prod, norms)
|
|
+ Resizing and conservative resizing
|
|
|
|
## Project status
|
|
### Current Releases
|
|
+ 08/2025 - Version 0.0.1beta
|
|
|
|
### Roadmap
|
|
+ Support `int`.
|
|
+ Support `array` and related operations.
|
|
+ Support non-trivial indexing.
|
|
+ Precompile and provide free functions API for common linear algebra solvers.
|
|
|
|
## License
|
|
|
|
**ROTGEN** is licensed under the Boost Software License
|
|
|
|
```
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in all
|
|
copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
SOFTWARE.
|
|
```
|
|
|