.. _devenv: """"""""""""""""""""""""""""" Setup Development Environment """"""""""""""""""""""""""""" Dakota has the following toolchain and software package dependencies. See sections that follow for suggestions on how to satisfy them. Dakota regression test baselines are based on the recommended Dakota RHEL 9 configuration below. Regression tests will typically exhibit numerical differences when running on other platforms. For developers needing to reproduce RHEL 9 baselines on other platforms, e.g., for pre-push code verification, a Docker-based build/test process is also described in :ref:`devenvironment-main`. .. note:: Dakota developers at SNL should augment this information with site-specific documentation. ========== Toolchains ========== .. list-table:: Dakota Build Toolchains :header-rows: 1 * - Tool - Version - Notes * - `CMake `_ - >= 3.23 - Required * - C Compiler - >= C99 - Required * - C++ Compiler - >= C++20 - Required * - Fortran Compiler - 77, 90 - Required * - `Python `_ - 3.x; >= 3.10 for ``DAKOTA_PYTHON_STUDY`` - Required; Python 3 only * - `Perl `_ - >= 5.16 - Required * - Java JDK - = 11 - Optional; required for ``DAKOTA_JAVA_SURROGATES`` * - Doxygen - = 1.8.20 - Optional; required for generating C++ code docs * - Sphinx - >= 5.0 - Optional; required for generating user docs. Requires sub-packages , myst-parser, sphinx-rtd-theme, sphinxcontrib-bibtex Notes on toolchains: - Dakota is most commonly built with GCC, Intel, and Visual C++ compilers, and to a lesser extent with Cray, PGI, IBM, and Clang. Recent versions of these compilers are not covered by automated testing so using really new ones may require patches or disabling some Dakota packages (often Acro and/or AMPL). - Typically the compilers should be from the same toolchain and version, i.e., don't mix Intel C++ with GCC Fortran unless you understand the consequences. - C99 is not supported by Dakota's AMPL package. - Refer to :ref:`Writing Dakota Documentation ` for detailed instructions on installing Sphinx into your preferred Python environment. ======== Packages ======== .. list-table:: Core Dakota Packages :header-rows: 1 * - Package - Version - Notes * - Linear Algebra - any - Required, e.g., BLAS/LAPACK, MKL, Accelerate * - `Boost `_ - >= 1.75 - Required; headers, plus libraries: filesystem, program_options, regex, serialization, system * - MPI - any - Optional, e.g., MPICH, OpenMPI * - `HDF5 `_ - >= 1.10.4 - Optional; required for Dakota structured results output * - `h5py `_ - - Optional; required to enable HDF5-based tests (recommended for developers) * - `GSL `_ - >= 1.15 - Optional; required for QUESO Bayesian calibration, **induces GPL dependency** * - `Trilinos `_ (Teuchos and ROL) - >= 13.0 - Optional, as Dakota includes a snapshot in :file:`packages/external/trilinos` **Notes on Packages:** Linear Algebra: - If installing with a package manager, consider including the user runtime as well as development packages, e.g., ``blas``, ``blas-devel``, ``lapack``, ``lapack-devel``, to facilitate both dynamic and static linking. - Some systems do not provide canonically named versions of these libraries, so it may be necessary to symbolically link, e.g., ``libblas.so -> libblas.so.3``. Otherwise you may be able to specify full paths to the desired libraries using the CMake variables ``BLAS_LIBS``, ``LAPACK_LIBS`` Boost: - Make sure the CMake version you're using is newer than the Boost version to properly find Boost. - If compiling Boost from source, it may be necessary to compile Boost with C++11, e.g., by setting ``-std=c++11`` or similar. MPI: - The MPI installation must be compatible with the compiler toolchain. HDF5: - If compiling HDF5 from source, C++ and HL support must be enabled (``--enable-cxx`` and ``--enable-hl`` options to configure), which are not the defaults when building it from source. Trilinos: - Dakota's Trilinos snapshot suffices for most users. Those who need Dakota to be compatible with a specific Trilinos installation, e.g., when linking Dakota as a library with a Trilinos-dependent application, should provide their own Trilinos. - If compiling Trilinos from source, enable at least the Teuchos and ROL packages. - Dakota likely cannot be compiled against Kokkos-enabled Trilinos. - Compatibility: * Dakota 6.10--6.12 require Trilinos dated May 2019 or newer, or otherwise disabling deprecated code in Teuchos due to removal of ``ostream::operator<<``. * Dakota 6.13 and newer require Trilinos 13.0 or newer. ======================= Platform-specific Hints ======================= For Linux platforms in general, it's easiest to satisfy Dakota's dependencies using OS package managers, supplementing with compiling from source as needed. ------ RHEL 9 ------ The following packages work for building Dakota on RHEL 9, Rocky Linux 9, or AlmaLinux 9. This is the platform used for Dakota regression test baselines. First enable the EPEL and CodeReady Builder (CRB) repositories:: dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm dnf config-manager --set-enabled crb Then install packages:: dnf install \ cmake clang clang-tools-extra gcc-gfortran git make ninja-build patch perl \ atlas atlas-devel blas blas-devel lapack lapack-devel \ boost-devel \ openmpi openmpi-devel \ hdf5 hdf5-devel \ gsl gsl-devel \ python3.12 python3.12-devel python3.12-pip python3.12-setuptools # Optional; only needed for DAKOTA_JAVA_SURROGATES dnf install java-17-openjdk-devel # Optional; only needed for generating C++ code docs dnf install doxygen The ``boost-devel`` package from EPEL satisfies the >= 1.75 requirement. Python packages for HDF5-based tests are most easily installed in a virtual environment:: python3.12 -m venv /path/to/dakota-venv source /path/to/dakota-venv/bin/activate pip install h5py numpy scipy For documentation builds, also install Sphinx and required plugins into the same environment:: pip install sphinx myst-parser sphinx-rtd-theme sphinxcontrib-bibtex \ sphinx-copybutton sphinx-inline-tabs pydantic autodoc-pydantic OpenMPI binaries and libraries are installed under ``/usr/lib64/openmpi`` and require either loading the environment module or setting paths manually before building or running Dakota:: module load mpi/openmpi-x86_64 or equivalently:: export MPI_HOME=/usr/lib64/openmpi export PATH=/usr/lib64/openmpi/bin:$PATH Basic build example:: source /path/to/dakota-venv/bin/activate module load mpi/openmpi-x86_64 cmake -D CMAKE_C_COMPILER=clang \ -D CMAKE_CXX_COMPILER=clang++ \ -D CMAKE_Fortran_COMPILER=gfortran \ -D DAKOTA_HAVE_MPI=ON \ -D DAKOTA_HAVE_HDF5=ON \ /path/to/dakota/source ------ Ubuntu ------ An incomplete, but perhaps helpful, list of packages for Ubuntu 20.04 LTS, starting from a minimal desktop installation: :: apt-get install gcc g++ gfortran cmake libboost-all-dev libblas-dev liblapack-dev libopenmpi-dev openmpi-bin gsl-bin libgsl-dev python perl libhdf5-dev An incomplete, but perhaps helpful, list of packages for Ubuntu 18.04 LTS: :: apt-get install gcc g++ gfortran cmake libboost-all-dev libblas-dev liblapack-dev libopenmpi-dev openmpi-bin gsl-bin libgsl-dev python perl Other possibly helpful package names: :: doxygen texlive-latex-base openjdk-11-jre-headless .. _devenv-mac: ------- Mac OS ------- A number of approaches can be used to satisfy Dakota's dependencies on macOS / OS X. Typically the OS-provided Accelerate linear algebra suffices. These are listed in reverse chronological order, in hopes of archiving useful information, with the first being the most promising approach currently. .. note:: Mac SIP and other security features can be highly problematic when running Dakota tests or even using the Dakota binaries. .. note:: If you build your own toolchains, make sure that the TPLs are built with the compiler you intend to use for Dakota and not the system compiler. .. _devenv-mac-clang-homebrew: **Verified on macOS Tahoe (Apple Silicon):** System Clang + GFortran + Homebrew Uses system-provided clang/clang++, VecLib/Accelerate for linear algebra, with Homebrew for the remaining dependencies. 1. Follow the instructions on the `Homebrew `_ website to install Homebrew. 2. Install packages:: brew install cmake gcc open-mpi boost@1.85 gsl hdf5 openjdk ``gcc`` is installed for GFortran only; C and C++ use Apple Clang. ``boost@1.85`` is used rather than the unversioned ``boost`` formula to ensure a known-working version. 3. Set ``JAVA_HOME`` for the CMake configure step (only needed for ``DAKOTA_JAVA_SURROGATES``):: export JAVA_HOME=/opt/homebrew/opt/openjdk 4. Sample basic build (from the build directory):: cmake \ -D CMAKE_Fortran_COMPILER=gfortran \ -D BOOST_ROOT=/opt/homebrew/Cellar/boost@1.85/1.85.0_3 \ -D DAKOTA_HAVE_MPI=ON \ -D DAKOTA_HAVE_HDF5=ON \ -D HDF5_ROOT=/opt/homebrew/Cellar/hdf5/2.2.0 \ -D DAKOTA_HAVE_GSL=ON \ -D GSL_ROOT_DIR=/opt/homebrew/Cellar/gsl/2.8 \ /path/to/dakota/source Adjust the Cellar version numbers to match what Homebrew installed (``brew info boost@1.85`` etc. will show the installed path). CMake will use system Apple Clang for C and C++ by default. Linear algebra is satisfied by the system VecLib/Accelerate framework.