diff --git a/CADETMatch/version.py b/CADETMatch/version.py index 56d6b26..00f78a8 100644 --- a/CADETMatch/version.py +++ b/CADETMatch/version.py @@ -18,5 +18,5 @@ __email__ = "w.heymann@fz-juelich.de" __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" diff --git a/doc/cli/examples.rst b/doc/cli/examples.rst index 62448c2..8f7e957 100644 --- a/doc/cli/examples.rst +++ b/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 diff --git a/doc/cli/index.rst b/doc/cli/index.rst index b9071f9..c115e1e 100644 --- a/doc/cli/index.rst +++ b/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 -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 diff --git a/doc/configuration/error.rst b/doc/configuration/error.rst index b1ccff1..b89ed77 100644 --- a/doc/configuration/error.rst +++ b/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. diff --git a/doc/configuration/experiments.rst b/doc/configuration/experiments.rst index 313c5a3..f587ac8 100644 --- a/doc/configuration/experiments.rst +++ b/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 diff --git a/doc/configuration/graphing.rst b/doc/configuration/graphing.rst index 9e7c4a6..3617a36 100644 --- a/doc/configuration/graphing.rst +++ b/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. diff --git a/doc/configuration/index.rst b/doc/configuration/index.rst index 5bb27d7..d10f300 100644 --- a/doc/configuration/index.rst +++ b/doc/configuration/index.rst @@ -3,8 +3,8 @@ Configuration ------------- -CADETMatch uses a JSON based configuration file format. -CADETMatch uses `jstyleson `_ to support JSON with comments. +CADET-Match uses a JSON based configuration file format. +CADET-Match uses `jstyleson `_ to support JSON with comments. You can programatically create the JSON in Python using nested dictionaries or `addict `_ and then convert to JSON. Ususally, the configuration has to include: diff --git a/doc/configuration/misc.rst b/doc/configuration/misc.rst index 2bdbbf5..c10c0b6 100644 --- a/doc/configuration/misc.rst +++ b/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) diff --git a/doc/configuration/scores.rst b/doc/configuration/scores.rst index bbb8c1e..af9be9b 100644 --- a/doc/configuration/scores.rst +++ b/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. diff --git a/doc/configuration/search.rst b/doc/configuration/search.rst index 8115e3e..b6ab105 100644 --- a/doc/configuration/search.rst +++ b/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 `_ 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 `_ 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 diff --git a/doc/configuration/transform.rst b/doc/configuration/transform.rst index 2a6cda5..34306f7 100644 --- a/doc/configuration/transform.rst +++ b/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. diff --git a/doc/index.rst b/doc/index.rst index 70fd672..a193555 100644 --- a/doc/index.rst +++ b/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. diff --git a/doc/install/index.rst b/doc/install/index.rst index 7e8abdf..1659fb5 100644 --- a/doc/install/index.rst +++ b/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.