Merge pull request #595 from sourceryinstitute/update-docs

Update docs: README, INSTALL, GETTING_STARTED

Author: Damian Rouson

GETTING_STARTED.md

@@ -25,39 +25,17 @@ path. This is an experimental script with limited but useful capabilities that w
 grow over time.  Please submit bug reports and feature requests via our [Issues] page.
 
 The `caf` script liberates the source code and workflow from explicit dependence on the
-underlying compiler and communication library in the following ways:
-
-1. With an OpenCoarrays-aware (OCA) CAF compiler, the `caf` script passes the unmodified
-   source code to the underlying compiler with the necessary arguments for building a
-   CAF program, embedding the paths to OpenCoarrays libraries (e.g., `libcaf_mpi.a`) installed
-   in the `lib` subdirectory of the OpenCoarrays installation path.  The `caf` script also
-   embeds the path to the relevant module file in the `mod` subdirectory of the installation
-   path (e.g., `opencoarrays.mod`).  This supports use association with module entities via
-   `use opencoarrays`.
-2. With a non-CAF compiler (including gfortran 4.9), `caf` supports a subset of CAF by
-   replacing CAF statements with calls to procedures in the [opencoarrays module] before
-   passing the source code to the compiler.
-
-When using GCC 4.9, we recommend using the `use` statement's `only` clause to
-avoid inadvertent procedure name clashes between OpenCoarrays procedures and their
-GCC counterparts.  For example, use `use opencoarrays, only : co_reduce`.
-
-With a non-OCA and OCA CAF compilers, the extensions that `caf` imports include the collective
-subroutines proposed for Fortran 2015 in the draft Technical Specification [TS 18508]
-_Additional Parallel Features in Fortran_.
-
-The latter use case provides an opportunity to mix a compiler's CAF support with that of OpenCoarrays.
-For example, a non-OCA CAF compiler, such as the Cray or Intel compilers, might support all of a
-program's coarray square-bracket syntax, while OpenCoarrays supports the same program's calls to
-collective subroutine such as `co_sum` and `co_reduce`.
+underlying compiler and communication library by passing the unmodified source code to 
+the compiler with the necessary arguments for building a parallel Fortran 2018 program,
+embedding the paths to OpenCoarrays libraries (e.g., `libcaf_mpi.a`) installed
+in the `lib` subdirectory of the OpenCoarrays installation path.  
 
 A sample basic workflow
 -----------------------
 
 The following program listing, compilation, and execution workflow exemplify
-the use of an OCA compiler (e.g., gfortran 5.1.0 or later) in a Linux bash shell
-with the `bin` directory of the chosen installation path in the user's PATH
-environment variable:
+the use of OpenCoarrays with GCC in a Linux bash shell with the `bin`
+directory of the chosen installation path in the user's `PATH` environment variable:
 
 ```fortran
 $ cat tally.f90
@@ -89,31 +67,15 @@ where "4" is the number of images to be launched at program start-up.
 An advanced workflow
 --------------------
 
-To extend the capabilities of a non-OCA CAF compiler (e.g., the Intel or Cray compilers),
-access the types and procedures of the [opencoarrays module] by use association.  We
-recommend using a `use` statement with an `only` clause to reduce the likelihood of a
-name clash with the compiler's native CAf support.  For example, insert the following
-at line 2 of `tally.f90` above:
-
-```fortran
-use opencoarrays, only : co_sum
-```
-
-To extend the capabilities of a non-CAF compiler (e.g., GCC 4.9), use an unqualified
-`use` statement with no `only` clause.  The latter practice reduces the likelihood of
-name clashes with the compiler's or programs existing capabilities.
-
-If the `caf` compiler wrapper cannot process the source code in question, invoke
-the underlying communication library directly:
-
-```bash
-mpifort -fcoarray=lib -L/opt/opencoarrays/ tally.f90 \ -lcaf_mpi -o htally -I<OpenCoarrays-install-path>/mod
-```
-
-and also run the program with the lower-level communication library:
+If you prefer to invoke the compiler directly, first run `caf` and `cafrun` with the `--show` flag 
+to see the proper linking and file includes.  For example, on a macOS system where OpenCoarrays 
+was installed via the [homebrew] package manager, the following results:
 
 ```bash
-mpiexec -np <number-of-images> ./tally
+$ caf --show
+/usr/local/bin/gfortran -I/usr/local/Cellar/opencoarrays/2.2.0/include/OpenCoarrays-2.2.0_GNU-8.2.0 -fcoarray=lib -Wl,-flat_namespace -Wl,-commons,use_dylibs -L/usr/local/Cellar/libevent/2.1.8/lib -L/usr/local/Cellar/open-mpi/3.1.1/lib ${@} /usr/local/Cellar/opencoarrays/2.2.0/lib/libcaf_mpi.a /usr/local/lib/libmpi_usempif08.dylib /usr/local/lib/libmpi_usempi_ignore_tkr.dylib /usr/local/lib/libmpi_mpifh.dylib /usr/local/lib/libmpi.dylib
+$ cafrun --show
+/usr/local/bin/mpiexec -n <number_of_images> /path/to/coarray_Fortran_program [arg4 [arg5 [...]]]
 ```
 
 ---
@@ -137,3 +99,4 @@ mpiexec -np <number-of-images> ./tally
 [The caf compiler wrapper]: #the-caf-compiler-wrapper
 [The cafrun program launcher]: #the-cafrun-program-launcher
 [pdf img]: https://img.shields.io/badge/PDF-GETTING_STARTED.md-6C2DC7.svg?style=flat-square "Download as PDF"
+[homebrew]: https://brew.sh

INSTALL.md

@@ -250,55 +250,49 @@ Execute `./install.sh --help` or `./install.sh -h` to see a list of flags
 that can be passed to the installer.  Below are examples of useful combinations
 of flags. Each flag also has a single-character version not shown here.
 
-1. Install after building any missing prerequisites -- all source, build,
-   and installation files will be inside the OpenCoarrays source tree under
-   prerequisites/installations:
+1. If you don't care about tailoring installation locations,use
 
    ```
    ./install.sh
    ```
 
-1. Install non-interactively by assuming a "yes" answer to all
-   questions
+2. Or build faster by multithreading, skipping user queries, and also specify
+    an installation destination for all packages that must be built:
 
    ```
-   ./install.sh --yes-to-all
+   ./install.sh \
+     --prefix-root ${HOME}/software \
+     --num-threads 4 \
+     --yes-to-all
    ```
 
-1. Install with the specified compilers, overriding the default
-   compilers:
+3. Specify the compilers to be used (overriding what is in your `PATH`) as follows:
 
    ```
    ./install.sh --with-fortran <path-to-gcc-bin>/gfortran \
                 --with-cxx <path-to-gcc-bin>/g++ \
                 --with-c <path-to-gcc-bin>/gcc
    ```
 
-   Without the latter arguments, [`install.sh`] will attempt to install the
-   default GCC version even if a newer version is available.  This happens
-   to protect users from instability in cases when known one or more
-   known regressions exist in the newer compiler.
-
-1. Install only a specific prerequisite package (the default version):
-
+4. Install only a specific prerequisite package (the default version):
    ```
    ./install.sh --package mpich
    ```
 
-1. Install a specific version of a prerequisite:
+5. Install a specific version of a prerequisite:
 
    ```
    ./install.sh --package cmake --install-version 3.7.0
    ```
 
-1. Download a prerequisite package (e.g., gcc/gfortran/g++ below) but
+6. Download a prerequisite package (e.g., gcc/gfortran/g++ below) but
    don't build or install it:
 
    ```
    ./install.sh --only-download gcc
    ```
 
-1. Print the default URL, version, or download mechanism that the
+7. Print the default URL, version, or download mechanism that the
    script will use for a given prerequisite package (e.g., mpich
    below) on this system:
 
@@ -308,51 +302,12 @@ of flags. Each flag also has a single-character version not shown here.
    ./install.sh --print-downloader mpich
    ```
 
-1. Install a prerelease branch (e.g., trunk below) of the GCC repository:
+8. Install a prerelease branch (e.g., trunk below) of the GCC repository:
 
    ```
    ./install.sh --package gcc --install-branch trunk
    ```
 
-1. Install to a specific location:
-
-   ```
-   ./install.sh --install-prefix /opt/gnu/
-   ```
-
-   If the path provided in the install prefix requires sudo privileges,
-   the user will be prompted for a password after the package download
-   and build complete and just before installing to the specified path.
-
-1. Install a prerequisite package from a non-default URL:
-
-   ```
-   ./install.sh --package gcc \
-     --from-url https://github.com/sourceryinstitute/gcc/archive/teams-20170919.tar.gz \
-     --install-version teams-20170919
-   ```
-
-   The latter command will install the Sourcery Institute GCC fork that provides
-   experimental support for the Fortran 2015 teams feature.
-
-1. Speed up a GCC build at a higher risk of a faild build:
-
-   ```
-   ./install.sh --package gcc --disable-bootstrap
-   ```
-
-   If the latter command works, it could reduce GCC's build time from
-   hours down to minutes.
-
-1. Speed up a GCC build with multithreading at a risk of a failed build:
-
-   ```
-   ./install.sh --package gcc --num-threads 4
-   ```
-
-   The latter command sometimes fails if the GCC build system has not fully
-   specified dependencies between source files.
-
 [top]
 
 ## Advanced Installation from Source ##

README.md

@@ -29,52 +29,33 @@ OpenCoarrays
 
 News
 ----
-
-You can now [try OpenCoarrays online] as a [Jupyter] [notebook kernel]
-using [Binder]! No downloads, configuration or installation required!
-Please note: the default [index.ipynb] notebook is read only. You can
-execute it, but if you want to make changes you should create a copy
-of it or create an entirely new [CAF kernel][notebook kernel]
-notebook.
+### Upcoming events ###
+* Nov. 5-8, 2018: "[Writing Fortran 2018 Today]" course by OpenCoarrays contributors Damian Rouson and Izaak Beekman.
+* Nov. 13, 2018: [Intel Speakerships at SC18] presentation by Damian Rouson and Sameer Shende
+* Nov. 16, 2018: SC18 [PAW-ATM Workshop] presentation by OpenCoarrays contributor Soren Rasmussen.
 
 Overview
 --------
 
-[OpenCoarrays] is an open-source software project
-that supports the coarray Fortran (CAF) parallel programming features
-of the Fortran 2008 standard and several features proposed for Fortran
-2015 in the draft Technical Specification [TS 18508] _Additional
-Parallel Features in Fortran_.
-
-OpenCoarrays provides a compiler wrapper (named `caf`), a runtime
-library (named `libcaf_mpi.a` by default), and an executable file
-launcher (named `cafrun`).  With OpenCoarrays-aware compilers, the
-compiler wrapper passes the provided source code to the chosen
-compiler (`mpifort` by default).  For non-OpenCoarrays-aware compilers,
-the wrapper transforms CAF syntax into OpenCoarrays procedure calls
-before invoking the chosen compiler on the transformed code.  The
-runtime library supports compiler communication and synchronization
-requests by invoking a lower-level communication library--the Message
-Passing Interface ([MPI]) by default.  The launcher passes execution
-to the chosen communication library's parallel program launcher
-(`mpiexec` by default).
-
-OpenCoarrays defines an application binary interface ([ABI]) that
-translates high-level communication and synchronization requests into
-low-level calls to a user-specified communication library.  This
-design decision liberates compiler teams from hardwiring
-communication-library choice into their compilers and it frees Fortran
-programmers to express parallel algorithms once and reuse identical
-CAF source with whichever communication library is most efficient for
-a given hardware platform.  The communication substrate for
-OpenCoarrays built with the preferred build system, CMake, is the
-Message Passing Interface ([MPI]).
-
-OpenCoarrays enables CAF application developers to express parallel
-algorithms without hardwiring a particular version of a particular
-communication library or library version into their codes.  Such
-abstraction makes application code less sensitive to the evolution of
-the underlying communication libraries and hardware platforms.
+[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 relinked 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 MPI, 
+which we expect to provide the broadest support for Fortran 2018 for 
+the foreseeable future.  However, having the option to parallel
+programming models at link-time aids portability and performance 
+(see [Rouson et al. (2017)] and [Rasmussen et al. (2018)]).
+
+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.
 
 Downloads
 ---------
@@ -84,39 +65,35 @@ Please see our [Releases] page.
 Compatibility
 -------------
 
-The GNU Compiler Collection ([GCC]) Fortran front end ([gfortran]) is
-OpenCoarrays-aware for release versions 5.1.0 and higher.  Users of
-other compilers, including earlier versions of gfortran, can access a
-limited subset of CAF features via the provided [opencoarrays module].
-After installation, please execute the `caf` script (which is
-installed in the `bin` directory of the installation path) with no
-arguments to see a list of the corresponding limitations.  Please also
-notify the corresponding compiler vendor and the OpenCoarrays team
-that you would like for a future version of the compiler to be
-OpenCoarrays-aware.
+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.
 
 Prerequisites
 -------------
 
-We expect our LIBCAF_MPI library to be the default OpenCoarrays
-library.  LIBCAF_MPI is the most straightforward to install and use,
-the most robust in terms of its internal complexity, and the most
-frequently updated and maintained.  Building LIBCAF_MPI requires prior
-installation of an MPI implementation.  We recommend [MPICH] generally
-or, if available, [MVAPICH] for better performance. [OpenMPI] is
-another option.
+Building OpenCoarrays requires
+
+* An MPI implementation (default: [MPICH]).
+* CMake.
+* A Fortran compiler (default: [GCC]).
+* _Optional_: An [OpenSHMEM] implementation.
+
+If you use a package manager or the OpenCoarrays installer, any
+missing prerequisites will be built for you.
 
-We offer an unsupported LIBCAF_GASNet alternative.  We intend for
-LIBCAF_GASNet to be an "expert" alternative capable of outperforming
-MPI for some applications on some platforms.  LIBCAF_GASNet requires
-greater care to configure and use and building LIBCAF_GASNet requires
-prior installation of [GASNet].
 
 Installation
 ------------
 
 Please see the [INSTALL.md] file.
 
+Or [try OpenCoarrays online] as a [Jupyter] [notebook kernel]
+using [Binder] with no downloads, configuration or installation required.
+The default [index.ipynb] notebook is read only, but you can
+execute it, copy it to make changes, or create an entirely 
+new [CAF kernel][notebook kernel] notebook.
+
 Getting Started
 ---------------
 
@@ -136,16 +113,14 @@ A list of open issues can be viewed on the
 Support
 -------
 
-* Please submit bug reports and feature requests via our [Issues] page.
-* Please submit questions regarding installation and use via our
-  [Google Group] by signing into [Google Groups] or [subscribing] and
-  sending email to [[email protected]].
+Please submit bug reports and feature requests via our [Issues] page.
 
 Acknowledgements
 ----------------
 
 We gratefully acknowledge support from the following institutions:
 
+* [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
   the initial development of OpenCoarrays.
@@ -191,6 +166,15 @@ to aid in development efforts.
 [Contributing]: #contributing
 [Acknowledgements]: #acknowledgements
 
+[Fortran 2018]: http://isotc.iso.org/livelink/livelink?func=ll&objId=19442438&objAction=Open&viewType=1
+[Rouson et al. (2017)]: https://github.com/sourceryinstitute/coarray-icar-paw17/blob/master/main.pdf
+[Rasmussen et al. (2018)]: https://github.com/scrasmussen/coarray-icar-paw18/blob/master/main.pdf
+[Arm]: https://www.arm.com
+[PAW-ATM Workshop]: http://sourceryinstitute.github.io/PAW/
+[Writing Fortran 2018 Today]: https://writing-fortran-2018-today.eventbrite.com
+[Intel Speakerships at SC18]: https://easychair.org/cfp/IntelSpeakershipsatSC18
+
+[OpenSHMEM]: http://www.openshmem.org
 [sourcery-institute logo]: http://www.sourceryinstitute.org/uploads/4/9/9/6/49967347/sourcery-logo-rgb-hi-rez-1.png
 [OpenCoarrays]: http://www.opencoarrays.org
 [ABI]: https://gcc.gnu.org/onlinedocs/gfortran/Coarray-Programming.html#Coarray-Programming
@@ -233,5 +217,7 @@ 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
+https://www.eventbrite.com/e/writing-fortran-2018-today-object-oriented-parallel-programming-tickets-48982176007
+[Writing Fortran 2018 Today]: https://writing-fortran-2018-today.eventbrite.com
 
 [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