From 043b44cf2b0187222d94a88529af8a4f9f8eeead Mon Sep 17 00:00:00 2001 From: Joe Kaushal Date: Mon, 29 Nov 2021 11:11:35 +0000 Subject: [PATCH] Remove unneeded READMEs and convert remaining to Markdown --- apps/c/README | 33 ---------------- apps/c/airfoil/README.md | 32 ++++++---------- doc/{README => README.md} | 24 ++++++------ op2/README | 64 ------------------------------- op2/include/{README => README.md} | 27 +++++++------ scripts/README.md | 11 ++---- translator/c/README.md | 37 ++++++++---------- translator/fortran/README.md | 62 +++++++++++++++--------------- 8 files changed, 89 insertions(+), 201 deletions(-) delete mode 100644 apps/c/README rename doc/{README => README.md} (55%) delete mode 100644 op2/README rename op2/include/{README => README.md} (81%) diff --git a/apps/c/README b/apps/c/README deleted file mode 100644 index 525354f61..000000000 --- a/apps/c/README +++ /dev/null @@ -1,33 +0,0 @@ -This directory contains example applications using the C and C++ OP2 library. - -Building -====================== - -The recommended way of building the examples is using the regular Makefiles under -each aexample pplication directory. - -To compile using the regular Makefiles provided, it is required to: - -1. Make sure that the OP2 backend libraries have been built under - ~/OP2-Common/op2/c/lib - - See ~/OP2-Common/op2/c/README for instructions on building the op2 - backend libs - -2. Use op2 code generator to generate the various paralleizations - - e.g for Airfoil_HDF5 the only file(s) that have OP2 API calls are airfoil.cpp - - ~/OP2-Common/translator/c/python/op2.py airfoil.cpp - - This will generate the variousl paralleizations under seperate directories - E.g. CUDA files under ~/OP2-Common/apps/c/airfoil/airfoil_hdf5/dp/CUDA etc. - (see user documentation for more details) - - -3. Change directory to the example application directory - e.g. cd ~/OP2-Common/apps/c/airfoil/airfoil_hdf5/dp/ - - type: - - make diff --git a/apps/c/airfoil/README.md b/apps/c/airfoil/README.md index 4dfaa3520..f2c876c76 100644 --- a/apps/c/airfoil/README.md +++ b/apps/c/airfoil/README.md @@ -1,5 +1,4 @@ ### Airfoil - Airfoil is a nonlinear 2D inviscid airfoil code that uses an unstructured grid. It is a finite volume application that solves the 2D Euler equations using a scalar numerical dissipation. The algorithm iterates towards the steady state solution, in each iteration using a control volume approach – for example the rate at which the mass changes within a @@ -14,34 +13,27 @@ indirect loops. Please see airfoil-doc under the ../../doc directory for further OP2 application development details -### Airfoil Application Directory Structure - +#### Airfoil Application Directory Structure Airfoil has been the main development, testing and benchmarking application in OP2. As such this directory contains several versions of Airfoil that demonstrate the use of various OP2 features. -airfoil_plain -- airfoil implemented with user I/O routines (mesh file in ASCI - see ../../apps/mesh_generators -on how to generate the mesh) - -airfoil_hdf5 -- airfoil implemented with OP2 HDF5 routines (mesh file in HDF5, see ASCI to HDF5 file converter) - -airfoil_vector -- airfoil user kernels modified to achieve vectorization - -airfoil_tempdats -- airfoil use op_decl_temp, i.e. temporary dats in application + * `airfoil_plain`: Airfoil implemented with user I/O routines (mesh file in ASCI - see ../../apps/mesh_generators +on how to generate the mesh). + * `airfoil_hdf5`: Airfoil implemented with OP2 HDF5 routines (mesh file in HDF5, see ASCI to HDF5 file converter). + * `airfoil_vector`: Airfoil user kernels modified to achieve vectorization. + * `airfoil_tempdats`: Airfoil use op_decl_temp, i.e. temporary dats in application. + * `compare_results`: Small utility code to compare two files (txt or bin), used to compare the final result from airfoil. -compare_results -- small utility code to compare two files (txt or bin), used to compare the final result from airfoil - -### Running the Application and Testing the Results - -The input meshes for the application can be generated by using the mesh generators located in : +#### Running the Application and Testing the Results +The input meshes for the application can be generated by using the mesh generators located in: ``` OP2-Common/apps/mesh_generators ``` -The HDF5 versions of the mesh could be generated by using the convert_mesh application at : +The HDF5 versions of the mesh could be generated by using the convert_mesh application at: ``` airfoil/airfoil_hdf5/dp/convert_mesh.cpp ``` - The various parallel versions of Airfoil should be compared against the single-threaded CPU version (also known as the reference implementation) to ascertain the correctness of the results. The p_q array holds the final result and as such will be the data array to compare. One way to achieve this is to use the following OP2 calls to write the data array to @@ -52,14 +44,12 @@ op_print_dat_to_txtfile(p_q, "out_grid_seq.dat"); //ASCI op_print_dat_to_binfile(p_q, "out_grid_seq.bin"); //Binary ``` -Then the code in compare.cpp and comparebin.cpp can be used to compare the text file or binary file with the reference -implementation. +Then the code in `compare.cpp` and `comparebin.cpp` can be used to compare the text file or binary file with the reference implementation. Bitwise accuracy can be expected across systems for the double precision version to within the accuracy of machine precision. For the single precision version, answers should be very close. A summary print of the rms value of the residual is printed out by default every 100 iterations. This in double precision for the first 1000 iterations should be exactly: - ``` 100 5.02186e-04 200 3.41746e-04 diff --git a/doc/README b/doc/README.md similarity index 55% rename from doc/README rename to doc/README.md index 1afa1f508..af0c2c1d7 100644 --- a/doc/README +++ b/doc/README.md @@ -1,19 +1,21 @@ +### Documentation To build documentation make sure that the following packages are installed - -texlive-science +``` +texlive-science texlive-latex-extra python-pygments latex-xcolor +``` -Usually the following will install these : - -sudo apt-get install texlive-science texlive-latex-extra latex-xcolor +Usually the following will install these: +``` +sudo apt-get install texlive-science texlive-latex-extra latex-xcolor sudo apt-get install python-pygments (or alternatively run: sudo easy_install Pygments) +``` -Then run the shell script build.sh - -./script build.sh +Then run the shell script `build_docs.sh`: +``` +./build_docs.sh +``` -This will build the C/C++ user documentation, OP2 developer documentation, -OP2 MPI (distributed memory) developer documentation and airfoil -application developer guide. +This will build the C/C++ user documentation, OP2 developer documentation, OP2 MPI (distributed memory) developer documentation and airfoil application developer guide. diff --git a/op2/README b/op2/README deleted file mode 100644 index a3c03b625..000000000 --- a/op2/README +++ /dev/null @@ -1,64 +0,0 @@ -This directory provides an implementation of the C and C++ OP2 interface. - -Third party -============= - - * Parallel build of HDF5 - * PT-Scotch version 6.0 (or greater) or ParMetis version (3.0 or greater) for distributed memory partitioning - * NVIDIA CUDA for GPU build - * MPI - -Building -====================== - -The recommended way of building OP2 is by using the regular Makefile build. -To compile using the regular Makefiles provided, it is required to: - -1. Set the environment variable CUDA_INSTALL_PATH to the appropriate path. - For instance, on under bash, if we want to use cuda, - we will have to set it as following: - - export CUDA_INSTALL_PATH=/usr/local/cuda/ - -2. Set the environment variable OP2_COMPILER to either 'intel', 'pgi', - 'gnu' or 'cray' to select building with either icc or gcc compilers. - Other compilers can also be supported by adding the relevant compilers - commands and flags. - -3. Set the environment variables MPI_INSTALL_PATH, PARMETIS_INSTALL_PATH and / - or PTSCOTCH_INSTALL_PATH, HDF5_INSTALL_PATH to the installation - directories of these libraries. - (Example source files for various compilers that set the above environment - variables can be found under ~/OP2/scripts directory) - - For instance: - - export PARMETIS_INSTALL_PATH=/opt/ParMetis-intel-3.1.1 - - and / or - - export PTSCOTCH_INSTALL_PATH=/opt/PT_Scotch-6.0-intel - - export MPI_INSTALL_PATH=/opt/compilers/intel/impi_latest/intel64/ - - export HDF5_INSTALL_PATH=/opt/hdf5-1.8.19-intel/ - -4. Set the LD_LIBRARY_PATHS as required for external libraries - - For example: - - export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH - export LD_LIBRARY_PATH=/opt/parmetis-intel/lib:/opt/ptscotch-intel/lib:/$LD_LIBRARY_PATH - export LD_LIBRARY_PATH=/home/mudalige/hdf5-1.8.19-intel/lib:$LD_LIBRARY_PATH - -5. Set environment variable OP2_INSTALL_PATH to the base op2 directory, - i.e. the one containing the "c" and "fortran" directories. - - e.g.: export OP2_INSTALL_PATH=~/OP2-Common/op2/ - - -6. Finally type : - - make - - Then the op2 libraries will be built under ~/OP2-Common/op2/c/lib diff --git a/op2/include/README b/op2/include/README.md similarity index 81% rename from op2/include/README rename to op2/include/README.md index c9087cacd..ad205de04 100644 --- a/op2/include/README +++ b/op2/include/README.md @@ -1,33 +1,38 @@ +### Headers -Core components ---------------- +#### Core components +``` op_lib_c.h (includes: op_lib_core.h) op_lib_core.h op_lib_cpp.h (includes: op_lib_core.h, op_lib_c.h) op_rt_support.h (includes: op_lib_core.h) +``` -Sequential layer ----------------- +#### Sequential layer +``` op_seq.h (auto-generated, includes: op_lib_core.h) +``` - -OpenMP layer ------------- +#### OpenMP layer +``` op_openmp_rt_support.h (includes: op_rt_support.h) +``` -CUDA layer ----------- +#### CUDA layer +``` op_cuda_rt_support.h (includes: op_lib_core.h, op_rt_support.h) op_cuda_reduction.h (has to be kept separate becuase of FORTRAN layer) +``` -MPI support ------------ +#### MPI support +``` op_hdf5.h (obsolete?) op_lib_mpi.h (include op_lib_core.h, op_rt_support.h, op_mpi_core.h, op_hdf5.h) op_mpi_core.h op_mpi_hdf5.h op_mpi_seq.h (includes: op_lib_core.h, op_rt_support.h) op_util.h +``` diff --git a/scripts/README.md b/scripts/README.md index 9a0cd4a2a..6c658fcba 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,13 +1,8 @@ ### Scripts - -This directory contains various scripts used for testing the build and correct -execution of OP2 and its example applications. These are provided and commited -to the repository simply as a referance to any one who is installing and using OP2. +This directory contains various scripts used for testing the build and correct execution of OP2 and its example applications. These are provided and commited to the repository simply as a referance to any one who is installing and using OP2. #### Files - -source_intel, source_pgi -- example files that can be sourced to set the required variables to compile and install with + * `source_intel`, `source_pgi`, ...: example files that can be sourced to set the required variables to compile and install with Intel and PGI compilers respectively. - -test_makefiles.sh -- builds and tests OP2 lib and apps with plain Makefiles (including Fortran libs and apps) + * `test_makefiles.sh` -- builds and tests OP2 lib and apps with plain Makefiles (including Fortran libs and apps) diff --git a/translator/c/README.md b/translator/c/README.md index 89fa99a32..e2ce213fb 100644 --- a/translator/c/README.md +++ b/translator/c/README.md @@ -1,31 +1,26 @@ -###OP2 Code Generators - +### C/C++ Code Generators This directory contains the OP2 code generators written in python targetting the C/C++ API. The parallelisations and optimisations supported by each generator are as follows: - -* op2_gen_seq.py -* op2_gen_openmp.py - Initial OpenMP code generator -* op2_gen_openmp_simple.py - Simplified and Optimized OpenMP code generator -* op2_gen_cuda.py - Optimized for Fermi GPUs -* op2_gen_cuda_simple - Optimized for Kepler GPUs -* op2_gen_cuda_simple_hyb.py - generates openmp code as well as cuda code into the same file. Both CPUs and GPUs will then be used to do computations as a hybrid application. - - -###Invoking the Code Generator - -Uncomment the parallelization you want to code generate in ops.py. For example for CUDA code generation do: - + * `op2_gen_seq.py` + * `op2_gen_openmp.py`: Initial OpenMP code generator. + * `op2_gen_openmp_simple.py`: Simplified and Optimized OpenMP code generator. + * `op2_gen_cuda.py`: Optimized for Fermi GPUs. + * `op2_gen_cuda_simple`: Optimized for Kepler GPUs. + * `op2_gen_cuda_simple_hyb.py`: Generates OpenMP code as well as CUDA code into the same file. Both CPUs and GPUs will then be used to do computations as a hybrid application. + +#### Invoking the Code Generator +Uncomment the parallelization you want to code generate in `op2.py`. For example for CUDA code generation do: ``` #op2_gen_seq(str(sys.argv[1]), date, consts, kernels) #op2_gen_openmp(str(sys.argv[1]), date, consts, kernels) # Initial OpenMP code generator op2_gen_cuda(str(sys.argv[1]), date, consts, kernels,sets) # Optimized for Fermi GPUs ``` -Make ./op2.py executable - -`chmod a+x ./op2.py` +Make `op2.py` executable +``` +chmod a+x ./op2.py +``` Invoke the code generator by supplying the files that contain op_* API calls. Thus for example for Airfoil do the following. - ``` -./ops.py airfoil.cpp -``` \ No newline at end of file +./op2.py airfoil.cpp +``` diff --git a/translator/fortran/README.md b/translator/fortran/README.md index d8336e1bc..3b6bc484c 100644 --- a/translator/fortran/README.md +++ b/translator/fortran/README.md @@ -1,40 +1,38 @@ -###OP2 Code Generators - -This directory contains the OP2 code generators written in python targetting the FORTRAN API. The parallelisations and optimisations supported by each generator are as follows: - -######MPI+SEQ -* op2_gen_mpiseq.py - generate host stubs for MPI+SEQ -* op2_gen_mpiseq3.py - generate host stubs for MPI+SEQ -- optimised by removing the overhead due to fortran c to f pointer setups -op2_gen_mpivec.py - generate host stubs for MPI+SEQ with intel vectorization optimisations - -######OpenMP -* op2_gen_openmp3.py - optimised by removing the overhead due to fortran c to f pointer setups -* op2_gen_openmp2.py - version without staging -* op2_gen_openmp.py - original version - one that most op2 papers refer to - -######CUDA -* op2_gen_cuda.py -* op2_gen_cuda_permute.py - permute does a different coloring (permute execution within blocks by color) -* op2_gen_cudaINC.py - stages increment data only in shared memory -* op2_gen_cuda_old.py - Code generator targettign Fermi GPUs - -######If hydra: -* op2_gen_cuda_hydra() - includes several Hydra specific features - -###Invoking the Code Generator - -Uncomment the parallelization you want to code generate in op2_fortran.py. For example for CUDA code generation do: - +### Fortran Code Generators +This directory contains the OP2 code generators written in Python targeting the Fortran API. The parallelisations and optimisations supported by each generator are as follows: + +##### MPI+SEQ + * `op2_gen_mpiseq.py`: Generate host stubs for MPI+SEQ. + * `op2_gen_mpiseq3.py`: Generate host stubs for MPI+SEQ -- optimised by removing the overhead due to Fortran C to F pointer setups. + * `op2_gen_mpivec.py`: Generate host stubs for MPI+SEQ with intel vectorization optimisations. + +##### OpenMP + * `op2_gen_openmp3.py`: Optimised by removing the overhead due to Fortran C to F pointer setups. + * `op2_gen_openmp2.py`: Version without staging. + * `op2_gen_openmp.py`: Original version - one that most OP2 papers refer to. + +##### CUDA + * `op2_gen_cuda.py` + * `op2_gen_cuda_permute.py`: Permute does a different coloring (permute execution within blocks by color). + * `op2_gen_cudaINC.py`: Stages increment data only in shared memory. + * `op2_gen_cuda_old.py`: Code generator targettign Fermi GPUs. + +##### If hydra: + * `op2_gen_cuda_hydra()`: Includes several Hydra specific features. + +#### Invoking the Code Generator +Uncomment the parallelization you want to code generate in `op2_fortran.py`. For example for CUDA code generation do: ``` #op2_gen_openmp(str(sys.argv[init_ctr]), date, consts, kernels, hydra) op2_gen_cuda(str(sys.argv[1]), date, consts, kernels, hydra) ``` -Make ./op2_fortran.py executable - -`chmod a+x ./op2_fortran.py` +Make `./op2_fortran.py` executable +``` +chmod a+x ./op2_fortran.py +``` Invoke the code generator by supplying the files that contain op_* API calls. Thus for example for Airfoil do the following. - ``` -./op2_fortran.py airfoil.F90 \ No newline at end of file +./op2_fortran.py airfoil.F90 +```