Modified the docs with a new order for topology plots and fixed previous diagrams not showing.

Author: wearysebas

manual/sphinx/user_docs/input_grids.rst

@@ -162,6 +162,43 @@ The directory ``tokamak_grids`` contains code to generate input grid
 files for tokamaks. These can be used by, for example, the ``2fluid`` and
 ``highbeta_reduced`` modules.
 
+
+3D Variables
+------------
+
+BOUT++ was originally designed for tokamak simulations where the input
+equilibrium varies only in X-Y, and Z is used as the axisymmetric toroidal
+angle direction. In those cases, it is often convenient to have input grids
+which are only 2D, and allow the Z dimension to be specified independently,
+such as in the options file. The problem then is how to store 3D variables in
+the grid file?
+
+Two representations are now supported for 3D variables:
+
+#. Real space, as values on grid points. If ``nz`` is set in the grid file,
+   then 3D variables in the grid file must have size ``nx``\
+   :math:`\times`\ ``ny``\ :math:`\times`\ ``nz``. These are then read in
+   directly into `Field3D` variables as required.
+
+#. A Fourier representation. If the size of the toroidal domain is not
+   specified in the grid file (``nz`` is not defined), then 3D fields are
+   stored as Fourier components. In the Z dimension the coefficients must be
+   stored as
+
+   .. math::
+
+      [n = 0, n = 1 (\textrm{real}), n = 1 (\textrm{imag}), n = 2
+      (\textrm{real}), n = 2 (\textrm{imag}), \ldots ]
+
+   where :math:`n` is the toroidal mode number. The size of the array must
+   therefore be odd in the Z dimension, to contain a constant (:math:`n=0`)
+   component followed by real/imaginary pairs for the non-axisymmetric
+   components.
+
+   If you are using IDL to create a grid file, there is a routine in
+   ``tools/idllib/bout3dvar.pro`` for converting between BOUT++'s real and
+   Fourier representation.
+
 From EFIT files
 ---------------
 

manual/sphinx/user_docs/supported_topologies.rst

@@ -43,15 +43,15 @@ The regions that form the building blocks of this topology are:
 - 2 "leg" regions which have a boundary in the ``y`` direction;
 - 1 "core" region which does not have boundaries in ``y``.
 
-.. figure:: ../figs/Topologies/SN/SN_regions.*
-    :alt: The regions of a single null configuration.
-
-    Single null configuration regions defined by the branch cuts in :math:`y`.
-
 .. figure:: ../figs/Topologies/SN/SN_processors.*
     :alt: The processor layout of a single null configuration.
 
     Division of Single Null configuration into processor layout in index space to compare with the INGRID geometry diagram. 
+
+.. figure:: ../figs/Topologies/SN/SN_regions.*
+    :alt: The regions of a single null configuration.
+
+    Single null configuration regions defined by the branch cuts in :math:`y`.
 
 
 Even though BOUT++ does not requiere each region to be divided into more processors, using an INGRID grid enables this division and makes it easier to understand the topology.
@@ -75,16 +75,16 @@ maintain experimentally for a long period of time.
 
     Connected double null geometry on the RZ plane generated by INGRID.
 
-.. figure:: ../figs/Topologies/CDN/CDN_regions.*
-    :alt: The regions of a connected double null configuration.
-
-    Connected double null configuration regions defined by the branch cuts in :math:`y`.
-
 .. figure:: ../figs/Topologies/CDN/CDN_processors.*
     :alt: The processor layout of a connected double null configuration.
 
     Division of Connected Double Null configuration into processor layout in index space to compare with the INGRID geometry diagram. 
 
+.. figure:: ../figs/Topologies/CDN/CDN_regions.*
+    :alt: The regions of a connected double null configuration.
+
+    Connected double null configuration regions defined by the branch cuts in :math:`y`.
+
 .. figure:: ../figs/Topologies/CDN/CDN_topology.*
     :alt: The topology of a connected double null configuration.
 
@@ -105,16 +105,17 @@ configurations.
 
     Unconnected double null geometry on the RZ plane generated by INGRID.
 
-.. figure:: ../figs/Topologies/UDN/UDN_regions.*
-    :alt: The regions of an unconnected double null configuration.
-
-    Unconnected double null configuration regions defined by the branch cuts in :math:`y`.
 
 .. figure:: ../figs/Topologies/UDN/UDN_processors.*
     :alt: The processor layout of an unconnected double null configuration.
 
     Division of Unconnected Double Null configuration into processor layout in index space to compare with the INGRID geometry diagram. 
 
+.. figure:: ../figs/Topologies/UDN/UDN_regions.*
+    :alt: The regions of an unconnected double null configuration.
+
+    Unconnected double null configuration regions defined by the branch cuts in :math:`y`.
+
 .. figure:: ../figs/Topologies/UDN/UDN_topology.*
     :alt: The topology of an unconnected double null configuration.
 
@@ -186,16 +187,16 @@ the same. The regions that form the building blocks of these topologies are:
 - 5 "leg" regions which have a boundary in the ``y`` direction;
 - 1 "core" region which does not have boundaries in ``y``.
 
-.. figure:: ../figs/Topologies/SF/SF_regions.*
-    :alt: The regions of a snowflake configuration.
-
-    Snowflake configuration regions defined by the branch cuts in :math:`y`.
-
 .. figure:: ../figs/Topologies/SF/SF_processors.*
     :alt: The processor layout of a snowflake configuration.
 
     Division of Snowflake configuration into processor layout in index space to compare with the INGRID geometry diagram. 
 
+.. figure:: ../figs/Topologies/SF/SF_regions.*
+    :alt: The regions of a snowflake configuration.
+
+    Snowflake configuration regions defined by the branch cuts in :math:`y`.
+
 .. figure:: ../figs/Topologies/SF/SF_topology.*
     :alt: The topology of a snowflake configuration.
 

manual/sphinx/user_docs/topology.rst

@@ -95,6 +95,17 @@ PFRs (private flux regions), and the core of the tokamak. If
 ``jyseps1_2 == jyseps2_1`` then the grid is a **single null** configuration,
 otherwise it can be any of the more advanced configurations.
 
+.. _fig-topology-cross-section:
+.. figure:: ../figs/topology_cross_section.*
+   :alt: Cross-section of the tokamak topology used in BOUT++
+
+   Deconstruction of a poloidal tokamak cross-section into logical
+   domains using the parameters ``ixseps1``, ``ixseps2``,
+   ``jyseps1_1``, ``jyseps1_2``, ``jyseps2_1``, and ``jyseps2_2``. This
+   configuration is a "disconnected double null" and shows all the
+   possible regions used in the BOUT++ topology.
+
+
 Advanced
 --------
 
@@ -119,6 +130,12 @@ across the domain boundaries is then handled internally.
    To ensure that communications work, branch cuts must align with processor
    boundaries.
 
+.. _fig-topology-schematic:
+.. figure:: ../figs/topology_schematic.*
+
+   Schematic illustration of domain decomposition and communication in
+   BOUT++ with ``ixseps1 = ixseps2``
+
 These branch cuts are used by the ``getMeshTopology()`` function to determine
 which topology is being used. See :ref:`sec-supported-topologies` for a
 detailed explanation of the available topologies.
@@ -178,6 +195,17 @@ controlled by the variables
     int DDATA_INDEST, DDATA_OUTDEST, DDATA_XSPLIT;
     int IDATA_DEST, ODATA_DEST;
 
+These control the behavior of the communications as shown in
+:numref:`fig-boutmesh-comms`.
+
+.. _fig-boutmesh-comms:
+.. figure:: ../figs/boutmesh-comms.*
+   :alt: Communication of guard cells in BOUT++
+
+   Communication of guard cells in BOUT++. Boundaries in X have only
+   one neighbour each, but boundaries in Y can be split into two,
+   allowing branch cuts.
+
 In the Y direction, each boundary region (**U**\ p and **D**\ own in Y) can be
 split into two, with ``0 <= x < UDATA_XSPLIT`` going to processor index
 ``UDATA_INDEST``, and ``UDATA_INDEST <= x < LocalNx`` going to
@@ -194,39 +222,3 @@ To change the topology, the function ``BoutMesh::set_connection`` checks that
 the requested branch cut is on a processor boundary, and changes the
 communications consistently so that communications are two-way and there are no
 "dangling" communications.
-
-3D Variables
-------------
-
-BOUT++ was originally designed for tokamak simulations where the input
-equilibrium varies only in X-Y, and Z is used as the axisymmetric toroidal
-angle direction. In those cases, it is often convenient to have input grids
-which are only 2D, and allow the Z dimension to be specified independently,
-such as in the options file. The problem then is how to store 3D variables in
-the grid file?
-
-Two representations are now supported for 3D variables:
-
-#. A Fourier representation. If the size of the toroidal domain is not
-   specified in the grid file (``nz`` is not defined), then 3D fields are
-   stored as Fourier components. In the Z dimension the coefficients must be
-   stored as
-
-   .. math::
-
-      [n = 0, n = 1 (\textrm{real}), n = 1 (\textrm{imag}), n = 2
-      (\textrm{real}), n = 2 (\textrm{imag}), \ldots ]
-
-   where :math:`n` is the toroidal mode number. The size of the array must
-   therefore be odd in the Z dimension, to contain a constant (:math:`n=0`)
-   component followed by real/imaginary pairs for the non-axisymmetric
-   components.
-
-   If you are using IDL to create a grid file, there is a routine in
-   ``tools/idllib/bout3dvar.pro`` for converting between BOUT++'s real and
-   Fourier representation.
-
-#. Real space, as values on grid points. If ``nz`` is set in the grid file,
-   then 3D variables in the grid file must have size ``nx``\
-   :math:`\times`\ ``ny``\ :math:`\times`\ ``nz``. These are then read in
-   directly into `Field3D` variables as required.