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 Initial refinement                 = 3
  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 Grid generation
    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 application executes the assembled affine system through LinearAdapter using the standard iterative solver and a block-diagonal local preconditioner. The adapter keeps the semantic field and execution storage separate, so the same 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

What to try next

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.