A c++ sparse block matrix library aimed at Second Order cone problems
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
So-Bogus Documentation


So-bogus is a set of loosely connected components, organized as follow:

  • Core ( a.k.a. bogus ), a MPL-licensed header-only library, which include
    • Block, A block-sparse matrix library
    • BlockSolvers, Solvers ( Projected Gauss-Seidel, Projected Gradient, Krylov linear solvers ) using those matrices
  • Extra, a GPL-licensed header-only library, which include
    • Second Order Tools for solving Second Order Cone complementarity problems with BlockSolvers. Includes enumerative and optimization-based one-contact solvers for Coulomb friction.
  • Interfaces Convenient, compilable wrappers for the most popular uses of the header-only libraries, such as solving Coulomb friction problems. GPL licensed.

Core ( a.k.a. bogus )

Header Naming Conventions

For each module of the Core library, several header files are available, following this naming pattern:

  • Module.fwd.hpp Forward declarations of the module's public classes
  • Module.hpp Public classes and operators definitions
  • Module.impl.hpp Full implementation

For the Block module, the file includes additional definitions for IO and serialization-related functions.


The behavior of the header-only libraries may be customized using the following compile-time macros:


If defined, bogus will not use multiple threads, even it is compiled with OpenMP enabled. Not defined by default.


Default integer index type, which will be used to refer to row or column indices. Should be signed for compatibility with OpenMP 2.0. Should be set to MKL_INT if you plan to use the mkl bindings. Can be overwritten using template parameters for e.g. MappedSparseBlockMatrix. Defaults to int


Integer type that will be used to refer to a given block within its sequential container. Defaults to std::size_t


Do not include Eigen bindings, or anything Eigen for this matter. Will break block_solvers and Second Order. Not defined by default.


Do not include Eigen/Sparse bindings. Not defined by default.


Enable MKL bindings. Only supports matrix/vector multiplication for compressed SparseBlockMatrixBase with fixed-size blocks. See mkl. Not defined by default.


Enable serialization API. Not defined by default.


If defined, bogus will use shared_ptr from this namespace instead of its own limited NaiveSharedPtr. Values such as tr1 for C++03 or std for C++11 should work. Not defined by default.


The Extra header-only library collects all modules that were not suited for inclusion in Core ( a.k.a. bogus ), for reasons as trivial as licensing issues.

At the time, the only module in Extra is Second Order.

Extra follows the same header naming convention as Core ( a.k.a. bogus ); see Header Naming Conventions.


The Interfaces part of So-bogus is not considered stable yet, but provide examples of how to use the Core ( a.k.a. bogus ) and Extra libraries. For instance, PrimalFrictionProblem is a relatively generic representation of a 2D or 3D friction problem for which the mass matrix is a diagonal of dense blocks. It can be converted to a DualFrictionProblem, which in turn can be solved using a GaussSeidel or ProjectedGradient block solver, or the Cadoux algorithm ACML11 .

On the other hand, MecheFrictionProblem defines a more specific interface, but provides more features, such as serialization or diagonal regularization. Its public interface rely on as few custom classes as possible.

So-bogus header-only parts are meant to be modular and composable; the Interfaces library is not, and address a very specific use case. Consequently, you should probably not use the compiled library in your program, but create your own wrapper over the Core ( a.k.a. bogus ) and Extra modules. For instance, for maximal coordinates models, PrimalFrictionProblem will not be optimal, as its mass matrix uses dense diagonal blocks. You will probably want to use a variation that use Eigen::SparseMatrix blocks for M and H.

Similarly, while bogus provides all the components required for solving Mixed Complementarity Problems, no such solver is exposed through the Interfaces .