Documentatino update, changed CADETMatch to CADET-Match where appropr…

…iate

Added UNSGA3 docs
Removed variables no longer used by NSGA3 or UNSGA3

CADETMatch/version.py

@@ -18,5 +18,5 @@
 __email__ = "[email protected]"
 __license__ = "GNU General Public License v3 (GPLv3)"
 __copyright__ = "2020 %s" % __author__
-__version__ = "0.7.7"
+__version__ = "0.7.8"
 __uri__ = "https://github.com/modsim/CADET-Match"

doc/cli/examples.rst

@@ -1,11 +1,11 @@
-CADETMatch Examples
+CADET-Match Examples
 -------------------
 
 Generating Examples and running them
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-CADETMatch can generate a complete set of examples and run them. This can be used to verify that all features used in CADETMatch
-are working correctly on your installation and to see how to run CADETMatch in various situations. The examples include variable transforms,
+CADET-Match can generate a complete set of examples and run them. This can be used to verify that all features used in CADET-Match
+are working correctly on your installation and to see how to run CADET-Match in various situations. The examples include variable transforms,
 search strategies, and search stratgies. Depending on the hardware available running the complete set of examples can hours to days.
 
 Generate examples
@@ -16,7 +16,7 @@ needs to be supplied. You can have multiple example directories that are run wit
 working correctly.
 
 The examples generated can all be run individually and the files used as a template to make your own matches. There are examples for every feature in 
-CADETMatch.
+CADET-Match.
 
 .. code-block:: bash
 

doc/cli/index.rst

@@ -1,8 +1,8 @@
 Running
 ^^^^^^^
 
-CADETMatch is designed to be used through a command line interface. It is also possible to use CADETMatch using Jupyter notebooks but this
-is not recommended for normal usage. CADETMatch has automatic checkpointing and if matching is interrupted it will resume from the last step
+CADET-Match is designed to be used through a command line interface. It is also possible to use CADET-Match using Jupyter notebooks but this
+is not recommended for normal usage. CADET-Match has automatic checkpointing and if matching is interrupted it will resume from the last step
 completed.
 
 These commands can be run from the Windows command line or from any Linux command line. These commands can also be run through cluster
@@ -19,7 +19,7 @@ control software.
 ``--generate_map`` Find the maximum a posteriori for an MCMC run 
 
 
-The following options are for genering graphs. CADETMatch generates graphs automatically periodically but these commands
+The following options are for genering graphs. CADET-Match generates graphs automatically periodically but these commands
 can be used to generate graphs immediately. These commands should be safe to run while matching is proceeding but they
 may fail if the required data has not been generated yet.
 
@@ -52,11 +52,11 @@ Generate graphs using 6 cores
     python -m CADETMatch --generate_graphs --json <path to connfiguration file> -n 6
 
 
-Running CADETMatch remotely
+Running CADET-Match remotely
 ---------------------------
 
-The most common way CADETMatch is used is by logging into a server with SSH and starting a matching session.
-These matches can take hours to days to complete and the following command allows CADETMatch to keep running
+The most common way CADET-Match is used is by logging into a server with SSH and starting a matching session.
+These matches can take hours to days to complete and the following command allows CADET-Match to keep running
 once you logout.
 
 .. code-block:: bash

doc/configuration/error.rst

@@ -1,8 +1,8 @@
 Error Modeling
 --------------
 
-CADETMatch includes error modeling and parameter estimation.
-Error modeling in CADETMatch is based on using a fitted simulation and creating an error model by manipulations to the fitted simulation.
+CADET-Match includes error modeling and parameter estimation.
+Error modeling in CADET-Match is based on using a fitted simulation and creating an error model by manipulations to the fitted simulation.
 Error modeling uses MCMC and can be a slow process which requires a lot of computing time.
 Some simple problems can be solved in a few hours on a powerful desktop and others can take weeks on a powerful server.
 

doc/configuration/experiments.rst

@@ -1,7 +1,7 @@
 Experiments
 -----------
 
-CADETMatch supports one or more experiments with one or more components. 
+CADET-Match supports one or more experiments with one or more components. 
 The basic structure is shown below.
 
 .. code-block:: json

doc/configuration/graphing.rst

@@ -1,7 +1,7 @@
 Graphing
 ^^^^^^^^
 
-Graphing in CADETMatch is done asyncronously from the normal running however it still takes computing time to generate the graphs.
+Graphing in CADET-Match is done asyncronously from the normal running however it still takes computing time to generate the graphs.
 There is a tradeoff between how frequently graphs are generated to see the progress and how much progress is slowed by generating the graphs.
 Graphs are generated at the end of a generation/step during estimation/error modeling.
 If the time in seconds since the last time graphs where generated at the end of a step than the specified time then the graphs are generated again and the time is reset.

doc/configuration/index.rst

@@ -3,8 +3,8 @@
 Configuration
 -------------
 
-CADETMatch uses a JSON based configuration file format.
-CADETMatch uses `jstyleson <https://github.com/linjackson78/jstyleson>`_ to support JSON with comments.
+CADET-Match uses a JSON based configuration file format.
+CADET-Match uses `jstyleson <https://github.com/linjackson78/jstyleson>`_ to support JSON with comments.
 You can programatically create the JSON in Python using nested dictionaries or `addict <https://github.com/mewwts/addict>`_ and then convert to JSON.
 
 Ususally, the configuration has to include:

doc/configuration/misc.rst

@@ -6,7 +6,7 @@ Most of these settings don't really fit with anything else and they should only
 ======================== =========== ================ ========== ====================================================================================================================================================
  Key                       Values       Default        Required     Description
 ======================== =========== ================ ========== ====================================================================================================================================================
-fullTrainingData           Integer       0              No        This causes CADETMatch to store ALL results of all simulations for machine learning. This can require many gigabytes of storage.
+fullTrainingData           Integer       0              No        This causes CADET-Match to store ALL results of all simulations for machine learning. This can require many gigabytes of storage.
 dynamicTolerance           Boolean       False          No        Automatically adapt the tolerance of the simulation based on search method requirements.
 abstolFactor               Float         1e-3           No        Set absTol for most searching to max(abstolFactor*smalltest_peak, abstolFactorGradMax*largest_peak)
 abstolFactorGrad           Float         1e-7           No        Set absTol for gradient descent to max(abstolFactorGrad*smalltest_peak, abstolFactorGradMax*largest_peak)

doc/configuration/scores.rst

@@ -1,7 +1,7 @@
 Scores
 ------
 
-CADETMatch has many scores available.
+CADET-Match has many scores available.
 Each score is designed to solve a particular type of problem. 
 The most common ones will be covered first.
 There are a few additional ones available in the code that are retained for backwards compatibility that will not be covered and their usage is not recomended.

doc/configuration/search.rst

@@ -1,23 +1,52 @@
 Search
 ------
 
-CADETMatch uses a number of different search strategies for parameter estimation.
+CADET-Match uses a number of different search strategies for parameter estimation.
 Parameters that are common to more than one search method will be repeated.
 The choice of search strategy is set by using searchMethod. 
 
 =================== =========== ================ ========== =========================================================================================================
  Key                  Values       Default        Required     Description
 =================== =========== ================ ========== =========================================================================================================
-searchMethod           String       NSGA3            No       Select the search method to use. (NSGA3, Multistart, GraphSpace, MCMC, AltScore, Gradient, ScoreTest)
+searchMethod           String       UNSGA3            No       Select the search method to use. (UNSGA3, NSGA3, Multistart, GraphSpace, MCMC, AltScore, Gradient, ScoreTest)
 =================== =========== ================ ========== =========================================================================================================
 
 Most of the search strategies are population based and capable of running in parallel. 
 
+UNSGA3
+^^^^^^
+
+UNSGA3 is a genetic algorithm designed for high-dimensional problems. `UNSGA3 <https://pymoo.org/algorithms/unsga3.html>`_ from pymoo is used.
+
+The difference between UNSGA3 and NSGA3 is that UNSGA3 uses a tournament selection to bread the best members instead
+of random mating. In almost all cases UNSGA3 will converge faster and to a better optimum. NSGA3 is mostly retained for backwards
+compatibility.
+
+=================== =========== ================ ========== =================================================================================================================================
+ Key                  Values       Default        Required     Description
+=================== =========== ================ ========== =================================================================================================================================
+population            Integer       100            No        Set the population size per parameter estimated.
+generations           Integer       1000           No        Set the max number of generations to population size * generations.
+sobolGeneration       Boolean       True           No        Use a sobol sequence to generate the initial population instead of random initialization
+stallGenerations      Integer       10             No        Terminate optimization after this many generations without progress
+stopAverage           Float         0.0            No        Stop searching when the average value of all metrics is less than or equal to this value
+stopBest              Float         0.0            No        Stop searching when the highest metric is less than or equal to this value
+stopRMSE              Float         0.0            No        Stop when the Root Mean Square Error is less than or equal to this value
+gradCheck             Float         0.0            No        If the geometric mean of the metrics drop below this value run gradient descent to refine the value
+finalGradRefinement   Boolean       False          No        Take the final pareto front and refine it with gradient descent
+gradFineStop          Float         1e-14          No        set xtol of scipy.optimize.least_squares
+localRefine           String        gradient       No        Can be gradient or powell
+continueMCMC          Boolean       False          No        Once search finishes start MCMC and carry over useful information automatically
+seeds                 List          None           No        Optimization can be seeded with specific values to test
+MultiObjectiveSSE     Boolean       False          No        If set to true SSE objectives are split apart and turned into a multi-objective system. This is useful for multiple experiments.
+=================== =========== ================ ========== =================================================================================================================================
+
+
 NSGA3
 ^^^^^
 
-NSGA3 is a genetic algorithm designed for high-dimensional problems.
-If only a single objective is used the system will automatically switch to NSGA2.
+NSGA3 is a genetic algorithm designed for high-dimensional problems. `NSGA3 <https://pymoo.org/algorithms/nsga3.html>`_ from pymoo is used. In most cases UNSGA3 should be used
+and NSGA3 is retained for backwards compatibility.
 
 =================== =========== ================ ========== =================================================================================================================================
  Key                  Values       Default        Required     Description
@@ -26,10 +55,6 @@ population            Integer       100            No        Set the population
 generations           Integer       1000           No        Set the max number of generations to population size * generations.
 sobolGeneration       Boolean       True           No        Use a sobol sequence to generate the initial population instead of random initialization
 stallGenerations      Integer       10             No        Terminate optimization after this many generations without progress
-stallCorrect          Integer       5              No        Increase population size (if allowed) after this many generations without progress
-progressCorrect       Integer       5              No        Decrease population size (if allowed) after this many generations with progress
-minPopulation         Integer     population       No        Allow CADETMatch to decrease the population to this size if progress is fast
-maxPopulation         Integer     population       No        Allow CADETMatch to increase the population to this size if progress stalls
 stopAverage           Float         0.0            No        Stop searching when the average value of all metrics is less than or equal to this value
 stopBest              Float         0.0            No        Stop searching when the highest metric is less than or equal to this value
 stopRMSE              Float         0.0            No        Stop when the Root Mean Square Error is less than or equal to this value

doc/configuration/transform.rst

@@ -1,7 +1,7 @@
 Transform
 ---------
 
-CADETMatch has many variable transforms available.
+CADET-Match has many variable transforms available.
 The most common ones will be covered first.
 There are a few additional ones available in the code that are retained for backwards compatibility that will not be covered and their usage is not recomended.
 

doc/index.rst

@@ -7,10 +7,10 @@
 .. image:: https://img.shields.io/github/release/modsim/CADET-Match.svg
    :target: https://github.com/modsim/CADET-Match/releases
 
-CADETMatch
+CADET-Match
 ==========
-CADETMatch is a parameter estimation and error modeling library for CADET.
-CADETMatch is developed at the Institute of Bio- and Geosciences 1 (IBG-1) of Forschungszentrum Jülich (FZJ) under supervision of Dr. Eric von Lieres.
+CADET-Match is a parameter estimation and error modeling library for CADET.
+CADET-Match is developed at the Institute of Bio- and Geosciences 1 (IBG-1) of Forschungszentrum Jülich (FZJ) under supervision of Dr. Eric von Lieres.
 
 
 - **Source:** https://github.com/modsim/CADET-Match
@@ -29,7 +29,7 @@ CADETMatch is developed at the Institute of Bio- and Geosciences 1 (IBG-1) of Fo
 
 .. rubric:: Ongoing Development
 
-CADETMatch is actively developed and we do our best to prevent breaking changes.
+CADET-Match is actively developed and we do our best to prevent breaking changes.
 For non-developers, it is recommended to upgrade from release to release instead of always working with the most recent commit.
 
 

doc/install/index.rst

@@ -3,7 +3,7 @@
 Install
 -------
 
-CADETMatch is a parameter estimation and error modeling library for Python. CADETMatch has a number of
+CADET-Match is a parameter estimation and error modeling library for Python. CADET-Match has a number of
 dependencies and they can be automatically installed. 
 
 The Python libraries for CADET don't include CADET and it must be installed separately by following the
@@ -27,6 +27,6 @@ If you prefer to install from PyPi you can run
 
 .. code-block:: bash
 
-   pip install CADETMatch
+   pip install cadetmatch
 
 The PyPi packages are updated more frequently than the conda packages are.