Clarify why FFTs cause fractal box decomposition limitations

这个提交包含在:
Nathan Mannall
2025-06-30 16:38:26 +01:00
父节点 70497fe2a3
当前提交 8bfbe63cb0

查看文件

@@ -59,53 +59,34 @@ The ``--mpi`` argument passed to gprMax takes three integers to define the numbe
Decomposition of Fractal Geometry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are some restrictions when using MPI domain decomposition with
:ref:`fractal user objects <fractals>`.
There are some restrictions when using MPI domain decomposition with :ref:`fractal user objects <fractals>`.
.. warning::
gprMax will throw an error during the model build phase if the MPI
decomposition is incompatible with the model geometry.
gprMax will throw an error during the model build phase if the MPI decomposition is incompatible with the model geometry.
**#fractal_box**
When a ``#fractal_box`` has a mixing model attached, it will perform a
parallel fast Fourier transforms (FFTs) as part of its construction. To
support this, the MPI domain decomposition of the fractal box must have
size one in at least one dimension:
When a ``#fractal_box`` has a mixing model attached, it will perform a parallel fast Fourier transforms (FFTs) as part of its construction. When performing a parallel FFT in 3D space, the decomposition must be either 1D or 2D - it cannot be decomposed in all 3 dimensions. To support this, the MPI domain decomposition of the fractal box must have size one in at least one dimension:
.. _fractal_domain_decomposition_figure:
.. figure:: ../../images_shared/fractal_domain_decomposition.png
Example slab and pencil decompositions. These decompositions could
be specified with ``--mpi 8 1 1`` and ``--mpi 3 3 1`` respectively.
Example slab and pencil decompositions. These decompositions could be specified with ``--mpi 8 1 1`` and ``--mpi 3 3 1`` respectively.
.. note::
This does not necessarily mean the whole model domain needs to be
divided this way. So long as the volume covered by the fractal box
is divided into either slabs or pencils, the model can be built.
This includes the volume covered by attached surfaces added by the
``#add_surface_water``, ``#add_surface_roughness``, or
``#add_grass`` commands.
This does not necessarily mean the whole model domain needs to be divided this way. So long as the volume covered by the fractal box is divided into either slabs or pencils, the model can be built. This includes the volume covered by attached surfaces added by the ``#add_surface_water``, ``#add_surface_roughness``, or ``#add_grass`` commands.
**#add_surface_roughness**
When adding surface roughness, a parallel fast Fourier transform is
applied across the 2D surface of a fractal box. Therefore, the MPI
domain decomposition across the surface must be size one in at least one
dimension.
When adding surface roughness, a parallel fast Fourier transform is applied across the 2D surface of a fractal box. Therefore, the MPI domain decomposition across the surface must be size one in at least one dimension.
For example, in figure :numref:`fractal_domain_decomposition_figure`, surface
roughness can be attached to any surface when using the slab
decomposition. However, if using the pencil decomposition, it could not
be attached to the XY surfaces.
For example, in figure :numref:`fractal_domain_decomposition_figure`, surface roughness can be attached to any surface when using the slab decomposition. However, if using the pencil decomposition, it could not be attached to the XY surfaces.
**#add_grass**
Domain decomposition of grass is not currently supported. Grass can
still be built in a model so long as it is fully contained within a
single MPI rank.
Domain decomposition of grass is not currently supported. Grass can still be built in a model so long as it is fully contained within a single MPI rank.
Task farm
---------