Free cookie consent management tool by TermsFeed Policy Generator

Changeset 884 for trunk/sources


Ignore:
Timestamp:
12/02/08 12:41:21 (16 years ago)
Author:
vdorfer
Message:

Created API documentation for HeuristicLab.Routing.TSP namespace (#331)

Location:
trunk/sources/HeuristicLab.Routing.TSP
Files:
12 edited

Legend:

Unmodified
Added
Removed

  • trunk/sources/HeuristicLab.Routing.TSP/DistanceMatrixPathTSPEvaluator.cs

    r2 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Evaluates the TSP path by using values in the distance matrix.
     33  /// </summary>
    3134  public class DistanceMatrixPathTSPEvaluator : SingleObjectiveEvaluatorBase {
     35    /// <inheritdoc/>
    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="DistanceMatrixPathTSPEvaluator"/> with two variable
     42    /// infos (<c>Permutation</c>, <c>DistanceMatrix</c>).
     43    /// </summary>
    3644    public DistanceMatrixPathTSPEvaluator()
    3745      : base() {
    … …  
    4048    }
    4149
     50    /// <summary>
     51    /// Calculates the length of the path in the given <paramref name="scope"/> by taking the
     52    /// values of the distance matrix.
     53    /// </summary>
     54    /// <param name="scope">The current scope with the permutation and the distance matrix.</param>
     55    /// <returns>The calculated length.</returns>
    4256    protected override double Evaluate(IScope scope) {
    4357      double[,] distanceMatrix = GetVariableValue<DoubleMatrixData>("DistanceMatrix", scope, true).Data;

  • trunk/sources/HeuristicLab.Routing.TSP/HeuristicLabRoutingTSPPlugin.cs

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

  • trunk/sources/HeuristicLab.Routing.TSP/PathTSPEvaluatorBase.cs

    r2 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Base class for TSP path evaluation, based on length calculation.
     33  /// </summary>
    3134  public abstract class PathTSPEvaluatorBase : SingleObjectiveEvaluatorBase {
     35    /// <summary>
     36    /// Initializes a new instance of <see cref="PathTSPEvaluatorBase"/> with two variable infos
     37    /// (<c>Coordinates</c> and <c>Permutation</c>).
     38    /// </summary>
    3239    public PathTSPEvaluatorBase()
    3340      : base() {
    … …  
    3643    }
    3744
     45    /// <summary>
     46    /// Calculates the length of a whole path of the given <paramref name="scope"/>.
     47    /// </summary>
     48    /// <param name="scope">The scope where to evaluate the path.</param>
     49    /// <returns>The calculated length.</returns>
    3850    protected sealed override double Evaluate(IScope scope) {
    3951      double[,] coordinates = GetVariableValue<DoubleMatrixData>("Coordinates", scope, true).Data;
    … …  
    5365    }
    5466
     67    /// <summary>
     68    /// Calculates the distance between two given points.
     69    /// </summary>
     70    /// <param name="x1">The x coordinate of point 1.</param>
     71    /// <param name="y1">The y coordinate of point 1.</param>
     72    /// <param name="x2">The x coordinate of point 2.</param>
     73    /// <param name="y2">The y coordinate of point 2.</param>
     74    /// <returns>The calculated distance.</returns>
    5575    protected abstract double CalculateDistance(double x1, double y1, double x2, double y2);
    5676  }

  • trunk/sources/HeuristicLab.Routing.TSP/RoundedEuclideanPathTSPEvaluator.cs

    r2 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Evaluates the TSP path by using the euclidean distance between two points.
     33  /// </summary>
    3134  public class RoundedEuclideanPathTSPEvaluator : PathTSPEvaluatorBase {
     35    /// <inheritdoc/>
    3236    public override string Description {
    3337      get { return @"TODO\r\nOperator description still missing ..."; }
    3438    }
    3539
     40    /// <summary>
     41    /// Calculates the distance between two points by using the euclidean distance.
     42    /// </summary>
     43    /// <param name="x1">The x coordinate of point 1.</param>
     44    /// <param name="y1">The y coordinate of point 1.</param>
     45    /// <param name="x2">The x coordinate of point 2.</param>
     46    /// <param name="y2">The y coordinate of point 2.</param>
     47    /// <returns>The euclidean distance between the two points.</returns>
    3648    protected override double CalculateDistance(double x1, double y1, double x2, double y2) {
    3749      return Math.Round(Math.Sqrt((x1 - x2) * (x1 - x2) + (y1 - y2) * (y1 - y2)));

  • trunk/sources/HeuristicLab.Routing.TSP/TSPDistanceMatrixInjectorBase.cs

    r77 r884  
    2828
    2929namespace HeuristicLab.Routing.TSP {
     30  /// <summary>
     31  /// Base class to inject the calculated distance matrix of the TSP path into the current scope.
     32  /// </summary>
    3033  public abstract class TSPDistanceMatrixInjectorBase : OperatorBase {
     34    /// <summary>
     35    /// Initializes a new instance of <see cref="TSPDistanceMatrixInjectorBase"/> with three variable infos
     36    /// (<c>Cities</c>, <c>Coordinates</c> and <c>DistanceMatrix</c>).
     37    /// </summary>
    3138    public TSPDistanceMatrixInjectorBase()
    3239      : base() {
    … …  
    3643    }
    3744
     45    /// <summary>
     46    /// Generates a distance matrix with the distances between all cities in the current path.
     47    /// </summary>
     48    /// <param name="scope">The current scope with the path.</param>
     49    /// <returns><c>null</c>.</returns>
    3850    public override IOperation Apply(IScope scope) {
    3951      int cities = GetVariableValue<IntData>("Cities", scope, true).Data;
    … …  
    5466    }
    5567
     68    /// <summary>
     69    /// Calculates the distance between two points in the path.
     70    /// </summary>
     71    /// <param name="x1">The x coordinate of point 1.</param>
     72    /// <param name="y1">The y coordinate of point 1.</param>
     73    /// <param name="x2">The x coordinate of point 2.</param>
     74    /// <param name="y2">The y coordinate of point 2.</param>
     75    /// <returns>The calculated distance.</returns>
    5676    protected abstract double CalculateDistance(double x1, double y1, double x2, double y2);
    5777  }

  • trunk/sources/HeuristicLab.Routing.TSP/TSPInjector.cs

    r77 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Injects a new TSP in a given scope with all its needed variables....
     33  /// </summary>
    3134  public class TSPInjector : OperatorBase {
     35    /// <inheritdoc/>
    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="TSPInjector"/> with four variable infos
     42    /// (<c>Maximization</c>, <c>Cities</c>, <c>Coordinates</c> and <c>BestKnownQuality</c>).
     43    /// </summary>
    3644    public TSPInjector()
    3745      : base() {
    … …  
    4654    }
    4755
     56    /// <summary>
     57    /// Creates a new instance of <see cref="TSPInjectorView"/> to display the current instance.
     58    /// </summary>
     59    /// <returns>The created view as <see cref="TSPInjectorView"/>.</returns>
    4860    public override IView CreateView() {
    4961      return new TSPInjectorView(this);
    5062    }
    5163
     64    /// <summary>
     65    /// Adds a new TSP to the given <paramref name="scope"/>, through adding the needed variables.
     66    /// </summary>
     67    /// <param name="scope">The current scope where to inject the variables.</param>
     68    /// <returns><c>null</c>.</returns>
    5269    public override IOperation Apply(IScope scope) {
    5370      scope.AddVariable(new Variable(scope.TranslateName("Maximization"), new BoolData(false)));

  • trunk/sources/HeuristicLab.Routing.TSP/TSPInjectorView.cs

    r2 r884  
    3232
    3333namespace HeuristicLab.Routing.TSP {
     34  /// <summary>
     35  /// Class to represent a <see cref="TSPInjector"/> visually.
     36  /// </summary>
    3437  public partial class TSPInjectorView : ViewBase {
     38    /// <summary>
     39    /// Gets or set the <see cref="TSPInjector"/> to represent visually.
     40    /// </summary>       
     41    /// <remarks>Uses property <see cref="ViewBase.Item"/> of base class <see cref="ViewBase"/>.
     42    /// No own data storage present.</remarks>
    3543    public TSPInjector TSPInjector {
    3644      get { return (TSPInjector)Item; }
    … …  
    3846    }
    3947
     48    /// <summary>
     49    /// Initializes a new instance of <see cref="TSPInjectorView"/>.
     50    /// </summary>
    4051    public TSPInjectorView() {
    4152      InitializeComponent();
    4253    }
     54    /// <summary>
     55    /// Initializes a new instance of <see cref="TSPInjectorView"/> with the given
     56    /// <paramref name="tspInjector"/>.
     57    /// </summary>
     58    /// <param name="tspInjector">The <see cref="TSPInjector"/> to display.</param>
    4359    public TSPInjectorView(TSPInjector tspInjector)
    4460      : this() {
    … …  
    4662    }
    4763
     64    /// <summary>
     65    /// Removes the event handlers in all children.
     66    /// </summary>
     67    /// <remarks>Calls <see cref="ViewBase.RemoveItemEvents"/> of base class <see cref="ViewBase"/>.</remarks>
    4868    protected override void RemoveItemEvents() {
    4969      operatorBaseVariableInfosView.Operator = null;
    … …  
    5171      base.RemoveItemEvents();
    5272    }
     73    /// <summary>
     74    /// Adds event handlers in all children.
     75    /// </summary>
     76    /// <remarks>Calls <see cref="ViewBase.AddItemEvents"/> of base class <see cref="ViewBase"/>.</remarks>
    5377    protected override void AddItemEvents() {
    5478      base.AddItemEvents();
    … …  
    5781    }
    5882
     83    /// <summary>
     84    /// Updates all controls with the latest data of the model.
     85    /// </summary>
     86    /// <remarks>Calls <see cref="ViewBase.UpdateControls"/> of base class <see cref="ViewBase"/>.</remarks>
    5987    protected override void UpdateControls() {
    6088      base.UpdateControls();

  • trunk/sources/HeuristicLab.Routing.TSP/TSPParser.cs

    r2 r884  
    2727
    2828namespace HeuristicLab.Routing.TSP {
     29  /// <summary>
     30  /// Parses a *.tsp file and extracts its information about a TSP.
     31  /// </summary>
    2932  public class TSPParser {
    3033    private const int EOF = 0;
    … …  
    3942
    4043    private string myName;
     44    /// <summary>
     45    /// Gets the name of the parsed TSP.
     46    /// </summary>
    4147    public string Name {
    4248      get { return myName; }
    4349    }
    4450    private double[,] myVertices;
     51    /// <summary>
     52    /// Gets the vertices of the parsed TSP.
     53    /// </summary>
    4554    public double[,] Vertices {
    4655      get { return myVertices; }
    4756    }
    4857    private int myWeightType;
     58    /// <summary>
     59    /// Gets the weight type of the parsed TSP.
     60    /// </summary>
    4961    public int WeightType {
    5062      get { return myWeightType; }
    5163    }
    5264
     65    /// <summary>
     66    /// Initializes a new instance of <see cref="TSPParser"/> with the given <paramref name="path"/>.
     67    /// </summary>
     68    /// <exception cref="ArgumentException">Thrown when the input file name is not in TSP format (*.tsp)
     69    /// </exception>
     70    /// <param name="path">The path where the TSP is stored.</param>
    5371    public TSPParser(String path) {
    5472      if (!path.EndsWith(".tsp"))
    … …  
    6179    }
    6280
     81    /// <summary>
     82    /// Reads the TSP file and parses the elements.
     83    /// </summary>
     84    /// <exception cref="InvalidDataException">Thrown when file contains unknown (edge) types.</exception>
    6385    public void Parse() {
    6486      int section = -1;

  • trunk/sources/HeuristicLab.Routing.TSP/TSPRoundedEuclideanDistanceMatrixInjector.cs

    r2 r884  
    2828
    2929namespace HeuristicLab.Routing.TSP {
     30  /// <summary>
     31  /// Injects a distance matrix with euclidean distances of a TSP path into the current scope.
     32  /// </summary>
    3033  public class TSPRoundedEuclideanDistanceMatrixInjector : TSPDistanceMatrixInjectorBase {
     34    /// <inheritdoc/>
    3135    public override string Description {
    3236      get { return @"TODO\r\nOperator description still missing ..."; }
    3337    }
    3438
     39    /// <summary>
     40    /// Calculates the distance between two points by using the euclidean distance.
     41    /// </summary>
     42    /// <param name="x1">The x coordinate of point 1.</param>
     43    /// <param name="y1">The y coordinate of point 1.</param>
     44    /// <param name="x2">The x coordinate of point 2.</param>
     45    /// <param name="y2">The y coordinate of point 2.</param>
     46    /// <returns>The euclidean distance between the two points.</returns>
    3547    protected override double CalculateDistance(double x1, double y1, double x2, double y2) {
    3648      return Math.Round(Math.Sqrt((x1 - x2) * (x1 - x2) + (y1 - y2) * (y1 - y2)));

  • trunk/sources/HeuristicLab.Routing.TSP/TSPTour.cs

    r2 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Represent the tour of a TSP.
     33  /// </summary>
    3134  public class TSPTour : ItemBase, IVisualizationItem {
    3235    private DoubleMatrixData myCoordinates;
     36    /// <summary>
     37    /// Gets or sets the coordinates of the current instance.
     38    /// </summary>
    3339    public DoubleMatrixData Coordinates {
    3440      get { return myCoordinates; }
    … …  
    3642    }
    3743    private Permutation.Permutation myTour;
     44    /// <summary>
     45    /// Gets or sets the current permutation/tour of the current instance.
     46    /// </summary>
    3847    public Permutation.Permutation Tour {
    3948      get { return myTour; }
    … …  
    4251
    4352
     53    /// <summary>
     54    /// Initializes a new instance of <see cref="TSPTour"/>.
     55    /// </summary>
    4456    public TSPTour() { }
     57    /// <summary>
     58    /// Initializes a new instance of <see cref="TSPTour"/> with the given <paramref name="coordinates"/>
     59    /// and the given <paramref name="tour"/>.
     60    /// </summary>
     61    /// <param name="coordinates">The coordinates of the TSP.</param>
     62    /// <param name="tour">The tour the current instance should represent.</param>
    4563    public TSPTour(DoubleMatrixData coordinates, Permutation.Permutation tour) {
    4664      myCoordinates = coordinates;
    … …  
    4866    }
    4967
    50 
     68    /// <summary>
     69    /// Clones the current instance (deep clone).
     70    /// </summary>
     71    /// <remarks>Uses <see cref="Auxiliary.Clone"/> method of class <see cref="Auxiliary"/> to clone
     72    /// the coordinates.</remarks>
     73    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
     74    /// <returns>The cloned object as <see cref="TSPTour"/>.</returns>
    5175    public override object Clone(IDictionary<Guid, object> clonedObjects) {
    5276      TSPTour clone = (TSPTour)base.Clone(clonedObjects);
    … …  
    5680    }
    5781
     82    /// <summary>
     83    /// Creates a new instance of <see cref="TSPTourView"/> to display the current instance.
     84    /// </summary>
     85    /// <returns>The created view as <see cref="TSPTourView"/>.</returns>
    5886    public override IView CreateView() {
    5987      return new TSPTourView(this);
    6088    }
    6189
     90    /// <summary>
     91    /// Occurs when the coordinates of the current instance have been changed.
     92    /// </summary>
    6293    public event EventHandler CoordinatesChanged;
     94    /// <summary>
     95    /// Fires a new <c>CoordinatesChanged</c> event.
     96    /// </summary>
    6397    protected virtual void OnCoordinatesChanged() {
    6498      if (CoordinatesChanged != null)
    6599        CoordinatesChanged(this, new EventArgs());
    66100    }
     101    /// <summary>
     102    /// Occurs when the tour of the current instance has been changed.
     103    /// </summary>
    67104    public event EventHandler TourChanged;
     105    /// <summary>
     106    /// Fires a new <c>TourChanged</c> event.
     107    /// </summary>
    68108    protected virtual void OnTourChanged() {
    69109      if (TourChanged != null)
    … …  
    72112
    73113    #region Persistence Methods
     114    /// <summary>
     115    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
     116    /// </summary>
     117    /// <remarks>Calls <see cref="StorableBase.GetXmlNode"/> of base class <see cref="ItemBase"/>. <br/>
     118    /// The coordinates and the tour are saved as a child node with the tag names <c>Coordinates</c> and
     119    /// <c>Tour</c>.</remarks>
     120    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
     121    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
     122    /// <param name="persistedObjects">The dictionary of all already persisted objects.
     123    /// (Needed to avoid cycles.)</param>
     124    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    74125    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid, IStorable> persistedObjects) {
    75126      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
    … …  
    78129      return node;
    79130    }
     131    /// <summary>
     132    /// Loads the persisted TSP tour from the specified <paramref name="node"/>.
     133    /// </summary>
     134    /// <remarks>Calls <see cref="StorableBase.Populate"/> of base class
     135    /// <see cref="ItemBase"/>.<br/>
     136    /// The coordinates and the tour must be saved as child nodes with the tag names <c>Coordinates</c>
     137    /// and <c>Tour</c> (see <see cref="GetXmlNode"/>).</remarks>
     138    /// <param name="node">The <see cref="XmlNode"/> where the TSP tour is saved.</param>
     139    /// <param name="restoredObjects">A dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    80140    public override void Populate(XmlNode node, IDictionary<Guid, IStorable> restoredObjects) {
    81141      base.Populate(node, restoredObjects);

  • trunk/sources/HeuristicLab.Routing.TSP/TSPTourInjector.cs

    r77 r884  
    2929
    3030namespace HeuristicLab.Routing.TSP {
     31  /// <summary>
     32  /// Injects a new TSP tour in a given scope with all its neccessary variables.
     33  /// </summary>
    3134  public class TSPTourInjector : OperatorBase {
     35    /// <inheritdoc/>
    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="TSPTourInjector"/> with three variable infos
     42    /// (<c>Coordinates</c>, <c>Permutation</c> and <c>Tour</c>).
     43    /// </summary>
    3644    public TSPTourInjector() {
    3745      AddVariableInfo(new VariableInfo("Coordinates", "City coordinates", typeof(DoubleMatrixData), VariableKind.In));
    … …  
    4048    }
    4149
     50    /// <summary>
     51    /// Adds a new <see cref="TSPTour"/> to the given <paramref name="scope"/> with all
     52    /// its neccessary variables.
     53    /// </summary>
     54    /// <param name="scope">The current scope where to inject the TSP tour.</param>
     55    /// <returns><c>null</c>.</returns>
    4256    public override IOperation Apply(IScope scope) {
    4357      DoubleMatrixData coordinates = GetVariableValue<DoubleMatrixData>("Coordinates", scope, true);

  • trunk/sources/HeuristicLab.Routing.TSP/TSPTourView.cs

    r2 r884  
    3333
    3434namespace HeuristicLab.Routing.TSP {
     35  /// <summary>
     36  /// Class for the visual representation of a <see cref="TSPTour"/>.
     37  /// </summary>
    3538  public partial class TSPTourView : ViewBase {
     39    /// <summary>
     40    /// Gets or sets the <see cref="TSPTour"/> to represent visually.
     41    /// </summary>
     42    /// <remarks>Uses property <see cref="ViewBase.Item"/> of base class <see cref="ViewBase"/>.
     43    /// No own data storage present.</remarks>
    3644    public TSPTour TSPTour {
    3745      get { return (TSPTour)base.Item; }
    … …  
    4048
    4149
     50    /// <summary>
     51    /// Initializes a new instance of <see cref="TSPTourView"/> with caption "TSP Tour View".
     52    /// </summary>
    4253    public TSPTourView() {
    4354      InitializeComponent();
    4455      Caption = "TSP Tour View";
    4556    }
     57    /// <summary>
     58    /// Initializes a new instance of <see cref="TSPTourView"/> with the given <paramref name="tspTour"/>.
     59    /// </summary>
     60    /// <param name="tspTour">The tour to display.</param>
    4661    public TSPTourView(TSPTour tspTour)
    4762      : this() {
    … …  
    5065
    5166
     67    /// <summary>
     68    /// Removes all event handlers from the underlying <see cref="TSPTour"/>.
     69    /// </summary>
     70    /// <remarks>Calls <see cref="ViewBase.RemoveItemEvents"/> of base class <see cref="ViewBase"/>.</remarks>
    5271    protected override void RemoveItemEvents() {
    5372      TSPTour.CoordinatesChanged -= new EventHandler(TSPTour_CoordinatesChanged);
    … …  
    5574      base.RemoveItemEvents();
    5675    }
     76    /// <summary>
     77    /// Adds event handlers to the underlying <see cref="TSPTour"/>.
     78    /// </summary>
     79    /// <remarks>Calls <see cref="ViewBase.AddItemEvents"/> of base class <see cref="ViewBase"/>.</remarks>
    5780    protected override void AddItemEvents() {
    5881      base.AddItemEvents();
    … …  
    6184    }
    6285
     86    /// <summary>
     87    /// Updates all controls with the latest data of the model.
     88    /// </summary>
     89    /// <remarks>Calls <see cref="ViewBase.UpdateControls"/> of base class <see cref="ViewBase"/>.</remarks>
    6390    protected override void UpdateControls() {
    6491      base.UpdateControls();
Note: See TracChangeset for help on using the changeset viewer.