# 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.