Changeset 1078 for branches/3.1/sources

Timestamp:

01/07/09 13:09:55 (16 years ago)

Author:

abeham

Message:

Adding the ES documentation comments from the trunk to the 3.1 branch

File:

• branches/3.1/sources/HeuristicLab.ES/ES.cs (modified) (22 diffs)

branches/3.1/sources/HeuristicLab.ES/ES.cs

@@ -35 +35 @@
 
 namespace HeuristicLab.ES {
+  /// <summary>
+  /// Class for the heuristic optimization technique "evolution strategy".
+  /// </summary>
   public class ES : ItemBase, IEditable {
     #region Create Operators
+    /// <summary>
+    /// Creates a new evolution strategy.
+    /// </summary>
+    /// <param name="engine">The engine of the ES to create.</param>
     public static void Create(IEngine engine) {
       engine.OperatorGraph.Clear();
@@ -373 +380 @@
     #region Properties
     private IEngine myEngine;
+    /// <summary>
+    /// Gets the engine of the current instance.
+    /// </summary>
     public IEngine Engine {
       get { return myEngine; }
     }
     private BoolData mySetSeedRandomly;
+    /// <summary>
+    /// Gets or sets the boolean flag whether to set the seed randomly or not.
+    /// </summary>
     public bool SetSeedRandomly {
       get { return mySetSeedRandomly.Data; }
@@ -382 +395 @@
     }
     private IntData mySeed;
+    /// <summary>
+    /// Gets or sets the seed of the current instance.
+    /// </summary>
+    /// <remarks>Calls <see cref="ItemBase.OnChanged"/> of base class <see cref="ItemBase"/> 
+    /// in the setter.</remarks>
     public int Seed {
       get { return mySeed.Data; }
@@ -390 +408 @@
     }
     private IntData myMu;
+    /// <summary>
+    /// Gets or sets the µ value of the current instance.
+    /// </summary>
+    /// <remarks>Sets also the lambda and the rho value. Calls <see cref="ItemBase.OnChanged"/> of
+    /// base class <see cref="ItemBase"/>.</remarks>
     public int Mu {
       get { return myMu.Data; }
@@ -402 +425 @@
     }
     private IntData myRho;
+    /// <summary>
+    /// Gets or sets the rho value of the current instance.
+    /// </summary>
+    /// <remarks>Sets also the µ value. Calls <see cref="ItemBase.OnChanged"/> of
+    /// base class <see cref="ItemBase"/>.</remarks>
     public int Rho {
       get { return myRho.Data; }
@@ -413 +441 @@
     }
     private IntData myLambda;
+    /// <summary>
+    /// Gets or sets the lambda value of the current instance.
+    /// </summary>
+    /// <remarks>May also change the µ value under certain circumstances. 
+    /// Calls <see cref="ItemBase.OnChanged"/> of base class <see cref="ItemBase"/>.</remarks>
     public int Lambda {
       get { return myLambda.Data; }
@@ -434 +467 @@
     }
     private BoolData myPlusNotation;
+    /// <summary>
+    /// Gets or sets the boolean flag whether it is a plus notation or not.
+    /// </summary>
+    /// <remarks>May also set the lambda value under certain circumstances. 
+    /// Calls <see cref="ItemBase.OnChanged"/> of base class <see cref="ItemBase"/>.</remarks>
     public bool PlusNotation {
       get { return myPlusNotation.Data; }
@@ -447 +485 @@
     }
     private DoubleData myShakingFactor;
+    /// <summary>
+    /// Gets or sets the shaking factor of the current instance.
+    /// </summary>
     public double ShakingFactor {
       get { return myShakingFactor.Data; }
@@ -452 +493 @@
     }
     private DoubleData mySuccessProbability;
+    
     private DoubleData myTargetSuccessProbability;
+    /// <summary>
+    /// Gets or sets the success probability.
+    /// </summary>
+    /// <remarks>Gets the target success probability and sets also the target success probability.</remarks>
     public double SuccessProbability {
       get { return myTargetSuccessProbability.Data; }
@@ -461 +507 @@
     }
     private DoubleData myLearningRate;
+    /// <summary>
+    /// Gets or sets the learning rate.
+    /// </summary>
+    /// <remarks>Calls <see cref="ItemBase.OnChanged"/> of base class <see cref="ItemBase"/> 
+    /// in the setter.</remarks>
     public double LearningRate {
       get { return myLearningRate.Data; }
@@ -471 +522 @@
     }
     private DoubleData myDampeningFactor;
+    /// <summary>
+    /// Gets or sets the dampening factor.
+    /// </summary>
+    /// <remarks>Calls <see cref="ItemBase.OnChanged"/> of base class <see cref="ItemBase"/> 
+    /// in the setter.</remarks>
     public double DampeningFactor {
       get { return myDampeningFactor.Data; }
@@ -481 +537 @@
     }
     private IntData myMaximumGenerations;
+    /// <summary>
+    /// Gets or sets the maximum number of generations.
+    /// </summary>
     public int MaximumGenerations {
       get { return myMaximumGenerations.Data; }
@@ -486 +545 @@
     }
     private BoolData myUseSuccessRule;
+    /// <summary>
+    /// Gets or sets the boolean flag whether to use the success rule or not.
+    /// </summary>
     public bool UseSuccessRule {
       get { return myUseSuccessRule.Data; }
@@ -493 +555 @@
     private IOperator myESMain;
     private IOperator myVariableInjection;
+    /// <summary>
+    /// Gets or sets the problem injection operator.
+    /// </summary>
     public IOperator ProblemInjector {
       get { return myVariableInjection.SubOperators[0]; }
@@ -503 +568 @@
     }
     private IOperator myPopulationInitialization;
+    /// <summary>
+    /// Gets or sets the solution generation operator.
+    /// </summary>
     public IOperator SolutionGenerator {
       get { return myPopulationInitialization.SubOperators[0]; }
@@ -512 +580 @@
       }
     }
+    /// <summary>
+    /// Gets or sets the evaluation operator.
+    /// </summary>
     public IOperator Evaluator {
       get { return myPopulationInitialization.SubOperators[1]; }
@@ -522 +593 @@
       }
     }
+    /// <summary>
+    /// Gets or sets the mutation operator. 
+    /// </summary>
     public IOperator Mutator {
       get { return myESMain.SubOperators[0]; }
@@ -531 +605 @@
       }
     }
+    /// <summary>
+    /// Gets or sets the recombination operator.
+    /// </summary>
     public IOperator Recombinator {
       get { return myESMain.SubOperators[2]; }
@@ -542 +619 @@
     #endregion
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="ES"/> having a <see cref="SequentialEngine"/> as engine.
+    /// </summary>
     public ES() {
       myEngine = new SequentialEngine.SequentialEngine();
@@ -548 +628 @@
     }
 
+    /// <summary>
+    /// Creates a new instance of <see cref="ESEditor"/> to display the current instance.
+    /// </summary>
+    /// <returns>The created view as <see cref="ESEditor"/>.</returns>
     public override IView CreateView() {
       return new ESEditor(this);
     }
+    /// <summary>
+    /// Creates a new instance of <see cref="ESEditor"/> to display the current instance.
+    /// </summary>
+    /// <returns>The created editor as <see cref="ESEditor"/>.</returns>
     public virtual IEditor CreateEditor() {
       return new ESEditor(this);
     }
 
+    /// <summary>
+    /// Clones the current instance (deep clone).
+    /// </summary>
+    /// <remarks>Uses <see cref="Auxiliary.Clone"/> method of the <see cref="Auxiliary"/> class to 
+    /// clone the engine.</remarks>
+    /// <param name="clonedObjects">A dictionary of all already cloned objects. 
+    /// (Needed to avoid cycles.)</param>
+    /// <returns>The cloned object as <see cref="ES"/>.</returns>
     public override object Clone(IDictionary<Guid, object> clonedObjects) {
       ES clone = new ES();
@@ -601 +697 @@
 
     #region Persistence Methods
+    /// <summary>
+    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
+    /// </summary>
+    /// <remarks>Calls <see cref="StorableBase.GetXmlNode"/> of base class <see cref="ItemBase"/>. 
+    /// <br/>The engine of the current instance is saved as child node with tag name <c>Engine</c>.</remarks>
+    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
+    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
+    /// <param name="persistedObjects">The dictionary of all already persisted objects. 
+    /// (Needed to avoid cycles.)</param>
+    /// <returns>The saved <see cref="XmlNode"/>.</returns>
     public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid, IStorable> persistedObjects) {
       XmlNode node = base.GetXmlNode(name, document, persistedObjects);
@@ -606 +712 @@
       return node;
     }
+    /// <summary>
+    /// Loads the persisted ES from the specified <paramref name="node"/>.
+    /// </summary>
+    /// <remarks>Calls <see cref="StorableBase.Populate"/> of base class <see cref="ItemBase"/>.<br/>
+    /// The engine must be saved as child node with tag name <c>Engine</c> (see 
+    /// <see cref="GetXmlNode"/>).</remarks>
+    /// <param name="node">The <see cref="XmlNode"/> where the value is saved.</param>
+    /// <param name="restoredObjects">The dictionary of all already restored objects. 
+    /// (Needed to avoid cycles.)</param>
     public override void Populate(XmlNode node, IDictionary<Guid, IStorable> restoredObjects) {
       base.Populate(node, restoredObjects);