Skip to content
Snippets Groups Projects
Commit 8ecc0dcd authored by Wiarda, Dorothea's avatar Wiarda, Dorothea
Browse files

Merge branch '10-update-readme' into 'master' 

Resolve "Update the README installation instructions"

Closes #10

See merge request rnsd/sammy!10
parents 68c387e6 e0f6c9e8
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 148 additions and 37 deletions
README.md
+ 148
− 37
View file @ 8ecc0dcd
......@@ -29,7 +29,7 @@ The structure of the code is broadly described by the image below.
## Quick Installation
Assuming you already have [SCALE installed](#building-scale-for-sammy) (if you do not have SCALE installed you should do that and come back to these steps), in a terminal execute the following commands:
Assuming you already have [SCALE installed](#building-scale-for-sammy) (if you do not have SCALE with [GTest](https://github.com/google/googletest) capability installed you should do that and come back to these steps), in a terminal execute the following commands:
```bash
$ git clone git@code.ornl.gov:rnsd/sammy.git
......@@ -61,7 +61,7 @@ $ ctest -j4
## Build and Test
The SAMMY build is based on CMake from KitWare, which supports a consistent experience on LINUX, Mac, and Windows.
The SAMMY build is based on CMake from KitWare, which supports a consistent experience on LINUX, Mac, and Windows. Keep in mind that SAMMY **must be built with the same compilers/compiler-options as SCALE/AMPX**. OS specific instructions are given below for [MacOS](#mac-osx), [Linux](#linux-ubuntu), and [Windows](#windows-10). Guidance for common CMake errors can be found [here](#common-cmake-errors).
SAMMY build requires:
......@@ -73,7 +73,7 @@ SAMMY build requires:
| Lapack/Blas | 3.0 or higher |
| SCALE | 6.3-b9 or higher |
> Instead of GNU compilers it is also possible to use Intel Fortran/C++ 13.1 or higher. The SCALE 6.2 source code can be requested from [RSICC](https://rsicc.ornl.gov/), and the beta version of SCALE can be obtained by request from email address scalehelp@ornl.gov. TriBITS is distributed with SAMMY but it could be installed separately, if needed, by running <SAMMY_DIR>/script/tribits.sh.
> Instead of GNU compilers it is also possible to use Intel Fortran/C++ 13.1 or higher. The SCALE 6.2 source code can be requested from [RSICC](https://rsicc.ornl.gov/), and the beta version of SCALE can be obtained by request from email address scalehelp@ornl.gov. TriBITS is currently distributed with SCALE.
There are four main steps to create an SAMMY installation:
......@@ -90,17 +90,18 @@ The BUILD TREE contains or will contain the build configuration, Make files, and
Then `make install` in the build directory will install the packages, and an optional `ctest` command will run several tests to ensure that SAMMY built correctly.
SAMMY requires Qt, LAPACK and BLAS routines. If these libraries reside in a known location (i.e., installed by apt, yum, macports, or brew [see below](#mac-osx-and-linux-special-instructions)), the installation procedure may automatically find the libraries. Otherwise the location can be given at configuration time in `configure_sammy_gcc.sh`.
SAMMY requires Qt, LAPACK and BLAS routines. If these libraries reside in a known location (i.e., installed by apt, yum, macports, or brew [see below](#mac-osx)), the installation procedure may automatically find the libraries. Otherwise the location can be given at configuration time in `configure_sammy_gcc.sh`.
Recommended instructions for building is as follows:
Recommended instructions for building is as follows. To clone the directory, if you have account credentials from ORNL (external users can start [here](https://web.ornl.gov/xcams/xcamsfaq.htm)), in a terminal type:
```bash
$ git clone git@code.ornl.gov:rnsd/sammy.git
$ cd sammy/sammy
$ ./script/tribits.sh
$ mkdir build
$ cd build
$ cp ../script/configure_sammy_gcc.sh .
```
if you want to clone without any credentials (without credentials you have limited user functionality in GitLab), type the following in the terminal:
```bash
$ git clone https://code.ornl.gov/RNSD/SAMMY.git
```
In the example above the main cloned directory is `sammy`, but it is possible to specify a different cloned directory name with the following command:
......@@ -109,6 +110,27 @@ In the example above the main cloned directory is `sammy`, but it is possible to
$ git clone git@code.ornl.gov:rnsd/sammy.git different_cloned_directory
```
Once having cloned the project onto your local machine, check to see if you have the TriBITS project. This project is distributed with SCALE, so if you do not yet have it, it should be copied from the scale source distribution to `sammy/sammy/TriBITS`.
```bash
$ cp -r <path-to-scale>/scale/TriBITS sammy/sammy/TriBITS
```
or
```bash
$ ln -s <path-to-scale>/scale/TriBITS sammy/sammy/TriBITS
```
Then run the following in the terminal:
```bash
$ cd sammy/sammy
$ mkdir build
$ cd build
$ cp ../script/configure_sammy_gcc.sh .
```
In this guide, however, the main cloned directory will be referred to as `sammy` or the "top `sammy` directory" since we want to simply use the default configuration.
In the editor of your choice, set up your configuration options in the file `configure_sammy_gcc.sh` that you've copied into the `build` directory. It's best to copy the file to `build` as the `build` directory is not tracked by `git` and the file will not be overwritten every time you `pull` the latest version of sammy from the remote server. There are several paths that can be defined for the build environment, such as the `path/to/scale`. From the `build` directory in the terminal:
......@@ -125,7 +147,7 @@ Finally run the tests with:
$ ctest -j4
```
Note that both `make` and `ctest` take -j option (e.g. -j7) to run in parallel on several cores (e.g. 7), where the number 7 would be exchanged for however many processors you have available.
Note that both `make` and `ctest` take -j option (e.g. -j8) to run in parallel on several cores (e.g. 8), where the number 8 would be exchanged for however many processors you have available.
Other CMake flags, e.g. `CMAKE_Fortran_COMPILER`, `CMAKE_Fortran_FLAGS`, `CMAKE_C_COMPILER`, `CMAKE_C_FLAGS`, `CMAKE_CXX_COMPILER`, and `CMAKE_CXX_FLAGS` may be modified in the cmake command invocation line to update the compilers or compiler flags to the desired settings.
......@@ -143,9 +165,9 @@ SCALE built for SAMMY requires:
| Lapack/Blas | 3.0 or higher |
| HDF5 | 1.10 or higher |
Only a portion of SCALE needs to be built for use with SAMMY. If you have already built the entire SCALE code system, then you can ignore these instructions. Otherwise, the following instructions may **save time** during the SCALE build as SAMMY only requires a small portion of the SCALE code. From the top `sammy` directory (which is the main cloned directory you created with the `git clone` command) run the following in a terminal:
Only a portion of SCALE needs to be built for use with SAMMY. If you have already built the entire SCALE code system with [Gtest](https://github.com/google/googletest) enabled (keep in mind that SAMMY **must be built with the same compilers/compiler-options as SCALE/AMPX**), then you can ignore these instructions. Otherwise, the following instructions may **save time** during the SCALE build as SAMMY only requires a small portion of the SCALE code. From the top `sammy` directory (which is the main cloned directory you created with the `git clone` command) run the following in a terminal:
```
```bash
$ mkdir scale
$ cd scale
$ cp ../sammy/script/install_minimum_scale.sh .
......@@ -169,7 +191,7 @@ Once SCALE libraries have been compiled, you can [begin building SAMMY](#quick-i
---------------------
### Windows Special Instructions
### Windows 10
Modern versions of SAMMY have not been fully tested on Windows OS's, but have been successfully built and tested on Windows Subsytem for Linux [WSL](https://docs.microsoft.com/en-us/windows/wsl/about). WSL can be used to run a Linux operating system as an application **inside the Windows OS** directly interacting with files in the Windows OS. SAMMY has been built and tested in Ubuntu for WSL. To set up the Ubuntu application in Windows you may follow the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10) on their website, but the basics are repeated here.
......@@ -183,7 +205,7 @@ Open a Windows PowerShell as an administrator and execute the following command:
$ Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```
You will likely need to restart your computer after executing this command in the PowerShell. Once your computer has restarted, open the Microsoft Store and search for "Ubuntu". Windows should lead you through a user-friendly installation procedure. Once you have the Ubuntu application installed you should be able open a Ubuntu shell and begin setting up your environment for SAMMY. First run:
You will likely need to restart your computer after executing this command in the PowerShell. Once your computer has restarted, open the Microsoft Store and search for "Ubuntu". Windows should lead you through a user-friendly installation procedure. Once you have the Ubuntu application installed you should be able to open a Ubuntu shell and begin setting up your environment for SAMMY. In the Ubuntu terminal:
```bash
$ sudo apt-get update
......@@ -202,7 +224,7 @@ Add brew to your `PATH` in the file `~/.bashrc` with the following line at the e
export PATH=/home/linuxbrew/.linuxbrew/bin:$PATH
```
Then execute the following in the shell to install the latest GNU compilers, Qt-4, LAPACK/BLAS libraries, Java Development Kit, and HDF5 libraries:
Then execute the following in the shell to install the latest GNU compilers (keep in mind that SAMMY **must be built with the same compilers/compiler-options as SCALE/AMPX**), Qt-4, LAPACK/BLAS libraries, Java Development Kit, and HDF5 libraries:
```bash
$ sudo apt-get update
......@@ -224,9 +246,15 @@ After successfully installing these programs, you should be able to follow the i
---------------------
### MAC OSX and Linux Special Instructions
### Mac OSX
XCode is needed to compile SAMMY on a Mac OS X computer. It is available free from the App Store. In addition, the command line options from XCode must be installed. This can typically be accomplished by running the following in the command line:
```bash
xcode-select --install
```
XCode is needed to compile SAMMY on a Mac OS X computer. It is available free from the App Store. In addition, the command line options from XCode must be installed. This can be accomplished by navigating to XCode->Preferences->Downloads->Components->Command Line Tools, and clicking Install.
and following any prompts given by the MacOS.
The latest version of macports, download-able from http://www.macports.org, can be used to download required programs as well as Homebrew (Homebrew works with both OS's).
......@@ -236,7 +264,7 @@ The latest version of macports, download-able from http://www.macports.org, can
Homebrew for **MacOS** (Linux will be different) can be downloaded from the Hombrew [website](https://brew.sh/) using the command:
```
```bash
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
......@@ -250,20 +278,10 @@ $ brew install cmake
$ brew tap cartr/qt4
$ brew tap-pin cartr/qt4
$ brew install qt@4
$ brew install hdf5
```
If `brew` successfully installs software it typically is stored in a Homebrew-specific folder such as `/usr/local/` on MacOS or `/home/linuxbrew/` on Linux distros. Current MacOS distributions come with `LAPACK` and `BLAS` in the Veclib Framework but can be installed with `brew`. On Linux distributions it is suggested to install with `apt`:
```bash
apt install liblapack-dev libblas-dev
```
and you can also install the Qt program and Java tools on Linux with `apt`:
```bash
$ apt install qt4-default
$ apt-get install default-jdk
```
If `brew` successfully installs software it typically is stored in a Homebrew-specific folder such as `/usr/local/` on MacOS. Current MacOS distributions come with `LAPACK` and `BLAS` in the Veclib Framework but can also be installed with `brew`.
</details>
</p>
......@@ -301,15 +319,13 @@ $ sudo port selfupdate
Regardless of rsync status, the following commands should be executed:
```bash
$ sudo port install gcc48
$ sudo port install gcc9
$ sudo port install qt4-mac
$ sudo port install cmake
```
Newer versions may be used if available from macports. Once the new version is installed,
the default gcc version must be selected.
First the available versions are listed:
the default gcc version must be selected. First the available versions can be listed:
```bash
$ port select --list gcc
......@@ -332,14 +348,109 @@ where a default {qt4_bin_dir} is /opt/local/libexec/qt4/bin. Installation will t
</details>
</p>
### Linux-Ubuntu
When installing the required software for SAMMY for a Linux OS (tested on Ubuntu) you should start with a general update:
```bash
$ sudo apt-get update
$ sudo apt-get upgrade
```
to get the latest and greatest tools for Ubuntu.
<p>
<details>
<summary>Homebrew instructions are detailed here.</summary>
Next get the package manager `brew` to install the necessary compilers and other supporting programs ([link](https://brew.sh/) to brew's website):
```bash
$ sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)"
```
Add brew to your `PATH` in the file `~/.bashrc` with the following line at the end of the file:
```bash
export PATH=/home/linuxbrew/.linuxbrew/bin:$PATH
```
The Homebrew website is a good resource for finding out more about how to install and use Homebrew on a Mac or Linux machine (it can also be installed on Windows Subsytem for Linux: **WSL**).
Once Homebrew has been built and installed (and is found in the `PATH`) use the following commands to install required software.
```bash
$ brew install gcc@9
$ brew install cmake
$ brew tap cartr/qt4
$ brew tap-pin cartr/qt4
$ brew install qt@4
$ brew install hdf5
```
If `brew` successfully installs software it typically is stored in a Homebrew-specific folder such as `/home/linuxbrew/` on Linux distros. On Linux distributions it is suggested to install `LAPACK` and `BLAS` with `apt`:
```bash
$ apt install liblapack-dev libblas-dev
```
and you can also install the Qt program and Java tools on Linux with `apt`:
```bash
$ apt install qt4-default
$ apt-get install default-jdk
```
</details>
</p>
---------------------
<p>
<h3>Common CMake Errors</h3>
<details>
<summary>Details</summary>
When users configure SAMMY, they often find that the CMake build process will not find a required package or third-party software. As an example, let's walk through the process for fixing a SCALE TPL error *in a general fashion* (see the bottom for the best SCALE not found fix). Typically an error message such as this will be printed at configure:
```
-- Searching for lib 'ScaleUtilsEndfLib' ...
-- NOTE: Did not find a lib in the lib set "ScaleUtilsEndfLib" for the TPL 'SCALE'!
-- ERROR: Could not find the libraries for the TPL 'SCALE'!
-- TIP: If the TPL 'SCALE' is on your system then you can set:
-DSCALE_LIBRARY_DIRS='<dir0>;<dir1>;...'
to point to the directories where these libraries may be found.
Or, just set:
-DTPL_SCALE_LIBRARIES='<path-to-libs0>;<path-to-libs1>;...'
to point to the full paths for the libraries which will
bypass any search for libraries and these libraries will be used without
question in the build. (But this will result in a build-time error
if not all of the necessary symbols are found.)
-- ERROR: Failed finding all of the parts of TPL 'SCALE' (see above), Aborting!
```
This error message is boilerplate text filled in with the missing package name `ScaleUtilsEndfLib` from the TPL `SCALE`. To fix the error, the message tells you the option name to specify (`-D SCALE_LIBRARY_DIRS`) in your configure script. So, in general, if you got this error message while compiling SAMMY, you would open the file `configure_sammy_gcc.sh` and add the following option to the `cmake` command:
```bash
-D SCALE_LIBRARY_DIRS='<dir>'
```
where `'<dir>'` is the directory where the `SCALE` library `ScaleUtilsEndfLib` can be found. For me it would be `-D SCALE_LIBRARY_DIRS='/Users/<username>/sammy/scale/install'`. This is the general process for most libraries.
**It should be noted however** that this is simply an example. The error message in the case of *SCALE libraries not being found* points to the fact that we never specified where the SCALE install path was. We can fix this with one line in the configure script:
```bash
-D ${SCALE_INSTALL_PATH}='/Users/<username>/sammy/scale/install'
```
</details>
<p>
<h3>Changing the Array Size</h3>
<details>
<summary>Details</summary>
Dynamic dimensioning is achieved in SAMMY by assigning and de-assigning zspace in a large container array, designated as A(-N:N). The default value for N is 100,000,000. To use a different value, modify the line in your configure file shown below, substituting a desired value for your computer system (current maximum is about 2,000,000,000):
Dynamic dimensioning is achieved in legacy portions of SAMMY by assigning and de-assigning space in a large container array, designated as A(-N:N). The default value for N is 100,000,000. To use a different value, modify the line in your configure file shown below, substituting a desired value for your computer system (current maximum is about 2,000,000,000):
current default value:
......@@ -353,7 +464,7 @@ The following value is near the current maximum for the Intel ifort compiler and
-D SAMMY_ARRAY_SIZE:INT=2000000000 \
```
Other compilers may have a smaller maximum SAMMY_ARRAY_SIZE that could be determined empirically
Other compilers may have a smaller maximum SAMMY_ARRAY_SIZE that could be determined empirically. This behavior is currently being stripped away however, and changing the array size in SAMMY will eventually become obsolete.
</details>
</p>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment