==============
Dakota INSTALL
==============

Dakota is a framework which provides access to a broad variety of
algorithms and services.  Downloading pre-built binaries from the
Dakota web site or accessing a site-supported installation are the
simplest routes to access Dakota. See https://dakota.sandia.gov.

For more experienced users, building Dakota from source (either
downloaded or checked out) allows customization with additional
packages and porting to additional platforms or operating systems.
This INSTALL file describes how to install pre-built binaries and setup 
the environment, as well as how to compile from source code.

NOTE: The most up to date installation guidance and tips can be found
alongside the downloads on the Dakota website.


=================
Table of Contents
=================

Distribution Contents
Binary Quick Start
 I.   Install Unix-Like Binary (Linux RHEL7/8, or binary compatible, macOS)
 II.  Install Windows Executable
 III. Test Binary Distribution installation.
Source Quick Start
Other Resources

=====================
Distribution Contents
=====================

The directories contained in Dakota distributions include:
  * bin-dist denotes binary distributions 
    	     (dakota.<release>.<platform>.tar.gz, dakota.<release>.<platform>.zip)
  * src-dist denotes source or checkout distributions
    	     (dakota.<release>.src.tar.gz, dakota.<release>.src.zip)

Distribution  Directory	 Description
Type
------------  ---------  --------------------------------------------------  
bin-dist      bin	 Binary files for Dakota, restart utility, dprepro
                         and various third-party libraries (TPLs).
src-dist      scripts    Source files for some scripts installed to bin-dist:bin


src-dist      examples	 Example problems from the Users Manual, examples of
bin-dist      share/	 interfacing with other codes using script-based or
               dakota/	 direct linkage-based interfaces, parallel computing
                examples examples, and platform installation examples.

src-dist      test	 Files for regression and unit testing of the
src-dist      unit_test	 Dakota system. Test simulator programs and Dakota
bin-dist      share/	 input files are provided for testing different
               dakota/   capabilities.
                test

bin-dist      share/     dakota Python package and Bash interface helpers
               dakota
src-dist      interfaces Corresponding source files

bin-dist      include	 Include files for Dakota and it's associated TPLs.

bin-dist      lib	 Library files for Dakota and it's associated TPLs.

src-dist      packages	 Libraries of iterative algorithms provided by
	      		 commercial vendors and related Sandia projects.
			 Additionally, libraries for parsing (nidr),
			 vector/matrix utilities (Trilinos Teuchos),
			 stochastic utilities (Pecos), algebraic
			 interface (AMPL), surface fitting (Surfpack), etc.

src-dist     cmake	 Scripts supporting CMake builds.	 

src-dist     docs	 The Users, Reference, and Developers Manuals are 
	     		 maintained here.  Other references are available from
			 the Dakota Web site (https://dakota.sandia.gov).

src-dist     src	 The main source code repository for Dakota core.

==================
Binary Quick Start
==================

Most users will install from a binary distribution, if available for
the target platform.  This typically involves unpacking the archive
and setting the PATH variable, if required.

Dakota binary distributions are provided in archive format (either tar.gz or 
zip).
 * See Section I below to install tar.gz archive on Unix-like platform.
 * See Section II below to install zip archive on Windows platform.
 * See Section III below to test binary installion.

-----------------------------------------------------------------------
I. Install Unix-Like Binary (Linux RHEL7/8 or binary compatible, macOS)
-----------------------------------------------------------------------

1. Extract archive file into suitable install location, e.g. /home/username.
   If you have root access, you may extract archive file in a shared directory,
   e.g. /usr/local. 

       $ cd /path/to/Dakota/install/directory
       $ tar xzvf /path/to/dakota-<release>.tar.gz
   
   Optionally, rename the extracted Dakota binary executable directory:

       $ ls
       dakota-<release>.<platform>
       $ mv dakota-<release>.<platform> dakota

   In the instructions below, $INSTALL_DIR refers to the path to this new
   directory,
	/path/to/Dakota/install/directory/dakota

2. Make sure Dakota executables (and optionally test files and current
   directory) are available on the PATH by typing 'which dakota' at command
   line prompt. 

   If your PATH variable is set correctly, the path to the dakota binary
   should be displayed. 
        $ which dakota
        $INSTALL_DIR/bin/dakota
   where $INSTALL_DIR will be the absolute path specified in step #1 above.
   Go to Section III to test the binary installation.

   If your PATH variable is NOT set correctly, you will get a message like
   the following:
        $ which dakota
        /usr/bin/which: no dakota in (/usr/local/bin:/usr/local/sbin)
   Continue with step #3 to set your PATH variable.

3. If your PATH is not set correctly, make the following change to your
   appropriate shell login script:

   Bash shell
   ----------
   a. Edit the startup file ~/.bashrc (~/.bash_profile on macOS) in your 
      favorite text editor.
   b. Modify and export PATH variable. Type the following line, replacing
      $INSTALL_DIR with the absolute path to your installation directory,
      e.g. /home/username.

         export PATH=$INSTALL_DIR/bin:$INSTALL_DIR/share/dakota/test:$PATH
     
   c. Save and close file.
   d. Update changes in your terminal window by sourcing the startup file
      that you modified, ~/.bashrc or ~/.bash_profile (source ~/.bashrc), 
      or by closing and re-opening your terminal.
      
   C shell
   -------
   a. Edit the startup file ~/.cshrc in your favorite text editor
   b. Set path variable. Type the following line, replacing
      $INSTALL_DIR with the absolute path to your installation directory,
      e.g. /home/username.

         setenv PATH $INSTALL_DIR/bin:$INSTALL_DIR/share/dakota/test $PATH

   c. Save and close file.
   d. Update changes in your terminal window. At
      
      $ source ~/.cshrc

4. To use the dakota Python package (and to enjoy the full features of
   dprepro), add the path $INSTALL_DIR/share/dakota/Python/ to the environment 
   variable PYTHONPATH. Adapt the instructions in step 3 by substituting 
   PYTHONPATH where you see PATH to make this change persistent. After 
   restarting the shell, issue the command:
   
      $ python -c "import dakota"

   If it exits silently, producing no output, installation was succcessful.
   An ImportError or ModuleNotFoundError indicates a problem. 

--------------------------------------------------------------------
II.  Install Windows Executable
--------------------------------------------------------------------

1. Extract archive file into suitable install location, e.g. C:\Dakota using
   the Windows extract utility. 
       a. In Windows Explorer window, highight Dakota.<release>.<platform>.zip
          file.
       b. Right click and select "Extract All"
       c. Select a destination, e.g. C:\Dakota, and click the Extract button.
          In the instructions below, %dest_dir% refers to this destination
	  directory.

   Rename the extracted Dakota executable directory folder:
       a. Right click the dakota-<release>.<platform> file, and select
          'Rename'.
       b. Rename file to 'Dakota'

   In the instructions below, %install_dir% refers to the path to this new
   directory, %dest_dir%\Dakota.

2. Set path to your executable.
   a. Click the Start button and type 'cmd' in the 'Search program and files'
      text box to open cmd.exe.
   b. At the command prompt, type the following command, replacing %install_dir%
      with the path to your Dakota installation:

      C:\Users\name> path=%path%;%install_dir%\bin;%install_dir%\share\dakota\test;%install_dir%\lib
      
      Note that the path will be set only for as long as the cmd window
      remains open. To permanently add Dakota to your path, consult the 
      documentation for your version of Windows.

3. To use the dakota Python package (and to enoy the full features of
   dprepro), add the path %install_dir%\share\dakota\Python to the environment
   variable PYTHONPATH. As with the change to %path%, this change will be lost 
   when the cmd Window is closed. Consult the documentation for your version of 
   Windows to make an environment variable persistent.

--------------------------------------------------------------------
III. Test Binary Distribution installation.
--------------------------------------------------------------------
1. At a terminal prompt (on Windows, dakota.exe), type 'dakota -v'. You should
   see Dakota version information displayed.

   > dakota -v
   Running serial executable in serial mode.
   Dakota released <release date>.
   Revision ### build <build data & time>.
   Dakota execution time in seconds;
   Total CPU = ...
   Total wall clock = ...

   If you do not get the expected version information, you may use the
   following Dakota wrapper script for your platform. This wrapper script sets
   expected environment variables and can be used instead of the executable
   name. To test the Dakota installation use the following command:

       Windows Command Terminal: dakota.bat -v
       Linux:                    dakota.sh -v
       macOS:                    dakota.sh -v

2. Refer to the "Tutorial" section of the User's Manual for instructions
   on using the dakota executables or see the Quick Start page on the Dakota
   web site.

3. For distributions with Graphical User Interface (GUI) support, the
   GUI can be launched using the following command:

       Windows Command Terminal: $INSTALL_DIR/gui/DakotaUI.exe
       Linux:                    dakota-ui.sh
       macOS:                    dakota-ui.sh


==================
Source Quick Start
==================

To compile Dakota source distributions, use CMake to populate a build
tree for the target platform with generated Makefiles, and then
execute 'make'.  Given the large number of supported packages,
specifying a few 'cmake' options and environment variables may be
required.  Building the software with all packages may take from 15
minutes to over an hour. 

The following are instructions for building Dakota on a Unix-like platform
in a Bash shell. You may need to use appropriate commands to work for your
particular platform or shell.

1. Install CMake 3.17 (or later) and ensure it is in your $PATH.

2. Extract Dakota source archive file. In the example below, Dakota will
   be extracted into the user's home directory, /home/username. 

   $ cd $HOME
   $ tar xzvf /path/to/dakota-<release>.public.src.tar.gz

   You will see a new directory, /home/username/dakota-<release>.src. In
   the instructions below, $DAK_SRC refers to this directory.

   $ export DAK_SRC=$HOME/dakota-<release>.src

3. Create separate build directory, e.g. $HOME/dakota-build. In the
   instructions below, $DAK_BUILD refers to the directory that you create
   for CMake to configure and build Dakota. 

   $ mkdir -p /path/to/Dakota/build/directory
   $ export DAK_BUILD=/path/to/Dakota/build/directory
   
4. Make a copy of the template BuildDakotaTemplate.cmake to customize a CMake
   Dakota build for your platform. Keep file in the $DAK_SRC/cmake directory 
   to use for subsequent Dakota CMake builds.

   $ cp $DAK_SRC/cmake/examples/BuildDakotaTemplate.cmake \
        $DAK_SRC/cmake/BuildDakotaCustom.cmake

5. Update $DAK_SRC/cmake/BuildDakotaCustom.cmake file to reflect your platform
   configuration. Instructions are provided in this file.

6. Configure and build Dakota. 

   $ cd $DAK_BUILD
   $ cmake -C $DAK_SRC/cmake/BuildDakotaCustom.cmake $DAK_SRC
   $ make [-j#]
   $ make install

7. Set paths. In the instructions below, $DAK_INSTALL refers to the Dakota 
   installation path you specified for the variable CMAKE_INSTALL_PREFIX 
   in your BuildCustom.cmake file.

   $ export PATH=$DAK_INSTALL/bin:$DAK_INSTALL/share/dakota/test:$PATH
   $ export PYTHONPATH=$DAK_INSTALL/share/dakota/Python:$PYTHONPATH

Miscellaneous Notes:
 * 'make [-j#]': Dakota supports concurrent build processes

 * 'make install' requires write privileges in CMAKE_INSTALL_PREFIX.

 * Executing cmake without any options will result in an attempt to
   build with as many vendor algorithms and packages as are available
   in the distribution.  Options below and on the Dakota website
   describe how to turn off features.

 * Once make has successfully completed, the generated Dakota
   executables (dakota and dakota_restart_util) will reside in
   $DAK_BUILD/src.  If 'make install' is invoked, copies of the
   executables will be placed in CMAKE_INSTALL_PREFIX/bin and copies
   of the libraries (libdakota.a, etc.) are placed in
   CMAKE_INSTALL_PREFIX/lib. You may set CMAKE_INSTALL_PREFIX in 
   BuildDakotaCustom.cmake.

===============
Other Resources
===============

For additional help with installing Dakota from source, please
see the Compiling Dakota section of the user's guide.

Topics include:
* Obtaining Dakota source code
* source installation dependencies
* source installation options
* Dakota CMake hints
* generating local documentation
* summary of distributed Dakota libraries
* installing commercial libraries, such as DOT, NPSOL, and NLPQL 
