User Resources

Basic installation

ROL is released through the Trilinos project. To browse ROL code, click here.

Trilinos uses Git for version control and distribution, and CMake for building and installing the headers and libraries. As of March 1, 2023, the following are the prerequisites for a successful installation:

C++17 compatible compiler
CMake 3.23
LAPACK and BLAS libraries that can be located by cmake

ROL only requires the Teuchos package from Trilinos. ROL optionally interfaces with many Trilinos packages; please consult their documentation for additional prerequisites. ROL does not require MPI libraries, however other Trilinos packages may require MPI.

To download a copy of Trilinos, including ROL, run:

>> git clone https://github.com/trilinos/Trilinos.git

The cloned directory Trilinos forms the source tree. ROL’s source code is located in the directory Trilinos/packages/rol. To build ROL, create a build tree separate from the source tree. A basic ROL build follows these steps:

>> mkdir rol >> cd rol >> git clone https://github.com/trilinos/Trilinos.git >> mkdir build >> cd build >> cmake -D CMAKE_BUILD_TYPE:STRING=RELEASE \ -D BUILD_SHARED_LIBS:BOOL=ON \ -D Trilinos_ENABLE_ROL:BOOL=ON \ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=OFF \ -D Trilinos_ENABLE_TESTS:BOOL=OFF \ -D Trilinos_ENABLE_EXAMPLES:BOOL=OFF \ -D ROL_ENABLE_TESTS=ON \ -D ROL_ENABLE_EXAMPLES=ON \ -D CMAKE_INSTALL_PREFIX:PATH=install \ ../Trilinos >> make -j20 install >> cd packages/rol >> ctest

If all tests pass, ROL is successfully installed. The headers and the libraries are in the subdirectories install/include and install/lib, respectively, of the build directory.

Advanced installation

For more complex builds, including the PDE-OPT test suite and interfaces to other Trilinos packages, it is best to consider an MPI build. In the following, we assume the knowledge of the basic installation procedure above. A key additional requirement is an MPI library, e.g., OpenMPI or MPICH, which cmake must be able to locate.

To build ROL with all its optional Trilinos dependencies, which also enables the PDE-OPT application development kit and test suite, follow these steps:

>> mkdir rol
>> cd rol
>> git clone https://github.com/trilinos/Trilinos.git
>> mkdir build
>> cd build
>> cmake -D CMAKE_BUILD_TYPE:STRING=RELEASE \
-D TPL_ENABLE_MPI:BOOL=ON \
-D BUILD_SHARED_LIBS:BOOL=ON \
-D Trilinos_ENABLE_EXPLICIT_INSTANTIATION:BOOL=ON \
-D Trilinos_ENABLE_ROL:BOOL=ON \
-D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
-D Trilinos_ENABLE_TESTS:BOOL=OFF \
-D Trilinos_ENABLE_EXAMPLES:BOOL=OFF \
-D ROL_ENABLE_TESTS=ON \
-D ROL_ENABLE_EXAMPLES=ON \
-D CMAKE_INSTALL_PREFIX:PATH=install \
../Trilinos
>> make -j20 install
>> cd packages/rol
>> ctest

If all tests pass, ROL is successfully installed. The headers and the libraries are in the directories build/install/include and build/install/lib, respectively. Note that the PDE-OPT examples are available in the directory build/packages/rol/example/PDE-OPT.

Tutorials

We are currently developing easy-to-use Python tutorials. For now, see the C++ examples in the source directory:

Trilinos/packages/rol/tutorial

They include demonstrations of of unconstrained optimization (example_unc.cpp), constrained optimization (example_ineq_bnd.cpp) and simulation-constrained optimization using ROL’s SimOpt inerface (rocket-simopt).

User Guide

We are working on a comprehensive user guide. We expect to release it by the end of 2023.

License

ROL is open-source software, released through the Trilinos Project under a BSD-compatible license. The license text is as follows:

(Begin notice)

               Rapid Optimization Library (ROL) Package
                 Copyright (2014) Sandia Corporation

Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
license for use of this work by or on behalf of the U.S. Government.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3. Neither the name of the Corporation nor the names of the
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

(End notice)