Changeset 881 for trunk/sources

Timestamp:

12/01/08 13:47:10 (16 years ago)

Author:

vdorfer

Message:

Created API documentation for HeuristicLab.Evolutionary namespace (#331)

Location:

trunk/sources/HeuristicLab.Evolutionary

Files:

• CrossoverBase.cs (modified) (3 diffs)
• HeuristicLabEvolutionaryPlugin.cs (modified) (1 diff)
• MultiCrossoverBase.cs (modified) (3 diffs)
• SASEGASAReunificator.cs (modified) (1 diff)
• SubScopesStorer.cs (modified) (2 diffs)
• SuccessRuleMutationStrengthAdjuster.cs (modified) (2 diffs)
• UnidirectionalRingMigrator.cs (modified) (1 diff)

trunk/sources/HeuristicLab.Evolutionary/CrossoverBase.cs

@@ -27 +27 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Base class for crossing over operators.
+  /// </summary>
   public abstract class CrossoverBase : OperatorBase {
+    /// <summary>
+    /// Initializes a new instance of <see cref="CrossoverBase"/> with one variable info (<c>Random</c>).
+    /// </summary>
     public CrossoverBase()
       : base() {
@@ -33 +39 @@
     }
 
+    /// <summary>
+    /// Replaces the parents (the sub scopes of the current <paramref name="scope"/>) with created children
+    /// by crossing over of two adjacent sub scopes.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown when the size of the mating pool 
+    /// is not even.</exception>
+    /// <param name="scope">The current scope whose sub scopes shall be parents.</param>
+    /// <returns><c>null</c>.</returns>
     public override IOperation Apply(IScope scope) {
       IRandom random = GetVariableValue<IRandom>("Random", scope, true);
@@ -53 +67 @@
     }
 
+    /// <summary>
+    /// Performs a cross over of <paramref name="parent1"/> and <paramref name="parent2"/>
+    /// to create a new <paramref name="child"/>.
+    /// </summary>
+    /// <param name="scope">The current scope.</param>
+    /// <param name="random">A random number generator.</param>
+    /// <param name="parent1">The parent scope 1 to cross over.</param>
+    /// <param name="parent2">The parent scope 2 to cross over.</param>
+    /// <param name="child">The resulting child of the cross over.</param>
     protected abstract void Cross(IScope scope, IRandom random, IScope parent1, IScope parent2, IScope child);
   }

trunk/sources/HeuristicLab.Evolutionary/HeuristicLabEvolutionaryPlugin.cs

@@ -26 +26 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Plugin class for HeuristicLab.Evolutionary plugin.
+  /// </summary>
   [ClassInfo(Name = "HeuristicLab.Evolutionary-3.2")]
   [PluginFile(Filename = "HeuristicLab.Evolutionary-3.2.dll", Filetype = PluginFileType.Assembly)]

trunk/sources/HeuristicLab.Evolutionary/MultiCrossoverBase.cs

@@ -28 +28 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Base class for cross over operators that use more than two parents.
+  /// </summary>
   public abstract class MultiCrossoverBase : OperatorBase {
+    /// <summary>
+    /// Initializes a new instance of <see cref="MultiCrossoverBase"/> with two variable infos
+    /// (<c>Parents</c> and <c>Random</c>).
+    /// </summary>
     public MultiCrossoverBase()
       : base() {
@@ -35 +42 @@
     }
 
+    /// <summary>
+    /// Replaces the parents (sub scopes of the given <paramref name="scope"/>) with created children
+    /// by crossing over a specified number of parents.
+    /// </summary>
+    /// <remarks>Adds the children to the given <paramref name="scope"/> and removes the parents.</remarks>
+    /// <exception cref="InvalidOperationException">Thrown when the size of the mating pool and the 
+    /// number of parents don't match.</exception>
+    /// <param name="scope">The scope whose sub scopes shall be crossed over.</param>
+    /// <returns><c>null</c>.</returns>
     public override IOperation Apply(IScope scope) {
       IRandom random = GetVariableValue<IRandom>("Random", scope, true);
@@ -57 +73 @@
       return null;
     }
-
+    /// <summary>
+    /// Performs a cross over of a number of <paramref name="parents"/>
+    /// to create a new <paramref name="child"/>.
+    /// </summary>
+    /// <param name="scope">The current scope.</param>
+    /// <param name="random">A random number generator.</param>
+    /// <param name="parents">The scopes to cross over.</param>
+    /// <param name="child">The result of the cross over.</param>
     protected abstract void Cross(IScope scope, IRandom random, IScope[] parents, IScope child);
   }

trunk/sources/HeuristicLab.Evolutionary/SASEGASAReunificator.cs

@@ -27 +27 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Joins all sub sub scopes of a specified scope, reduces the number of sub 
+  /// scopes by 1 and uniformly partitions the sub sub scopes again, maintaining the order.
+  /// </summary>
   public class SASEGASAReunificator : OperatorBase {
+    /// <inheritdoc select="summary"/>
     public override string Description {
       get { return @"TODO\r\nOperator description still missing ..."; }
     }
 
+    /// <summary>
+    /// Joins all sub sub scopes of the given <paramref name="scope"/>, reduces the number of sub 
+    /// scopes by 1 and uniformly partitions the sub sub scopes again, maintaining the order.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown when only 0 or 1 sub scope is available.</exception>
+    /// <param name="scope">The current scope whose sub scopes to reduce.</param>
+    /// <returns><c>null</c>.</returns>
     public override IOperation Apply(IScope scope) {
       int subScopes = scope.SubScopes.Count;

trunk/sources/HeuristicLab.Evolutionary/SubScopesStorer.cs

@@ -28 +28 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Stores the sub scopes of the right sub scope until enough newly created child scopes are available
+  /// (for example to replace a generation).
+  /// </summary>
   public class SubScopesStorer : OperatorBase {
+    /// <inheritdoc select="summary"/>
     public override string Description {
       get { return @"TODO\r\nOperator description still missing ..."; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="SubScopesStorer"/> with two variable infos 
+    /// (<c>SubScopes</c> and <c>SubScopesStore</c>).
+    /// </summary>
     public SubScopesStorer()
       : base() {
@@ -39 +48 @@
     }
 
+    /// <summary>
+    /// Stores all sub scopes of the right branch to get the required number of sub scopes. Shifts the left
+    /// branch one level up, if sub scopes are still missing (so that another selection and mutation circle
+    /// can take place). 
+    /// </summary>
+    /// <param name="scope">The current scope whose sub scopes to store.</param>
+    /// <returns><c>null</c> if the required number of sub scopes is available, the next 
+    /// <see cref="AtomicOperation"/> if sub scopes are still missing.</returns>
     public override IOperation Apply(IScope scope) {
       IntData subScopes = GetVariableValue<IntData>("SubScopes", scope, true);

trunk/sources/HeuristicLab.Evolutionary/SuccessRuleMutationStrengthAdjuster.cs

@@ -27 +27 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Adjusts the mutation strength based on the ratio of successful offsprings.
+  /// </summary>
   public class SuccessRuleMutationStrengthAdjuster : OperatorBase {
+    /// <inheritdoc select="summary"/>
     public override string Description {
       get { return @"Adjusts the mutation strength based on the ratio of successful offsprings"; }
     }
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="SuccessRuleMutationStrengthAdjuster"/> with six variable
+    /// infos (<c>ShakingFactor</c>, <c>SuccessfulChild</c>, <c>TargetSuccessProbability</c>, 
+    /// <c>SuccessProbability</c>, <c>LearningRate</c> and <c>DampeningFactor</c>).
+    /// </summary>
     public SuccessRuleMutationStrengthAdjuster() {
       AddVariableInfo(new VariableInfo("ShakingFactor", "The mutation strength to adjust", typeof(DoubleData), VariableKind.In | VariableKind.Out));
@@ -41 +50 @@
     }
 
+    /// <summary>
+    /// Adjusts the mutation strength based on the ratio of successful offsprings.
+    /// </summary>
+    /// <param name="scope">The current scope where to adjust the mutation strength.</param>
+    /// <returns><c>null</c>.</returns>
     public override IOperation Apply(IScope scope) {
       DoubleData shakingFactor = GetVariableValue<DoubleData>("ShakingFactor", scope, true);

trunk/sources/HeuristicLab.Evolutionary/UnidirectionalRingMigrator.cs

@@ -27 +27 @@
 
 namespace HeuristicLab.Evolutionary {
+  /// <summary>
+  /// Operator class that migrates one sub scope of each child to its left neighbour sub scope, like a ring.
+  /// </summary>
   public class UnidirectionalRingMigrator : OperatorBase {
+    /// <inheritdoc select="summary"/>
     public override string Description {
       get { return @"TODO\r\nOperator description still missing ..."; }
     }
 
+    /// <summary>
+    /// Migrates every first sub scope of each child to its left neighbour (like a ring).
+    /// <pre>                                                               
+    ///                    scope                    scope             
+    ///                /     |     \            /     |     \         
+    ///               A      B      C    =>    A      B      C           
+    ///              /|\    /|\    /|\        /|\    /|\    /|\       
+    ///             G H I  J K L  M N O      H I J  K L M  N O G     
+    /// </pre>
+    /// </summary>
+    /// <param name="scope">The scope whose sub scopes of the children should migrate.</param>
+    /// <returns><c>null</c>.</returns>
     public override IOperation Apply(IScope scope) {
       IList<IScope> emigrantsList = new List<IScope>();