###################################################################################
#                                                                                 #
#                                    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 PAGE:

https://www.gerad.ca/nomad/


CONTACT:

nomad@gerad.ca


VERSION WARNING:

This repository is for NOMAD 4. NOMAD 3 is not on GitHub.

NOMAD 4 is similar in usage to NOMAD 3. It does not have all
functionalities from NOMAD 3 yet. 

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
              ! 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. 
              
              ! Extra flags might be required to prevent CMake errors. See details 
              in User Guide (Section Matlab interface).

         To enable *Python* interface (PyNomad) building:
              cmake -DBUILD_INTERFACE_PYTHON=ON -DTEST_OPENMP=OFF -S . -B build/release
             
              ! Building requires to have Cython. Cython can be obtained with
              Anaconda distribution platform.

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

              ! On *Windows*, using Visual Studio, see the user guide 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 installed into the directory:
build/release/bin/  (build/debug/bin/ when in debug mode). A symbolic link
is added in the bin directory for OSX and Linux. 

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 always prepared
         (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

BINARIES:
Nomad libraries are available in a Julia package for some plateforms at 
https://github.com/JuliaBinaryWrappers/NOMAD_jll.jl/tree/main

BINARIES:
Nomad libraries are available in a Julia package for some plateforms at 
https://github.com/JuliaBinaryWrappers/NOMAD_jll.jl/tree/main


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%. 

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


NOTE:

We recommend to download the complete NOMAD source files and examples and build the project for your platform. For users who do not follow this recommendation, a compact version with binaries (zipped) are available for Windows, Mac-OSX and Linux Ubuntu in the Assets section of the Release. 

For OSX: After download and unzip, the binaries must be de-quarantined (OSX will not let you run the executables)
To remove the quarantine:
         xattr -d com.apple.quarantine ./bin/nomad 
         xattr -d com.apple.quarantine ./lib/libnomadUtils.4.3.0.dylib
         xattr -d com.apple.quarantine ./lib/libnomadEval.4.3.0.dylib
         xattr -d com.apple.quarantine ./lib/libnomadAlgos.4.3.0.dylib
         xattr -d com.apple.quarantine ./lib/libsgtelib.2.0.3.dylib
The rpath needs also to be changed:
         install_name_tool -rpath /Users/runner/work/nomad/nomad/instdir/lib @loader_path/../lib ./bin/nomad


For Linux, due to different compiler versions and available standard libraries, the binaries will most likely not be executable. If they are, you may still need to change the LD_LIBRARY_PATH variable to find the nomad shared object libraries (lib/libnomad*.so.*).

For Windows, you may want to update the %PATH% environment variable to add the directory where the executable and the dll have been put (for example: C:\Users\Unknown\Downloads\windows-latest\bin).