Merge pull request #757 from sourceryinstitute/reorganize

Reorganize & rename subdirectories, remove dead code, and document archival code

Author: rouson

CMakeLists.txt

@@ -28,10 +28,6 @@ if($ENV{OPENCOARRAYS_DEVELOPER})
 endif()
 option(CAF_RUN_DEVELOPER_TESTS "Run tests intended only for developers" ${_TF})
 mark_as_advanced(CAF_RUN_DEVELOPER_TESTS)
-option( CAF_ENABLE_ISO_Fortran_BINDING
-  "Build and install F2018 C interop iso_fortran_binding.h header; experimental!"
-  ${_TF} )
-
 
 # Name project and specify source languages
 # Parse version from .VERSION file so that more info can be added and easier to get from scripts
@@ -701,7 +697,7 @@ add_custom_target( hash_installed
 #---------------------------------------------------------------------------------------
 # Define macro for adding CAF tests, and ensuring proper flags are passed to MPI runtime
 #---------------------------------------------------------------------------------------
-# Test for OpenMPI moved to src/mpi/CMakeLists.txt and passed back up through set(... PARENT_SCOPE)
+# Test for OpenMPI moved to src/runtime-libraries/mpi/CMakeLists.txt and passed back up through set(... PARENT_SCOPE)
 function(add_caf_test name num_caf_img test_target)
   # Function to add MPI tests.
   if(TARGET ${test_target})
@@ -973,16 +969,6 @@ add_installation_script_test(installation-scripts.sh src/tests/installation/)
 if( CAF_ENABLE_FAILED_IMAGES AND ( NOT
       (	"${CMAKE_C_COMPILER_ID}" STREQUAL "GNU" ) AND ( "${CMAKE_SYSTEM_PROCESSOR}" STREQUAL "x86_64" ) )
     )
-  message ( WARNING
-    "ISO_Fortran_BINDING has only been tested with recent GCC C compilers on x86_64 architectures!
-     Some people have reported problems on other architectures or using other C compilers (Clang).
-     There are likely bugs present; use at your own risk!")
-endif()
-
-# Test ISO_Fortran_binding library
-if( CAF_ENABLE_ISO_Fortran_BINDING OR ( CAF_RUN_DEVELOPER_TESTS OR $ENV{OPENCOARRAYS_DEVELOPER} ) )
-  # See https://github.com/sourceryinstitute/OpenCoarrays/issues/523#issuecomment-401613209
-  add_test(NAME ISO_Fortran_binding_tests COMMAND "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/ISO_Fortran_binding_tests")
 endif()
 
 # Lint the Travis-CI scripts

README.md

@@ -5,7 +5,7 @@
 [https://github.com/sourceryinstitute/OpenCoarrays/blob/master/README.md]:#
 <div align="center">
 
-[![Sourcery Institute][sourcery-institute logo]][Sourcery, Inc.]
+[![Sourcery Institute][sourcery-institute logo]][Sourcery Institute]
 
 OpenCoarrays
 ============
@@ -30,25 +30,22 @@ OpenCoarrays
 Overview
 --------
 
-[OpenCoarrays] supports [Fortran 2018] compilers by providing a
-parallel application binary interface (ABI) that abstracts away the
-underlying parallel programming model, which can be the Message
-Passing Interface ([MPI]) or [OpenSHMEM].  Parallel Fortran 2018
-programs may be written and compiled into object files once and
-then linked or re-linked to either MPI or [OpenSHMEM] without modifying
-or recompiling the Fortran source.  Not a single line of source code
-need change to switch parallel programming models.  The default
-programming model is MPI because it provides the broadest capability
-for supporting Fortran 2018  features.  However, having the option to
-change parallel programming models at link-time may enhance portability
-and performance (see [Rouson et al. (2017)]).
-
-OpenCoarrays provides a compiler wrapper (`caf`), parallel runtime
-libraries (`libcaf_mpi` and `libcaf_openshmem`), and a parallel
-executable file launcher (`cafrun`).  The wrapper and launcher
-provide a uniform abstraction for compiling and executing parallel
-Fortran 2018 programs without direct reference to the underlying
-parallel programming model.
+[OpenCoarrays] supports the GNU Compiler Collection ([GCC]) Fortran compiler
+([`gfortran`]) by providing a parallel application binary interface (ABI) that
+abstracts away the underlying communication library.  OpenCoarrays thus enables
+`gfortran` to support Fortran's parallel programming features, often called
+"Coarray Fortran," without making direct reference to the back-end communication
+library: the Message Passing Interface (MPI).  This ensures that Fortran
+programs and Fortran compilers may take advantage of other communication
+libraries without costly refactoring.  Work is underway on the [Caffeine]
+project to support alternative communication libraries and alternative compilers
+by defining a compiler-independent parallel ABI atop the [GASNet-EX] exascale
+networking middleware.
+
+OpenCoarrays provides a compiler wrapper (`caf`), a parallel runtime library
+(`libcaf_mpi`), and a program launcher (`cafrun`).  The wrapper and launcher
+provide a uniform abstraction for compiling and executing Coarray Fortran
+without direct reference to the underlying MPI layer.
 
 Downloads
 ---------
@@ -58,22 +55,20 @@ Please see our [Releases] page.
 Compatibility
 -------------
 
-The GNU Compiler Collection ([GCC]) Fortran front end ([gfortran]) has
-used OpenCoarrays since the GCC 5.1.0 release .  Discussions are under
-way around incorporating OpenCoarrays into other compilers.
+The OpenCoarrays ABI was adopted by `gfortran` in release the GCC 5.1.0 release
+and `gfortran` continues to work with OpenCoarrays as of this writing.  
 
 Prerequisites
 -------------
 
 Building OpenCoarrays requires
 
-* An MPI implementation (default: [MPICH]).
-* CMake.
-* A Fortran compiler (default: [GCC]).
-* _Optional_: An [OpenSHMEM] implementation.
+* An MPI implementation,
+* CMake, and
+* The GCC C and Fortran compilers: `gcc` and `gfortran`.
 
-If you use a package manager or the OpenCoarrays installer, any
-missing prerequisites will be built for you.
+If you use a package manager or the OpenCoarrays installer, any missing
+prerequisites will be built for you.
 
 
 Installation
@@ -124,6 +119,12 @@ Acknowledgments
 
 We gratefully acknowledge support from the following institutions:
 
+* The U.S. Nuclear Regulatory Commission ([NRC]) for funding the work that led to support for
+  - the Windows operating system, 
+  - the `random_init` subroutine, and 
+  - `co_broadcast` of derived-type objects with `allocatable` components.
+* The National Aeronautics and Space Administration [NASA] for funding the work that led to
+  support for the `co_broadcast` of derived-type objects.
 * [Arm] for approving compiler engineer contributions of code.
 * [National Center for Atmospheric Research] for access to the
   Yellowstone/Caldera supercomputers and for logistics support during
@@ -137,7 +138,7 @@ We gratefully acknowledge support from the following institutions:
   of Energy under Contract No. DE-AC02-05CH11231, for access to the
   Hopper and Edison supercomputers under the OpenCoarrays project
   start allocation.
-* [Sourcery, Inc.], for financial support for the domain registration,
+* [Archaeologic Inc.] for financial support for the domain registration,
   web hosting, advanced development, and conference travel.
 
 Donate
@@ -169,7 +170,6 @@ to aid in development efforts.
 [Contributing]: #contributing
 [Acknowledgments]: #acknowledgments
 
-[Fortran 2018]: https://j3-fortran.org/doc/year/18/18-007r1.pdf 
 [Arm]: https://www.arm.com
 
 [OpenSHMEM]: http://www.openshmem.org/site/
@@ -178,9 +178,9 @@ to aid in development efforts.
 [ABI]: https://gcc.gnu.org/onlinedocs/gfortran/Coarray-Programming.html#Coarray-Programming
 [MPI]: https://www.mpi-forum.org/
 [GCC]: https://gcc.gnu.org
-[gfortran]: https://gcc.gnu.org/wiki/GFortran
+[`gfortran`]: https://gcc.gnu.org/wiki/GFortran
 [MPICH]: https://www.mpich.org
-[Sourcery, Inc.]: http://www.sourceryinstitute.org
+[Sourcery Institute]: http://www.sourceryinstitute.org
 [Google]: https://www.google.com
 [CINECA]: https://www.cineca.it/en
 [NERSC]: https://www.nersc.gov
@@ -210,7 +210,10 @@ to aid in development efforts.
 [release img]: https://img.shields.io/github/release/sourceryinstitute/OpenCoarrays.svg?style=flat-square "Latest release badge"
 [pdf img]: https://img.shields.io/badge/PDF-README.md-6C2DC7.svg?style=flat-square "Download this readme as a PDF"
 [twitter img]: https://img.shields.io/twitter/url/http/shields.io.svg?style=social
-[Writing Fortran 2018 Today]: https://www.eventbrite.com/e/writing-fortran-2018-today-object-oriented-parallel-programming-tickets-48982176007
-[Rouson et al. (2017)]: http://www.opencoarrays.org/uploads/6/9/7/4/69747895/a4-rouson.pdf
+[NRC]: https://www.nrc.gov
+[NASA]: https://www.nasa.gov
+[Caffeine]: https://go.lbl.gov/caffeine
+[Archaeologic Inc.]: https://www.archaeologic.codes
+[GASNet-EX]: https://go.lbl.gov/gasnet
 
 [default tweet]: https://twitter.com/intent/tweet?hashtags=HPC,Fortran,PGAS&related=zbeekman,gnutools,HPCwire,HPC_Guru,hpcprogrammer,SciNetHPC,DegenerateConic,jeffdotscience,travisci&text=Stop%20programming%20w%2F%20the%20%23MPI%20docs%20in%20your%20lap%2C%20try%20Coarray%20Fortran%20w%2F%20OpenCoarrays%20%26%20GFortran!&url=https%3A//github.com/sourceryinstitute/OpenCoarrays

install.sh

@@ -81,7 +81,7 @@
 
 ### Start of boilerplate -- do not edit this block #######################
 export OPENCOARRAYS_SRC_DIR="${OPENCOARRAYS_SRC_DIR:-${PWD%/}}"
-if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/libcaf.h" ]]; then
+if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/runtime-libraries/mpi/mpi_caf.c" ]]; then
   echo "Please run this script inside the top-level OpenCoarrays source directory or "
   echo "set OPENCOARRAYS_SRC_DIR to the OpenCoarrays source directory path."
   exit 1
@@ -332,6 +332,7 @@ elif [[ "${arg_p:-}" == "opencoarrays" ]]; then
     fi
   fi
 
+
 elif [[ "${arg_p:-}" == "ofp" ]]; then
 
   # Install Xcode command line tools (CLT) if on macOS and if needed

prerequisites/build.sh

@@ -32,7 +32,7 @@
 
 export OPENCOARRAYS_SRC_DIR="${OPENCOARRAYS_SRC_DIR:-${PWD%prerequisites*}}"
 export __usage=${OPENCOARRAYS_SRC_DIR}/prerequisites/build.sh-usage
-if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/libcaf.h" ]]; then
+if [[ ! -f "${OPENCOARRAYS_SRC_DIR}/src/runtime-libraries/mpi/mpi_caf.c" ]]; then
   echo "Please run this script inside the OpenCoarrays source \"prerequisites\" subdirectory"
   echo "or set OPENCOARRAYS_SRC_DIR to the top-level OpenCoarrays source directory path."
   exit 1

src/CMakeLists.txt

@@ -1,18 +1,10 @@
-set(directories_to_build mpi tests)
-if( CAF_ENABLE_ISO_Fortran_BINDING OR ( CAF_RUN_DEVELOPER_TESTS OR $ENV{OPENCOARRAYS_DEVELOPER} ) )
-  list( APPEND directories_to_build iso-fortran-binding )
-endif()
-foreach(directory ${directories_to_build})
-  add_subdirectory(${directory})
-endforeach()
+add_subdirectory(application-binary-interface )
+add_subdirectory(runtime-libraries )
+add_subdirectory(tests)
 
 set(N_CPU ${N_CPU} PARENT_SCOPE)
 set(HOST_NAME ${HOST_NAME} PARENT_SCOPE)
 
 if(openmpi)
   set(openmpi ${openmpi} PARENT_SCOPE)
 endif()
-
-install( FILES libcaf.h libcaf-gfortran-descriptor.h libcaf-version-def.h
-  DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
-)

src/Makefile

@@ -0,0 +1,25 @@
+OpenCoarrays Runtime Libraries
+==============================
+
+One original goal of the OpenCoarrays project was to provide a transparent application binary interface (ABI) supported by interchangeable parallel runtime libraries based on a range of communication libraries.  The following header files in this directory define that ABI:
+
+* libcaf.h
+* libcaf-gfortran-descriptor.h
+* libcaf-version-def.h: 
+
+where the above files are in dependency order: each file depends on the file(s) listed below it.  The [runtime-libraries](./runtime-libraries) subdirectory contains runtimes based on the following communication libraries:
+
+* Message Passing Interface (MPI)
+* OpenSHMEM
+* GASNet
+
+We currently maintain, build, and test only the MPI runtime.  The GASNet and OpenSHMEM runtime library source code serve only to provide detailed, open-source documentation of the research described by [Fanfarillo et al. (2014)] and [Rouson et al. (2017)].  For a Fortran 2018 parallel runtime library based on the more recent GASNet-EX exascale networking middleware described by [Bonachea and Hargrove (2018)], please see the [Caffeine] repository.
+
+One exception regarding the transparent nature of the ABI is the [opencoarrays module], which provides a public function that returns the underlying MPI communicator. This capability can be useful for using coarray Fortran to drive an ensemble of simulations using pre-existing MPI as described in [Rouson, McCreight, and Fanfarillo (2017)].
+
+[Fanfarillo et al. (2014)]: http://dx.doi.org/10.1145/2676870.2676876
+[Rouson et al. (2017)]: https://doi.org/10.1145/3144779.3169104
+[Bonachea and Hargrove (2018)]: https://doi.org/10.25344/S4QP4W
+[Caffeine]: https://go.lbl.gov/caffeine
+[opencoarrays module]: ./runtime-libraries/mpi/opencoarrays.F90
+[Rouson, McCreight, and Fanfarillo (2017)]: https://doi.org/10.1145/3144779.3169110

src/README.md

@@ -0,0 +1,3 @@
+install( FILES libcaf.h libcaf-gfortran-descriptor.h libcaf-version-def.h
+  DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+)

src/application-binary-interface/CMakeLists.txt

@@ -30,8 +30,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  */
 
 #include "libcaf-version-def.h"
 
-/* GNU Fortran's array descriptor.  Keep in sync with libgfortran.h.  To be
-   replaced by TS29113's ISO_Fortran_binding.h with CFI_cdesc_t.  */
+/* GNU Fortran's array descriptor.  Keep in sync with libgfortran.h.  */
 
 enum
 { BT_UNKNOWN = 0, BT_INTEGER, BT_LOGICAL, BT_REAL, BT_COMPLEX,