From 5d1a5c0fc52a456613da1270e5062539fa657b7d Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 22 Apr 2021 13:52:57 -0400 Subject: [PATCH 01/21] Modif L. Salomon --- .../source/AdvancedFunctionalities.rst | 4 +- doc/user_guide/source/Installation.rst | 5 ++- doc/user_guide/source/Introduction.rst | 42 ++++++++++++++----- doc/user_guide/source/LibraryMode.rst | 4 +- doc/user_guide/source/TricksOfTheTrade.rst | 4 +- 5 files changed, 41 insertions(+), 18 deletions(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 4d54bc94..c2beeb97 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -22,7 +22,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: @@ -82,7 +82,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``. diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index 4630ffc3..526b8f6b 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -125,7 +125,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 `_ or `Homebrew `_. +.. 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 `_ or `Homebrew `_. Testing installation diff --git a/doc/user_guide/source/Introduction.rst b/doc/user_guide/source/Introduction.rst index 97bb7c1d..1c386cb4 100644 --- a/doc/user_guide/source/Introduction.rst +++ b/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,24 +75,31 @@ 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) @@ -90,7 +107,8 @@ NOMAD 3 was created and developed by Charles Audet, Sebastien Le Digabel, Christ 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. diff --git a/doc/user_guide/source/LibraryMode.rst b/doc/user_guide/source/LibraryMode.rst index 381e8fa5..4c07f572 100644 --- a/doc/user_guide/source/LibraryMode.rst +++ b/doc/user_guide/source/LibraryMode.rst @@ -139,7 +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 \sComp{NOMAD} is used for all NOMAD types, and you must type ``NOMAD::`` +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 @@ -395,7 +395,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: diff --git a/doc/user_guide/source/TricksOfTheTrade.rst b/doc/user_guide/source/TricksOfTheTrade.rst index 8b969442..3ebe0d40 100644 --- a/doc/user_guide/source/TricksOfTheTrade.rst +++ b/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 ` - 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` From baad264be27e1556e3f46a513e3130844b49fb47 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Fri, 23 Apr 2021 10:41:23 -0400 Subject: [PATCH 02/21] add link to doxygen documentation --- doc/user_guide/source/AdvancedFunctionalities.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index c2beeb97..f3e4e303 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -220,6 +220,11 @@ only for point evaluation. An example of usage of PSD-MADS in library mode is in ``$NOMAD_HOME/examples/advanced/library/PSDMads``. +Doxygen +------- + +The local doxygen documentation can be consulted by opening ``$NOMAD_HOME/doc/doxygen/html/index.html``. + .. topic:: References From a6efb4ce59a1778a8e80357ecdd7efc58c1b62e0 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Fri, 23 Apr 2021 11:18:23 -0400 Subject: [PATCH 03/21] Add nomad binary test for nomad version --- doc/user_guide/source/Installation.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index 526b8f6b..777a1ac1 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -107,7 +107,6 @@ Additionally a symbolic link to ``nomad`` binary is available:: - Bulding for debug version """"""""""""""""""""""""" @@ -135,7 +134,15 @@ 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 From 8b1f7857f944e795cb883224f3d99608dcfe09bf Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:43:28 -0400 Subject: [PATCH 04/21] Update README.txt Add the directives to build a single target --- README.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.txt b/README.txt index eadee742..a3d9b2ef 100644 --- a/README.txt +++ b/README.txt @@ -90,7 +90,7 @@ cmake -S . -B build/release ---> Create the CMake files and directories for cmake -DTEST_OPENMP=OFF -S . -B build/release -cmake --build build/release ---> Build the libraries and applications +cmake --build build/release ---> Build all the libraries and applications Option --parallel xx can be added for faster build @@ -101,6 +101,13 @@ cmake --install build/release ---> Copy binaries and headers in The executable "nomad" will installed into the directory: build/release/bin/ (build/debug/bin/ when in debug mode). +It is possible to only build a single application in its working directory. +To build an example, + +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): From 548608a70e45894b57f37dadc52107df3dbf3e22 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:44:32 -0400 Subject: [PATCH 05/21] Update README.txt v++ --- README.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.txt b/README.txt index a3d9b2ef..82c13609 100644 --- a/README.txt +++ b/README.txt @@ -101,8 +101,7 @@ cmake --install build/release ---> Copy binaries and headers in The executable "nomad" will installed into the directory: build/release/bin/ (build/debug/bin/ when in debug mode). -It is possible to only build a single application in its working directory. -To build an example, +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 From 1bc89b7c92800d96cf5530c38220e2a3eb095bbd Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:48:32 -0400 Subject: [PATCH 06/21] Update README.txt v++ --- README.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/README.txt b/README.txt index 82c13609..505629b2 100644 --- a/README.txt +++ b/README.txt @@ -102,6 +102,7 @@ The executable "nomad" will installed into the directory: build/release/bin/ (build/debug/bin/ when in debug mode). 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 From 0189612c357f343c6018245f103efe22149bed04 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:51:14 -0400 Subject: [PATCH 07/21] Update Installation.rst Add directives to build specific target --- doc/user_guide/source/Installation.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index 777a1ac1..d8edb165 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -84,12 +84,18 @@ The command can be modified to enable/disable some options (see side bar). 2- Build """""""" -Build the libraries and applications:: +Build all the libraries and applications:: cmake --build build/release Option ``--parallel xx`` can be added for faster build +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 + 3- Install """""""""" From 21129081ee7b30c4ef12401095a3fab7377dda65 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:52:43 -0400 Subject: [PATCH 08/21] Update Installation.rst v++ --- doc/user_guide/source/Installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index d8edb165..f0f2e5ef 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -94,7 +94,7 @@ It is possible to build only a single application in its working directory (with cd $NOMAD_HOME/examples/basic/library/example1 cmake --build $NOMAD_HOME/build/release --target example1_lib.exe - cmake --install $NOMAD_HOME/build/release +v++ 3- Install """""""""" From 262cd0392b6630d9e8dbb563a125d083d288ec0e Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:53:16 -0400 Subject: [PATCH 09/21] Update Installation.rst --- doc/user_guide/source/Installation.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index f0f2e5ef..76255c41 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -94,7 +94,6 @@ It is possible to build only a single application in its working directory (with cd $NOMAD_HOME/examples/basic/library/example1 cmake --build $NOMAD_HOME/build/release --target example1_lib.exe -v++ 3- Install """""""""" From 902dc4f9866e55da9f3b6b1566d6ce8158719cfb Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Thu, 27 May 2021 10:56:12 -0400 Subject: [PATCH 10/21] Update Installation.rst --- doc/user_guide/source/Installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index 76255c41..b49a2ef9 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -90,7 +90,7 @@ Build all the libraries and applications:: Option ``--parallel xx`` can be added for faster build -It is possible to build only a single application in its working directory (with NOMAD_HOME environment variable properly set):: +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 From c1fef7776b0429c55eb724d964eb70ae7008c893 Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 16:40:14 -0400 Subject: [PATCH 11/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index f3e4e303..0e0ef6c1 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -220,6 +220,13 @@ 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 restart +-------- + +Information to be added shortly + Doxygen ------- From d2f26c0f45255e2cc346bf73b20fdc70ea10b9ed Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 16:57:42 -0400 Subject: [PATCH 12/21] Info on hot restart --- .../source/AdvancedFunctionalities.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 0e0ef6c1..6b78abda 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -222,10 +222,22 @@ An example of usage of PSD-MADS in library mode is in .. _hot_restart: -Hot restart +Hot and Warm Restart -------- -Information to be added shortly +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. + +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 ``LH_SEARCH 0 20``. +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. + Doxygen ------- From a3070fcf9eb8977195098cd72bf7fa9a77e9393f Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 16:58:47 -0400 Subject: [PATCH 13/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 6b78abda..59e13963 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -223,7 +223,7 @@ An example of usage of PSD-MADS in library mode is in .. _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. From 149053e071931bc7432467d2ee3ece86ea02187b Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 16:59:35 -0400 Subject: [PATCH 14/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 59e13963..77a3610b 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -225,8 +225,8 @@ An example of usage of PSD-MADS in library mode is in 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. +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. From f6f6432c4b712a8967ebe1dccfbd2333f797cbd7 Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 17:00:58 -0400 Subject: [PATCH 15/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 77a3610b..4a33a46b 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -231,6 +231,9 @@ In the case of hot restart, the user interrupts the solver to change the value o 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 ``LH_SEARCH 0 20``. @@ -238,6 +241,10 @@ 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 +"""""""""""" + +(Info to be added shortly). Doxygen ------- From 34811c02cf676c4af616c18f5f350c5e2ac4c66f Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 17:12:42 -0400 Subject: [PATCH 16/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 4a33a46b..55a1cd62 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -236,7 +236,8 @@ 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 ``LH_SEARCH 0 20``. +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. @@ -244,7 +245,14 @@ the command ``CTRL-D``. The new parameter values will be taken into account. Warm restart """""""""""" -(Info to be added shortly). +To enable warm restart, set parameters ``HOT_RESTART_READ_FILES`` and ``HOT_RESTART_WRITE_FILES`` to ``true``. +When NOMAD has run, 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 ------- From 52af38620dbba4f93a0b2a3487ca86ca7d362f32 Mon Sep 17 00:00:00 2001 From: Viviane Rochon Montplaisir Date: Fri, 18 Jun 2021 17:13:48 -0400 Subject: [PATCH 17/21] Update AdvancedFunctionalities.rst --- doc/user_guide/source/AdvancedFunctionalities.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 55a1cd62..8968eaff 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -245,8 +245,8 @@ the command ``CTRL-D``. The new parameter values will be taken into account. Warm restart """""""""""" -To enable warm restart, set parameters ``HOT_RESTART_READ_FILES`` and ``HOT_RESTART_WRITE_FILES`` to ``true``. -When NOMAD has run, files ``hotrestart.txt`` and ``cache.txt`` are written to the problem directory. +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. From 5529bcbf2c47f4d3f3f163335e70185627ab78ea Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Tue, 22 Jun 2021 15:11:29 -0400 Subject: [PATCH 18/21] The html files of the Doxygen doc will not be provided anymore. Explain how to obtain them. --- doc/user_guide/source/AdvancedFunctionalities.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/source/AdvancedFunctionalities.rst b/doc/user_guide/source/AdvancedFunctionalities.rst index 8968eaff..3ec67a6c 100644 --- a/doc/user_guide/source/AdvancedFunctionalities.rst +++ b/doc/user_guide/source/AdvancedFunctionalities.rst @@ -257,7 +257,7 @@ NOMAD will start where it was, with evaluation 101. Doxygen ------- -The local doxygen documentation can be consulted by opening ``$NOMAD_HOME/doc/doxygen/html/index.html``. +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 From 0e3d210cc1c79ad66e304c02d29844aa92287139 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Wed, 30 Jun 2021 10:20:54 -0400 Subject: [PATCH 19/21] Add comment for Windows Release build --- doc/user_guide/source/Installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/source/Installation.rst b/doc/user_guide/source/Installation.rst index b49a2ef9..f3aef2b3 100644 --- a/doc/user_guide/source/Installation.rst +++ b/doc/user_guide/source/Installation.rst @@ -88,7 +88,9 @@ Build all the libraries and applications:: cmake --build build/release -Option ``--parallel xx`` can be added for faster build +Option ``--parallel xx`` can be added for faster build. + +Option ``--config Release`` should be used on *Windows* to compile in Release configuration. The default configuration is Debug. It is possible to build only a single application in its working directory:: From 1dfe4d70ac2f875af00f07b89e3f131e9bd72d48 Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Wed, 30 Jun 2021 10:30:51 -0400 Subject: [PATCH 20/21] Update README.txt Add some information to build for Release in Windows. --- README.txt | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/README.txt b/README.txt index 505629b2..a7c81563 100644 --- a/README.txt +++ b/README.txt @@ -71,7 +71,7 @@ nomad@gerad.ca COMPILATION (Release): -On Linux, Unix, and Mac OS X, NOMAD can be compiled using CMake. +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. @@ -86,17 +86,25 @@ cmake -S . -B build/release ---> Create the CMake files and directories for cmake -DTIME_STATS=ON -S . -B build/release To enable interfaces (C and Python) building: cmake -DBUILD_INTERFACES=ON -S . -B build/release + Python and Cython need to be available; + using Anaconda is recommended. To deactivate compilation with OpenMP: cmake -DTEST_OPENMP=OFF -S . -B build/release cmake --build build/release ---> Build all the libraries and applications Option --parallel xx can be added for faster - build + build. + Option --config Release should be used on + *Windows* to compile in Release configuration. + The default configuration is Debug. cmake --install build/release ---> Copy binaries and headers in - build/release/[bin, include, lib] - and in the examples/tests directories + build/release/[bin, include, lib] + and in the examples/tests directories. + Option --config Release should be used on + Windows to install in Release configuration. + The default configuration is Debug. The executable "nomad" will installed into the directory: build/release/bin/ (build/debug/bin/ when in debug mode). @@ -129,8 +137,8 @@ EXAMPLES OF OPTIMIZATION: Batch Mode: There are examples in batch mode in examples/basic/batch/. -In each directory, the blackbox (usually named bb.exe) may be compiled using -the provided makefile. +In each directory, the blackbox (usually named bb) may be compiled using +the provided makef. The problem may be resolved using NOMAD and the parameter file: nomad param.txt From 75754f256f85d4caaf787949337ee0430933c1fe Mon Sep 17 00:00:00 2001 From: Christophe Tribes Date: Wed, 30 Jun 2021 10:41:51 -0400 Subject: [PATCH 21/21] Update README.txt More changes for Windows --- README.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.txt b/README.txt index a7c81563..241d9acf 100644 --- a/README.txt +++ b/README.txt @@ -123,10 +123,14 @@ 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 build + Debug, RelWithDebugInfo, MinSizeRel, Release); + flag CMAKE_BUILD_TYPE is ignored. cmake --build build/debug ---> Build the libraries and applications Option --parallel xx can be added for faster - build + build. + On Windows, the default configuration is Debug. cmake --install build/debug ---> Copy binaries and headers in build/debug/[bin, include, lib] @@ -137,8 +141,7 @@ EXAMPLES OF OPTIMIZATION: Batch Mode: There are examples in batch mode in examples/basic/batch/. -In each directory, the blackbox (usually named bb) may be compiled using -the provided makef. +In each directory, the blackbox (usually named bb) are compiled by default. The problem may be resolved using NOMAD and the parameter file: nomad param.txt