adam_flail_object

ADAM, FLAIL: the elliptic solver library (issue #84).

One entry point for the elliptic solves of every ADAM application. It is built on the two solvers verified in issues #81 and #87: the FFT solver poisson_fft_object (uniform grids, periodic or isolated, FFTW on the host; its FNL extension runs the transforms on cuFFT) and the multigrid-preconditioned conjugate-gradient solver poisson_mg_object (2:1 AMR grids, the symmetric composite operator, periodic or isolated through the James step, its coarsest level solved by the FFT solver). PRISM's t0 solves moved here in issue #84 E3, and its legacy smoothers (adam_flail_legacy_object, the [linear-algebra] section) were deleted in E4.

Phase E0 is a facade over the two solvers: setup chooses one for the current grid, as FLUME's self-gravity did, and solve/solve_packed forward to it with the call sequence unchanged, so a client gets bitwise the results it got from the solvers directly. The operator is the compact second-order Laplacian L_h phi = factor (f - mean f) (periodic) or L_h phi = factor f (isolated); further operators come in E2.

Boundary kinds (E1c). setup(..., bc) gives the kind of every face (adam_flail_parameters: periodic, Dirichlet or Neumann at the face, ghost-Dirichlet; mixed across axes and within one), forwarded to the solver chosen; the grid's periodicity must agree with it. Without a Dirichlet face the operator is singular and the mean of the source is removed, as on a periodic grid. Without bc the setup is the E0 one, unchanged: periodic or isolated. The values at the boundary are homogeneous on the FFT path; solve(..., ghost=) gives inhomogeneous ones (the multigrid's boundary-face list, mg%nbnd, mg%bnd_kind, mg%bnd_dir, mg%bnd_x) and needs the multigrid path (FLAIL_BACKEND_MULTIGRID: on a uniform grid one V-cycle is the exact FFT solve). FLAIL_BC_ZERO_GHOSTS (E2b, PRISM's Dirichlet face) is ghost-Dirichlet at zero for the compact operator; with the wide D(G) the FFT solver solves it by preconditioned CG. FLAIL_BC_FREE_GHOSTS (E3c, PRISM's exact/open face) holds the free-space potential of the source in the ghosts, on the same CG path. A vector whose components take different kinds (PRISM's vector potential at a PEC face: Neumann for the normal component, Dirichlet for the others) takes one FLAIL per set of kinds: the operators differ, and the instances coexist.

The wide operator (E2a). setup(..., dg_order=p) (2, 4, 6, 8) solves PRISM's D(G), the order-p centred first derivative composed with itself, instead of the compact Laplacian: on a uniform grid the FFT solver inverts it exactly (adam_poisson_fft_object). On AMR it is refused: a composite wide operator across 2:1 faces is not defined yet (#84 E7), and a compact multigrid preconditioner does not converge for it in a bounded number of iterations (the checkerboard branch; the #84 E2 prototype).

A backend's FFT solver is chosen by allocating the fft component before setup (the FNL backend allocates the cuFFT extension); otherwise setup allocates the host one. Its multigrid solver likewise by allocating the mg_mold component (the FNL backend allocates the device extension, #84 E6a); otherwise the host one.

Source: src/lib/common/adam_flail_object.F90

Dependencies

Contents

• flail_object
• destroy
• setup
• solve
• solve_packed
• refuse_ghost
• is_multigrid
• iterations

Variables

Name	Type	Attributes	Description
FLAIL_BACKEND_AUTO	integer(kind=I4P)	parameter	FFT on a uniform grid, multigrid otherwise.
FLAIL_BACKEND_FFT	integer(kind=I4P)	parameter	The FFT solver (uniform grids only).
FLAIL_BACKEND_MULTIGRID	integer(kind=I4P)	parameter	The multigrid solver, on any 2:1 grid.

Derived Types

flail_object

FLAIL: the elliptic solver of a realm.

Components

Name	Type	Attributes	Description
fft	class(poisson_fft_object)	allocatable	FFT solver; on a multigrid setup, the mold of its coarsest level.
mg	class(poisson_mg_object)	allocatable	Multigrid solver, allocated only when the current setup uses it.
mg_mold	class(poisson_mg_object)	allocatable	The backend's multigrid solver type (none: the host one).

Type-Bound Procedures

Name	Attributes	Description
destroy	pass(self)	Destroy the solvers.
is_multigrid	pass(self)	True when the current setup uses the multigrid solver.
iterations	pass(self)	FCG iterations of the last multigrid solve (0 for the FFT solver).
setup	pass(self)	Choose and set up the solver for the current grid.
solve	pass(self)	Solve for phi from one variable of q.
solve_packed	pass(self)	Solve for phi from the packed interior source.

Subroutines

destroy

Destroy the solvers.

subroutine destroy(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	inout		FLAIL.

Call graph

setup

Choose and set up the solver for the current grid: call it on the initial grid and after every regrid.

FLAIL_BACKEND_AUTO uses the FFT solver when every leaf is at one level and the multigrid solver otherwise; FLAIL_BACKEND_FFT on a grid with more than one level is fatal, the message naming option_name (the client's input key, default [flail].(backend)). The multigrid solver is rebuilt at every call, its coarsest level solved by a solver of the fft component's type. bc (E1c): the kind of every face, forwarded to the solver; isolated boundaries take none (fatal: the FFT solver would ignore it). dg_order (E2a): 0 the compact Laplacian (the default), 2, 4, 6 or 8 the wide D(G), on the FFT path only. root_cells (#84 E6): the multigrid's root at most this many cells (default: the root solver's root_cells_max); for measurements.

subroutine setup(self, grid, field, isolated, backend, option_name, bc, dg_order, root_cells)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	inout		FLAIL.
grid	type(grid_object)	in		The grid.
field	type(field_object)	in		The field (block coordinates).
isolated	logical	in		Free-space boundaries, else periodic.
backend	integer(kind=I4P)	in		FLAIL_BACKEND_AUTO, _FFT or _MULTIGRID.
option_name	character(len=*)	in	optional	The client's input key, for the messages.
bc	integer(kind=I4P)	in	optional	Kinds per face [lo/hi, axis] (adam_flail_parameters).
dg_order	integer(kind=I4P)	in	optional	0 compact (default); 2, 4, 6, 8: the wide D(G).
root_cells	integer(kind=I4P)	in	optional	Most cells of the multigrid's root.

Call graph

solve

Solve for phi from the variable iv of q, every ghost layer of phi filled; optionally the energy sum_cells f phi dV (every rank). ghost (E1c): the boundary value of each of this rank's boundary faces (mg%nbnd, of its kind), multigrid path only.

subroutine solve(self, field, q, iv, factor, phi, energy, ghost)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	inout		FLAIL.
field	type(field_object)	in		The field (coordinates).
q	real(kind=R8P)	in		Conservative [nv,i,j,k,nb], ghosts included.
iv	integer(kind=I4P)	in		Variable of q, the source.
factor	real(kind=R8P)	in		Source factor (4 pi G for gravity).
phi	real(kind=R8P)	inout		Potential [i,j,k,nb], ghosts included.
energy	real(kind=R8P)	out	optional	sum_cells f phi dV (all ranks).
ghost	real(kind=R8P)	in	optional	Boundary values per boundary face (multigrid path).

Call graph

solve_packed

Solve for phi from the packed interior source of the active blocks (block-major, i fastest), every ghost layer of phi filled; optionally the energy sum_cells f phi dV (every rank); ghost as in solve.

subroutine solve_packed(self, field, buf, factor, phi, energy, ghost)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	inout		FLAIL.
field	type(field_object)	in		The field (coordinates).
buf	real(kind=R8P)	in		Packed interior source.
factor	real(kind=R8P)	in		Source factor (4 pi G for gravity).
phi	real(kind=R8P)	inout		Potential [i,j,k,nb], ghosts included.
energy	real(kind=R8P)	out	optional	sum_cells f phi dV (all ranks).
ghost	real(kind=R8P)	in	optional	Boundary values per boundary face (multigrid path).

Call graph

refuse_ghost

Boundary values given on the FFT path, which solves the homogeneous problem: fatal.

subroutine refuse_ghost()

Call graph

Functions

is_multigrid

True when the current setup uses the multigrid solver.

Attributes: pure

Returns: logical

function is_multigrid(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	in		FLAIL.

Call graph

iterations

FCG iterations of the last multigrid solve (0 for the FFT solver).

Attributes: pure

Returns: integer(kind=I4P)

function iterations(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flail_object)	in		FLAIL.

Call graph