Rodin

Rodin is a lightweight and modular finite element framework which provides many of the associated functionalities that are needed when implementing shape and topology optimization algorithms. These functionalities range from refining and remeshing the underlying shape, to providing elegant mechanisms to specify and solve variational problems.

It is named after the French sculptor Auguste Rodin, considered the founder of modern sculpture.

Any contributors are warmly encouraged and any help or comments are always appreciated!

Getting Started

New to Rodin? Check out our comprehensive Getting Started Guide which covers:

• Installation and Setup - Platform-specific installation instructions and verification
• First Steps - Basic concepts, project structure, and your first Rodin program
• Your First Problem - Complete walkthrough solving the Poisson equation
• Core Concepts - Deep dive into meshes, finite elements, and variational formulations

Status

Branch	Matrix	Tests	Code Coverage	Benchmarks	Documentation
master
develop

Table of Contents

1. Getting Started
2. Installation
3. Building the project
4. Features
5. Documentation
6. Third-Party integrations
7. Requirements
8. CMake options
9. Development

Installation

Rodin can be easily installed from source on Linux and macOS systems.

Prerequisites

Required:

• CMake 3.16.0+
• C++20 compatible compiler (GCC 12+, Clang 14+, or AppleClang)
• Boost 1.74+
• Eigen3

Optional:

• OpenMP (for parallel execution)
• SuiteSparse (for additional linear solvers)
• MPI (for distributed computing)

Quick Install

# Clone repository with submodules
git clone --recursive https://github.com/cbritopacheco/rodin.git
cd rodin

# Configure and build
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release
make -j4

# Install (may require sudo for system-wide installation)
sudo make install

User-Local Installation

For installation without sudo (recommended for development):

# Configure with local prefix
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.local -DCMAKE_BUILD_TYPE=Release
make -j4
make install

# Add to your shell profile (~/.bashrc or ~/.zshrc)
export CMAKE_PREFIX_PATH=$HOME/.local:$CMAKE_PREFIX_PATH

Verifying Installation

After installation, you can verify it works by creating a simple test project:

CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)
project(MyRodinProject CXX)
set(CMAKE_CXX_STANDARD 20)

find_package(Rodin REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE Rodin::Geometry Rodin::Variational Rodin::Solver)

main.cpp:

#include <Rodin/Solver.h>
#include <Rodin/Geometry.h>
#include <Rodin/Variational.h>

using namespace Rodin;
using namespace Rodin::Geometry;
using namespace Rodin::Variational;

int main() {
  Mesh mesh = Mesh().UniformGrid(Polytope::Type::Triangle, {8, 8});
  P1 Vh(mesh);
  std::cout << "Rodin installation verified!" << std::endl;
  return 0;
}

Then build and run:

mkdir build && cd build
cmake ..
make
./my_app

Platform-Specific Notes

Ubuntu/Debian:

sudo apt-get install cmake libboost-all-dev libeigen3-dev libomp-dev

macOS (Homebrew):

brew install cmake boost eigen libomp

Troubleshooting

• CMake can't find Rodin: Ensure CMAKE_PREFIX_PATH includes your installation directory
• Linker errors: Make sure all required dependencies (Boost, Eigen) are installed
• Compiler errors: Verify you're using a C++20 compatible compiler

For detailed installation instructions, advanced configuration options, and troubleshooting, see INSTALL.md.

Building the project

git clone --recursive https://github.com/carlos-brito-pacheco/rodin
cd rodin
mkdir build && cd build
cmake ..
make -j4

Features

Embedded form language for FEM modelling

Rodin comes with a native C++20 form language for assembling and solving variational formulations.

For example, given a domain $\Omega$ with boundary $\Gamma := \partial \Omega$, the Poisson problem:

$$\left\{ \begin{aligned} -\Delta u &= f && \text{in } \Omega\\\ u &= 0 && \text{on } \Gamma \ , \end{aligned} \right.$$

has the associated weak formulation:

$$\text{Find} \ u \in H^1(\Omega) \quad \text{s.t.} \quad \forall v \in H^1_0(\Omega), \quad \int_\Omega \nabla u \cdot \nabla v \ dx = \int_\Omega f v \ dx, \quad \text{with } \quad H^1_0(\Omega) := \{ v \in H^1(\Omega) \mid v = 0 \text{ on } \Gamma \}$$

which can be quickly implemented via the following lines of code:

#include <Rodin/Types.h>
#include <Rodin/Solver.h>
#include <Rodin/Geometry.h>
#include <Rodin/Assembly.h>
#include <Rodin/Variational.h>

using namespace Rodin;
using namespace Rodin::Solver;
using namespace Rodin::Geometry;
using namespace Rodin::Variational;

int main(int, char**)
{
  Mesh mesh;
  mesh = mesh.UniformGrid(Polytope::Type::Triangle, { 16, 16 });
  mesh.getConnectivity().compute(1, 2); // Compute boundary

  P1 vh(mesh);

  TrialFunction u(vh);
  TestFunction  v(vh);

  RealFunction f = 1;

  // Apply Dirichlet conditions on the entire boundary.
  Problem poisson(u, v);
  poisson = Integral(Grad(u), Grad(v))
          - Integral(f, v)
          + DirichletBC(u, Zero());
  CG(poisson).solve();

  // Save solution
  u.getSolution().save("Poisson.gf");
  mesh.save("Poisson.mesh");

  return 0;
}

Solution of the Poisson equation in 2D.

Full high level mesh access and functionalities

Cell, Face, Vertex Iterators

The API offers full support for iteration over all polytopes of the mesh of some given dimension:

Mesh mesh;
mesh = mesh.UniformGrid(Polytope::Type::Triangle, 16, 16); // 2D Mesh

for (auto it = mesh.getCell(); it; ++it)
{
 // Access information about the cell
}

for (auto it = mesh.getFace(); it; ++it)
{
 // Access information about the face
}

for (auto it = mesh.getVertex(); it; ++it)
{
 // Access information about the vertex
}

for (auto it = mesh.getPolytope(1); it; ++it)
{
 // Access information about the face (face dimension in 2D is equal to 1)
}

Full connectivity computation

Rodin is able to compute any connectivity information on the mesh. For example, the following computes the adjacency information from faces to cells:

Mesh mesh;
mesh = mesh.UniformGrid(Polytope::Type::Triangle, 16, 16); // 2D Mesh

mesh.getConnectivity().compute(1, 2);

In general, this means that given a face, we are able to obtain the incident (neighboring) cells.

However, one can also compute any connectivity information on different dimensions. For example, for a mesh $\mathcal{T}_h \subset \mathbb{R}^d$, $d = 2$ of topological dimension $d$, we have:

// Compute connectivity between vertices and faces
// i.e. Given a vertex, give me the incident edges
mesh.getConnectivity().compute(0, 1);

// Compute connectivity between faces and cells
// i.e. Given a vertex, give me the incident cells
mesh.getConnectivity().compute(0, 2); 

// Compute connectivity between faces
// i.e. Given a face, give me the adjacent faces
mesh.getConnectivity().compute(1, 1);

// Compute connectivity between cells
// i.e. Given a cell, give me the adjacent cells
mesh.getConnectivity().compute(2, 2);

// Compute connectivity between cells and faces
// i.e. Given a cell, give me the adjacent faces
mesh.getConnectivity().compute(2, 1);

// Etc.

Additional Features

Rodin provides many powerful features for finite element analysis:

Solver Integration:

• Direct integration with Eigen for linear algebra operations
• Support for various linear solvers (CG, BiCGSTAB, SparseLU, etc.)
• Iterative and direct solver methods

Finite Element Spaces:

• P1 (piecewise linear) elements
• P0 (piecewise constant) elements
• H1

File Format Support:

• MFEM mesh and grid function formats
• MEDIT mesh format (.mesh)
• GMSH mesh format (.msh)
• Support for reading and writing solutions

Quadrature Formulas:

• Multiple quadrature rules for integration
• Grundmann-Moeller quadrature
• Gauss-Legendre quadrature
• See the complete list of quadrature formulas

Advanced Mesh Operations:

• SubMesh extraction for domain decomposition
• Mesh partitioning for parallel computing
• Boundary and interface mesh generation
• See the Mesh Utilities Guide for more details

For comprehensive documentation on all features, see the Documentation section below.

Documentation

Rodin provides comprehensive documentation covering all aspects of the library:

User Guides

Getting Started:

• Installation and setup instructions
• Your first Rodin program
• Solving your first PDE (Poisson equation)
• Understanding core concepts

Mesh Guide:

• Creating meshes - UniformGrid, file loading, Builder API
• Connectivity - Computing and using connectivity relations
• Iteration - Iterating over mesh entities
• Queries - Geometric measurements
• I/O - File formats and operations
• Utilities - Advanced operations

Examples

The documentation includes numerous examples demonstrating Rodin's capabilities:

• PDE Examples: Poisson equation, elasticity system, and more
• MMG Integration: Mesh optimization, adaptation, and remeshing
• Shape Optimization: Topology and shape optimization workflows
• Geometry Operations: Mesh manipulation and transformations

API Reference

Complete API documentation is available for all classes, functions, and modules:

• Full API Documentation
• Geometry Module
• Variational Module
• Solver Module

Building Documentation Locally

To build the documentation yourself:

# Clone repository with submodules
git clone --recursive https://github.com/cbritopacheco/rodin.git
cd rodin

# Configure with documentation enabled
mkdir build && cd build
cmake .. -DRODIN_BUILD_DOC=ON -DRODIN_USE_MCSS=ON

# Build documentation
make RodinDoxygen

The generated documentation will be in the doc/ directory. For more details, see doc/README.md.

Third-Party integrations

MMG

MMG is an open source software for bidimensional and tridimensional surface and volume remeshing.

• Loading the mesh:

  MMG::Mesh Omega;
  Omega.load(meshFile, IO::FileFormat::MEDIT);

• Optimizing the mesh:

  MMG::Optimizer().setHMax(hmax) // maximal edge size
                  .setHMin(hmin) // minimal edge size
                  .setGradation(hgrad) // ratio between two edges
                  .setHausdorff(hausd) // curvature refinement
                  .optimize(Omega);

Requirements

• CMake 3.16.0+
• Boost 1.74+

Any of these should be available for quick install from your standard package manager.

CMake options

Option	Description
RODIN_BUILD_EXAMPLES	Builds the examples in the examples/ directory.
RODIN_BUILD_DOC	Builds the documentation using Doxygen
RODIN_USE_MCSS	Builds the documentation using Doxygen and m.css
RODIN_BUILD_SRC	Build the Rodin source code
RODIN_BUILD_EXAMPLES	Build the Rodin examples
RODIN_BUILD_DOC	Build the Rodin documentation
RODIN_USE_MCSS	Use m.css style documentation
RODIN_WITH_PLOT	Build the Rodin::Plot module
RODIN_USE_MPI	Build with MPI support
RODIN_USE_OPENMP	Build with OpenMP support
RODIN_USE_SUITESPARSE	Build with SuiteSparse support
RODIN_SILENCE_WARNINGS	Silence warnings outputted by Rodin
RODIN_BUILD_PY	Build Python bindings

Development

Rodin includes a GitHub Copilot custom agent called Rodin that assists with building and testing code changes.

Using the Rodin Agent

The Rodin agent can help you:

• Compile the Rodin codebase
• Run unit tests, manufactured tests, and benchmarks
• Troubleshoot build and test failures
• Understand the build system

To use the Rodin agent in GitHub Copilot Chat:

@Rodin build and test my changes
@Rodin compile the code and run unit tests
@Rodin help me fix this build error

For more information, see .github/agents/README.md.