General concepts » Core concepts

Follow the path from a geometric domain to a discrete solution.

A Rodin solve connects a mesh, a finite element space, fields, a variational problem, and a solver. This guide explains their roles and the information passed between them. The Poisson tutorial supplies a complete executable.

Describe the domain

Mesh geometry and topology

A mesh discretizes a domain into cells. Coordinates describe where the vertices lie; connectivity describes how vertices, edges, faces, and cells meet. These are related but distinct pieces of data.

The following code constructs a triangular mesh of the unit square.

Mesh mesh = Mesh().UniformGrid(Polytope::Type::Triangle, {16, 16});
mesh.scale(1.0 / 15.0);

The grid parameters count vertices. There are 15 intervals per direction, hence 256 vertices and 450 triangles. The scaling maps unit grid spacing onto the unit square.

Cells and ambient dimension

A polytope describes an entity such as a segment, triangle, or tetrahedron. Cells have the mesh's topological dimension; boundary faces have one lower dimension. Ambient dimension records the number of coordinate components. A surface triangulation in three-dimensional space therefore has getDimension() == 2 and getSpaceDimension() == 3.

See Polytopes for reference elements and geometric mappings, and Meshes for mesh creation and queries.

Establish incidence relations

Algorithms need particular incidence relations. For boundary conditions on a two-dimensional mesh, edge-to-cell connectivity identifies exterior edges.

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

The arguments are entity dimensions. In a three-dimensional volume mesh, the corresponding face-to-cell relation is (2, 3). Each required incidence relation is computed explicitly. The connectivity guide explains the supported queries.

Traverse mesh entities

Mesh iterators expose cells, faces, and vertices. Traversal and geometric evaluation serve different purposes. An entity index identifies topology, while a Geometry::Point combines an entity with a reference coordinate for field evaluation. See Mesh iteration.

Choose an approximation

Finite element spaces

A finite element space determines the local approximation and how degrees of freedom are shared between cells. For scalar fields on a triangular mesh:

SpaceApproximationContinuity
P0Constant on each cellDiscontinuous
P1Affine on each cellContinuous across cell boundaries
H1Configurable higher orderConforming continuity
P1 vh(mesh);

Scalar P1 has one degree of freedom per vertex. Higher-order and vector spaces use their own DOF maps and numbering. The finite element definition and space guide develop this distinction. Quadratic elements are constructed with H1 of order two.

Distinguish fields from symbolic unknowns

A GridFunction stores coefficients in a finite element space. For the scalar nodal P1 space, these coefficients are vertex values. For other spaces, the DOF functionals determine the meaning of each coefficient; field values are obtained by evaluation.

Interpolate a known field

Assignment applies the space's degree-of-freedom functionals to an expression.

GridFunction field(vh);
field = [](const Geometry::Point& p) { return p.x() * p.y(); };

This assignment interpolates the prescribed function. An $L^2$ projection is obtained from a variational mass-matrix problem. See Numerical contracts.

Coefficients and evaluation

getData() exposes coefficients. Evaluation at a Geometry::Point uses the element basis and its mapping. The distinction matters for higher-order elements, vector components, and non-nodal spaces. Component expressions such as field.x() are available for compatible vector-valued fields.

Trial and test functions

Trial and test functions construct the discrete equations symbolically.

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

The trial function represents the unknown. Its associated grid function, u.getSolution(), stores the coefficients computed by the solve. The test function supplies the test basis used to form the equations.

For a linear weak problem, the discrete task is to find $u_h\in V_h$ such that

\[ a(u_h,v_h)=\ell(v_h)\qquad\text{for every }v_h\in V_h. \]

With basis functions $\phi_j$ and expansion $u_h=\sum_j x_j\phi_j$ , the system is $A\mathbf{x}=\mathbf{b}$ , where $A_{ij}=a(\phi_j,\phi_i)$ and $b_i=\ell(\phi_i)$ . Prescribed boundary values restrict the admissible trial and test fields.

Supply coefficients and data

Function expressions describe known source terms, material coefficients, and boundary values. They are evaluated at geometric points during integration or interpolation.

RealFunction source = 1;
RealFunction boundary([](const Geometry::Point& p) { return p.x(); });
VectorFunction force{0, -1};

Zero() supplies scalar zero data; Zero(dimension) supplies vector zero data. Coordinate expressions in F, pointwise mathematical operators, and complex expressions such as Re, Im, and Conjugate are described in Variational formulations in Rodin and the Variational reference.

Express the weak problem

Operators and integrals

Expressions retain the mathematical structure until evaluation is required. Grad(u) is the gradient of a scalar field; pairing it with Grad(v) inside an integral gives the Poisson stiffness form.

Problem poisson(u, v);
poisson = Integral(Grad(u), Grad(v)) - Integral(source, v)
           + DirichletBC(u, Zero());

Integral integrates over cells. BoundaryIntegral integrates over exterior faces; natural boundary loads enter through such boundary terms. Essential boundary conditions constrain the unknown. Selecting an attribute with .on(attribute) or .over(attribute) requires that the mesh already carries the intended labels. See Boundary conditions.

From forms to a system

The expression represents the residual $a(u_h,v_h)-\ell(v_h)$ together with constraints. Assembly evaluates local contributions using quadrature, combines them into the matrix and vector, and applies the constraints. The minus sign on the source therefore yields a positive right-hand side in $A\mathbf{x}=\mathbf{b}$ .

Choose a compatible solver

The Poisson problem with these boundary conditions gives a symmetric positive definite system, so conjugate gradient is appropriate.

Solver::CG solver(poisson);
solver.solve();

Check solver.success() before treating u.getSolution() as a completed result. CG requires a symmetric or Hermitian positive definite system; solver selection follows the assembled matrix properties. See Solvers.

Interpret and export the solution

The computed grid function can be evaluated, used in another form, or exported with its mesh.

IO::XDMF xdmf("Poisson");
xdmf.grid().setMesh(mesh).add("u", u.getSolution());
xdmf.write().flush();

The explicit name "u" labels the exported field. Alternatively, set a grid-function name before calling the unnamed add(field) overload. Meshes, spaces, and fields must remain valid while the writer observes them. See Input, output, and visualization for file formats and visualization.

Continue to specialized formulations

Once the local conforming workflow is understood, these guides introduce additional numerical requirements:

Numerical contracts

Read Numerical contracts before relying on coefficient layouts, projection semantics, assembly reuse, or nonlinear tangent consistency. These contracts connect the mathematical formulation to the behavior of the numerical implementation.