updated readme

CMake/cuda.cmake

@@ -15,8 +15,14 @@ if( GITR_USE_CUDA )
   include( FindCUDAToolkit )
 
   if( NOT CUDAToolkit_FOUND )
-    message( FATAL_ERROR "CUDA toolkit not found: to enable, set -DCUDAToolkit_ROOT=/path/to/cuda_root"
-             " or disable GPU support, set -DGITR_USE_CUDA=0" )
+
+    message( FATAL_ERROR
+             "CUDA toolkit not found: to enable, set -DCUDAToolkit_ROOT=/path/to/cuda_root."
+             "The CUDA root path can be inferred from your nvcc executable: run 'which nvcc'
+              to indicate where nvcc is located, take the directory portion of the path as
+              the root."
+             " Alternatively, to disable GPU support, set -DGITR_USE_CUDA=0 when configuring
+               with CMake" )
   endif()
 
   include_directories( ${CUDAToolkit_INCLUDE_DIRS} )

README.md

@@ -30,46 +30,69 @@ fields and profiles of the background.
 ```
 . Top Level: Top level build system file **CMakeLists.txt**, LICENSE file, README.md (this file)
 ├── CMake           ---> build system files
-├── docs            ---> more detailed documentation 
-├── dev_docs        ---> documentation for developers
 ├── images          ---> repo visuals for websites and presentations
+├── examples        ---> contains a post-processing example script
 ├── include         ---> C++ header files
 ├── src             ---> C++ source files
 ├── test_include    ---> C++ unit test header files
 └── test_src        ---> C++ unit test source files
 ```
-## Dependencies 
+## Installation
 
-- cmake version 3.13 or newer required
-- **CUDA**
-  - Enabled by default, disable with -DGITR_USE_CUDA=0
-  - Requires existing installation. Set:
-    - -DCMAKE_CUDA_COMPILER=/path/to/nvcc
-- [libconfig](https://github.com/hyperrealm/libconfig)
-  - consumes human-readable input config files
-  - to use existing installation, set:
-    - -DLIBCONFIG_INCLUDE_DIR=/path/to/libconfig/include (libconfig headers)
-    - -DLIBCONFIG_LIBRARY=/path/to/libconfig.so
-    - -DLIBCONFIGPP_INCLUDE_DIR=/path/to/libconfig++/include (libconfig headers)
-    - -DLIBCONFIGPP_LIBRARY=/path/to/libconfig++.so
-- [netcdf-c](https://github.com/Unidata/netcdf-c)
-  - input/output raw data format
-  - to use existing installation set:
-    - -DNETCDF_LIBRARY=/path/to/libnetcdf.so
-    - -DNETCDF_INCLUDE_DIR=/path/to/netcdf-c/include (netcdf-c headers)
-- [netcdf-cxx4](https://github.com/Unidata/netcdf-cxx4)
-  - C++ extensions to netcdf-c
-  - to use an existing installation, set:
-    - -DNETCDF_CXX_LIBRARY=/path/to/libnetcdf-cxx4.so
-    - -DNETCDF_CXX_INCLUDE_DIR=/path/to/netcdf-cxx4/include (netcdf-c headers)
-- [thrust](https://github.com/thrust/thrust)
-  - header-only library
-    - included in CUDA installation if gpu support enabled
-  - to use existing installation, set:
-    - -DTHRUST_INCLUDE_DIR=/path/to/thrust
-    - this should only be necessary if CUDA is disabled
+### Ubuntu 20.04
 
-## Installation
+1. Install g++ and associated utilities. This is best done by installing the "build-essential" package with the command:
+> apt install build-essential
+This also installs make and other useful utilities.
+
+2. Install the newest version of CMake. This can be done with **apt** or by building from source.
+   To build from source, visit the CMake website and download the newest stable release as a
+   zipped tar archive. Unizip and extract with
+> tar -xvf <cmake_file_name>.tar.gz
+   Move the directory into your home directory. Create an out-of-source build directory.
+   Navigate to the cmake source directory and run:
+> ./bootstrap --prefix=/path/to/cmake_build_directory
+> make -j
+> make install
+
+  Naviate to the build folder and verify you see bin, doc, and share - bin contains the cmake
+  executable. Get the full filepath of the executable in the bin directory with:
+> readlink -f <cmake-executable file>
+  Running this file like
+> ./<cmake-executable-file> --version
+  from within the bin folder should print out the version. Now, to make this executable invokable
+  from any directory, open the file .bashrc in your home directory or create it if it doesn't
+  exist. Add this line to the end:
+> alias cmake=<paste the filepath of the cmake executable immediately after the equals sign, no quotes or spaces>
+
+To use this cmake binary, either open a new terminal window to re-parse the .bashrc file, or
+re-parse it manually by running:
+> source ~/.bashrc
+
+3. To run large problems, you will need to leverage a GPU. This means that nvcc, the NVIDIA CUDA
+   compiler, must be installed. Follow these instructions:
+   [**CUDA install**](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html)
+   You will likely need a restart after this to initiate CUDA drivers.
+
+4. CUDA is now installed, but you must point your shell to it for it to find it. Add the PATH
+   and LD\_LIBRARY\_PATH exports to your .bashrc file. Open a new terminal window or source it as
+   explained in the CMake installation step for it to take effect.
+
+5. For Netcdf to work properly, you must have the m4 package installed:
+> sudo apt install m4
+
+6. For Netcdf to work, you must also have HDF5 installed. Make sure it is installing
+   a modern version from the package repo:
+> sudo apt install libhdf5-dev
+
+### Mac OSx
+1. If you do not have the Homebrew package manager, get it.
+2. You must install HDF5:
+> brew install [email protected]
+3. You must install CMake if you do not already have it:
+> brew install cmake
+4. You may need to install m4 as well:
+> brew install m4
 
 ### Configure
 Configure build system with CMake. Physics operators can be activated via **-D**-style build-time
@@ -97,7 +120,7 @@ Once the project is configured, compile:
 
 ### Run
 
-GITR expects to be run in a directory containing directories **input** and **output**.
+GITR expects to be run in a directory containing subdirectories **input** and **output**.
 The **input** directory must contain a file called *gitrInput.cfg*. Reference 
 docs/runtime_config.md for details about this file. These following options in the file must
 be mirrored with their CMake **-D**-style counterpart build-time option.
@@ -117,6 +140,39 @@ Navigate to the user-created build directory and run:
 
 > ctest
 
+### Adding a test:
+
+1. Navigate to 
+> CMake/define\_test\_components.cmake.
+   Pick a name for the test and add it to
+   the CMake variable
+> 'gpu\_test\_targets' 
+   if it can optionally use the GPU. Otherwise put it in
+> 'cpu\_test\_targets'.
+
+2. Create the actual unit test file - it must be named **exactly** the name you picked with .cpp
+   at the end, and in the directory GITR/test\_src. You must include:
+> \#include "test\_utils.hpp"
+
+3. Link any libraries your test needs. Do this in GITR/CMake/crosslink\_components.cmake
+
+### Adding a data file accessible to the unit tests:
+1. Include this file in your test file:
+> \#include "test\_data\_filepath.hpp"
+   It contains preprocessor definitions for filepaths. This file is automatically generated by
+   the build system. To use a data file in the tests, you will need to instruct the build system
+   to create a new entry in that header file.
+
+2. Copy your test file into GITR/test\_data/.
+
+3. Add the following lines anywhere after the macro definition in 
+   GITR/CMake/configure\_test\_data.cmake:
+> generate\_testing\_file( "test\_data/your\_test\_file.extension" )
+> set( YOUR\_PREPROCESSOR\_DEFINE\_NAME ${destination\_path})
+
+4. Navigate to GITR/CMake/define\_define\_test\_components.cmake. Add a line:
+> \#cmakedefine YOUR\_PREPROCESSOR\_DEFINE\_NAME "${YOUR\_PREPROCESSOR\_DEFINE\_NAME}"
+
 ## Bugs/Issues
 
 Create a new issue under GitHub's Issues tab.
@@ -134,3 +190,35 @@ Fork this repository, branch off of *dev*, and open a merge request into *dev*.
 Navigate to
 
 > GITR/docs/release_notes.md
+
+## Dependencies 
+
+- cmake version 3.13 or newer required
+- **CUDA**
+  - Enabled by default, disable with -DGITR_USE_CUDA=0
+  - Requires existing installation. Set:
+    - -DCMAKE_CUDA_COMPILER=/path/to/nvcc
+- [**libconfig**](https://github.com/hyperrealm/libconfig)
+  - consumes human-readable input config files
+  - to use an existing installation, set:
+    - -DLIBCONFIG_INCLUDE_DIR=/path/to/libconfig/include (libconfig headers)
+    - -DLIBCONFIG_LIBRARY=/path/to/libconfig.so
+    - -DLIBCONFIGPP_INCLUDE_DIR=/path/to/libconfig++/include (libconfig headers)
+    - -DLIBCONFIGPP_LIBRARY=/path/to/libconfig++.so
+- [**netcdf-c**](https://github.com/Unidata/netcdf-c)
+  - input/output raw data format
+  - to use existing installation set:
+    - -DNETCDF_LIBRARY=/path/to/libnetcdf.so
+    - -DNETCDF_INCLUDE_DIR=/path/to/netcdf-c/include (netcdf-c headers)
+- [**netcdf-cxx4**](https://github.com/Unidata/netcdf-cxx4)
+  - C++ extensions to netcdf-c
+  - to use an existing installation, set:
+    - -DNETCDF_CXX_LIBRARY=/path/to/libnetcdf-cxx4.so
+    - -DNETCDF_CXX_INCLUDE_DIR=/path/to/netcdf-cxx4/include (netcdf-c headers)
+- [**thrust**](https://github.com/thrust/thrust)
+  - header-only library
+    - included in CUDA installation if gpu support enabled
+  - to use existing installation, set:
+    - -DTHRUST_INCLUDE_DIR=/path/to/thrust
+    - this should only be necessary if CUDA is disabled
+