rotgen/README.md

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. 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:

-- ==================== 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:

-- ==================== 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 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.