Merge pull request #3 from 2decomp-fft/doc--api-io

Doc  api io

Author: rfj82982

docs/source/index.rst

@@ -2,50 +2,59 @@
    sphinx-quickstart on Wed Feb 15 14:31:32 2023.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
-
-Welcome to the documentation for the 2decomp&fft library!
+=========================================================
+Welcome to the documentation for the 2DECOMP&FFT library!
 =========================================================
 
-.. note::
-    This website is still **under development**!
-
-The 2DECOMP&FFT library is a software framework written in modern Fortran to build large-scale parallel applications. It is designed for applications using three-dimensional structured mesh and spatially implicit numerical algorithms. At the foundation it implements a general-purpose 2D pencil decomposition for data distribution. On top it provides a highly scalable and efficient interface to perform three-dimensional distributed Fast Fourier Transforms. The library was originaly designed for CPUs only in the 2010's. The new version has be designed to work on CPUs and (NVIDIA) GPUs. We will aim to expend the capabilities of the library in the future (and to fix bugs!).
+The 2DECOMP&FFT library is a software framework written in modern Fortran to build large-scale parallel applications. 
+It is designed for applications using three-dimensional structured mesh and spatially implicit numerical algorithms. 
+At the foundation it implements a general-purpose 2D pencil decomposition for data distribution. 
+On top it provides a highly scalable and efficient interface to perform three-dimensional distributed Fast Fourier Transforms. 
+The library was originaly designed for CPUs only in the 2010's. 
+The new version has be designed to work on CPUs and (NVIDIA) GPUs. We will aim to expend the capabilities of the library in the future (and to fix bugs!).
 
-**Features**
-=============
+Features
+========
 
 Here is a list of 2DECOMP&FFT's main features:
 
--General-purpose 2D pencil decomposition module to support building large-scale parallel applications on supercomputers.
+* General-purpose 2D pencil decomposition module to support building large-scale parallel applications on supercomputers.
 
--Highly scalable and efficient distributed Fast Fourier Transform module, supporting three dimensional FFTs (both complex-to-complex and real-to-complex/complex-to-real).
+* Highly scalable and efficient distributed Fast Fourier Transform module, 
+  supporting three dimensional FFTs (both complex-to-complex and real-to-complex/complex-to-real).
 
--Halo-cell support allowing explicit message passing between neighbouring blocks.
+* Halo-cell support allowing explicit message passing between neighbouring blocks.
 
--Parallel I/O module to support the handling of large data sets.
+* Parallel I/O module to support the handling of large data sets.
 
--Interface with most popular external FFT libraries.
+* Interface with most popular external FFT libraries.
 
 **2DECOMP&FFT is designed to be:**
 
-**Scalable** - The library and applications built upon it are known to scale well on thousands of CPU cores.
+* **Scalable** - The library and applications built upon it are known 
+  to scale well on thousands of CPU cores.
 
-**Flexible** - Software framework to support building higher-level libraries and many types of applications.
+* **Flexible** - Software framework to support building higher-level 
+  libraries and many types of applications.
 
-**User-friendly** - Black-box implementation and very clean application programming interface hiding most communication details from applications.
+* **User-friendly** - Black-box implementation and very clean application programming 
+  interface hiding most communication details from applications.
 
-**Portable** - Code tested on major hardware architectures, with different compilers.
+* **Portable** - Code tested on major hardware architectures, with different compilers.
 
-**Publication**
-===============
+Publication
+===========
 
 N. Li and S. Laizet, "2DECOMP&FFT – A highly scalable 2D decomposition library and FFT interface", Cray User Group 2010 conference, Edinburgh, 2010
 
 **a new paper is in preparation to introduce the new capabilities of the library**
 
 **Acknowledgements**
 ====================
-The library was initially designed thanks to several projects funded under the HECToR Distributed Computational Science and Engineering (CSE) Service operated by NAG Ltd. The new library has been designed thanks to the support of EPSRC via the `CCP Turbulence <https://www.ukturbulence.co.uk/ccp-turbulence.html>`_ (EP/T026170/1).
+The library was initially designed thanks to several projects funded under the 
+HECToR Distributed Computational Science and Engineering (CSE) Service operated by NAG Ltd. 
+The new library has been designed thanks to the support of EPSRC via the 
+`CCP Turbulence <https://www.ukturbulence.co.uk/ccp-turbulence.html>`_ (EP/T026170/1).
 
 .. toctree::
    :maxdepth: 2

docs/source/pages/api_domain.rst

@@ -2,7 +2,8 @@
 2D Pencil Decomposition API
 ===========================
 
-This page explains the key public interfaces of the 2D decomposition library. After reading this section, users should be able to easily build applications using this domain decomposition strategy. The library interface is designed to be very simple. One can refer to the sample applications for a quick start.
+This page explains the key public interfaces of the 2D decomposition library. After reading this section, users should be able to easily build applications using this domain decomposition strategy. 
+The library interface is designed to be very simple. One can refer to the sample applications for a quick start.
 
 The 2D Pencil Decomposition API is defined in three Fortran module which should be used by applications as:
 
@@ -15,7 +16,8 @@ The 2D Pencil Decomposition API is defined in three Fortran module which should
 The ``use decomp_2d_constants`` defines all the parameters, ``use decomp_2d_mpi`` introduces all the MPI
 related interfaces and ``use decomp_2d`` cointains the main decomposition and transposition APIs. 
 
-**Module decomp_2d_constant: Global Variables**
+Module **decomp_2d_constant**: Global Variables
+_______________________________________________
 
 The ``decomp_2d_constants`` cointains global parameters that used to define the KIND of floating 
 point data (e.g. single or double precision). 
@@ -46,7 +48,8 @@ The module contains additional parameters to control :
 
 * define the release major and minor version
 
-**Module decomp_2d_mpi: MPI communication**
+Module **decomp_2d_mpi**: MPI communication
+___________________________________________
 
 The ``decomp_2d_mpi`` cointains global parameters that are used for MPI operation:  
 
@@ -60,9 +63,10 @@ The ``decomp_2d_mpi`` cointains global parameters that are used for MPI operatio
 
 * ``decomp_2d_warning`` - interface to display error message together with line number and function.
 
-**Module decomp_2d: decompostion module**
+Module **decomp_2d**: decompostion module
+_________________________________________
 
-The ``decomp_2d`` cointains the variables and the routines to perform the global transpostion operations. 
+The ``decomp_2d`` module cointains the variables and the routines to perform the global transpostion operations. 
 The important variables are
 
 * ``nx_global, ny_global, nz_global`` - size of the global data.
@@ -129,7 +133,8 @@ The allocation for a x pencil decomposition would be equivalent to the statement
 
 Allocated arrays can be simply released with an ``deallocate(var)`` statement. 
 
-**Basic 2D Decomposition API**
+Basic 2D Decomposition API
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 All the global variables described above, the defualt common type ``decomp`` and the MPI initialization is done 
 using the following call
@@ -193,7 +198,8 @@ Finally, before exit, applications should clean up the memory by:
 
   call decomp_2d_finalize
 
-**Advanced 2D Decomposition API**
+Advanced 2D Decomposition API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While the basic decomposition API is very user-friendly, there may be situations in which 
 applications need to handle more complex data structures. There are quite a few examples:
@@ -211,7 +217,7 @@ applications need to handle more complex data structures. There are quite a few
 
 In all these examples, there are multiple global sizes and applications need to be able to distributed 
 different data sets as 2D pencils. 
-``2decomp&FFT`` provides a powerful and flexible programming interface to handle this:
+2DECOMP&FFT provides a powerful and flexible programming interface to handle this:
 
 :: 
 

docs/source/pages/api_fft.rst

@@ -8,6 +8,9 @@ To use the FFT programming interface, first of all, one additional Fortran modul
 
   use decomp_2d_fft
 
+Initialisation of the FFT module
+________________________________
+
 The FFT interface is built on top of the 2D decomposition library, which, naturally, 
 needs to be initialised first:
 
@@ -55,7 +58,8 @@ The result of the ``decomp_2d_fft_init`` operation is to create two new objects
 
    * ``PHYSICAL_IN_Z`` - :math:`nx\times ny\times nz/2+1` (default) or :math:`n1\times n2\times n3/2+1` (customized)
 
-**Complex-to-complex Transforms**
+Complex-to-complex Transforms
+_____________________________
 
 The library supports three-dimensional FFTs whose data is distributed as 2D pencils and stored in ordinary ijk-ordered 3D arrays across processors. 
 For complex-to-complex (c2c) FFTs, the user interface is:
@@ -70,7 +74,8 @@ The input array ``input`` and ``output`` array out are both complex and
 and have to be either a X-pencil/Z-pencil combination or vice versa, depending on the direction of FFT and 
 how the FFT interface is initialised (``PHYSICAL_IN_X``, the default, or ``PHYSICAL_IN_Z`` the optional).
 
-**Real-to-complex & Complex-to-Real Transforms**
+Real-to-complex & Complex-to-Real Transforms
+____________________________________________
 
 The interface for the the real-to-complex and complex-to-real transform is 
 
@@ -102,10 +107,11 @@ Please note that the complex output arrays obtained from X-pencil and Z-pencil i
 However, if *Hermitian redundancy* is taken into account, no physical information is lost and the real input can be fully recovered 
 through the corresponding inverse FFT from either complex array.
 
-Please also note that ``2decomp&FFT`` does not scale the transforms. So a forward transform followed by a backward transform 
+Please also note that 2DECOMP&FFT does not scale the transforms. So a forward transform followed by a backward transform 
 will not recover the input unless applications normalise the result by the size of the transforms.
 
-**Finalisation**
+Deallocation of the FFT module
+______________________________
 
 Finally, to release the memory used by the FFT interface: