TypedLinearAlgebra: A Strongly Typed Facade for C++ Matrix Backends

The Problem: Silent Shape and Unit Errors in Matrix Code

Matrix libraries like Eigen and Kokkos give you fast, flexible containers, but they leave dimensional consistency to the programmer. Multiply a 3x2 matrix by a 4x1 vector and you get a runtime assertion, or worse, undefined behavior if assertions are off. Units are another silent hazard: adding meters to seconds compiles fine, and your simulation drifts without a crash. TypedLinearAlgebra addresses both problems by moving shape and unit validation to compile time. The library is for engineers and scientists who write numerical code in C++ and want the compiler to catch these mistakes before the program runs. It does not replace a matrix backend; it wraps one.

How It Works: A Facade with Compile-Time Index Types

The core type is `typed_matrix<Matrix, RowIndexes, ColumnIndexes>`. The `Matrix` template parameter is the underlying backend, such as `Eigen::MatrixXd`. The `RowIndexes` and `ColumnIndexes` are tuples of types that describe the physical meaning of each row and column. For example, a state vector with position, velocity, and acceleration might have row indexes like `length`, `length_per_time`, and `length_per_time_squared`. The library composes these index types into the element type. The documentation shows a state vector `x` with elements in meters, meters per second, and meters per second squared. When you compute `x * transposed(x)`, the result has units like `m^2/s` and `m^2/s^2` baked into the type. The compiler enforces that you only add or multiply compatible quantities. The facade also supports operations like `add`, `scale`, `matrix_product`, and `transposed`, with names deliberately aligned to `std::linalg`.

Getting Started: Installation and Basic Use

Installation is standard CMake. From a shell, you clone the repository, configure, build, and install: `git clone --depth 1 "https://github.com/FrancoisCarouge/TypedLinearAlgebra"`, `cmake -S "TypedLinearAlgebra" -B "build"`, `cmake --build "build" --parallel`, then `sudo cmake --install "build"`. For CMake projects, the README shows a `FetchContent` declaration with `FIND_PACKAGE_ARGS NAMES fcarouge-typed-linear-algebra`, and you link with `target_link_libraries(your_target PRIVATE fcarouge-typed-linear-algebra::tlinalg)`. Include the header `#include "fcarouge/typed_linear_algebra.hpp"`. For strong types like Au or mp-units, you need a plug-in; the README points to example plug-ins under `support/`. Built-in types and `std::linalg` need no plug-in. The library provides a user-defined literal `_i` in the `fcarouge::literals` namespace for compile-time index construction, though the README truncates the details.

What the Type System Actually Enforces

The type system enforces two things: shape and unit compatibility. Shape is encoded in the row and column index tuples. A matrix with row indexes `(length, time)` and column indexes `(mass)` has a fixed shape. Multiplying it by a matrix with different index types will fail to compile. Units are handled through the plug-in system. With Au or mp-units, the element type carries the unit, so operations like addition check unit compatibility at compile time. The README's example shows a state vector with mixed units and the resulting outer product has units like `m^2/s^3`. This is a real improvement over raw Eigen, where such an operation would compile and produce nonsense. However, the library does not enforce unit consistency for built-in types; without a units plug-in, you get shape checking only.

Limitations and Failure Modes

The most obvious limitation is that TypedLinearAlgebra is a facade, not a solver. It does not provide LU decomposition, eigenvalues, or least squares. You still need the underlying backend for actual computation. A second limitation is the dependency on plug-ins. If you use Au or mp-units, you must maintain the plug-in code, and the README shows these as examples, not as part of the core library. The documentation is thin: the README gives a reference table but no detailed explanation of how the index tuples map to actual matrix dimensions. The `operator[i, j]` and `operator(i, j)` are listed as read-only, which suggests you cannot modify elements through these operators, only through `at<i, j>()`. That may be intentional for type safety, but it is a constraint to know. Finally, the project is young: version 0.2.0 was released in July 2026, so expect API changes.

Alternatives: Boost.Units and Direct std::linalg

The most direct alternative is to use a units library like Boost.Units or mp-units directly with your matrix backend, without a typed facade. Boost.Units provides compile-time unit checking for scalar values, but you still have to manage matrix dimensions manually. For example, you would write `Eigen::Matrix<boost::units::quantity<si::length, double>, 3, 1>` and hope you multiply the right shapes. That approach gives you unit safety but not shape safety. Another alternative is to use `std::linalg` directly, which provides standard matrix operations but no unit or dimension checking. TypedLinearAlgebra sits between these: it wraps either backend and adds both shape and unit checking. The trade-off is complexity: you must learn the plug-in system and the index tuple syntax, which is not trivial.

Maintenance and Upgrade Cost

The library is header-only, so installation is low overhead. The last push was July 2026, and there are two releases, 0.1.0 and 0.2.0. The 0.2.0 release came four months after 0.1.0, which suggests active development. The license is listed as NOASSERTION, which is a red flag: there is no standard open source license, so you cannot assume you have the right to use it commercially. You should contact the author or check the repository for a license file before using it in production. The README mentions compatibility with `std::linalg` and standard library primitives, but the API is still evolving. Upgrading from 0.1.0 to 0.2.0 may require changes to your code, especially if you rely on the `_i` literal or the format specialization. There is no documentation on migration.

Editorial conclusion

Adopt TypedLinearAlgebra if you work in scientific or engineering C++ and want compile-time dimensional and unit checking on top of Eigen, Kokkos, or std::linalg. Do not adopt it if you need a full linear algebra library or if your team is not comfortable with template metaprogramming. Before adopting, verify that the plug-in for your chosen backend is maintained and that the library's nomenclature, which deliberately mirrors std::linalg, matches your codebase. The 0.2.0 release is recent, but the project is young, so check the issue tracker and sample directory for real-world usage patterns.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes