###################################################################################
#                                                                                 #
#                                    README                                       #
#                                                                                 #
#---------------------------------------------------------------------------------#
#  NOMAD - Nonlinear Optimization by Mesh Adaptive Direct Search -                #
#                                                                                 #
#  NOMAD - Version 4 has been created and developed by                            #
#                 Viviane Rochon Montplaisir  - Polytechnique Montreal            #
#                 Christophe Tribes           - Polytechnique Montreal            #
#                                                                                 #
#  The copyright of NOMAD - version 4 is owned by                                 #
#                 Charles Audet               - Polytechnique Montreal            #
#                 Sebastien Le Digabel        - Polytechnique Montreal            #
#                 Viviane Rochon Montplaisir  - Polytechnique Montreal            #
#                 Christophe Tribes           - Polytechnique Montreal            #
#                                                                                 #
#  NOMAD 4 has been funded by Rio Tinto, Hydro-Québec, Huawei-Canada,             #
#  NSERC (Natural Sciences and Engineering Research Council of Canada),           #
#  InnovÉÉ (Innovation en Énergie Électrique) and IVADO (The Institute            #
#  for Data Valorization)                                                         #
#                                                                                 #
#  NOMAD v3 was created and developed by Charles Audet, Sebastien Le Digabel,     #
#  Christophe Tribes and Viviane Rochon Montplaisir and was funded by AFOSR       #
#  and Exxon Mobil.                                                               #
#                                                                                 #
#  NOMAD v1 and v2 were created and developed by Mark Abramson, Charles Audet,    #
#  Gilles Couture, and John E. Dennis Jr., and were funded by AFOSR and           #
#  Exxon Mobil.                                                                   #
#                                                                                 #
#  Contact information:                                                           #
#    Polytechnique Montreal - GERAD                                               #
#    C.P. 6079, Succ. Centre-ville, Montreal (Quebec) H3C 3A7 Canada              #
#    e-mail: nomad@gerad.ca                                                       #
#                                                                                 #
#  This program is free software: you can redistribute it and/or modify it        #
#  under the terms of the GNU Lesser General Public License as published by       #
#  the Free Software Foundation, either version 3 of the License, or (at your     #
#  option) any later version.                                                     #
#                                                                                 #
#  This program is distributed in the hope that it will be useful, but WITHOUT    #
#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or          #
#  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License    #
#  for more details.                                                              #
#                                                                                 #
#  You should have received a copy of the GNU Lesser General Public License       #
#  along with this program. If not, see <http://www.gnu.org/licenses/>.           #
#                                                                                 #
#  You can find information on the NOMAD software at www.gerad.ca/nomad           #
#---------------------------------------------------------------------------------#

DESCRIPTION:

NOMAD is a C++ implementation of the Mesh Adaptive Direct Search (MADS)
algorithm, designed for constrained optimization of black-box functions.

The algorithms implemented are based on the book
"Derivative-Free and Blackbox Optimization", by Charles Audet and Warren Hare,
Springer 2017.


WEB PAGES:

https://www.gerad.ca/nomad/
Https://github.com/bbopt/nomad


CONTACT:

nomad@gerad.ca


VERSION WARNING:

This repository is for NOMAD 4. The previous version, NOMAD 3, 
is not on GitHub. NOMAD 3 will be deprecated in the future.

NOMAD 4 is similar in usage to NOMAD 3. 

NOMAD 4 has a new software architecture, uses OpenMP to run 
evaluations in parallel, and also has some new functionalities.


COMPILATION (Release):

On Linux, Unix, Windows and Mac OS X, NOMAD can be compiled using CMake.
The minimum version of CMake is 3.14. Older versions will trigger
an error. A recent C++ compiler is also required.

Before starting the procedure we recommend to set the environment variable 
$NOMAD_HOME with the path where NOMAD has been copied. For Linux and OSX,

export NOMAD_HOME=/home/myUserName/PathToNomad

For Windows, add an environment variable %NOMAD_HOME% containing the path.
The remaining text uses the $NOMAD_HOME environment variable.

The procedure is the following. On the command line in the
 $NOMAD_HOME directory:

cmake -S . -B build/release     
    ---> Create the CMake files and directories for building (-B) in build/release.
         The source (-S) CMakeLists.txt file is in the $NOMAD_HOME directory.

         To deactivate compilation with OpenMP:
              cmake -DTEST_OPENMP=OFF -S . -B build/release

         To enable *C interface* building:
              cmake -DBUILD_INTERFACE_C=ON -S . -B build/release

         To enable *Matlab* interface building:
              cmake -DBUILD_INTERFACE_MATLAB=ON  -DTEST_OPENMP=OFF -S . -B build/release

              ! Before proceeding, have a look into 
              $NOMAD_HOME/interfaces/Matlab_MEX/readme.txt

              ! Extra flags might be required to prevent CMake errors. 

              ! Compiler version and Matlab version need to be compatible;
              ! Check https://www.mathworks.com/support/requirements/supported-compilers.html
               
              ! The Matlab interface will not be built if OpenMP is enabled.

              ! An extra addpath Matlab command must be done to have access 
              to nomad Mex binaries:
              addpath(strcat(getenv('NOMAD_HOME'),'/build/release/bin'))

         To enable *Python* interface (PyNomad) building:
              cmake -DBUILD_INTERFACE_PYTHON=ON -DTEST_OPENMP=OFF -S . -B build/release

              ! Before proceeding, have a look into 
              $NOMAD_HOME/interfaces/PyNomad/readme.txt

	      ! The Python interface will not be built if OpenMP is enabled.

              ! More details are provided in $NOMAD_HOME/interfaces/PyNomad/readme.txt 
             
              ! Building requires to have Cython. Cython can be obtained with
              Anaconda distribution platform.
  
              ! On *Windows*, using Visual Studio, see the user guide or the readme
              to properly manage X86/X64 building of binaries. 
              
         To enable *Java* interface building (with Swig):
              cmake -DBUILD_INTERFACE_JAVA=ON -S . -B build/release

cmake --build build/release --config Release (for *Windows*)
or
cmake --build build/release (for *OSX* and *Linux*)
    ---> Build all the libraries and applications
    
         Option --parallel xx can be added for faster build.

         The option --config Release should be used on *Windows* to build only
         Release configuration. The default configuration is Debug.

cmake --install build/release --config Release (for *Windows*)
or
cmake --install build/release (for *OSX* and *Linux*)
    ---> Copy binaries and headers in build/release/[bin, include, lib]
         and in the examples/tests directories.

By default, the executable "nomad" will be installed into the directory:
build/release/bin/  (build/debug/bin/ when in debug mode). A symbolic link
is added in the bin directory (not functional for windows).

It is possible to build only a single application in its working directory:
(with NOMAD_HOME environment variable properly set)

cd $NOMAD_HOME/examples/basic/library/example1
cmake --build $NOMAD_HOME/build/release --target example1_lib.exe
cmake --install $NOMAD_HOME/build/release


COMPILATION (Debug):

The procedure to build the debug version is the following.
On the command line in the $NOMAD_HOME directory:

cmake -S . -B build/debug -D CMAKE_BUILD_TYPE=Debug
    ---> On *Windows*, all 4 configurations are configured
         (Debug, RelWithDebugInfo, MinSizeRel, Release); flag 
         CMAKE_BUILD_TYPE is ignored.

cmake --build build/debug --config Debug (for *Windows*)
or
cmake --build build/debug (for *OSX* and *Linux*)   
    ---> Build the libraries and applications
         
         Option --parallel xx can be added for faster build.

cmake --install build/debug --config Debug (for *Windows*)
or
cmake --install build/debug  (for *OSX* and *Linux*)
    ---> Copy binaries and headers in build/debug/[bin, include, lib]
         and in the examples/tests directories


EXAMPLES OF OPTIMIZATION:

Batch Mode:
There are examples in batch mode in $NOMAD_HOME/examples/basic/batch/.
In each directory, the blackbox functions (usually named bb) are compiled 
by default. The problem may be resolved using NOMAD and the parameter file:

$NOMAD_HOME/build/release/bin/nomad param.txt

For convenience, the path to $NOMAD_HOME/build/release/bin directory 
can be added to the $PATH environment variable. For *Windows*, this is 
achieved by setting the parameters for environment variable %PATH% to
%NOMAD_HOME\build\release\bin\
 

Library Mode:
There are examples in library mode in $NOMAD_HOME/examples/basic/library/.
In each directory, the executable may be compiled when building
Nomad application. The problems may be resolved by execution,
for instance:

./example_lib.exe

IMPORTANT: Library mode examples with *Windows* require to set 
the %PATH% environment variable (see above). Otherwise, the executables
cannot find NOMAD dlls.