So-Bogus Documentation

Introduction

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 )

• Core ( a.k.a. bogus ) is a set of heavily templated, header-only libraries.
• Block is self-contained and independent from the other modules.
• BlockSolvers is written to operate on matrices from Block.

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 Block.io.hpp includes additional definitions for IO and serialization-related functions.

Configuration

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

BOGUS_DONT_PARALLELIZE

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

BOGUS_DEFAULT_INDEX_TYPE

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

BOGUS_DEFAULT_BLOCK_PTR

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

BOGUS_WITHOUT_EIGEN

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

BOGUS_BLOCK_WITHOUT_EIGEN_SPARSE

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

BOGUS_WITH_MKL

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

BOGUS_WITH_BOOST_SERIALIZATION

Enable serialization API. Not defined by default.

BOGUS_SHARED_PTR_NS

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.

Extra

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.

Interfaces

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.

Note

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 .