% MTSPF_GA Fixed Multiple Traveling Salesmen Problem (M-TSP) Genetic Algorithm (GA)
% Finds a (near) optimal solution to a variation of the M-TSP by setting
% up a GA to search for the shortest route (least distance needed for
% each salesman to travel from the start location to individual cities
% and back to the original starting place)
%
% Summary:
% 1. Each salesman starts at the first point, and ends at the first
% point, but travels to a unique set of cities in between
% 2. Except for the first, each city is visited by exactly one salesman
%
% Note: The Fixed Start/End location is taken to be the first XY point
%
% Input:
% USERCONFIG (structure) with zero or more of the following fields:
% - XY (float) is an Nx2 matrix of city locations, where N is the number of cities
% - DMAT (float) is an NxN matrix of city-to-city distances or costs
% - NSALESMEN (scalar integer) is the number of salesmen to visit the cities
% - MINTOUR (scalar integer) is the minimum tour length for any of the
% salesmen, NOT including the start/end point
% - POPSIZE (scalar integer) is the size of the population (should be divisible by 8)
% - NUMITER (scalar integer) is the number of desired iterations for the algorithm to run
% - SHOWPROG (scalar logical) shows the GA progress if true
% - SHOWRESULT (scalar logical) shows the GA results if true
% - SHOWWAITBAR (scalar logical) shows a waitbar if true
%
% Input Notes:
% 1. Rather than passing in a structure containing these fields, any/all of
% these inputs can be passed in as parameter/value pairs in any order instead.
% 2. Field/parameter names are case insensitive but must match exactly otherwise.
%
% Output:
% RESULTSTRUCT (structure) with the following fields:
% (in addition to a record of the algorithm configuration)
% - OPTROUTE (integer array) is the best route found by the algorithm
% - OPTBREAK (integer array) is the list of route break points (these specify the indices
% into the route used to obtain the individual salesman routes)
% - MINDIST (scalar float) is the total distance traveled by the salesmen
%
% Route/Breakpoint Details:
% If there are 10 cities and 3 salesmen, a possible route/break
% combination might be: rte = [5 6 9 4 2 8 10 3 7], brks = [3 7]
% Taken together, these represent the solution [1 5 6 9 1][1 4 2 8 10 1][1 3 7 1],
% which designates the routes for the 3 salesmen as follows:
% . Salesman 1 travels from city 1 to 5 to 6 to 9 and back to 1
% . Salesman 2 travels from city 1 to 4 to 2 to 8 to 10 and back to 1
% . Salesman 3 travels from city 1 to 3 to 7 and back to 1
%
% Usage:
% mtspf_ga
% -or-
% mtspf_ga(userConfig)
% -or-
% resultStruct = mtspf_ga;
% -or-
% resultStruct = mtspf_ga(userConfig);
% -or-