Import sample application doc

Author: ningli

doc/samples.md

@@ -0,0 +1,15 @@
+## Sample Applications
+
+A list of sample applications are distributed with 2DECOMP&FFT package to validate the library and to demonstrate the proper use of it.
+
+- **test2d** - This application is to test the base 2D pencil decomposition module. It arranges to transpose data among the three pencil orientations and validate the result against a copy of the global data held on each process. It also demonstrates the use of the parallel I/O library - regardless of how the global data is distributed (X-pencil, Y-pencil or Z-pencil), when processes write to files collectively using the I/O library the resulting files should be identical.
+- **fft_test_c2c** - This is a simple application to validate the complex-to-complex FFT programming interface. Its input is taken from the example program of NAG library routine C06FXF (also for c2c FFTs). Its output should match the C06FXF output exactly.
+- **fft_test_r2c** - This is to test the FFT library's real-to-complex and complex-to-real interface. It generates some random input, computes a serial 3D r2c transform on rank 0 to generate reference data. It then computes two sets of transforms on distributed data, with the input distributed in X-pencil and Z-pencil, respectively. In both cases, a r2c transform is computed first and its result on rank 0 printed out (which should contain a subset of numbers found in the reference serial transform output). An inverse c2r transform is then followed to recover the input to machine accuracy (system dependent, but somewhere around 10<sup>-6</sup> for single precision and 10<sup>-15</sup> for double precision).
+- **timing** - This application can be used to benchmark the FFT library performance when porting it to a new system. It performs both c2c and r2c/c2r benchmarks, collects timing information and validates the results.
+- **halo_test** - This application demonstrate the use of the halo-cell support API. It calculates the divergence of a random field using an explicit 3-stencil finite different method. The parallel program relies on two different communication methods: (1) the global transposition routines; (2) the halo-cell support API. Both methods should return exactly the same results. Of course the halo-cell method is more efficient for such a stencil-based calculation.
+- **io_test** - A collection of sample applications testing the I/O APIs thoroughly.
+- **tecplot_view** - This application was used to generate the visualisation of the 2D decomposition, as frequently shown in the documentation. The output is in the format of Tecplot, a popular visualisation tool mainly used by the CFD community. Data from each process is written as a zone.
+- **p3dfft** - This application uses 2DECOMP&FFT and P3DFFT side-by-side to perform some FFTs. It was used to validate and benchmark 2DECOMP&FFT against its famous counterpart. P3DFFT has to be built separately in order to use this test.
+- **non_blocking** - This contains sample applications to compute multi-variable FFTs using the both the blocking and non-blocking versions of the communication library. This demonstrates how to use the non_blocking APIs to overlap communication and computation.
+
+Please consult the README files associated with these sample applications for more detail.