Poisson: your first ImmersX simulation

This tutorial introduces the shortest complete ImmersX workflow: generate a mesh, configure a scalar finite-element problem, solve Poisson’s equation, and inspect the output.

The executable is poisson. Its entry point is apps/app_poisson.cc, and the canonical input is tutorials/poisson/poisson_2d.prm.in:

subsection Poisson
  set Dirichlet boundary ids             = 0,1,2,3
  set FE degree                          = 1
  set Output directory                   = @TEST_OUTPUT_DIR@/tutorial-output/poisson-2d
  set Output name                        = poisson_2d
  set Output results also before solving = false
  subsection Dirichlet boundary conditions
    set Function constants  =
    set Function expression = 0
    set Variable names      = x,y,t
  end
  subsection Domain
    set Initial refinement                 = 3
    set Grid generator           = hyper_cube
    set Grid generator arguments = -1: 1: false
    set Triangulation type       = distributed
  end
  subsection Refinement and remeshing
    set Coarsening fraction         = 0
    set Maximum number of cells     = 20000
    set Number of refinement cycles = 3
    set Refinement fraction         = 0.3
    set Strategy                    = global
  end
  subsection Right hand side
    set Function constants  =
    set Function expression = 1
    set Variable names      = x,y,t
  end
  subsection Solver
    subsection Control
      set Log frequency = 1
      set Log history   = false
      set Log result    = true
      set Max steps     = 100
      set Reduction     = 1.e-10
      set Tolerance     = 1.e-12
    end
  end
end

The problem

The example solves

\[-\Delta u = 1\]

on a square generated by hyper_cube, with homogeneous Dirichlet data on all boundary faces. The finite element degree, initial refinement, solver control, and output name are ordinary parameter-file choices.

The application reads dimension and space dimension before constructing a statically typed solver. The filename does not select the dimension. The example above omits those entries, so the default full-dimensional 2D instantiation is used. Other supported combinations are listed in the application reference.

Run it

Configure and build the project, then run the configured input:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DDEAL_II_DIR=/path/to/deal.II
cmake --build build -j
./build/poisson build/tutorials/poisson/poisson_2d.prm

The configured input writes results below build/test_output/tutorial-output/poisson-2d. A Debug build uses poisson_debug instead. The same canonical input is exercised by AppExecutables.TutorialPoisson.

The poisson executable solves the assembled system with conjugate gradients and an AMG preconditioner. The poisson_adapter executable registers the same assembled Problem with LinearAdapter. The adapter keeps the semantic field and execution storage separate, so that Problem can also be composed with other Problems in a coupled adapter.

For a distributed run, launch the executable explicitly with MPI:

mpirun -np 2 ./build/poisson build/tutorials/poisson/poisson_2d.prm

Simplex meshes

poisson and poisson_adapter accept meshes containing only triangles or only tetrahedra. Select Triangulation type = fullydistributed and read the mesh through the Domain:

subsection Poisson
  subsection Domain
    set Triangulation type = fullydistributed
    set Grid generator = /absolute/path/mesh.msh
    set Initial refinement = 0
  end
  subsection Refinement and remeshing
    set Number of refinement cycles = 1
  end
end

The solver uses FE_SimplexP, simplex Gauss quadrature, and a linear MappingFE. Set dimension and space dimension to match the imported mesh. Initial refinement is performed before distributing the mesh. Refinement between solve cycles is unavailable with this backend. The convergence table is skipped because deal.II’s ParsedConvergenceTable uses hypercube quadrature. Mixed cell meshes are rejected.

Robin and mixed boundary conditions

Select Robin boundary ids to impose

\[\nabla u\cdot n + \beta u = g\]

where \(n\) is the outward normal, or the outward conormal on an embedded mesh. The solver adds \(\int_{\Gamma_R}\beta u v\) to the matrix and \(\int_{\Gamma_R}g v\) to the right-hand side. The coefficient and data are scalar parsed functions of the physical coordinates. Robin and Dirichlet ids must be disjoint; other faces retain the homogeneous natural condition.

For example, on the unit square with boundary ids generated by subdivided_hyper_cube with 2:0:1:true, this imposes \(u=1+y\) on the left face and \(\nabla u\cdot n+2u=g\) on the other three faces:

subsection Poisson
  set Dirichlet boundary ids = 0
  set Robin boundary ids = 1,2,3
  subsection Dirichlet boundary conditions
    set Function expression = 1+y
  end
  subsection Robin coefficient
    set Function expression = 2
  end
  subsection Robin boundary conditions
    set Function expression = if(y<1e-9,-1,if(y>1-1e-9,1,0))+2*(1+y)
  end
end

The coefficient must be finite and nonnegative at the quadrature points, and \(g\) must be finite. A zero coefficient gives Neumann data. For a pure Robin problem, clear Dirichlet boundary ids and choose a positive coefficient on a boundary portion of positive measure. An all-Neumann problem still needs a nullspace constraint, which this solver does not add automatically.

The same parameters work with poisson_adapter and Poisson components in coupled problems, since they use the assembled Poisson operator. Both hypercube and simplex meshes are supported, including the embedded dimensions listed above. These parameters configure the scalar Poisson problem; they do not add Robin parameters to the elasticity applications.

Further examples

Change FE degree, Initial refinement, or the right-hand-side expression and rerun. For imported grids, see Configure a parameter file and the API reference. Continue to static elasticity when you are ready for vector-valued fields.