General concepts » Variational formulations in Rodin

Translate a weak equation into trial fields, test fields, forms, and assembly.

A Rodin problem is built from the same objects as a weak formulation, including spaces, unknown fields, test functions, known data, and integrals. This guide explains their roles in code. The weak formulation guide supplies the derivation; the Poisson tutorial provides a complete runnable solve.

Write the weak equation

For homogeneous Dirichlet Poisson, the weak equation is

\[ a(u,v)=\ell(v),\qquad a(u,v)=\int_\Omega\nabla u\cdot\nabla v\,dx,\qquad \ell(v)=\int_\Omega fv\,dx. \]

Rodin writes this as a residual $a(u,v)-\ell(v)=0$ , together with the essential boundary condition.

  P1 vh(mesh);
  TrialFunction u(vh);
  TestFunction v(vh);
  RealFunction f = 1;

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

Here mesh is the previously constructed unit-square mesh. P1 selects a continuous, piecewise affine space. Trial fields, data and forms then define the discrete equation on that space.

Unknown fields and prescribed data

ObjectRole during assembly
TrialFunction u(vh)Unknown field expanded in trial basis functions
TestFunction v(vh)Test basis functions indexing the equations
RealFunction fKnown scalar coefficient or source
VectorFunction gKnown vector-valued data
GridFunction field(vh)A field represented by finite element coefficients

Trial and test functions are symbolic until integration evaluates their basis functions on a cell. A solved trial function exposes its finite element field through u.getSolution(). A separately constructed grid function may instead hold initial data, a previous time step, or another known coefficient.

Assignment of a known function to a grid function applies the space's DOF functionals. For nodal P1 this gives interpolation. An $L^2$ projection is defined by a mass-matrix problem; see Numerical contracts.

Construct the forms

The number and role of symbolic arguments determine what an integral produces.

ExpressionRole over real fields
Integral(Grad(u), Grad(v))Diffusion bilinear form
Integral(c * u, v)Weighted mass bilinear form
Integral(f, v)Domain load linear form
BoundaryIntegral(g, v).over(label)Load on selected boundary facets

A coefficient such as c must be defined before forming the expression. It supplies known data during assembly. With scalar data, these forms represent products; with vector or tensor data, the corresponding inner products must have compatible shapes.

Residual signs

The matrix and load for basis functions $\phi_j$ and $\psi_i$ have entries $A_{ij}=a(\phi_j,\psi_i)$ and $b_i=\ell(\psi_i)$ before essential elimination. A linear form subtracted in the residual becomes a positive right-hand-side load.

Each bilinear term retains its sign from the weak equation. The Helmholtz residual contains a negative mass term, while the mixed Stokes residual contains signed velocity–pressure coupling blocks.

Select named forms

MassForm, DiffusionForm, HelmholtzForm, and LinearElasticityForm expose common cell operators. For compatible spaces and the corresponding quadrature order, they represent the same discrete forms as their integral expressions. Their reference pages specify supported field types and assembly backends.

The following forms use scalar trial and test functions with previously defined coefficients.

MassForm mass(c, u, v);
DiffusionForm diffusion(a, u, v);
HelmholtzForm helmholtz(a, c, u, v);

Named forms restrict their cell domain with .over(attribute). Their coefficients, boundary conditions and quadrature are specified by the mathematical problem.

Choose operators by field shape

ExpressionMeaning
Grad(u) for a scalar fieldGradient vector
Jacobian(w) for a vector fieldMatrix with entries $\partial_jw_i$
Div(w)Scalar divergence $\sum_i\partial_iw_i$
Transpose(Jacobian(w))Transposed gradient matrix
Mult(Jacobian(w), velocity)Directional derivative $(\mathrm{velocity}\cdot\nabla)w$

For linear elasticity, the symmetric strain is $\varepsilon(w)=\tfrac12(\nabla w+\nabla w^T)$ . Omitting the factor $1/2$ changes the strain energy. The elasticity tutorial uses LinearElasticityIntegral to include the complete Lamé-parameter form.

Complex test convention

Over complex fields, Rodin's bilinear-form interface is sesquilinear. It is linear in the trial argument and conjugate-linear in the test argument. Thus Integral(c * u, v) represents $\int_\Omega c\,u\overline v\,dx$ . The coefficient retains its original complex value. The corresponding discrete action is $y^*Ax$ .

The form language and assembly apply this conjugation once. Backend transfer preserves the assembled entries. Hermitian symmetry depends on the particular form and coefficients. See the complex Helmholtz example.

Apply boundary data

An essential condition is appended as a DirichletBC. A prescribed natural load is part of the residual through a BoundaryIntegral. Their selections have different roles. .on(label) selects constrained DOFs, while .over(label) selects an integration region.

The boundary conditions guide develops a checked mixed-boundary example, including the normal-derivative sign. It also explains periodic identification and the normalization of nullspaces.

Couple multiple fields

A mixed problem lists all trial fields, followed by all test fields. In the Stokes example, velocity, pressure, and a global pressure-mean multiplier have distinct spaces.

  H1 velocitySpace(std::integral_constant<size_t, 2>{}, mesh, 2);
  H1 pressureSpace(std::integral_constant<size_t, 1>{}, mesh);
  P0g meanSpace(mesh);
  TrialFunction u(velocitySpace);
  TrialFunction p(pressureSpace);
  TrialFunction multiplier(meanSpace);
  TestFunction v(velocitySpace);
  TestFunction q(pressureSpace);
  TestFunction meanTest(meanSpace);
  constexpr Real viscosity = 1;
  VectorFunction lidVelocity{16 * Pow(F::x, 2) * Pow(1 - F::x, 2), Zero()};
  Problem stokes(u, p, multiplier, v, q, meanTest);
  stokes = viscosity * Integral(Jacobian(u), Jacobian(v)) - Integral(p, Div(v)) +
    Integral(Div(u), q) + Integral(multiplier, q) + Integral(p, meanTest) +
    DirichletBC(u, lidVelocity).on(lid) + DirichletBC(u, Zero(2)).on(walls);

P0g supplies a single global constant. The multiplier imposes zero mean pressure as a constraint. Quadratic velocity and linear pressure form the Taylor–Hood pair.

Couple discontinuous fields

A discontinuous method needs numerical coupling between neighboring cells. Jump, Average, FaceIntegral, and InterfaceIntegral supply the relevant trace and facet operations; the interface and DG guide defines their side and normal conventions.

A P0 field has zero cellwise gradient, so its diffusion coupling must be supplied through the DG formulation. A consistent method specifies numerical fluxes, stabilization, boundary treatment and the mesh/degree scaling of penalty terms.

Assemble, solve, and inspect

A configured solver retains a reference to its problem. On the first solve, the problem is assembled before the algebraic solver runs. The Poisson example checks the result before export.

  CG solver(poisson);
  solver.solve();
  if (!solver.success())
    return EXIT_FAILURE;

Reassigning a Problem body marks its assembly stale. When known field data change, explicitly reassemble or rebuild the problem. A new mesh or a different finite element space requires a new problem and linear system, with fresh associated solver objects. See Numerical contracts for the lifetime rules.

Export the solved field

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

u.getSolution() supplies the computed grid function for export. Keep referenced HDF5 files alongside the XDMF descriptor. The I/O guide covers multiple fields and time series.

Examples

The Poisson tutorial combines these steps in one program. The Helmholtz, Stokes, and Navier–Stokes examples show how a different weak equation changes matrix properties and solver requirements. Use the solver guide to interpret those requirements.