Merge branch 'master' into routes-with-specified-start-and-end

CHANGELOG.md

@@ -1,5 +1,40 @@
 Change-log
 ==========
+**v1.1.0** @ 2014-01-27
+
+- [detailed changelog](https://github.com/jsprit/misc-rep/raw/master/changelog_1.1.0_to_1.1.0.txt)
+
+<em>jsprit-core:</em>
+- added javadocs (VehicleRoutingProblem and classes in package vehicle. and job.)
+- added unit-tests (for classes in package vehicle., job. and io.)
+- deprecated methods in VehicleRoutingProblem, VehicleTypeImpl, VehicleImpl
+- added func in VehicleRoutingProblem.Builder (.addPenaltyVehicle(...) methods)
+- added feature: open-routes ([#54](https://github.com/jsprit/jsprit/issues/54))
+- added func in VehicleImpl and VehicleImpl.Builder (.setReturnToDepot(...), isReturnToDepot())
+- added feature: prohibit vehicles to take over entire route ([#70](https://github.com/jsprit/jsprit/issues/70))
+- fixed bug: [#58](https://github.com/jsprit/jsprit/issues/58),[#76](https://github.com/jsprit/jsprit/issues/76)-[#79](https://github.com/jsprit/jsprit/issues/79)
+- added abstract class AbstractForwardVehicleRoutingCosts
+- inspected and removed all warnings
+- visibility of methods activity.Start.get/setCoordinate(...) decreased from public to private <b>[potential Break Change]</b>
+- visibility of methods activity.End.get/setCoordinate(...) decreased from public to private <b>[potential Break Change]</b>
+- method isReturnToDepot() has been added to interface Vehicle <b>[potential Break Change]</b>
+- visibility of constructor VehicleImpl.Builder decreased from public to private <b>[potential Break Change]</b>
+
+<em>jsprit-analysis:</em>
+- added GraphStreamViewer
+- inspected and removed all warnings
+
+<em>jsprit-example:</em>
+- added BicycleMessenger
+- enriched examples with GraphStreamViewer
+- inspected and removed all warnings
+
+<em>jsprit-instance:</em>
+- added VrphGoldenReader (plus instances to bechmark VRPH)
+- inspected and removed all warnings
+
+
+
 **v1.0.0** @ 2013-11-26 (break change)
 
 - re-organized API

README.md

@@ -1,7 +1,7 @@
 jsprit
 ======
 jsprit is a java based, open source toolkit for solving rich <a href="http://en.wikipedia.org/wiki/Travelling_salesman_problem" target="_blank">traveling salesman</a> (TSP) and <a href="http://neo.lcc.uma.es/vrp/vehicle-routing-problem/" target="_blank">vehicle routing problems</a> (VRP). 
-It is lightweight, flexible and easy-to-use, and based on a single all-purpose <a href="http://www.sciencedirect.com/science/article/pii/S0021999199964136" target="_blank">meta-heuristic</a> currently solving 
+It is lightweight, flexible and easy-to-use, and based on a single all-purpose <a href="https://github.com/jsprit/jsprit/wiki/Meta-Heuristic-and-Configuration" target="_blank">meta-heuristic</a> currently solving 
 - Capacitated VRP
 - Multiple Depot VRP
 - VRP with Time Windows
@@ -16,10 +16,6 @@ It is lightweight, flexible and easy-to-use, and based on a single all-purpose <
 Setting up the problem, defining additional constraints, modifying the algorithms and visualising the discovered solutions is as easy and handy as 
 reading classical VRP instances to benchmark your algorithm. It is fit for change and extension due to a modular design and a comprehensive set of unit and integration-tests.
 
-Additionally, jsprit can be used along with <a href="http://www.matsim.org" target="blank_">MATSim</a> 
-to solve the above problem-types in real networks (i.e. without preprocessing transport times and costs). A variety of least cost path algorithms such as Dijkstra and A*
-can be used, and a dynamic and interactive visualiser greatly enhances the analysis.
-
 ##In Development
 - continues improvement of code, handling and performance
 - soft constraints

jsprit-analysis/pom.xml

@@ -22,7 +22,7 @@
   <parent>
   	<groupId>jsprit</groupId>
   	<artifactId>jsprit</artifactId>
-  	<version>1.0.1-SNAPSHOT</version>
+  	<version>1.1.1-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <artifactId>jsprit-analysis</artifactId>

jsprit-core/pom.xml

@@ -3,7 +3,7 @@
   <parent>
   	<groupId>jsprit</groupId>
   	<artifactId>jsprit</artifactId>
-  	<version>1.0.1-SNAPSHOT</version>
+  	<version>1.1.1-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <artifactId>jsprit-core</artifactId>

jsprit-core/src/main/java/jsprit/core/problem/solution/route/VehicleRoute.java

@@ -37,22 +37,65 @@ import jsprit.core.problem.vehicle.Vehicle;
 import jsprit.core.problem.vehicle.VehicleImpl;
 import jsprit.core.problem.vehicle.VehicleImpl.NoVehicle;
 
+/**
+ * Contains the tour, i.e. a number of activities, a vehicle servicing the tour and a driver.
+ * 
+ * 
+ * @author stefan
+ *
+ */
 public class VehicleRoute {
-			
+		
+	/**
+	 * Returns a deep copy of this vehicleRoute.
+	 * 
+	 * @param route
+	 * @return copied route
+	 * @throws IllegalArgumentException if route is null
+	 */
 	public static VehicleRoute copyOf(VehicleRoute route) {
+		if(route == null) throw new IllegalArgumentException("route must not be null");
 		return new VehicleRoute(route);
 	}
 	
+	/**
+	 * Returns a newInstance of {@link VehicleRoute}.
+	 * 
+	 * @param tour
+	 * @param driver
+	 * @param vehicle
+	 * @return
+	 */
 	public static VehicleRoute newInstance(TourActivities tour, Driver driver, Vehicle vehicle) {
 		return new VehicleRoute(tour,driver,vehicle);
 	}
 
+	/**
+	 * Returns an empty route.
+	 * 
+	 * <p>An empty route has an empty list of tour-activities, no driver (DriverImpl.noDriver()) and no vehicle (VehicleImpl.createNoVehicle()).
+	 * 
+	 * @return
+	 */
 	public static VehicleRoute emptyRoute() {
 		return new VehicleRoute(TourActivities.emptyTour(), DriverImpl.noDriver(), VehicleImpl.createNoVehicle());
 	}
 	
+	/**
+	 * Builder that builds the vehicle route.
+	 * 
+	 * @author stefan
+	 *
+	 */
 	public static class Builder {
 		
+		/**
+		 * Returns new instance of this builder.
+		 * 
+		 * @param vehicle
+		 * @param driver
+		 * @return this builder
+		 */
 		public static Builder newInstance(Vehicle vehicle, Driver driver){
 			return new Builder(vehicle,driver);
 		}
@@ -73,10 +116,24 @@ public class VehicleRoute {
 		
 		private Set<Shipment> openShipments = new HashSet<Shipment>();
 		
+		/**
+		 * Sets the serviceActivityFactory to create serviceActivities.
+		 * 
+		 * <p>By default {@link DefaultTourActivityFactory} is used.
+		 * 
+		 * @param serviceActivityFactory
+		 */
 		public void setServiceActivityFactory(TourActivityFactory serviceActivityFactory) {
 			this.serviceActivityFactory = serviceActivityFactory;
 		}
 
+		/**
+		 * Sets the shipmentActivityFactory to create shipmentActivities.
+		 * 
+		 * <p>By default {@link DefaultShipmentActivityFactory} is used.
+		 * 
+		 * @param shipmentActivityFactory
+		 */
 		public void setShipmentActivityFactory(TourShipmentActivityFactory shipmentActivityFactory) {
 			this.shipmentActivityFactory = shipmentActivityFactory;
 		}
@@ -100,7 +157,7 @@ public class VehicleRoute {
 		}
 
 		/**
-		 * Sets the departure-time of the route.
+		 * Sets the departure-time of the route, i.e. which is the time the vehicle departs from start-location.
 		 * 
 		 * @param departureTime
 		 * @return
@@ -110,16 +167,46 @@ public class VehicleRoute {
 			return this;
 		}
 		
+		/**
+		 * Sets the end-time of the route, i.e. which is the time the vehicle has to be at its end-location at latest.
+		 * 
+		 * @param endTime
+		 * @return this builder
+		 */
 		public Builder setRouteEndArrivalTime(double endTime){
 			end.setArrTime(endTime);
 			return this;
 		}
 		
+		/**
+		 * Adds a service to this route.
+		 * 
+		 * <p>This implies that for this service a serviceActivity is created with {@link TourActivityFactory} and added to the sequence of tourActivities.
+		 * 
+		 * <p>The resulting activity occurs in the activity-sequence in the order adding/inserting.
+		 * 
+		 * @param service
+		 * @return this builder
+		 * @throws IllegalArgumentException if service is null
+		 */
 		public Builder addService(Service service){
+			if(service == null) throw new IllegalArgumentException("service must not be null");
 			addService(service,0.0,0.0);
 			return this;
 		}
 		
+		/**
+		 * Adds a service with specified activity arrival- and endTime.  
+		 * 
+		 * <p>This implies that for this service a serviceActivity is created with {@link TourActivityFactory} and added to the sequence of tourActivities.
+		 * 
+		 * <p>Basically this activity is then scheduled with an activity arrival and activity endTime.
+		 * 
+		 * @param service
+		 * @param arrTime
+		 * @param endTime
+		 * @return builder
+		 */
 		public Builder addService(Service service, double arrTime, double endTime){
 			TourActivity act = serviceActivityFactory.createActivity(service);
 			act.setArrTime(arrTime);
@@ -266,15 +353,38 @@ public class VehicleRoute {
 		return tourActivities;
 	}
 	
-
+	/**
+	 * Returns the vehicle operating this route.
+	 * 
+	 * @return Vehicle
+	 */
 	public Vehicle getVehicle() {
 		return vehicle;
 	}
 
+	/**
+	 * Returns the driver operating this route.
+	 * 
+	 * @return Driver
+	 */
 	public Driver getDriver() {
 		return driver;
 	}
 
+	/**
+	 * Sets the vehicle and its departureTime.
+	 * 
+	 * <p>This implies the following:<br>
+	 * if start and end are null, new start and end activities are created.<br>
+	 * <p>startActivity is initialized with the location of the specified vehicle. the time-window of this activity is initialized 
+	 * as follows: [time-window.start = vehicle.getEarliestDeparture()][time-window.end = vehicle.getLatestArrival()]
+	 * <p>endActivity is initialized with the location of the specified vehicle as well. time-window of this activity:[time-window.start = vehicle.getEarliestDeparture()][time-window.end = vehicle.getLatestArrival()]
+	 * <p>start.endTime is set to the specified departureTime
+	 * <p>Note that start end end-locations are always initialized with the location of the specified vehicle. (this will change soon, then there will be start and end location of vehicle which can be different, 23.01.14)    
+	 * 
+	 * @param vehicle
+	 * @param vehicleDepTime
+	 */
 	public void setVehicle(Vehicle vehicle, double vehicleDepTime){
 		this.vehicle = vehicle;
 		setStartAndEnd(vehicle, vehicleDepTime);
@@ -297,24 +407,50 @@ public class VehicleRoute {
 		
 	}
 
+	/**
+	 * Sets departureTime of this route, i.e. the time the vehicle departs from its start-location.
+	 * 
+	 * @param vehicleDepTime
+	 */
 	public void setDepartureTime(double vehicleDepTime){
 		if(start == null) throw new IllegalStateException("cannot set departureTime without having a vehicle on this route. use setVehicle(vehicle,departureTime) instead.");
 		start.setEndTime(vehicleDepTime);
 	}
 	
+	/**
+	 * Returns the departureTime of this vehicle.
+	 * 
+	 * @return departureTime
+	 * @throws IllegalStateException if start is null
+	 */
 	public double getDepartureTime(){
 		if(start == null) throw new IllegalStateException("cannot get departureTime without having a vehicle on this route. use setVehicle(vehicle,departureTime) instead.");
 		return start.getEndTime();
 	}
 	
+	/**
+	 * Returns tour if tour-activity-sequence is empty, i.e. to activity on the tour yet.
+	 * 
+	 * @return
+	 */
 	public boolean isEmpty() {
 		return tourActivities.isEmpty();
 	}
 
+	/**
+	 * Returns start-activity of this route.
+	 * 
+	 * @return start
+	 */
 	public Start getStart() {
 		return start;
 	}
 
+	/**
+	 * Returns end-activity of this route.
+	 * 
+	 * @return end
+	 */
 	public End getEnd() {
 		return end;
 	}

jsprit-examples/pom.xml

@@ -3,7 +3,7 @@
   <parent>
   	<groupId>jsprit</groupId>
   	<artifactId>jsprit</artifactId>
-  	<version>1.0.1-SNAPSHOT</version>
+  	<version>1.1.1-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   

jsprit-instances/pom.xml

@@ -3,7 +3,7 @@
   <parent>
   	<groupId>jsprit</groupId>
   	<artifactId>jsprit</artifactId>
-  	<version>1.0.1-SNAPSHOT</version>
+  	<version>1.1.1-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
  

pom.xml

@@ -4,7 +4,7 @@
   
   <groupId>jsprit</groupId>
   <artifactId>jsprit</artifactId>
-  <version>1.0.1-SNAPSHOT</version>
+  <version>1.1.1-SNAPSHOT</version>
   
   <packaging>pom</packaging>