Changeset 1153


Ignore:
Timestamp:
01/16/09 11:24:03 (12 years ago)
Author:
vdorfer
Message:

Created API documentation for HeuristicLab.Random, HeuristicLab.SGA and HeuristicLab.Selection.OffspringSelection namespace (#331)

Location:
trunk/sources
Files:
14 edited

Legend:

Unmodified
Added
Removed
  • trunk/sources/HeuristicLab.Random/HeuristicLabRandomPlugin.cs

    r582 r1153  
    2626
    2727namespace HeuristicLab.Random {
     28  /// <summary>
     29  /// Plugin class for HeuristicLab.Random plugin.
     30  /// </summary>
    2831  [ClassInfo(Name = "HeuristicLab.Random-3.2")]
    2932  [PluginFile(Filename = "HeuristicLab.Random-3.2.dll", Filetype = PluginFileType.Assembly)]
  • trunk/sources/HeuristicLab.Random/MersenneTwister.cs

    r2 r1153  
    3939
    4040namespace HeuristicLab.Random {
     41  /// <summary>
     42  /// A 623-Dimensionally Equidistributed Uniform Pseudo-Random Number Generator.
     43  /// </summary>
    4144  public class MersenneTwister : ItemBase, IRandom {
    4245    private const int n = 624, m = 397;
     
    4750    private bool init = false;
    4851
     52    /// <summary>
     53    /// Initializes a new instance of <see cref="MersenneTwister"/>.
     54    /// </summary>
    4955    public MersenneTwister() {
    5056      if (!init) seed((uint)DateTime.Now.Ticks);
    5157      init = true;
    5258    }
     59    /// <summary>
     60    /// Initializes a new instance of <see cref="MersenneTwister"/>
     61    /// with the given seed <paramref name="s"/>.
     62    /// </summary>
     63    /// <param name="s">The seed with which to initialize the random number generator.</param>
    5364    public MersenneTwister(uint s) {
    5465      seed(s);
    5566      init = true;
    5667    }
     68    /// <summary>
     69    /// Initializes a new instance of <see cref="MersenneTwister"/> with the given seed array.
     70    /// </summary>
     71    /// <param name="array">The seed array with which to initialize the random number generator.</param>
    5772    public MersenneTwister(uint[] array) {
    5873      seed(array);
     
    6075    }
    6176
     77    /// <summary>
     78    /// Clones the current instance (deep clone).
     79    /// </summary>
     80    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
     81    /// <returns>The cloned object as <see cref="MersenneTwister"/>.</returns>
    6282    public override object Clone(IDictionary<Guid, object> clonedObjects) {
    6383      MersenneTwister clone = new MersenneTwister();
     
    6989    }
    7090
     91    /// <summary>
     92    /// Resets the current random number generator.
     93    /// </summary>
    7194    public void Reset() {
    7295      lock (locker)
    7396        seed((uint)DateTime.Now.Ticks);
    7497    }
     98    /// <summary>
     99    /// Resets the current random number generator with the given seed <paramref name="s"/>.
     100    /// </summary>
     101    /// <param name="s">The seed with which to reset the current instance.</param>
    75102    public void Reset(int s) {
    76103      lock (locker)
     
    78105    }
    79106
     107    /// <summary>
     108    /// Gets a new random number.
     109    /// </summary>
     110    /// <returns>A new int random number.</returns>
    80111    public int Next() {
    81112      lock (locker) {
     
    83114      }
    84115    }
     116    /// <summary>
     117    /// Gets a new random number being smaller than the given <paramref name="maxVal"/>.
     118    /// </summary>
     119    /// <exception cref="ArgumentException">Thrown when the given maximum value is
     120    /// smaller or equal to zero.</exception>
     121    /// <param name="maxVal">The maximum value of the generated random number.</param>
     122    /// <returns>A new int random number.</returns>
    85123    public int Next(int maxVal) {
    86124      lock (locker) {
     
    93131      }
    94132    }
     133    /// <summary>
     134    /// Gets a new random number being in the given interval <paramref name="minVal"/> and
     135    /// <paramref name="maxVal"/>.
     136    /// </summary>
     137    /// <param name="minVal">The minimum value of the generated random number.</param>
     138    /// <param name="maxVal">The maximum value of the generated random number.</param>
     139    /// <returns>A new int random number.</returns>
    95140    public int Next(int minVal, int maxVal) {
    96141      lock (locker) {
     
    100145      }
    101146    }
     147    /// <summary>
     148    /// Gets a new double random variable.
     149    /// </summary>
     150    /// <returns></returns>
    102151    public double NextDouble() {
    103152      lock (locker) {
     
    107156
    108157    #region Persistence Methods
     158    /// <summary>
     159    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
     160    /// </summary>
     161    /// <remarks>The state(s) are saved as child node with the tag <c>State</c>, each state separaated with
     162    /// a semicolon. Also the elements <c>p</c> and the <c>init</c> flag are saved as child nodes with
     163    /// tag names <c>P</c> and <c>Init</c> respectively.</remarks>
     164    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
     165    /// <param name="document">The <see cref="XmlDocument"/> where the data is saved.</param>
     166    /// <param name="persistedObjects">A dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
     167    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    109168    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid,IStorable> persistedObjects) {
    110169      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
     
    130189      return node;
    131190    }
     191    /// <summary>
     192    /// Loads the persisted random number generator from the specified <paramref name="node"/>.
     193    /// </summary>
     194    /// <remarks>The elements of the current instance must be saved in a special way, see
     195    /// <see cref="GetXmlNode"/>.</remarks>
     196    /// <param name="node">The <see cref="XmlNode"/> where the instance is saved.</param>
     197    /// <param name="restoredObjects">The dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    132198    public override void Populate(XmlNode node, IDictionary<Guid,IStorable> restoredObjects) {
    133199      base.Populate(node, restoredObjects);
     
    143209
    144210    #region Seed Methods
     211    /// <summary>
     212    /// Initializes current instance with random seed.
     213    /// </summary>
     214    /// <param name="s">A starting seed.</param>
    145215    public void seed(uint s) {
    146216      state[0] = s & 0xFFFFFFFFU;
     
    151221      p = n;
    152222    }
     223    /// <summary>
     224    /// Initializes current instance with random seed.
     225    /// </summary>
     226    /// <param name="array">A starting seed array.</param>
    153227    public void seed(uint[] array) {
    154228      seed(19650218U);
  • trunk/sources/HeuristicLab.Random/NormalDistributedRandom.cs

    r344 r1153  
    3838    private double mu;
    3939
     40    /// <summary>
     41    /// Gets or sets the value for µ.
     42    /// </summary>
    4043    public double Mu {
    4144      get { return mu; }
     
    4447    private double sigma;
    4548
     49    /// <summary>
     50    /// Gets or sets the value for sigma.
     51    /// </summary>
    4652    public double Sigma {
    4753      get { return sigma; }
     
    440446    };
    441447
     448    /// <summary>
     449    /// Initializes a new instance of <see cref="NormalDistributedRandom"/> with µ = 0 and sigma = 1
     450    /// and a new random number generator.
     451    /// </summary>
    442452    public NormalDistributedRandom() {
    443453      this.mu = 0.0;
     
    446456    }
    447457
     458    /// <summary>
     459    /// Initializes a new instance of <see cref="NormalDistributedRandom"/> with the given parameters.
     460    /// <note type="caution"> No CopyConstructor! The random number generator is not copied!</note>
     461    /// </summary>   
     462    /// <param name="uniformRandom">The random number generator.</param>
     463    /// <param name="mu">The value for µ.</param>
     464    /// <param name="sigma">The value for sigma.</param>
    448465    public NormalDistributedRandom(IRandom uniformRandom, double mu, double sigma) {
    449466      this.mu = mu;
     
    454471    #region IRandom Members
    455472
     473    /// <inheritdoc cref="IRandom.Reset()"/>
    456474    public void Reset() {
    457475      uniform.Reset();
    458476    }
    459477
     478    /// <inheritdoc cref="IRandom.Reset(int)"/>
    460479    public void Reset(int seed) {
    461480      uniform.Reset(seed);
    462481    }
    463482
     483    /// <summary>
     484    /// TODO: The method is not implemented.
     485    /// </summary>
     486    /// <returns>TODO</returns>
    464487    public int Next() {
    465488      throw new Exception("The method or operation is not implemented.");
    466489    }
    467490
     491    /// <summary>
     492    /// TODO: The method is not implemented.
     493    /// </summary>
     494    /// <param name="maxVal">TODO</param>
     495    /// <returns>TODO</returns>
    468496    public int Next(int maxVal) {
    469497      throw new Exception("The method or operation is not implemented.");
    470498    }
    471499
     500    /// <summary>
     501    /// TODO: The method is not implemented.
     502    /// </summary>
     503    /// <param name="minVal">TODO</param>
     504    /// <param name="maxVal">TODO</param>
     505    /// <returns>TODO</returns>
    472506    public int Next(int minVal, int maxVal) {
    473507      throw new Exception("The method or operation is not implemented.");
    474508    }
    475509
     510    /// <summary>
     511    /// Generates a new double random number.
     512    /// </summary>
     513    /// <returns>A double random number.</returns>
    476514    public double NextDouble() {
    477515      double signFactor = uniform.Next()%2==0?1.0:-1.0;
     
    512550
    513551    #region persistence
     552    /// <summary>
     553    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
     554    /// </summary>
     555    /// <remarks>The value of µ and sigma are saved as child nodes with tag names <c>Mu</c> and <c>Sigma</c>,
     556    /// also the random number generator is saved as a child node with tag name <c>UniformRandom</c>.</remarks>
     557    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
     558    /// <param name="document">The <see cref="XmlDocument"/> where the data is saved.</param>
     559    /// <param name="persistedObjects">A dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
     560    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    514561    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid, IStorable> persistedObjects) {
    515562      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
     
    528575    }
    529576
     577    /// <summary>
     578    /// Loads the persisted normally distributed random variable from the specified <paramref name="node"/>.
     579    /// </summary>
     580    /// <remarks>The elements of the current instance must be saved in a special way, see
     581    /// <see cref="GetXmlNode"/>.</remarks>
     582    /// <param name="node">The <see cref="XmlNode"/> where the instance is saved.</param>
     583    /// <param name="restoredObjects">The dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    530584    public override void Populate(XmlNode node, IDictionary<Guid, IStorable> restoredObjects) {
    531585      base.Populate(node, restoredObjects);
     
    536590    }
    537591
     592    /// <summary>
     593    /// Clones the current instance (deep clone).
     594    /// </summary>
     595    /// <remarks>Deep clone through <see cref="Auxiliary.Clone"/> method of helper class
     596    /// <see cref="Auxiliary"/>.</remarks>
     597    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
     598    /// <returns>The cloned object as <see cref="NormalDistributedRandom"/>.</returns>
    538599    public override object Clone(IDictionary<Guid, object> clonedObjects) {
    539600      NormalDistributedRandom clone = new NormalDistributedRandom((IRandom)Auxiliary.Clone(uniform, clonedObjects), mu, sigma);
  • trunk/sources/HeuristicLab.Random/NormalRandomAdder.cs

    r763 r1153  
    2828
    2929namespace HeuristicLab.Random {
     30  /// <summary>
     31  /// Normally distributed random number generator that adds the generated value to the existing value
     32  /// in the specified scope.
     33  /// </summary>
    3034  public class NormalRandomAdder : OperatorBase {
    3135    private static int MAX_NUMBER_OF_TRIES = 100;
    3236
     37    /// <inheritdoc select="summary"/>
    3338    public override string Description {
    3439      get {
     
    4045    }
    4146
     47    /// <summary>
     48    /// Gets or sets the value for µ.
     49    /// </summary>
     50    /// <remarks>Gets or sets the variable with the name <c>Mu</c> through the method
     51    /// <see cref="OperatorBase.GetVariable"/> of class <see cref="OperatorBase"/>.</remarks>
    4252    public double Mu {
    4353      get { return ((DoubleData)GetVariable("Mu").Value).Data; }
    4454      set { ((DoubleData)GetVariable("Mu").Value).Data = value; }
    4555    }
     56    /// <summary>
     57    /// Gets or sets the value for sigma.
     58    /// </summary>
     59    /// <remarks>Gets or sets the variable with the name <c>Sigma</c> through the method
     60    /// <see cref="OperatorBase.GetVariable"/> of class <see cref="OperatorBase"/>.</remarks>
    4661    public double Sigma {
    4762      get { return ((DoubleData)GetVariable("Sigma").Value).Data; }
     
    4964    }
    5065
     66    /// <summary>
     67    /// Initializes a new instance of <see cref="NormalRandomAdder"/> with five variable infos
     68    /// (<c>Mu</c>, <c>Sigma</c>, <c>Value</c>, <c>ShakingFactor</c> and <c>Random</c>).
     69    /// </summary>
    5170    public NormalRandomAdder() {
    5271      AddVariableInfo(new VariableInfo("Mu", "Parameter mu of the normal distribution", typeof(DoubleData), VariableKind.None));
     
    6382    }
    6483
     84    /// <summary>
     85    /// Generates a new normally distributed random number and adds it to the specified value in the
     86    /// given <paramref name="scope"/>.
     87    /// </summary>
     88    /// <param name="scope">The scope where to add the generated random number.</param>
     89    /// <returns>null.</returns>
    6590    public override IOperation Apply(IScope scope) {
    6691      IObjectData value = GetVariableValue<IObjectData>("Value", scope, false);
     
    87112      else throw new InvalidOperationException("Can't handle type " + value.GetType().Name);
    88113    }
     114    /// <summary>
     115    /// Generates a new double random number and adds it to the value of
     116    /// the given <paramref name="data"/>.
     117    /// </summary>
     118    /// <param name="data">The double object where to add the random number.</param>
     119    /// <param name="normal">The continuous, normally distributed random variable.</param>
    89120    public void AddNormal(DoubleData data, NormalDistributedRandom normal) {
    90121      data.Data += normal.NextDouble();
    91122    }
    92123
     124    /// <summary>
     125    /// Generates a new double random number and adds it to the value of the given <paramref name="data"/>
     126    /// checking its constraints.
     127    /// </summary>
     128    /// <exception cref="InvalidProgramException">Thrown when with the current settings no valid value
     129    /// could be found.</exception>
     130    /// <param name="data">The double object where to add the random number and whose constraints
     131    /// to fulfill.</param>
     132    /// <param name="normal">The continuous, normally distributed random variable.</param>
    93133    public void AddNormal(ConstrainedDoubleData data, NormalDistributedRandom normal) {
    94134      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
     
    104144    }
    105145
     146    /// <summary>
     147    /// Generates a new int random number and adds it to value of the given <paramref name="data"/>.
     148    /// </summary>
     149    /// <param name="data">The int object where to add the random number.</param>
     150    /// <param name="normal">The continuous, normally distributed random variable.</param>
    106151    public void AddNormal(IntData data, NormalDistributedRandom normal) {
    107152      data.Data = (int)Math.Round(data.Data + normal.NextDouble());
    108153    }
    109154
     155    /// <summary>
     156    /// Generates a new int random number and adds it to the value of the given <paramref name="data"/>
     157    /// checking its constraints.
     158    /// </summary>
     159    /// <exception cref="InvalidProgramException">Thrown when with the current settings no valid value
     160    /// could be found.</exception>
     161    /// <param name="data">The int object where to add the generated value and whose contraints to check.</param>
     162    /// <param name="normal">The continuous, normally distributed random variable.</param>
    110163    public void AddNormal(ConstrainedIntData data, NormalDistributedRandom normal) {
    111164      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
  • trunk/sources/HeuristicLab.Random/NormalRandomizer.cs

    r763 r1153  
    2828
    2929namespace HeuristicLab.Random {
     30  /// <summary>
     31  /// Normally distributed random number generator.
     32  /// </summary>
    3033  public class NormalRandomizer : OperatorBase {
    3134    private static int MAX_NUMBER_OF_TRIES = 100;
    3235
     36    /// <inheritdoc select="summary"/>
    3337    public override string Description {
    3438      get { return "Initializes the value of variable 'Value' to a random value normally distributed with 'Mu' and 'Sigma'."; }
    3539    }
    3640
     41    /// <summary>
     42    /// Gets or sets the value for µ.
     43    /// </summary>
     44    /// <remarks>Gets or sets the variable with the name <c>Mu</c> through the method
     45    /// <see cref="OperatorBase.GetVariable"/> of class <see cref="OperatorBase"/>.</remarks>
    3746    public double Mu {
    3847      get { return ((DoubleData)GetVariable("Mu").Value).Data; }
    3948      set { ((DoubleData)GetVariable("Mu").Value).Data = value; }
    4049    }
     50    /// <summary>
     51    /// Gets or sets the value for sigma.
     52    /// </summary>
     53    /// <remarks>Gets or sets the variable with the name <c>Sigma</c> through the method
     54    /// <see cref="OperatorBase.GetVariable"/> of class <see cref="OperatorBase"/>.</remarks>
    4155    public double Sigma {
    4256      get { return ((DoubleData)GetVariable("Sigma").Value).Data; }
     
    4458    }
    4559
     60    /// <summary>
     61    /// Initializes a new instance of <see cref="NormalRandomizer"/> with four variable infos
     62    /// (<c>Mu</c>, <c>Sigma</c>, <c>Value</c> and <c>Random</c>).
     63    /// </summary>
    4664    public NormalRandomizer() {
    4765      AddVariableInfo(new VariableInfo("Mu", "Parameter mu of the normal distribution", typeof(DoubleData), VariableKind.None));
     
    5775    }
    5876
     77    /// <summary>
     78    /// Generates a new normally distributed random variable and assigns it to the specified variable
     79    /// in the given <paramref name="scope"/>.
     80    /// </summary>
     81    /// <param name="scope">The scope where to assign the new random value to.</param>
     82    /// <returns>null.</returns>
    5983    public override IOperation Apply(IScope scope) {
    6084      IObjectData value = GetVariableValue<IObjectData>("Value", scope, false);
     
    81105    }
    82106
     107    /// <summary>
     108    /// Generates a new double random variable based on a continuous, normally distributed random number generator
     109    /// <paramref name="normal"/> and checks some contraints.
     110    /// </summary>
     111    /// <exception cref="InvalidOperationException">Thrown when with the given settings no valid value in
     112    /// 100 tries could be found.
     113    /// </exception>
     114    /// <param name="data">The double object where to assign the new number to and whose constraints
     115    /// must be fulfilled.</param>
     116    /// <param name="normal">The continuous, normally distributed random variable.</param>
    83117    public void RandomizeNormal(ConstrainedDoubleData data, NormalDistributedRandom normal) {
    84118      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
     
    94128    }
    95129
     130    /// <summary>
     131    /// Generates a new int random variable based on a continuous, normally distributed random number
     132    /// generator <paramref name="normal"/> and checks some constraints.
     133    /// </summary>
     134    /// <exception cref="InvalidOperationException">Thrown when with the given settings no valid
     135    /// value could be found.</exception>
     136    /// <param name="data">The int object where to assign the new value to and whose constraints must
     137    /// be fulfilled.</param>
     138    /// <param name="normal">The continuous, normally distributed random variable.</param>
    96139    public void RandomizeNormal(ConstrainedIntData data, NormalDistributedRandom normal) {
    97140      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
    98141        double r = normal.NextDouble();
    99         if (data.TrySetData((int)Math.Round(r))) // since r is a continuous normally distributed random variable rounding should be OK
     142        if (data.TrySetData((int)Math.Round(r))) // since r is a continuous, normally distributed random variable rounding should be OK
    100143          return;
    101144      }
     
    103146    }
    104147
     148    /// <summary>
     149    /// Generates a new double random number based on a continuous, normally distributed random number
     150    /// generator <paramref name="normal"/>.
     151    /// </summary>
     152    /// <param name="data">The double object where to assign the new value to.</param>
     153    /// <param name="normal">The continuous, normally distributed random variable.</param>
    105154    public void RandomizeNormal(DoubleData data, NormalDistributedRandom normal) {
    106155      data.Data = normal.NextDouble();
    107156    }
    108157
     158    /// <summary>
     159    /// Generates a new int random number based on a continuous, normally distributed random number
     160    /// generator <paramref name="normal"/>.
     161    /// </summary>
     162    /// <param name="data">The int object where to assign the new value to.</param>
     163    /// <param name="normal">The continuous, normally distributed random variable.</param>
    109164    public void RandomizeNormal(IntData data, NormalDistributedRandom normal) {
    110165      data.Data = (int)Math.Round(normal.NextDouble());
  • trunk/sources/HeuristicLab.Random/RandomInjector.cs

    r77 r1153  
    2929
    3030namespace HeuristicLab.Random {
     31  /// <summary>
     32  /// Injects a random variable in a given scope.
     33  /// </summary>
    3134  public class RandomInjector : OperatorBase {
     35    /// <inheritdoc select="summary"/>
    3236    public override string Description {
    3337      get { return @"TODO\r\nOperator description still missing ..."; }
    3438    }
    3539
     40    /// <summary>
     41    /// Initializes a new instance of <see cref="RandomInjector"/> with three variable infos
     42    /// (<c>SetSeedRandomly</c>, <c>Seed</c> and <c>Random</c>.)
     43    /// </summary>
    3644    public RandomInjector()
    3745      : base() {
     
    4856    }
    4957
     58    /// <summary>
     59    /// Injects a new random variable in the given <paramref name="scope"/> .
     60    /// </summary>
     61    /// <param name="scope">The scope where to inject the variable.</param>
     62    /// <returns>null.</returns>
    5063    public override IOperation Apply(IScope scope) {
    5164      bool setRandomly = GetVariableValue<BoolData>("SetSeedRandomly", scope, true).Data;
  • trunk/sources/HeuristicLab.Random/UniformRandomAdder.cs

    r763 r1153  
    2828
    2929namespace HeuristicLab.Random {
     30  /// <summary>
     31  /// Uniformly distributed random number generator that adds the generated value to the existing one.
     32  /// </summary>
    3033  public class UniformRandomAdder : OperatorBase {
    3134
    3235    private static int MAX_NUMBER_OF_TRIES = 100;
    3336
     37    /// <inheritdoc select="summary"/>
    3438    public override string Description {
    3539      get {
     
    4347    }
    4448
     49    /// <summary>
     50    /// Initializes a new instance of <see cref="UniformRandomAdder"/> with five variable infos
     51    /// (<c>Value</c>, <c>ShakingFactor</c>, <c>Random</c>, <c>Min</c> and <c>Max</c>), having an interval
     52    /// of -1.0 to 1.0.
     53    /// </summary>
    4554    public UniformRandomAdder() {
    4655      AddVariableInfo(new VariableInfo("Value", "The value to manipulate (type is one of: IntData, ConstrainedIntData, DoubleData, ConstrainedDoubleData)", typeof(IObjectData), VariableKind.In));
     
    5665    }
    5766
     67    /// <summary>
     68    /// Generates a new uniformly distributed random number and adds it to the value in the given
     69    /// <paramref name="scope"/>.
     70    /// </summary>
     71    /// <param name="scope">The current scope where to add the generated random number.</param>
     72    /// <returns>null.</returns>
    5873    public override IOperation Apply(IScope scope) {
    5974      IObjectData value = GetVariableValue<IObjectData>("Value", scope, false);
     
    85100    }
    86101
    87 
     102    /// <summary>
     103    /// Adds a new double random variable being restricted to some constraints to the value of the given
     104    /// <paramref name="data"/>.
     105    /// </summary>
     106    /// <exception cref="InvalidProgramException">Thrown when no valid value can be found.</exception>
     107    /// <param name="data">The data where to add the new variable and where to assign the new value to.</param>
     108    /// <param name="mt">The random number generator.</param>
     109    /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     110    /// <param name="max">The right border (exclusive) of the interval in which the next random number
     111    /// has to lie.</param>
    88112    public void AddUniform(ConstrainedDoubleData data, MersenneTwister mt, double min, double max) {
    89113      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
     
    99123    }
    100124
     125    /// <summary>
     126    /// Adds a new int random variable being restricted to some constraints to the value of the given
     127    /// <paramref name="data"/>.
     128    /// </summary>
     129    /// <exception cref="InvalidProgramException">Thrown when no valid value could be found.</exception>
     130    /// <param name="data">The data where to add the random value and where to assign the new value to.</param>
     131    /// <param name="mt">The random number generator.</param>
     132    /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     133    /// <param name="max">The right border (exclusive) of the interval in which the next random number
     134    /// has to lie.</param>
    101135    public void AddUniform(ConstrainedIntData data, MersenneTwister mt, double min, double max) {
    102136      for (int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
     
    109143    }
    110144
     145    /// <summary>
     146    /// Generates a new double random variable and adds it to the value of
     147    /// the given <paramref name="data"/>.
     148    /// </summary>
     149    /// <param name="data">The double object where to add the random value.</param>
     150    /// <param name="mt">The random number generator.</param>
     151    /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     152    /// <param name="max">The right border (exclusive) of the interval in which the next random number
     153    /// has to lie.</param>
    111154    public void AddUniform(DoubleData data, MersenneTwister mt, double min, double max) {
    112155      data.Data = data.Data + mt.NextDouble() * (max - min) + min;
    113156    }
    114157
     158    /// <summary>
     159    /// Generates a new int random variable and adds it to the value of the given
     160    /// <paramref name="data"/>.
     161    /// </summary>
     162    /// <param name="data">The int object where to add the random value.</param>
     163    /// <param name="mt">The random number generator.</param>
     164    /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     165    /// <param name="max">The right border (exclusive) of the interval in which the next random number
     166    /// has to lie.</param>
    115167    public void AddUniform(IntData data, MersenneTwister mt, double min, double max) {
    116168      data.Data = (int)Math.Floor(data.Data + mt.NextDouble() * (max - min) + min);
  • trunk/sources/HeuristicLab.Random/UniformRandomizer.cs

    r763 r1153  
    2828
    2929namespace HeuristicLab.Random {
     30  /// <summary>
     31  /// Uniformly distributed random number generator.
     32  /// </summary>
    3033  public class UniformRandomizer : OperatorBase {
    3134    private static int MAX_NUMBER_OF_TRIES = 100;
     35    /// <inheritdoc select="summary"/>
    3236    public override string Description {
    3337      get { return "Initializes the value of variable 'Value' to a random value uniformly distributed between 'Min' and 'Max' (exclusive)"; }
    3438    }
    3539
     40    /// <summary>
     41    /// Gets or sets the maximum value of the random number generator (exclusive).
     42    /// </summary>
     43    /// <remarks>Gets or sets the variable with name <c>Max</c> through the
     44    /// <see cref="OperatorBase.GetVariable"/> method of class <see cref="OperatorBase"/>.</remarks>
    3645    public double Max {
    3746      get { return ((DoubleData)GetVariable("Max").Value).Data; }
    3847      set { ((DoubleData)GetVariable("Max").Value).Data = value; }
    3948    }
     49    /// <summary>
     50    /// Gets or sets the minimum value of the random number generator.
     51    /// </summary>
     52    /// <remarks>Gets or sets the variable with name <c>Min</c> through the
     53    /// <see cref="OperatorBase.GetVariable"/> method of class <see cref="OperatorBase"/>.</remarks>
    4054    public double Min {
    4155      get { return ((DoubleData)GetVariable("Min").Value).Data; }
     
    4357    }
    4458
     59    /// <summary>
     60    /// Initializes a new instance of <see cref="UniformRandomizer"/> with four variable infos
     61    /// (<c>Value</c>, <c>Random</c>, <c>Max</c> and <c>Min</c>), being a random number generator
     62    /// between 0.0 and 1.0.
     63    /// </summary>
    4564    public UniformRandomizer() {
    4665      AddVariableInfo(new VariableInfo("Value", "The value to manipulate (type is one of: IntData, ConstrainedIntData, DoubleData, ConstrainedDoubleData)", typeof(IObjectData), VariableKind.In));
     
    5574    }
    5675
     76    /// <summary>
     77    /// Generates a new uniformly distributed random variable.
     78    /// </summary>
     79    /// <param name="scope">The scope where to apply the random number generator.</param>
     80    /// <returns>null.</returns>
    5781    public override IOperation Apply(IScope scope) {
    5882      IObjectData value = GetVariableValue<IObjectData>("Value", scope, false);
     
    6589    }
    6690
     91    /// <summary>
     92    /// Generates a new random number depending on the type of the <paramref name="value"/>.
     93    /// </summary>
     94    /// <exception cref="ArgumentException">Thrown when an unhandleable type appears.</exception>
     95    /// <param name="value">The object whose data should be a new randomly generated number.</param>
     96    /// <param name="mt">The MersenneTwister to generate a new random number.</param>
     97    /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     98    /// <param name="max">The right border (exclusive) of the interval in which the next random number
     99    /// has to lie.</param>
    67100    private void RandomizeUniform(IObjectData value, MersenneTwister mt, double min, double max) {
    68101      // Dispatch manually based on dynamic type,
     
    79112    }
    80113
    81 
     114      /// <summary>
     115      /// Generates a new double random number.
     116      /// </summary>
     117      /// <param name="data">The double object which the new value is assigned to.</param>
     118      /// <param name="mt">The random number generator.</param>
     119      /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     120      /// <param name="max">The right border (exclusive) of the interval in which the next random number
     121      /// has to lie.</param>
    82122      public void RandomizeUniform(DoubleData data, MersenneTwister mt, double min, double max) {
    83123        data.Data = mt.NextDouble() * (max - min) + min;
    84124      }
    85125
     126      /// <summary>
     127      /// Generates a new int random number.
     128      /// </summary>
     129      /// <param name="data">The int object which the new value is assigned to.</param>
     130      /// <param name="mt">The random number generator.</param>
     131      /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     132      /// <param name="max">The right border (exclusive) of the interval in which the next random number
     133      /// has to lie.</param>
    86134      public void RandomizeUniform(IntData data, MersenneTwister mt, double min, double max) {
    87135        data.Data = (int)Math.Floor(mt.NextDouble() * (max - min) + min);
    88136      }
    89137
     138      /// <summary>
     139      /// Generates a new double random number, being restricted to some constraints.
     140      /// </summary>
     141      /// <exception cref="InvalidOperationException">Thrown when no valid value could be found.</exception>
     142      /// <param name="data">The double object which the new value is assigned to and whose constraints
     143      /// must be fulfilled.</param>
     144      /// <param name="mt">The random number generator.</param>
     145      /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     146      /// <param name="max">The right border (exclusive) of the interval in which the next random number
     147      /// has to lie.</param>
    90148      public void RandomizeUniform(ConstrainedDoubleData data, MersenneTwister mt, double min, double max) {
    91149        for(int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
     
    100158        throw new InvalidOperationException("Couldn't find a valid value");
    101159      }
    102 
     160      /// <summary>
     161      /// Generates a new int random number, being restricted to some constraints.
     162      /// </summary>
     163      /// <exception cref="InvalidOperationException">Thrown when no valid value could be found.</exception>
     164      /// <param name="data">The int object which the new value is assigned to and whose constraints
     165      /// must be fulfilled.</param>
     166      /// <param name="mt">The random number generator.</param>
     167      /// <param name="min">The left border of the interval in which the next random number has to lie.</param>
     168      /// <param name="max">The right border (exclusive) of the interval in which the next random number
     169      /// has to lie.</param>
    103170      public void RandomizeUniform(ConstrainedIntData data, MersenneTwister mt, double min, double max) {
    104171        for(int tries = MAX_NUMBER_OF_TRIES; tries >= 0; tries--) {
  • trunk/sources/HeuristicLab.SGA/HeuristicLabSGAPlugin.cs

    r582 r1153  
    2626
    2727namespace HeuristicLab.SGA {
     28  /// <summary>
     29  /// Plugin class for HeuristicLab.SGA plugin.
     30  /// </summary>
    2831  [ClassInfo(Name = "HeuristicLab.SGA-3.2")]
    2932  [PluginFile(Filename = "HeuristicLab.SGA-3.2.dll", Filetype = PluginFileType.Assembly)]
  • trunk/sources/HeuristicLab.SGA/SGA.cs

    r65 r1153  
    3333
    3434namespace HeuristicLab.SGA {
     35  /// <summary>
     36  /// Class for the heuristic optimization technique "simple genetic algorithm".
     37  /// </summary>
    3538  public class SGA : ItemBase, IEditable {
    3639    #region Create Operators
     40    /// <summary>
     41    /// Creates operators for the current instance.
     42    /// </summary>
     43    /// <param name="engine">The engine where to add the operators.</param>
    3744    public static void Create(IEngine engine) {
    3845      engine.OperatorGraph.Clear();
     
    355362    #region Properties
    356363    private IEngine myEngine;
     364    /// <summary>
     365    /// Gets the engine of the current instance.
     366    /// </summary>
    357367    public IEngine Engine {
    358368      get { return myEngine; }
    359369    }
    360370    private BoolData mySetSeedRandomly;
     371    /// <summary>
     372    /// Gets or sets the flag whether to set the seed randomly or not.
     373    /// </summary>
    361374    public bool SetSeedRandomly {
    362375      get { return mySetSeedRandomly.Data; }
     
    364377    }
    365378    private IntData mySeed;
     379    /// <summary>
     380    /// Gets or sets the value of the seed of the current instance.
     381    /// </summary>
    366382    public int Seed {
    367383      get { return mySeed.Data; }
     
    370386    private IntData myPopulationSize;
    371387    private IntData myParents;
     388    /// <summary>
     389    /// Gets or sets the population size of the current instance.
     390    /// </summary>
     391    /// <remarks>The number of parents is set to two times the population size.</remarks>
    372392    public int PopulationSize {
    373393      get { return myPopulationSize.Data; }
     
    378398    }
    379399    private IntData myMaximumGenerations;
     400    /// <summary>
     401    /// Gets or sets the number of maximum generations.
     402    /// </summary>
    380403    public int MaximumGenerations {
    381404      get { return myMaximumGenerations.Data; }
     
    383406    }
    384407    private DoubleData myMutationRate;
     408    /// <summary>
     409    /// Gets or sets the mutation rate of the current instance.
     410    /// </summary>
    385411    public double MutationRate {
    386412      get { return myMutationRate.Data; }
     
    388414    }
    389415    private IntData myElites;
     416    /// <summary>
     417    /// Gets or sets the elites of the current instance.
     418    /// </summary>
    390419    public int Elites {
    391420      get { return myElites.Data; }
     
    394423    private CombinedOperator mySGA;
    395424    private IOperator myVariableInjection;
     425    /// <summary>
     426    /// Gets or sets the problem injector of the current instance.
     427    /// </summary>
    396428    public IOperator ProblemInjector {
    397429      get { return myVariableInjection.SubOperators[0]; }
     
    404436    }
    405437    private IOperator myPopulationInitialization;
     438    /// <summary>
     439    /// Gets or sets the solution generator of the current instance.
     440    /// </summary>
    406441    public IOperator SolutionGenerator {
    407442      get { return myPopulationInitialization.SubOperators[0]; }
     
    413448      }
    414449    }
     450    /// <summary>
     451    /// Gets or sets the evaluator of the current instance.
     452    /// </summary>
    415453    public IOperator Evaluator {
    416454      get { return myPopulationInitialization.SubOperators[1]; }
     
    424462    }
    425463    private IOperator mySGAMain;
     464    /// <summary>
     465    /// Gets or sets the selection operator of the current instance.
     466    /// </summary>
    426467    public IOperator Selector {
    427468      get { return mySGAMain.SubOperators[0]; }
     
    433474      }
    434475    }
     476    /// <summary>
     477    /// Gets or sets the crossover operator of the current instance.
     478    /// </summary>
    435479    public IOperator Crossover {
    436480      get { return mySGAMain.SubOperators[1]; }
     
    442486      }
    443487    }
     488    /// <summary>
     489    /// Gets or sets the mutation operator of the current instance.
     490    /// </summary>
    444491    public IOperator Mutator {
    445492      get { return mySGAMain.SubOperators[2]; }
     
    453500    #endregion
    454501
     502    /// <summary>
     503    /// Initializes a new instance of <see cref="SGA"/>.
     504    /// </summary>
    455505    public SGA() {
    456506      myEngine = new SequentialEngine.SequentialEngine();
     
    459509    }
    460510
     511    /// <summary>
     512    /// Creates a new instance of the <see cref="SGAEditor"/> class.
     513    /// </summary>
     514    /// <returns>The created instance of the <see cref="SGAEditor"/>.</returns>
    461515    public override IView CreateView() {
    462516      return new SGAEditor(this);
    463517    }
     518    /// <summary>
     519    /// Creates a new instance of the <see cref="SGAEditor"/> class.
     520    /// </summary>
     521    /// <returns>The created instance of the <see cref="SGAEditor"/>.</returns>
    464522    public virtual IEditor CreateEditor() {
    465523      return new SGAEditor(this);
    466524    }
    467525
     526    /// <summary>
     527    /// Clones the current instance (deep clone).
     528    /// </summary>
     529    /// <remarks>Deep clone through <see cref="Auxiliary.Clone"/> method of helper class
     530    /// <see cref="Auxiliary"/>.</remarks>
     531    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
     532    /// <returns>The cloned object as <see cref="SGA"/>.</returns>
    468533    public override object Clone(IDictionary<Guid, object> clonedObjects) {
    469534      SGA clone = new SGA();
     
    506571
    507572    #region Persistence Methods
     573    /// <summary>
     574    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
     575    /// </summary>
     576    /// <remarks>The engine of the current instance is saved as a child node with the tag name
     577    /// <c>Engine</c>.</remarks>
     578    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
     579    /// <param name="document">The <see cref="XmlDocument"/> where the data is saved.</param>
     580    /// <param name="persistedObjects">A dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
     581    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    508582    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid,IStorable> persistedObjects) {
    509583      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
     
    511585      return node;
    512586    }
     587    /// <summary>
     588    /// Loads the persisted instance from the specified <paramref name="node"/>.
     589    /// </summary>
     590    /// <remarks>The elements of the current instance must be saved in a special way, see
     591    /// <see cref="GetXmlNode"/>.</remarks>
     592    /// <param name="node">The <see cref="XmlNode"/> where the instance is saved.</param>
     593    /// <param name="restoredObjects">The dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    513594    public override void Populate(XmlNode node, IDictionary<Guid,IStorable> restoredObjects) {
    514595      base.Populate(node, restoredObjects);
  • trunk/sources/HeuristicLab.SGA/SGAEditor.cs

    r65 r1153  
    3131
    3232namespace HeuristicLab.SGA {
     33  /// <summary>
     34  /// Visual representation of the <see cref="SGA"/> class.
     35  /// </summary>
    3336  public partial class SGAEditor : EditorBase {
    3437    private ChooseOperatorDialog chooseOperatorDialog;
    3538
     39    /// <summary>
     40    /// Gets or sets the <see cref="SGA"/> item to represent visually.
     41    /// </summary>
     42    /// <remarks>Uses property <see cref="ViewBase.Item"/> of base class <see cref="EditorBase"/>.
     43    /// No own data storage present!</remarks>
    3644    public SGA SGA {
    3745      get { return (SGA)Item; }
     
    3947    }
    4048
     49    /// <summary>
     50    /// Initializes a new instance of <see cref="SGAEditor"/>.
     51    /// </summary>
    4152    public SGAEditor() {
    4253      InitializeComponent();
    4354    }
     55    /// <summary>
     56    /// Initializes a new instance of <see cref="SGAEditor"/> with the given <paramref name="sga"/>.
     57    /// </summary>
     58    /// <param name="sga">The simple genetic algorithm to represent visually.</param>
    4459    public SGAEditor(SGA sga)
    4560      : this() {
     
    4762    }
    4863
     64    /// <summary>
     65    /// Removes the eventhandlers from the underlying <see cref="IEngine"/> of the <see cref="SGA"/>.
     66    /// </summary>
     67    /// <remarks>Calls <see cref="ViewBase.RemoveItemEvents"/> of base class <see cref="EditorBase"/>.</remarks>
    4968    protected override void RemoveItemEvents() {
    5069      SGA.Engine.ExceptionOccurred -= new EventHandler<ExceptionEventArgs>(Engine_ExceptionOccurred);
     
    5372      base.RemoveItemEvents();
    5473    }
     74    /// <summary>
     75    /// Adds eventhandlers to the underlying <see cref="IEngine"/> of the <see cref="SGA"/>.
     76    /// </summary>
     77    /// <remarks>Calls <see cref="ViewBase.AddItemEvents"/> of base class <see cref="EditorBase"/>.</remarks>
    5578    protected override void AddItemEvents() {
    5679      base.AddItemEvents();
     
    6184    }
    6285
     86    /// <summary>
     87    /// Updates all controls with the latest data of the model.
     88    /// </summary>
     89    /// <remarks>Calls <see cref="EditorBase.UpdateControls"/> of base class <see cref="EditorBase"/>.</remarks>
    6390    protected override void UpdateControls() {
    6491      base.UpdateControls();
  • trunk/sources/HeuristicLab.Selection.OffspringSelection/HeuristicLabSelectionOffspringSelectionPlugin.cs

    r582 r1153  
    2626
    2727namespace HeuristicLab.Selection.OffspringSelection {
     28  /// <summary>
     29  /// Plugin class for HeuristicLab.Selection.OffspringSelection plugin.
     30  /// </summary>
    2831  [ClassInfo(Name = "HeuristicLab.Selection.OffspringSelection-3.2")]
    2932  [PluginFile(Filename = "HeuristicLab.Selection.OffspringSelection-3.2.dll", Filetype = PluginFileType.Assembly)]
  • trunk/sources/HeuristicLab.Selection.OffspringSelection/OffspringAnalyzer.cs

    r806 r1153  
    2727
    2828namespace HeuristicLab.Selection.OffspringSelection {
     29  /// <summary>
     30  /// Analyzes the offspring in a given scope whether it is successful or not.
     31  /// </summary>
    2932  public class OffspringAnalyzer : OperatorBase {
     33    /// <inheritdoc select="summary"/>
    3034    public override string Description {
    3135      get { return @"TODO\r\nOperator description still missing ..."; }
    3236    }
    3337
     38    /// <summary>
     39    /// Initializes a new instance of <see cref="OffspringAnalyzer"/> with six variable infos
     40    /// (<c>Maximization</c>, <c>Quality</c>, <c>ParentQualities</c>, <c>SuccessfulChild</c>,
     41    /// <c>ComparisonFactor</c> and <c>ParentsCount</c>).
     42    /// </summary>
    3443    public OffspringAnalyzer() {
    3544      AddVariableInfo(new VariableInfo("Maximization", "Problem is a maximization problem", typeof(BoolData), VariableKind.In));
     
    4857    }
    4958
     59    /// <summary>
     60    /// Analyzes the offspring in the given scope whether the children are successful or not.
     61    /// </summary>
     62    /// <exception cref="InvalidOperationException">Thrown when <c>ParentsCount</c> smaller than 1.</exception>
     63    /// <exception cref="InvalidOperationException">Thrown when the number of children is not constant or
     64    /// smaller than 1.</exception>
     65    /// <param name="scope">The scope whose offspring should be analyzed.</param>
     66    /// <returns>The next operation or null.</returns>
    5067    public override IOperation Apply(IScope scope) {
    5168      bool maximize = GetVariableValue<BoolData>("Maximization", scope, true).Data;
  • trunk/sources/HeuristicLab.Selection.OffspringSelection/OffspringSelector.cs

    r301 r1153  
    2727
    2828namespace HeuristicLab.Selection.OffspringSelection {
     29  /// <summary>
     30  /// Selects successful and also according to the selection pressure some unsuccessful children.
     31  /// </summary>
    2932  public class OffspringSelector : OperatorBase {
     33    /// <inheritdoc select="summary"/>
    3034    public override string Description {
    3135      get { return @"TODO\r\nOperator description still missing ..."; }
    3236    }
    3337
     38    /// <summary>
     39    /// Initializes a new instance of <see cref="OffspringSelector"/> with seven variable infos
     40    /// (<c>SuccessfulChild</c>, <c>SelectionPressureLimit</c>, <c>SuccessRatioLimit</c>,
     41    /// <c>SelectionPressure</c>, <c>SuccessRatio</c>, <c>GoodChildren</c> and <c>BadChildren</c>).
     42    /// </summary>
    3443    public OffspringSelector() {
    3544      AddVariableInfo(new VariableInfo("SuccessfulChild", "True if the child was successful", typeof(BoolData), VariableKind.In));
     
    4251    }
    4352
     53    /// <summary>
     54    /// Selects successful children and also some bad ones depending on the selection
     55    /// pressure out of a population.
     56    /// </summary>
     57    /// <param name="scope">The current scope of the parents and the children.</param>
     58    /// <returns>The next operation or null.</returns>
    4459    public override IOperation Apply(IScope scope) {
    4560      double selectionPressureLimit = GetVariableValue<DoubleData>("SelectionPressureLimit", scope, true).Data;
Note: See TracChangeset for help on using the changeset viewer.