Merge branch 'master' into develop

README.txt

@@ -105,7 +105,7 @@ cmake --build build/release     ---> Build all the libraries and applications
                                      Option --parallel xx can be added for faster
                                        build.
                                      Option --config Release should be used on
-                                       *Windows* to compile in Release configuration.
+                                       *Windows* to compile Release configuration.
                                      The default configuration is Debug.
 
 cmake --install build/release   ---> Copy binaries and headers in

doc/user_guide/source/AdvancedFunctionalities.rst

@@ -39,7 +39,7 @@ The parameter may be entered with several types of arguments:
 * A vector of :math:`n` values with format ``(v0 v1 ... vn-1)``. Character ``-`` is used for free variables.
 
 * An index range if at least one starting point has been defined. ``FIXED_VARIABLE i-j``: variables ``i`` to ``j``
-  are fixed to their initial (``i-j`` may be replaced by ``i`` only). See :ref`x0` for practical examples of index ranges.
+  are fixed to their initial (``i-j`` may be replaced by ``i`` only). See :ref:`x0` for practical examples of index ranges.
 
 .. _seed:
 
@@ -113,7 +113,7 @@ The possible syntaxes to specify the granularity of the variables are as follows
 
 * :math:`n` real values with format ``GRANULARITY (v0 v1 ... vn-1)``.
 
-* ``GRANULARITY i-j v``: coordinates  ``i` to  ``j`` set to ``v``.
+* ``GRANULARITY i-j v``: coordinates  ``i`` to  ``j`` set to ``v``.
 
 * ``GRANULARITY * v``: all coordinates set to ``v``.
 
@@ -270,6 +270,45 @@ only for point evaluation.
 An example of usage of PSD-MADS in library mode is in
 ``$NOMAD_HOME/examples/advanced/library/PSDMads``.
 
+.. _hot_restart:
+
+Hot and Warm Restart
+--------------------
+
+This new feature of NOMAD 4 makes it possible to continue the solving process after it has started, 
+without having to restart it from the beginning.
+In the case of hot restart, the user interrupts the solver to change the value of a parameter. 
+With warm restart, the user changes a parameter from a resolution that has already reached a termination condition. 
+In both cases, the solving process is then continued from its current state.
+
+Hot restart
+"""""""""""
+
+To enable hot restart, set parameter ``HOT_RESTART_ON_USER_INTERRUPT`` to ``true``.
+While NOMAD is running, interrupt the run with the command ``CTRL-C``.
+New values for parameters may be entered.
+For example, entering ``LH_SEARCH 0 20`` will make LH search be used for the rest of the optimization.
+The syntax is the same as the syntax of a parameter file, when in batch mode.
+When all new parameter values are entered, continue optimization by entering
+the command ``CTRL-D``. The new parameter values will be taken into account.
+
+Warm restart
+""""""""""""
+
+To enable warm restart, parameters ``HOT_RESTART_READ_FILES`` and ``HOT_RESTART_WRITE_FILES`` need to be set to ``true``.
+When NOMAD runs a first time, files ``hotrestart.txt`` and ``cache.txt`` are written to the problem directory.
+This information is used if NOMAD is run a second time.
+Instead of redoing the same optimization, NOMAD will continue where it was when the first run was ended.
+For example, suppose the first NOMAD run stopped at evaluation 100 because the value of parameter ``MAX_BB_EVAL`` was 100.
+The user still has room for 50 more evaluations.
+The parameter file may be changed with value ``MAX_BB_EVAL 150``, and the second run of
+NOMAD will start where it was, with evaluation 101.
+
+Doxygen
+-------
+
+A local doxygen documentation can be created by running the ``doxygen`` command (if available) in ``$NOMAD_HOME/doc/doxygen``. The documentation can be opened by a browser at ``$NOMAD_HOME/doc/doxygen/html/index.html``.
+
 
 .. topic:: References
 

doc/user_guide/source/Installation.rst

@@ -98,6 +98,11 @@ For Windows, the default configuration is Debug. To obtain the Release version::
 
 Option ``--parallel xx`` can be added for faster build
 
+It is possible to build only a single application in its working directory::
+
+  cd $NOMAD_HOME/examples/basic/library/example1
+  cmake --build $NOMAD_HOME/build/release --target example1_lib.exe
+
 3- Install
 """"""""""
 
@@ -117,7 +122,6 @@ Additionally a symbolic link to ``nomad`` binary is available::
 
 
 
-
 Bulding for debug version
 """""""""""""""""""""""""
 
@@ -136,7 +140,10 @@ Use another compiler
 
 The environment variables ``CC`` and ``CXX`` can be used to select the ``C`` and ``C++`` compilers.
 
-.. note:: ``Clang`` is the default compiler for Mac OSX using XCode. Users of Mac OSX can install ``GCC`` compilers using `MacPorts <https://www.macports.org/>`_ or `Homebrew <http://brew.sh/>`_.
+.. note:: ``Clang`` is the default compiler for Mac OSX using XCode. But, *OpenMP* (used for parallel evaluations)
+   support is disabled in *Clang* that come with *Xcode*.
+   Users of Mac OSX can install and use another compiler to enable *OpenMP* support.
+   For example, ``GCC`` compilers can be obtained using `MacPorts <https://www.macports.org/>`_ or `Homebrew <http://brew.sh/>`_.
 
 
 Testing installation
@@ -145,6 +152,14 @@ Testing installation
 Once building **and installation** have been performed some tests can be performed.
 By default the examples are built and can be tested::
 
+The NOMAD binary can be tested::
+
+  $NOMAD_HOME/bin/nomad -v
+
+This should return the version number on the command line.
+
+Additionally, by default the examples are built and can be tested::
+
   cd build/release
   ctest
 

doc/user_guide/source/Introduction.rst

@@ -43,13 +43,23 @@ where the feasible set :math:`\Omega = \{ x \in X : c_j(x) \leq 0, j \in J\} \su
 Basics of the MADS algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-At the core of NOMAD resides the *Mesh Adaptive Direct Search (MADS)* algorithm. As the name implies, this method generates iterates on a series of meshes with varying size. A mesh is a discretization of the space of variables. However, also as the name implies, the algorithm performs an adaptive search on the meshes including controlling the refinement of the meshes. The reader interested in the rather technical details should read Reference [AuDe2006]_.
+At the core of NOMAD resides the *Mesh Adaptive Direct Search (MADS)* algorithm.
+As the name implies, this method generates iterates on a series of meshes with varying size.
+A mesh is a discretization of the space of variables.
+However, also as the name implies, the algorithm performs an adaptive search on the meshes including controlling the refinement of the meshes.
+The reader interested in the rather technical details should read Reference [AuDe2006]_.
 
-The objective of each iteration of the *MADS* algorithm, is to generate a trial point on the mesh that improves the current best solution. When an iteration fails to achieve this, the next iteration is initiated on a finer mesh.
+The objective of each iteration of the *MADS* algorithm, is to generate a trial point on the mesh that improves the current best solution.
+When an iteration fails to achieve this, the next iteration is initiated on a finer mesh.
 
-Each iteration is composed of two principal steps called the *Search* and the *Poll* steps [AuDe2006]_. The *Search* step is crucial in practice because it is so flexible, but it is a difficulty for the theory for the same reason. The *Search* can return any point on the underlying mesh, but of course, it is trying to identify a point that improves the current best solution.
+Each iteration is composed of two principal steps called the *Search* and the *Poll* steps [AuDe2006]_.
+The *Search* step is crucial in practice because it is so flexible and can improve the performance significantly.
+The *Search* step is constrained by the theory to return points on the underlying mesh, but of course,
+it is trying to identify a point that improves the current best solution.
 
-The *Poll* step is more rigidly defined, though there is still some flexibility in how this is implemented. The *Poll* step generates trial mesh points in the vicinity of the best current solution. Since the *Poll* step is the basis of the convergence analysis, it is the part of the algorithm where most research has been concentrated.
+The *Poll* step is more rigidly defined, though there is still some flexibility in how this is implemented.
+The *Poll* step generates trial mesh points in the vicinity of the best current solution.
+Since the *Poll* step is the basis of the convergence analysis, it is the part of the algorithm where most research has been concentrated.
 
 A high-level presentation of *MADS* is shown in the pseudo-code below.
 
@@ -65,32 +75,40 @@ Using NOMAD
 
 Minimally, users must accomplish several tasks to solve their own optimization problems:
 
-* Create a custom blackbox program(s) to evaluate the functions :math:`f` and :math:`c_j` OR embed the functions evaluations in C++ source code to be linked with the NOMAD library.
+* Create a custom blackbox program(s) to evaluate the functions :math:`f` and :math:`c_j` OR embed
+  the functions evaluations in C++ source code to be linked with the NOMAD library.
 
 * Create the optimization problem definition in a parameter file OR embed the problem definition in C++ source code to be linked with the NOMAD library.
 
 * Launch the execution at the command prompt OR from another executable system call.
 
 
-Users can find several examples provided in the installation package and described in this user guide to perform customization for their problems. The installation procedure is given in :ref:`installation`. New users should refer to :ref:`getting_started`. The most important instructions to use NOMAD are in :ref:'how_to_use_nomad'. In addition, tricks that may help solving specific problems and improve NOMAD efficiency are presented in :ref:`tricks_of_the_trade`. Advanced parameters and functionalities are presented in :ref:`advanced_functionalities`.
+Users can find several examples provided in the installation package and described in this user guide to perform customization for their problems.
+The installation procedure is given in :ref:`installation`. New users should refer to :ref:`getting_started`.
+The most important instructions to use NOMAD are in :ref:'basic_nomad_usage'.
+In addition, tricks that may help solving specific problems and improve NOMAD efficiency are presented in :ref:`tricks_of_the_trade`.
+Advanced parameters and functionalities are presented in :ref:`advanced_functionalities`.
 
 Supported platforms and environments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-NOMAD source codes are in C++ and are identical for all supported platforms. See :ref:`installation` for details to obtain binaries from the source files.
+NOMAD source codes are in C++ and are identical for all supported platforms.
+See :ref:`installation` for details to obtain binaries from the source files.
 
 Authors and fundings
 ^^^^^^^^^^^^^^^^^^^^
 
-The development of NOMAD started in 2001. Three versions of NOMAD have been developed before NOMAD 4. NOMAD 4 and NOMAD 3 are currently supported. NOMAD 4 is almost a completely new code compared with NOMAD 3.
+The development of NOMAD started in 2001. Three versions of NOMAD have been developed before NOMAD 4.
+NOMAD 4 and NOMAD 3 are currently supported. NOMAD 4 is almost a completely new code compared with NOMAD 3.
 
 NOMAD 4 has been funded by Huawei Canada, Rio Tinto, Hydro-Québec, NSERC (Natural Sciences and Engineering Research Council of Canada), InnovÉÉ (Innovation en Énergie Électrique) and IVADO (The Institute for Data Valorization)
 
 NOMAD 3 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 1 and 2 were created and developed by Mark Abramson, Charles Audet, Gilles Couture, and John E. Dennis Jr., and were funded by AFOSR and Exxon Mobil.
 
-The library for dynamic surrogates (SGTELIB) has been developed by Bastien Talgorn (bastien-talgorn@fastmail.com), McGill University, Montreal. The SGTELIB is included in NOMAD since version 3.8.0.
+The library for dynamic surrogates (SGTELIB) has been developed by Bastien Talgorn (bastien-talgorn@fastmail.com), McGill University, Montreal.
+The SGTELIB is included in NOMAD since version 3.8.0.
 
 **Developers** of the methods behind NOMAD include:
 
@@ -105,9 +123,11 @@ The library for dynamic surrogates (SGTELIB) has been developed by Bastien Talgo
 Acknowledgments
 ^^^^^^^^^^^^^^^
 
-The developers of NOMAD wish to thank Florian Chambon, Mohamed Sylla and Quentin Reynaud, all from ISIMA, for their contribution to the project during Summer internships, and to Anthony Guillou and Dominique Orban for their help with AMPL, and their suggestions.
+The developers of NOMAD wish to thank Florian Chambon, Mohamed Sylla and Quentin Reynaud, all from ISIMA, for their contribution
+to the project during Summer internships, and to Anthony Guillou and Dominique Orban for their help with AMPL, and their suggestions.
 
-A special thank to Maud Bay, Eve Bélisle, Vincent Garnier, Michal Kvasnička, Alexander Lutz, Rosa-Maria Torres-Calderon, Yuri Vilmanis, Martin Posch, Etienne Duclos, Emmanuel Bigeon, Walid Zghal, Jerawan Armstrong, Stéphane Alarie and Klaus Truemper for their feedbacks and tests that significantly contributed to improve NOMAD. Some features of NOMAD have been developed under the impulsion of enthusiastic users/developers: Andrea Ianni, Florian Chambon, Mohamed Sylla, Quentin Reynaud, Amina Ihaddadene, Bastien Talgorn, Nadir Amaioua and Catherine Poissant. We also wish to thank Pascal Côté for his contribution in the development of the Python interface pyNomad and Jonathan Currie for the development of the foundations for a strong NOMAD interface for MATLAB.
+A special thank to Maud Bay, Eve Bélisle, Vincent Garnier, Michal Kvasnička, Alexander Lutz, Rosa-Maria Torres-Calderon, Yuri Vilmanis, Martin Posch, Etienne Duclos, Emmanuel Bigeon, Walid Zghal, Jerawan Armstrong, Stéphane Alarie and Klaus Truemper for their feedbacks and tests that significantly contributed to improve NOMAD. Some features of NOMAD have been developed under the impulsion of enthusiastic users/developers: Andrea Ianni, Florian Chambon, Mohamed Sylla, Quentin Reynaud, Amina Ihaddadene, Bastien Talgorn, Nadir Amaioua and Catherine Poissant.
+We also wish to thank Pascal Côté for his contribution in the development of the Python interface pyNomad and Jonathan Currie for the development of the foundations for a strong NOMAD interface for MATLAB.
 
 The contributions of  Miguel Anjos, Romain Couderc, Miguel Diago Martinez, Solène Kojtych, Guillaume Lameynardie, Wim Lavrijsen, Alexis Montoison, Caroline Rocha, Ludovic Salomon and Renaud Saltet was highly appreciated during the development and testing of NOMAD 4.
 

doc/user_guide/source/LibraryMode.rst

@@ -139,8 +139,7 @@ is suggested that you use the NOMAD types as much as  possible. For reals, NOMAD
 and for vectors, the classes ``NOMAD::Point`` or ``NOMAD::ArrayOfDouble``.
 A lot of functionalities have been coded for theses classes, which are visible  in files ``$NOMAD_HOME/src/Math/*.hpp``.
 
-The namespace ``NOMAD`` is used for all NOMAD types, and you must type ``NOMAD::``
-in front of all types unless you type ``using namespace NOMAD;``  at the beginning of your program.
+The namespace ``NOMAD`` is used for all NOMAD types, and you must type ``NOMAD::`` in front of all types unless you type ``using namespace NOMAD;``  at the beginning of your program.
 
 Providing the blackbox evaluation of objective and constraints directly in the code avoids
 the use of temporary files and system calls by the algorithm. This is achieved by defining a derived
@@ -397,7 +396,7 @@ A C interface for NOMAD is provided for Mac OS X and Linux.
 The source codes are provided in ``$NOMAD_HOME/interfaces/CInterface/``.
 To enable the building of the C interface, option ``-DBUILD_INTERFACES=ON`` must be
 set when building NOMAD, as such: ``cmake -DBUILD_TESTS=ON -S . -B build/release``.
-The command ``cmake --install build/release`` must be run before using the PyNomad module.
+The command ``cmake --install build/release`` must be run before using the library.
 
 All functionalities of NOMAD are available in the C interface.
 NOMAD parameters are provided via these functions:

doc/user_guide/source/TricksOfTheTrade.rst

@@ -15,8 +15,8 @@ Here are a few suggestions for tuning NOMAD when facing different symptoms. The
    Quantifiable constraints	,	Try PB  EB or combinations , :ref:`bb_output_type`
    Difficult constraint , Try PB instead of EB , :ref:`bb_output_type`
    No initial point		,	 	Add a LH search , :ref:`LH Search and X0 <x0>`
-   Variables of widely , 	Change blackbox input scaling	, :ref:`create_blackbox_program`
-   Different magnitudes	, Change :math:`\Delta_0` per variable , :ref:`initial_mesh_size`
+   Variables of different magnitudes , 	Change blackbox input scaling	, :ref:`create_blackbox_program`
+   " ", Change :math:`\Delta_0` per variable , :ref:`initial_mesh_size`
    " ",	Tighten bounds , :ref:`bounds`
    Many variables ,	Fix some variables  , :ref:`fixed_variable`
    " ",	Use *PSD-MADS*  , :ref:`psd_mads`