From: Jean-Philippe ARGAUD Date: Wed, 4 Nov 2020 17:28:34 +0000 (+0100) Subject: Updating documentation by review and snippets (14) X-Git-Tag: V9_7_0b1~79 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=9efe826c23c32df35b8e30d1323ae83b1fa0ecaf;p=modules%2Fadao.git Updating documentation by review and snippets (14) --- diff --git a/doc/en/ref_algorithm_3DVAR.rst b/doc/en/ref_algorithm_3DVAR.rst index 730c9c0..9378efe 100644 --- a/doc/en/ref_algorithm_3DVAR.rst +++ b/doc/en/ref_algorithm_3DVAR.rst @@ -62,18 +62,7 @@ which is usually designed as the "*3D-VAR*" function (see for example .. include:: snippets/MaximumNumberOfSteps.rst -Minimizer - .. index:: single: Minimizer - - This key allows to choose the optimization minimizer. The default choice is - "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained - minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear - constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" - (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is - strongly recommended to stay with the default. - - Example : - ``{"Minimizer":"LBFGSB"}`` +.. include:: snippets/Minimizer_xDVAR.rst .. include:: snippets/NumberOfSamplesForQuantiles.rst diff --git a/doc/en/ref_algorithm_4DVAR.rst b/doc/en/ref_algorithm_4DVAR.rst index 80b5d68..1d216f3 100644 --- a/doc/en/ref_algorithm_4DVAR.rst +++ b/doc/en/ref_algorithm_4DVAR.rst @@ -65,33 +65,22 @@ filters, specially the :ref:`section_ref_algorithm_ExtendedKalmanFilter` or the .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -Minimizer - .. index:: single: Minimizer - - This key allows to choose the optimization minimizer. The default choice is - "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained - minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear - constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" - (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is - strongly recommended to stay with the default. - - Example : - ``{"Minimizer":"LBFGSB"}`` - .. include:: snippets/BoundsWithNone.rst .. include:: snippets/ConstrainedBy.rst -.. include:: snippets/MaximumNumberOfSteps.rst - .. include:: snippets/CostDecrementTolerance.rst .. include:: snippets/EstimationOf.rst -.. include:: snippets/ProjectedGradientTolerance.rst - .. include:: snippets/GradientNormTolerance.rst +.. include:: snippets/MaximumNumberOfSteps.rst + +.. include:: snippets/Minimizer_xDVAR.rst + +.. include:: snippets/ProjectedGradientTolerance.rst + StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/en/ref_algorithm_NonLinearLeastSquares.rst b/doc/en/ref_algorithm_NonLinearLeastSquares.rst index 6fc563a..98c9706 100644 --- a/doc/en/ref_algorithm_NonLinearLeastSquares.rst +++ b/doc/en/ref_algorithm_NonLinearLeastSquares.rst @@ -56,28 +56,18 @@ for its stability as for its behavior during optimization. .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -Minimizer - .. index:: single: Minimizer - - This key allows to choose the optimization minimizer. The default choice is - "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained - minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear - constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" - (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is - strongly recommended to stay with the default. +.. include:: snippets/BoundsWithNone.rst - Example : - ``{"Minimizer":"LBFGSB"}`` +.. include:: snippets/CostDecrementTolerance.rst -.. include:: snippets/BoundsWithNone.rst +.. include:: snippets/GradientNormTolerance.rst .. include:: snippets/MaximumNumberOfSteps.rst -.. include:: snippets/CostDecrementTolerance.rst +.. include:: snippets/Minimizer_xDVAR.rst .. include:: snippets/ProjectedGradientTolerance.rst -.. include:: snippets/GradientNormTolerance.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/en/ref_algorithm_ParticleSwarmOptimization.rst b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst index ea37af7..8619001 100644 --- a/doc/en/ref_algorithm_ParticleSwarmOptimization.rst +++ b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst @@ -59,49 +59,19 @@ least squares function, classically used in data assimilation. .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -.. index:: single: NumberOfInsects -.. index:: single: SwarmVelocity -.. index:: single: GroupRecallRate -.. index:: single: QualityCriterion -.. index:: single: BoxBounds - .. include:: snippets/MaximumNumberOfSteps_50.rst .. include:: snippets/MaximumNumberOfFunctionEvaluations.rst .. include:: snippets/QualityCriterion.rst -NumberOfInsects - This key indicates the number of insects or particles in the swarm. The - default is 100, which is a usual default for this algorithm. - - Example : - ``{"NumberOfInsects":100}`` +.. include:: snippets/NumberOfInsects.rst -SwarmVelocity - This key indicates the part of the insect velocity which is imposed by the - swarm. It is a positive floating point value. The default value is 1. - - Example : - ``{"SwarmVelocity":1.}`` +.. include:: snippets/SwarmVelocity.rst -GroupRecallRate - This key indicates the recall rate at the best swarm insect. It is a - floating point value between 0 and 1. The default value is 0.5. +.. include:: snippets/GroupRecallRate.rst - Example : - ``{"GroupRecallRate":0.5}`` - -BoxBounds - This key allows to define upper and lower bounds for *increments* on every - state variable being optimized (and not on state variables themselves). - Bounds have to be given by a list of list of pairs of lower/upper bounds for - each increment on variable, with extreme values every time there is no bound - (``None`` is not allowed when there is no bound). This key is required and - there is no default values. - - Example : - ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` +.. include:: snippets/BoxBounds.rst .. include:: snippets/SetSeed.rst diff --git a/doc/en/snippets/BoxBounds.rst b/doc/en/snippets/BoxBounds.rst new file mode 100644 index 0000000..c358810 --- /dev/null +++ b/doc/en/snippets/BoxBounds.rst @@ -0,0 +1,12 @@ +.. index:: single: BoxBounds + +BoxBounds + *List of pairs of real values*. This key allows to define upper and lower + bounds for *increments* on every state variable being optimized (and not on + state variables themselves). Bounds have to be given by a list of list of + pairs of lower/upper bounds for each increment on variable, with extreme + values every time there is no bound (``None`` is not allowed when there is no + bound). This key is required and there is no default values. + + Example : + ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` diff --git a/doc/en/snippets/GroupRecallRate.rst b/doc/en/snippets/GroupRecallRate.rst new file mode 100644 index 0000000..ebde3e7 --- /dev/null +++ b/doc/en/snippets/GroupRecallRate.rst @@ -0,0 +1,8 @@ +.. index:: single: GroupRecallRate + +GroupRecallRate + *Real value*. This key indicates the recall rate at the best swarm insect. It + is a floating point value between 0 and 1. The default value is 0.5. + + Example : + ``{"GroupRecallRate":0.5}`` diff --git a/doc/en/snippets/Minimizer_xDVAR.rst b/doc/en/snippets/Minimizer_xDVAR.rst new file mode 100644 index 0000000..ed4f589 --- /dev/null +++ b/doc/en/snippets/Minimizer_xDVAR.rst @@ -0,0 +1,15 @@ + .. index:: single: Minimizer + +Minimizer + *Predefined name*. This key allows to choose the optimization minimizer. The + default choice is "LBFGSB", and the possible ones are + "LBFGSB" (nonlinear constrained minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), + "TNC" (nonlinear constrained minimizer), + "CG" (nonlinear unconstrained minimizer), + "BFGS" (nonlinear unconstrained minimizer), + "NCG" (Newton CG minimizer). + It is strongly recommended to stay with the default. + + Example : + ``{"Minimizer":"LBFGSB"}`` + diff --git a/doc/en/snippets/NumberOfInsects.rst b/doc/en/snippets/NumberOfInsects.rst new file mode 100644 index 0000000..aeb192a --- /dev/null +++ b/doc/en/snippets/NumberOfInsects.rst @@ -0,0 +1,8 @@ +.. index:: single: NumberOfInsects + +NumberOfInsects + *Integer value*. This key indicates the number of insects or particles in the + swarm. The default is 100, which is a usual default for this algorithm. + + Example : + ``{"NumberOfInsects":100}`` diff --git a/doc/en/snippets/SwarmVelocity.rst b/doc/en/snippets/SwarmVelocity.rst new file mode 100644 index 0000000..57f4e07 --- /dev/null +++ b/doc/en/snippets/SwarmVelocity.rst @@ -0,0 +1,9 @@ +.. index:: single: SwarmVelocity + +SwarmVelocity + *Real value*. This key indicates the part of the insect velocity which is + imposed by the swarm, named "group velocity". It is a positive floating point + value. The default value is 1. + + Example : + ``{"SwarmVelocity":1.}`` diff --git a/doc/fr/ref_algorithm_3DVAR.rst b/doc/fr/ref_algorithm_3DVAR.rst index dd04163..08172e7 100644 --- a/doc/fr/ref_algorithm_3DVAR.rst +++ b/doc/fr/ref_algorithm_3DVAR.rst @@ -63,19 +63,7 @@ qui est usuellement désignée comme la fonctionnelle "*3D-VAR*" (voir par exemp .. include:: snippets/MaximumNumberOfSteps.rst -Minimizer - .. index:: single: Minimizer - - Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par - défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non - linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC" - (minimisation non linéaire sous contraintes), "CG" (minimisation non - linéaire sans contraintes), "BFGS" (minimisation non linéaire sans - contraintes), "NCG" (minimisation de type gradient conjugué de Newton). Il - est fortement conseillé de conserver la valeur par défaut. - - Exemple : - ``{"Minimizer":"LBFGSB"}`` +.. include:: snippets/Minimizer_xDVAR.rst .. include:: snippets/NumberOfSamplesForQuantiles.rst diff --git a/doc/fr/ref_algorithm_4DVAR.rst b/doc/fr/ref_algorithm_4DVAR.rst index a047072..8d4c79d 100644 --- a/doc/fr/ref_algorithm_4DVAR.rst +++ b/doc/fr/ref_algorithm_4DVAR.rst @@ -66,34 +66,22 @@ l':ref:`section_ref_algorithm_UnscentedKalmanFilter`. .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -Minimizer - .. index:: single: Minimizer - - Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par - défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non - linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC" - (minimisation non linéaire sous contraintes), "CG" (minimisation non - linéaire sans contraintes), "BFGS" (minimisation non linéaire sans - contraintes), "NCG" (minimisation de type gradient conjugué de Newton). Il - est fortement conseillé de conserver la valeur par défaut. - - Exemple : - ``{"Minimizer":"LBFGSB"}`` - .. include:: snippets/BoundsWithNone.rst .. include:: snippets/ConstrainedBy.rst -.. include:: snippets/MaximumNumberOfSteps.rst - .. include:: snippets/CostDecrementTolerance.rst .. include:: snippets/EstimationOf.rst -.. include:: snippets/ProjectedGradientTolerance.rst - .. include:: snippets/GradientNormTolerance.rst +.. include:: snippets/MaximumNumberOfSteps.rst + +.. include:: snippets/Minimizer_xDVAR.rst + +.. include:: snippets/ProjectedGradientTolerance.rst + StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations @@ -151,6 +139,7 @@ StoreSupplementaryCalculations .. include:: snippets/CostFunctionJoAtCurrentOptimum.rst .. include:: snippets/CurrentIterationNumber.rst + .. include:: snippets/CurrentOptimum.rst .. include:: snippets/CurrentState.rst diff --git a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst index 97f47e5..4390bb6 100644 --- a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst +++ b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst @@ -57,30 +57,18 @@ comportement lors de l'optimisation. .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -Minimizer - .. index:: single: Minimizer - - Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par - défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non - linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC" - (minimisation non linéaire sous contraintes), "CG" (minimisation non - linéaire sans contraintes), "BFGS" (minimisation non linéaire sans - contraintes), "NCG" (minimisation de type gradient conjugué de Newton), "LM" - (minimisation non linéaire de type Levenberg-Marquard). Il est fortement - conseillé de conserver la valeur par défaut. +.. include:: snippets/BoundsWithNone.rst - Exemple : - ``{"Minimizer":"LBFGSB"}`` +.. include:: snippets/CostDecrementTolerance.rst -.. include:: snippets/BoundsWithNone.rst +.. include:: snippets/GradientNormTolerance.rst .. include:: snippets/MaximumNumberOfSteps.rst -.. include:: snippets/CostDecrementTolerance.rst +.. include:: snippets/Minimizer_xDVAR.rst .. include:: snippets/ProjectedGradientTolerance.rst -.. include:: snippets/GradientNormTolerance.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst index c7d2390..6391286 100644 --- a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst +++ b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst @@ -60,51 +60,19 @@ en assimilation de données. .. ------------------------------------ .. .. include:: snippets/Header2Algo03AdOp.rst -.. index:: single: NumberOfInsects -.. index:: single: SwarmVelocity -.. index:: single: GroupRecallRate -.. index:: single: QualityCriterion -.. index:: single: BoxBounds - .. include:: snippets/MaximumNumberOfSteps_50.rst .. include:: snippets/MaximumNumberOfFunctionEvaluations.rst .. include:: snippets/QualityCriterion.rst -NumberOfInsects - Cette clé indique le nombre d'insectes ou de particules dans l'essaim. La - valeur par défaut est 100, qui est une valeur par défaut usuelle pour cet - algorithme. - - Exemple : - ``{"NumberOfInsects":100}`` +.. include:: snippets/NumberOfInsects.rst -SwarmVelocity - Cette clé indique la part de la vitesse d'insecte qui est imposée par - l'essaim. C'est une valeur réelle positive. Le défaut est de 1. - - Exemple : - ``{"SwarmVelocity":1.}`` +.. include:: snippets/SwarmVelocity.rst -GroupRecallRate - Cette clé indique le taux de rappel vers le meilleur insecte de l'essaim. - C'est une valeur réelle comprise entre 0 et 1. Le défaut est de 0.5. +.. include:: snippets/GroupRecallRate.rst - Exemple : - ``{"GroupRecallRate":0.5}`` - -BoxBounds - Cette clé permet de définir des bornes supérieure et inférieure pour chaque - incrément de variable d'état optimisée (et non pas chaque variable d'état - elle-même). Les bornes doivent être données par une liste de liste de paires - de bornes inférieure/supérieure pour chaque incrément de variable, avec une - valeur extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas une - valeur autorisée lorsqu'il n'y a pas de borne). Cette clé est requise et il - n'y a pas de valeurs par défaut. - - Exemple : - ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` +.. include:: snippets/BoxBounds.rst .. include:: snippets/SetSeed.rst diff --git a/doc/fr/snippets/BoxBounds.rst b/doc/fr/snippets/BoxBounds.rst new file mode 100644 index 0000000..068f46f --- /dev/null +++ b/doc/fr/snippets/BoxBounds.rst @@ -0,0 +1,13 @@ +.. index:: single: BoxBounds + +BoxBounds + *Liste de paires de valeurs réelles*. Cette clé permet de définir des bornes + supérieure et inférieure pour chaque incrément de variable d'état optimisée + (et non pas chaque variable d'état elle-même). Les bornes doivent être + données par une liste de liste de paires de bornes inférieure/supérieure pour + chaque incrément de variable, avec une valeur extrême chaque fois qu'il n'y a + pas de borne (``None`` n'est pas une valeur autorisée lorsqu'il n'y a pas de + borne). Cette clé est requise et il n'y a pas de valeurs par défaut. + + Exemple : + ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` diff --git a/doc/fr/snippets/GroupRecallRate.rst b/doc/fr/snippets/GroupRecallRate.rst new file mode 100644 index 0000000..3372e7f --- /dev/null +++ b/doc/fr/snippets/GroupRecallRate.rst @@ -0,0 +1,9 @@ +.. index:: single: GroupRecallRate + +GroupRecallRate + *Valeur réelle*. Cette clé indique le taux de rappel vers le meilleur insecte + de l'essaim. C'est une valeur réelle comprise entre 0 et 1. Le défaut est de + 0.5. + + Exemple : + ``{"GroupRecallRate":0.5}`` diff --git a/doc/fr/snippets/Minimizer_xDVAR.rst b/doc/fr/snippets/Minimizer_xDVAR.rst new file mode 100644 index 0000000..2ab061b --- /dev/null +++ b/doc/fr/snippets/Minimizer_xDVAR.rst @@ -0,0 +1,14 @@ +.. index:: single: Minimizer + +Minimizer + *Nom prédéfini*. Cette clé permet de changer le minimiseur pour l'optimiseur. + Le choix par défaut est "LBFGSB", et les choix possibles sont + "LBFGSB" (minimisation non linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), + "TNC" (minimisation non linéaire sous contraintes), + "CG" (minimisation non linéaire sans contraintes), + "BFGS" (minimisation non linéaire sans contraintes), + "NCG" (minimisation de type gradient conjugué de Newton). + Il est fortement conseillé de conserver la valeur par défaut. + + Exemple : + ``{"Minimizer":"LBFGSB"}`` diff --git a/doc/fr/snippets/NumberOfInsects.rst b/doc/fr/snippets/NumberOfInsects.rst new file mode 100644 index 0000000..19ba899 --- /dev/null +++ b/doc/fr/snippets/NumberOfInsects.rst @@ -0,0 +1,9 @@ +.. index:: single: NumberOfInsects + +NumberOfInsects + *Valeur entière*. Cette clé indique le nombre d'insectes ou de particules + dans l'essaim. La valeur par défaut est 100, qui est une valeur par défaut + usuelle pour cet algorithme. + + Exemple : + ``{"NumberOfInsects":100}`` diff --git a/doc/fr/snippets/SwarmVelocity.rst b/doc/fr/snippets/SwarmVelocity.rst new file mode 100644 index 0000000..b1e52ec --- /dev/null +++ b/doc/fr/snippets/SwarmVelocity.rst @@ -0,0 +1,9 @@ +.. index:: single: SwarmVelocity + +SwarmVelocity + *Valeur réelle*. Cette clé indique la part de la vitesse d'insecte qui est + imposée par l'essaim, dite "vitesse de groupe". C'est une valeur réelle + positive. Le défaut est de 1. + + Exemple : + ``{"SwarmVelocity":1.}``