# CustomTopology

`CustomTopology()`

The CustomTopology class provides a mechanism to describe parametric domain decompositions. It allows users to specify how the dimensions of a domain are decomposed into chunks based on certain parameters.

## Examples

For example, let’s consider a domain with three distributed dimensions: x, y, and z, and an MPI communicator with N processes. Here are a few examples of CustomTopology:

With N known, say N=4: * `(1, 1, 4)`

: the z Dimension is decomposed into 4 chunks * `(2, 1, 2)`

: the x Dimension is decomposed into 2 chunks and the z Dimension is decomposed into 2 chunks

With N unknown: * `(1, '*', 1)`

: the wildcard `'*'`

indicates that the runtime should decompose the y Dimension into N chunks * `('*', '*', 1)`

: the wildcard `'*'`

indicates that the runtime should decompose both the x and y Dimensions in `nstars`

factors of N, prioritizing the outermost dimension

Assuming that the number of ranks `N`

cannot evenly be decomposed to the requested stars=6 we decompose as evenly as possible by prioritising the outermost dimension

For N=3 * `('*', '*', 1)`

gives: (3, 1, 1) * `('*', 1, '*')`

gives: (3, 1, 1) * `(1, '*', '*')`

gives: (1, 3, 1)

For N=6 * `('*', '*', 1)`

gives: (3, 2, 1) * `('*', 1, '*')`

gives: (3, 1, 2) * `(1, '*', '*')`

gives: (1, 3, 2)

For N=8 * `('*', '*', '*')`

gives: (2, 2, 2) * `('*', '*', 1)`

gives: (4, 2, 1) * `('*', 1, '*')`

gives: (4, 1, 2) * `(1, '*', '*')`

gives: (1, 4, 2)

## Notes

Users should not directly use the CustomTopology class. It is instantiated by the Devito runtime based on user input.