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:
| Space | Approximation | Continuity |
|---|---|---|
P0 | Constant on each cell | Discontinuous |
P1 | Affine on each cell | Continuous across cell boundaries |
H1 | Configurable higher order | Conforming 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 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 such that
With basis functions and expansion , the system is , where and . 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 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 .
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:
- Interfaces, traces, and discontinuous Galerkin — Traces, jumps, averages, and facet integrals.
- Variational formulations in Rodin — Vector and complex expressions and integral forms.
- Integral equation source examples — Integral-potential source examples.
- Surface evolution source examples — Advection and surface-evolution source examples.
- Backends and supported configurations — OpenMP, MPI, and PETSc execution paths.
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.