Module ppm_module_decomp

This module provides the PPM decomposition routines.

PPM core provides 4 different decomposition routines that are called within the topology routines.

Defined Types

name description

no types

Defined Module Interfaces

Defined Module Subroutines

name description

no subroutines

Interface ppm_decomp_boxsplit

Subroutines contained in this interface:

name description

decomp_bsplit_s

This routine splits a (parent) box in its 4 or 8 children for

decomp_bsplit_d

This routine splits a (parent) box in its 4 or 8 children for

Interface ppm_decomp_cartesian

Subroutines contained in this interface:

name description

decomp_cart_s

Decomposes space using a Cartesian domain decomposition topology.

decomp_cart_d

Decomposes space using a Cartesian domain decomposition topology.

Interface ppm_decomp_pruned_cell

Subroutines contained in this interface:

name description

decomp_pcell_s

This routine performs a domain decomposition using a

decomp_pcell_d

This routine performs a domain decomposition using a

Interface ppm_decomp_tree

Subroutines contained in this interface:

name description

decomp_tree_s

Performs a tree-like decomposition.

decomp_tree_d

Performs a tree-like decomposition.

Subroutine decomp_bsplit_d

This routine splits a (parent) box in its 4 or 8 children for 2D and 3D problems. The particles contained within the parent box are sorted into the respective child boxes.

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(INOUT)

Particle coordinates

ppb

integer array

(:)

(INOUT)

ppb(i_box) returns the first index of the particle in the box of

npbx

integer array

(:)

(INOUT)

npbx(i_box) returns the number of particles in the box of index ibox

kbox

integer

(IN)

ID of the parent box

nbox

integer

(INOUT)

Current number of boxes

min_box

real array

(:,:)

(INOUT)

Smallest extremum of the sub-domains

max_box

real array

(:,:)

(INOUT)

Largest extremum of the sub-domains

info

integer

(OUT)

Returns status, 0 upon success

xp

real array, (:,:), (INOUT)

Particle coordinates

ppb

integer array, (:), (INOUT)

ppb(i_box) returns the first index of the particle in the box of index ibox

npbx

integer array, (:), (INOUT)

npbx(i_box) returns the number of particles in the box of index ibox

kbox

integer, , (IN)

ID of the parent box

nbox

integer, , (INOUT)

Current number of boxes

min_box

real array, (:,:), (INOUT)

Smallest extremum of the sub-domains

max_box

real array, (:,:), (INOUT)

Largest extremum of the sub-domains

info

integer, , (OUT)

Returns status, 0 upon success

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_util_sort, ppm_module_substart

Subroutine decomp_bsplit_s

This routine splits a (parent) box in its 4 or 8 children for 2D and 3D problems. The particles contained within the parent box are sorted into the respective child boxes.

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(INOUT)

Particle coordinates

ppb

integer array

(:)

(INOUT)

ppb(i_box) returns the first index of the particle in the box of

npbx

integer array

(:)

(INOUT)

npbx(i_box) returns the number of particles in the box of index ibox

kbox

integer

(IN)

ID of the parent box

nbox

integer

(INOUT)

Current number of boxes

min_box

real array

(:,:)

(INOUT)

Smallest extremum of the sub-domains

max_box

real array

(:,:)

(INOUT)

Largest extremum of the sub-domains

info

integer

(OUT)

Returns status, 0 upon success

xp

real array, (:,:), (INOUT)

Particle coordinates

ppb

integer array, (:), (INOUT)

ppb(i_box) returns the first index of the particle in the box of index ibox

npbx

integer array, (:), (INOUT)

npbx(i_box) returns the number of particles in the box of index ibox

kbox

integer, , (IN)

ID of the parent box

nbox

integer, , (INOUT)

Current number of boxes

min_box

real array, (:,:), (INOUT)

Smallest extremum of the sub-domains

max_box

real array, (:,:), (INOUT)

Largest extremum of the sub-domains

info

integer, , (OUT)

Returns status, 0 upon success

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_util_sort, ppm_module_substart

Subroutine decomp_cart_d

Decomposes space using a Cartesian domain decomposition topology.

[Tip]Tip

In the user_defined case, the routine must be called with a non-zero number of subdomains in min_sub(:,:), max_sub(:,:) and this user-defined decomposition is used unchanged.

[Note]Note

This routine is unaware of particles and simply decomposes space into equal grid volumes. When used for particles, this should be followed by a check of the cost balancing and possibly iterated with increasing ndom.

[Note]Note

The computational domain is subdivided in exactly as many subdomains as there are processors. This is done to minimize memory usage of ghost layers (grids need ghost layers also at intra-processor subdomain boundaries!) and to get good convergence of the grid solver (artificial internal boundary conditionds at subdomain boundaries deteriorate convergence). A quad-/oct-tree decomposition of the computational domain is made until the remaining number of subs does not contain anymore a power of 2 factor. The remaining factor is used to do a parallel slab decomposition, such that the surface-to-volume ratio is minimized (in terms of numbers of grid points). This way, nproc equally sized subdomains with minimal collective surface nodes are created. The pencil decomposition works exactly the same except that cuts in one direction are prohibited.

Arguments

name type dimension intent optional description

nm

integer array

(:)

(IN)

Number of mesh points (not cells) in each direction of the

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

decomp

integer

(IN)

Domain decomposition can be one of:

min_sub

real array

(:,:)

Minimum extend of the subs

max_sub

real array

(:,:)

Maximum extend of the subs

nsubs

integer

(INOUT)

Total number of subdomains

info

integer

(OUT)

Retuns status, 0 upon success

ndom

integer

(IN)

X

Number of subdomains to be created. If not specified,

nm

integer array, (:), (IN)

Number of mesh points (not cells) in each direction of the global comput. domain. (including those ON the boundaries)

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

decomp

integer, , (IN)

Domain decomposition can be one of:

  • ppm_param_decomp_xpencil
  • ppm_param_decomp_ypencil
  • ppm_param_decomp_zpencil
  • ppm_param_decomp_cuboid
  • ppm_param_decomp_user_defined
min_sub

real array, (:,:), no intent declared

Minimum extend of the subs

max_sub

real array, (:,:), no intent declared

Maximum extend of the subs

nsubs

integer, , (INOUT)

Total number of subdomains

info

integer, , (OUT)

Retuns status, 0 upon success

(Optional) ndom

integer, , (IN)

Number of subdomains to be created. If not specified, the number of subdomains will be equal to the number of processors.

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_write, ppm_module_substart

Subroutine decomp_cart_s

Decomposes space using a Cartesian domain decomposition topology.

[Tip]Tip

In the user_defined case, the routine must be called with a non-zero number of subdomains in min_sub(:,:), max_sub(:,:) and this user-defined decomposition is used unchanged.

[Note]Note

This routine is unaware of particles and simply decomposes space into equal grid volumes. When used for particles, this should be followed by a check of the cost balancing and possibly iterated with increasing ndom.

[Note]Note

The computational domain is subdivided in exactly as many subdomains as there are processors. This is done to minimize memory usage of ghost layers (grids need ghost layers also at intra-processor subdomain boundaries!) and to get good convergence of the grid solver (artificial internal boundary conditionds at subdomain boundaries deteriorate convergence). A quad-/oct-tree decomposition of the computational domain is made until the remaining number of subs does not contain anymore a power of 2 factor. The remaining factor is used to do a parallel slab decomposition, such that the surface-to-volume ratio is minimized (in terms of numbers of grid points). This way, nproc equally sized subdomains with minimal collective surface nodes are created. The pencil decomposition works exactly the same except that cuts in one direction are prohibited.

Arguments

name type dimension intent optional description

nm

integer array

(:)

(IN)

Number of mesh points (not cells) in each direction of the

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

decomp

integer

(IN)

Domain decomposition can be one of:

min_sub

real array

(:,:)

Minimum extend of the subs

max_sub

real array

(:,:)

Maximum extend of the subs

nsubs

integer

(INOUT)

Total number of subdomains

info

integer

(OUT)

Retuns status, 0 upon success

ndom

integer

(IN)

X

Number of subdomains to be created. If not specified,

nm

integer array, (:), (IN)

Number of mesh points (not cells) in each direction of the global comput. domain. (including those ON the boundaries)

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

decomp

integer, , (IN)

Domain decomposition can be one of:

  • ppm_param_decomp_xpencil
  • ppm_param_decomp_ypencil
  • ppm_param_decomp_zpencil
  • ppm_param_decomp_cuboid
  • ppm_param_decomp_user_defined
min_sub

real array, (:,:), no intent declared

Minimum extend of the subs

max_sub

real array, (:,:), no intent declared

Maximum extend of the subs

nsubs

integer, , (INOUT)

Total number of subdomains

info

integer, , (OUT)

Retuns status, 0 upon success

(Optional) ndom

integer, , (IN)

Number of subdomains to be created. If not specified, the number of subdomains will be equal to the number of processors.

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_write, ppm_module_substart

Subroutine decomp_pcell_d

This routine performs a domain decomposition using a pruned (incomplete) cell index list.

[Caution]Caution

The way we compute the min_sub, max_sub may have problems with roundoff errors!

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(IN)

Position of the particles

npart

integer

(IN)

Number of particles

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

ghostsize

real

(IN)

Size (width) of the ghost layer

min_sub

real array

(:,:)

Minimum extent of the subdomain

max_sub

real array

(:,:)

Maximum extent of the subdomain

nsubs

integer

(OUT)

Total number of subdomains

info

integer

(OUT)

Return status, 0 on success

pcost

real array

(:)

(IN)

X

Argument of length Npart, specifying the

xp

real array, (:,:), (IN)

Position of the particles

npart

integer, , (IN)

Number of particles

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

ghostsize

real, , (IN)

Size (width) of the ghost layer

min_sub

real array, (:,:), no intent declared

Minimum extent of the subdomain

max_sub

real array, (:,:), no intent declared

Maximum extent of the subdomain

nsubs

integer, , (OUT)

Total number of subdomains

info

integer, , (OUT)

Return status, 0 on success

(Optional) pcost

real array, (:), (IN)

Argument of length Npart, specifying the computational cost of each particle

Used Modules

ppm_module_data, ppm_module_alloc, ppm_module_error, ppm_module_substop, ppm_module_substart

Subroutine decomp_pcell_s

This routine performs a domain decomposition using a pruned (incomplete) cell index list.

[Caution]Caution

The way we compute the min_sub, max_sub may have problems with roundoff errors!

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(IN)

Position of the particles

npart

integer

(IN)

Number of particles

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

ghostsize

real

(IN)

Size (width) of the ghost layer

min_sub

real array

(:,:)

Minimum extent of the subdomain

max_sub

real array

(:,:)

Maximum extent of the subdomain

nsubs

integer

(OUT)

Total number of subdomains

info

integer

(OUT)

Return status, 0 on success

pcost

real array

(:)

(IN)

X

Argument of length Npart, specifying the

xp

real array, (:,:), (IN)

Position of the particles

npart

integer, , (IN)

Number of particles

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

ghostsize

real, , (IN)

Size (width) of the ghost layer

min_sub

real array, (:,:), no intent declared

Minimum extent of the subdomain

max_sub

real array, (:,:), no intent declared

Maximum extent of the subdomain

nsubs

integer, , (OUT)

Total number of subdomains

info

integer, , (OUT)

Return status, 0 on success

(Optional) pcost

real array, (:), (IN)

Argument of length Npart, specifying the computational cost of each particle

Used Modules

ppm_module_data, ppm_module_alloc, ppm_module_error, ppm_module_substop, ppm_module_substart

Subroutine decomp_tree_d

Performs a tree-like decomposition. It subdivides space until the number of leaves in the tree exceeds the number of processors and until the variance of the number of particles in the leaves is below a certain tolerance.

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(IN)

Position of the particles

npart

integer

(IN)

Number of particles

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

minboxsize

real

(IN)

Minimum box size

tolerance

real

(IN)

Maximum relative variance of the box cost allowed before

min_sub

real array

(:,:)

Minimum extent of the subdomain

max_sub

real array

(:,:)

Maximum extent of the subdomain

nsubs

integer

(OUT)

Total number of subdomains

info

integer

(OUT)

Return status, 0 on success

pcost

real array

(:)

(IN)

X

Argument of length Npart, specifying the

xp

real array, (:,:), (IN)

Position of the particles

npart

integer, , (IN)

Number of particles

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

minboxsize

real, , (IN)

Minimum box size

tolerance

real, , (IN)

Maximum relative variance of the box cost allowed before terminating the tree; tolerance >= 0

min_sub

real array, (:,:), no intent declared

Minimum extent of the subdomain

max_sub

real array, (:,:), no intent declared

Maximum extent of the subdomain

nsubs

integer, , (OUT)

Total number of subdomains

info

integer, , (OUT)

Return status, 0 on success

(Optional) pcost

real array, (:), (IN)

Argument of length Npart, specifying the computational cost of each particle.

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_write, ppm_module_substart

Subroutine decomp_tree_s

Performs a tree-like decomposition. It subdivides space until the number of leaves in the tree exceeds the number of processors and until the variance of the number of particles in the leaves is below a certain tolerance.

Arguments

name type dimension intent optional description

xp

real array

(:,:)

(IN)

Position of the particles

npart

integer

(IN)

Number of particles

min_phys

real array

(:)

(IN)

Minimum coordinate of the physical/computational domain

max_phys

real array

(:)

(IN)

Maximum coordinate of the physical/computational domain

minboxsize

real

(IN)

Minimum box size

tolerance

real

(IN)

Maximum relative variance of the box cost allowed before

min_sub

real array

(:,:)

Minimum extent of the subdomain

max_sub

real array

(:,:)

Maximum extent of the subdomain

nsubs

integer

(OUT)

Total number of subdomains

info

integer

(OUT)

Return status, 0 on success

pcost

real array

(:)

(IN)

X

Argument of length Npart, specifying the

xp

real array, (:,:), (IN)

Position of the particles

npart

integer, , (IN)

Number of particles

min_phys

real array, (:), (IN)

Minimum coordinate of the physical/computational domain

max_phys

real array, (:), (IN)

Maximum coordinate of the physical/computational domain

minboxsize

real, , (IN)

Minimum box size

tolerance

real, , (IN)

Maximum relative variance of the box cost allowed before terminating the tree; tolerance >= 0

min_sub

real array, (:,:), no intent declared

Minimum extent of the subdomain

max_sub

real array, (:,:), no intent declared

Maximum extent of the subdomain

nsubs

integer, , (OUT)

Total number of subdomains

info

integer, , (OUT)

Return status, 0 on success

(Optional) pcost

real array, (:), (IN)

Argument of length Npart, specifying the computational cost of each particle.

Used Modules

ppm_module_data, ppm_module_error, ppm_module_alloc, ppm_module_substop, ppm_module_write, ppm_module_substart

Defined Module Variables

name type dimension description

no variables

Used Modules

has no uses