Physical unit mismatches in matrix and vector computations have sunk missions and cost millions, because ordinary linear algebra treats a mismatched unit, an out-of-order axis, or a mixed-up reference frame as just another number and lets it compile, run, and fail silently. This library is a C++ strongly-typed facade to a matrix linear algebra backend — Eigen, std::linalg/mdspan, Au, mp-units, nholthaus/units, or Kokkos — that brings type safety to matrix operations. It enforces dimensional consistency and unit compatibility, turning those mismatches into compile errors and preventing common errors in scientific and engineering computations.

state x{3. * m,
        2. * m / s,
        1. * m / s2};
 
std::println("{}", x * transposed(x));
 
// [[9 m²,    6 m²/s,  3 m²/s²],
//  [6 m²/s,  4 m²/s², 2 m²/s³],
//  [3 m²/s², 2 m²/s³, 1 m²/s⁴]]

More usage examples in the sample directory..

Installation & Usage

See INSTALL.md for installation instructions.

Reference

CMake

Link against the CMake target fcarouge-typed-linear-algebra::tlinalg.

Include

Include the library header in your sources:

#include "fcarouge/typed_linear_algebra.hpp"

typed_linear_algebra.hpp

Typed linear algebra implementation.

For forward declarations only, include instead:

#include "fcarouge/typed_linear_algebra_forward.hpp"

typed_linear_algebra_forward.hpp

Authoritative forward declaration header.

Namespace

The public API lives in the fcarouge namespace. Import it with a using-declaration or namespace alias as your project's style prefers.

Plug-ins

Add a plug-in for each strong type or linear algebra backend you use:

Integration	Example Plug-in
Armadillo	See example plug-in at `support/armadillo`.
Au	See example plug-in at `support/au/fcarouge/au.hpp`.
Built-in Types	No plug-in needed.
Eigen	See example plug-in at `support/eigen`.
Kokkos	See example plug-in at `support/kokkos`.
mp-units	See example plug-in at `support/mp_units/fcarouge/mp_units.hpp`.
nholthaus/units	See example plug-in at `support/nholthaus/fcarouge/nholthaus.hpp`.
std::chrono	No plug-in needed.
std::linalg	No plug-in needed.

Class Typed Matrix

Strongly typed matrix. Compose a linear algebra backend matrix into a typed matrix. Row and column indexes provide each element's index type.

Also documented in the fcarouge/typed_linear_algebra.hpp header.

Declaration

template <typename Matrix, typename RowIndexes, typename ColumnIndexes>

class typed_matrix

Template Parameters

Template Parameter	Definition
`Matrix`	The underlying linear algebra matrix.
`RowIndexes`	The tuple type of the row indexes.
`ColumnIndexes`	The tuple type of the row indexes.

Member Types

Member Type	Definition
`matrix`	The type of the composed matrix.
`underlying`	The type of the element's underlying storage.
`row_indexes`	The tuple with the row components of the indexes.
`column_indexes`	The tuple with the column components of the indexes.
`element<i, j>`	The type of the element at the given matrix indexes position.

Member Variables

Member Variable	Definition
`rows`	The count of rows.
`columns`	The count of columns.

Member Functions

Member Function	Definition
`(default constructor)`	Construct a default typed matrix.
`(default copy constructor)`	Copy construct the typed matrix.
`(default copy assignment operator)`	Copy assign a typed matrix.
`(default move constructor)`	Move construct a typed matrix.
`(default move assignment operator)`	Move construct a typed matrix.
`(conversion copy constructor)`	Copy construct generalization of a compatible typed matrix.
`(conversion copy assignment operator)`	Copy assign generalization of a compatible typed matrix.
`(conversion move constructor)`	Move construct generalization of a compatible typed matrix.
`(conversion move assignment operator)`	Move assign generalization of a compatible typed matrix.
`(conversion copy constructor)`	Convert construct a typed matrix from an underlying matrix.
`(conversion copy constructor)`	Convert construct a one-dimension uniformly typed matrix from array.
`(conversion copy constructor)`	Convert construct a uniformly typed matrix from list-initializers.
`(conversion copy constructor)`	Convert construct a row or column typed vector from elements.
`(conversion copy constructor)`	Convert construct a singleton typed matrix from a single value.
`operator[i, j]`	Read the specified element.
`operator(i, j)`	Read the specified element.
`at<i, j>()`	Read, write the specified element.
`at<Type>()`	Read the distinct element whose type is implicitly convertible to `Type`.
`(conversion operator)`	Access the singleton typed matrix element.
`(destructor)`	Destruct a default typed matrix.

Operations

The following useful operations are supported. This library attempts to align its nomenclature aligned with that of the primitives provided by std::linalg. This library attempts some compatibility with other C++ standard library primitives, ranges, and iterators.

Operation	Definition
`-`	Substraction where the terms are of identical shapes and substractable types. Unary negation of a row, column, or regular matrix.
`*`	Multiplication where the factors are of multipliable shapes and multipliable types.
`/`	Solution, if there exists one, to the inverse multiplication, where the factor are of compatible shapes and types.
`+`	Addition where the terms are of identical shapes and addable types.
`==`	Direct, strict equality comparison, with traditional floating-point comparison pitfalls.
`add`	Element-wise add two matrices.
`magnitude`	Euclidean L2 norm of a row or column vector.
`matrix_product`	General matrix-matrix product.
`matrix_vector_product`	Matrix-vector product.
`scale`	Multiply matrix elements by a scalar.
`transposed`	Transpose the input matrix.

Aliases

template <typename Matrix, typename... ColumnIndexes>
typed_row_vector;
 
template <typename Matrix, typename... RowIndexes>
typed_column_vector;

Format

A specialization of the standard formatter is provided for the typed matrix. Use std::format to store a formatted representation of the matrix. Standard format parameters to be supported.

Literals

A user-defined literal _i operator in the fcarouge::literals namespace that converts a decimal integer literal into a compile-time index type permitting the use of traditional accessor operator with strong types.

using literals::operator""_i;

std::println("{}", m[1_i, 2_i]); // Same as: m.at<1, 2>()

Concepts

Concept	Definition
`column_typed_matrix`	Concept of a column typed matrix, vector.
`distinct_typed_matrix`	Concept of a typed matrix in which no two element positions share an implicit conversion target, so an element can be located by type.
`index`	Concept of a compile-time index.
`other`	Concept of any type other than the typed matrix type.
`other_tuple_like_vector`	Concept of a tuple-like vector convertible to a one-dimension typed matrix.
`rank_typed_matrix<0>`	Concept of a singleton, one-element typed matrix type.
`rank_typed_matrix<1>`	Concept of a typed matrix with only one dimension, row, or column.
`rank_typed_matrix<2>`	Concept of a regular two-dimension typed matrix.
`row_typed_matrix`	Concept of a row typed matrix, vector.
`same_as_typed_matrix`	Concept of a typed matrix type.
`same_shape`	Concept of typed matrices of the same shape, that is they have the same number of rows and columns.
`uniform_typed_matrix`	Concept of a typed matrix in which all element types are the same.

Structure Element Caster

Typed matrix element conversions customization point. Specialize this template to allow conversion to and from the element's type and underlying type.

template <typename To, typename From>

struct element_caster;

The library uses a static instance of element_caster to make a call to the function call operator allowing the instance to be called as if it were a conversion function. This idiom permits the conversion to be externally defined and found through template specialization lookup.

// Specialize the conversion class for your types:
template <typename To, typename From>
struct element_caster<To, From> {
  [[nodiscard]] static constexpr auto operator()(From value) -> To {
    // Implement the conversion for this specialization:
    return result;
  }
};

A variety of conversions may be needed, notably value and reference conversions. Performance considerations may influence the value conversion implementation and whether the converted value is provided by a value parameter or by a constant reference parameter.

More

Use Cases

The library serves computations where a matrix or vector is not a bag of interchangeable numbers but a collection of quantities that carry meaning: a state estimate, a set of sensor readings, a set of correlated measures. Ordinary linear algebra erases that meaning at the type level, so a mismatched unit, an out-of-order axis, or a mixed-up reference frame compiles cleanly and fails silently, if at all, at runtime. By attaching an index type to each row and column, the library keeps that meaning through every operation, so dimensionally or semantically invalid computations fail to compile instead of producing a wrong number downstream.

Domains and use cases include:

Estimation and filtering: state, measurement, and covariance vectors and matrices where each element is a distinct physical quantity and covariance terms compound units automatically.
Guidance, navigation, and control: vehicle or robot state combining position, velocity, and orientation across multiple coordinate frames that must not be interchanged.
Aerospace and spacecraft systems: interface data exchanged between subsystems where a unit or frame mismatch has historically caused mission-critical failures.
Robotics: transform and kinematic chains where axes, joints, and reference frames must remain distinguishable through composition.
Structural and mechanical engineering: stiffness, compliance, and gain matrices mixing forces, moments, and rates that must not be scaled or combined incorrectly.
Process and chemical engineering: reaction and rate matrices where dimensional homogeneity across concentration, rate, and energy terms is a correctness requirement.
Quantitative finance and econometrics: covariance and factor matrices over labeled instruments or risk factors where a misaligned row or column silently corrupts a risk figure.
Computer graphics and simulation: transforms and state buffers spanning multiple spaces or units that are easy to conflate without a type-level distinction.
Machine learning and scientific computing: tensors and feature matrices where axis meaning and shape compatibility are as important as the numeric values themselves.

As seen at CppNow 2026

This library was presented at CppNow 2026 as a first, free, and open-source implementation that integrates dimensional analysis in linear algebra computations through the type system while preserving the performance of established numerical backends. The talk motivated the safety proposition. And worked through the typed matrix definition and examples. We evaluated ergonomics and compatibility with std::linalg, std::mdspan, Eigen, mp-units. We noted lessons learned, tradeoffs, frictions. We looked to other additional safeties, open problems, and opportunities for better linear algebra in C++ applications. The discussions identified improvements for the library. The slides and the video.

Roadmap & Vision

The library's core typed_matrix API, the element-casting customization point, and the backend plug-in shape are stable in practice but not yet frozen; version 1.0 will mark a settled public API and ABI-relevant surface, complete operator coverage matching std::linalg's algorithm set, and every backend exercised by the same test matrix, with the longer-term ambition of tracking std::linalg as it grows in the standard library implementations so that dimensional and semantic type safety becomes a thin, zero-overhead layer over the standard's own primitives, rather than a competing linear algebra library, and the std::mdspan-based backend needs less bridging as std::linalg gains adoption, not more.

Toward version 1.0:

Match std::linalg's operator and algorithm coverage.
Track std::linalg/std::mdspan maturity; shrink plug-ins.
Broaden the test matrix: one safety guarantee, one test.
Stabilize the public API and element-casting customization points.
Evaluate compatibility with more strong types and backends.
Evaluate integration with established use cases.

Lessons Learned

Type safety cannot be guaranteed at compilation time without index safety. The indexes can either be non-type template parameters or strong types overloadings. Converting a runtime index to a dependent template type is not possible in C++. A proxy reference could be used to allow traditional assignment syntax but the runtime check and extra indirection are not interesting tradeoffs. A template call operator can be used for getting a type safe value but impractical syntax for setting. Without index safety, the accepted tradeoff is a templated index at<i, j>() method.

Lvalue reference assignment cannot be provided due to a contradiction. For example, in user code: m[0_i, 0_i] = 2 * m;. On one hand, if the storage is a tuple of strong types, then the access for linear operations suffers a performance penalty because std::tuple is not a contiguous array. Tuples are stored in implementation-dependent order, alignement, size, and padding. On the other hand, if the storage is a contiguous of built-in types, then materializing a lvalue reference of strong type from the build-in type is undefined behavior. Reinterpret-casting is never constexpr and undefined behavior when aliasing, punning types, even when appropriatly sized and aligned memory. Fortunately, there is a conjecture that lvalue reference assignment is never useful given linear algebra works over vector and matrix entities, and not their elements. A practical set of constructors should suffice. While lvalue reference assignment could be conditionally provided given compatible storage, the end-user experience would be confusing when assignment could not be provided. Assigning an element is supported via the at member function.

Extraneous indexes tradeoffs convenience for safety. For example, m[0, 0, 0, 0, ...] to access the first row/column element of a matrix, rank 2. While the allowance was practical for generic meta-programming in early development, community feedback informed of the user defects permitted by the mis-matching number of indeces, weak guarantees. For safety, the number of indexes must match the rank at compile-time.

Strongly typed memory storage is not a selected design due to its performance tradeoff. A std::tuple or other type-list storages can be used as underlying memory storage. Such storage permits strongly typed lvalue reference assignment which improves the end-user ergonomics. Unfortunately std::tuple does not offer the same guarantees provided by contiguous memory storage and its alignment, padding, and ordering specification. The lack of guarantees prevents the direct, efficient, optimized memory accesses, resulting in a performance penalty. Undefined behavior is avoided. No known solution.

Interoperability and compatibility with other libraries works well with customization point objects (CPO) and presence/absence of overloads and specializations. The argument-dependent lookup (ADL) supports extensions of either integrated parties with limited collisions. The compatibility dimishes when static assertions are abused to replace, constrain application programming interfaces in place of concepts. Static assertions should be kept for internal validation, not for interface type availability.

A vector of C++ typed values is not a mathematically typed vector even though both may support linear algebra agorithms. The difference may appear subtle. Especially when the types in the vector are homogeneous. And particularly in some engineering domains where both tools cohabit, interconvert to solve their respective uses cases. Software is a reductive abstraction of the physical reality to make computation possible. This library supports aggregates of types and the subset of algorithms that are meaningful over these types. Usage friction may reveal inadequate tooling selection.

The matrix cell unit convention admits two valid choices when combining a row type and a column type into the type of cell (i, j): the product, row[i] * column[j], or the quotient, row[i] / column[j]. Mathematically, this encodes whether the matrix is interpreted as a bilinear form or as a linear map. A bilinear form combines two vectors into a scalar, sum(i, j, v[i] * w[j] * G(i, j)); both indices play the same, covector role, so the product convention is natural. A linear map transforms a vector into a vector, y[i] = sum(j, A[i][j] * x[j]); the column index cancels against the input unit, so the quotient convention is natural instead. In tensor index notation, the quotient corresponds to mixed variance, M^i_j, and the product to same variance, G_ij. In C++, RowIndexes and ColumnIndexes are tuples of types, and element<i, j> is computed through a product<> or a symmetric quotient<> type metafunction. Neither convention is more correct, only suited to a different use. The library keeps the product convention, favoring bilinear forms and quadratic, energy-like expressions over vectors. Consumers relying on linear map semantics, such as state-transition matrices, must declare column types as the reciprocal of the corresponding input type, not the input type itself.

Projects

The library is used in projects:

Kalman: A Kalman filter library.

Your project link here!

Resources

G. W. Hart, Multidimensional Analysis: Algebras and Systems for Science and Engineering. New York, NY, USA: Springer-Verlag, 1995.
B. D. Hall, "Software support for physical quantities," in Proc. 9th Electronics New Zealand Conf. (ENZCON), Dunedin, New Zealand, 2002.
M. Pusz, "Implementing Physical Units Library for C++" presented at C++Now, Aspen, CO, USA, May 2019. [Online]. Available: https://www.youtube.com/watch?v=wKchCktZPHU
C. Hogg, "Units Libraries and Autonomous Vehicles: Lessons from the Trenches," presented at CppCon, Aurora, CO, USA, Oct. 2021. [Online]. Available: https://www.youtube.com/watch?v=5dhFtSu3wCo
D. Withopf, "Taking Static Type-Safety to the Next Level: Physical Units for Matrices," presented at C++Now, Aspen, CO, USA, May 2022. [Online]. Available: https://www.youtube.com/watch?v=SLSTS-EvOx4
M. Hoemmen, "std::linalg: Linear Algebra Coming to Standard C++" (WG21 P1673), presented at CppCon, Aurora, CO, USA, Oct. 2023. [Online]. Available: https://www.youtube.com/watch?v=-UXHMlAMXNk
D. Hanson, "Guide to Linear Algebra With the Eigen C++ Library," presented at CppCon, Aurora, CO, USA, Sep. 2024. [Online]. Available: https://www.youtube.com/watch?v=99G-APJkMc0

Third Party Acknowledgement

The library is designed, developed, and tested with the help of third-party tools and services acknowledged and thanked here:

actions-gh-pages to upload the documentation to GitHub pages.
Armadillo for linear algebra.
Au the physical units library for C++, by Aurora Innovation.
Clang for compilation and code sanitizers.
clang-format for code formatting.
clang-tidy for static analysis.
CMake for build automation.
cmakelang for pretty CMake list files.
cppcheck for static analysis.
Doxygen for documentation generation.
Doxygen Awesome for pretty documentation.
Eigen for linear algebra.
GCC for compilation and code sanitizers.
gsl-lite for guidelines support library.
Kokkos for performance-portable parallel programming.
lcov to process coverage information.
mdspan for multidimensional array views.
mp-units the quantities and units library for C++.
MSVC for compilation and code sanitizers.
nholthaus/units the compile-time dimensional analysis and unit conversion library for C++.
stdBLAS for standard BLAS interface.
Valgrind to check for correct memory management.

License

TypedLinearAlgebra is public domain:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

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

For more information, please refer to https://unlicense.org