Merge pull request #279 from matsim-vsp/addJavadoc4LspStrategies

add Javadoc for LSP strategies

src/main/java/org/matsim/freight/logistics/examples/multipleChains/ProximityStrategyFactory.java

@@ -38,6 +38,13 @@
 import org.matsim.freight.logistics.*;
 import org.matsim.freight.logistics.shipment.LSPShipment;
 
+/**
+ *  This strategy removes **one** randomly selected shipment from logistic chain with the most shipments and reassign it to the chain with the closest chain.
+ *  The distance is measured as the Euclidean distance between the shipment's destination and the resource's start link.
+ *  This strategy allows to slowly change the plans and therefore follow the iterative learning process.
+ *
+ *  @author nrichter (during his master thesis @VSP)
+ */
 final class ProximityStrategyFactory {
   //This is ok so as long as it is **non-public**.
   //Before making it public, it should be configurable either via config or Injection.

src/main/java/org/matsim/freight/logistics/examples/multipleChains/RandomDistributionAllShipmentsStrategyFactory.java

@@ -1,22 +1,22 @@
 /*
-  *********************************************************************** *
-  * project: org.matsim.*
-  *                                                                         *
-  * *********************************************************************** *
-  *                                                                         *
-  * copyright       :  (C) 2024 by the members listed in the COPYING,       *
-  *                   LICENSE and WARRANTY file.                            *
-  * email           : info at matsim dot org                                *
-  *                                                                         *
-  * *********************************************************************** *
-  *                                                                         *
-  *   This program is free software; you can redistribute it and/or modify  *
-  *   it under the terms of the GNU General Public License as published by  *
-  *   the Free Software Foundation; either version 2 of the License, or     *
-  *   (at your option) any later version.                                   *
-  *   See also COPYING, LICENSE and WARRANTY file                           *
-  *                                                                         *
-  * ***********************************************************************
+ *********************************************************************** *
+ * project: org.matsim.*
+ *                                                                         *
+ * *********************************************************************** *
+ *                                                                         *
+ * copyright       :  (C) 2024 by the members listed in the COPYING,       *
+ *                   LICENSE and WARRANTY file.                            *
+ * email           : info at matsim dot org                                *
+ *                                                                         *
+ * *********************************************************************** *
+ *                                                                         *
+ *   This program is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU General Public License as published by  *
+ *   the Free Software Foundation; either version 2 of the License, or     *
+ *   (at your option) any later version.                                   *
+ *   See also COPYING, LICENSE and WARRANTY file                           *
+ *                                                                         *
+ * ***********************************************************************
  */
 
 package org.matsim.freight.logistics.examples.multipleChains;
@@ -35,50 +35,56 @@
 import org.matsim.freight.logistics.LogisticChain;
 import org.matsim.freight.logistics.shipment.LSPShipment;
 
+/**
+ *  This strategy removes **all** shipments from the logistic chains and reassigns them randomly.
+ *  It does not seem to be a very useful strategy in terms of going forward towards a (local) optimum, as long as it is the only one.
+ *  But it is i) a good example how to write such a strategy and ii) can be used to reshuffle the current state and find a new starting point when running with different strategies.
+ *  @author nrichter (during his master thesis @VSP)
+ */
 final class RandomDistributionAllShipmentsStrategyFactory {
-  //This is ok so as long as it is **non-public**.
-  //Before making it public, it should be configurable either via config or Injection.
-  //KMT, KN (Jan'24)
+    //This is ok so as long as it is **non-public**.
+    //Before making it public, it should be configurable either via config or Injection.
+    //KMT, KN (Jan'24)
 
-  private
-  RandomDistributionAllShipmentsStrategyFactory() {} // class contains only static methods; do not
-                                                     // instantiate
+    private
+    RandomDistributionAllShipmentsStrategyFactory() {} // class contains only static methods; do not
+    // instantiate
 
-  static GenericPlanStrategy<LSPPlan, LSP> createStrategy() {
+    static GenericPlanStrategy<LSPPlan, LSP> createStrategy() {
 
-    GenericPlanStrategyImpl<LSPPlan, LSP> strategy =
-        new GenericPlanStrategyImpl<>(new ExpBetaPlanSelector<>(new ScoringConfigGroup()));
-    GenericPlanStrategyModule<LSPPlan> randomModule =
-        new GenericPlanStrategyModule<>() {
+        GenericPlanStrategyImpl<LSPPlan, LSP> strategy =
+                new GenericPlanStrategyImpl<>(new ExpBetaPlanSelector<>(new ScoringConfigGroup()));
+        GenericPlanStrategyModule<LSPPlan> randomModule =
+                new GenericPlanStrategyModule<>() {
 
-          @Override
-          public void prepareReplanning(ReplanningContext replanningContext) {}
+                    @Override
+                    public void prepareReplanning(ReplanningContext replanningContext) {}
 
-          @Override
-          public void handlePlan(LSPPlan lspPlan) {
+                    @Override
+                    public void handlePlan(LSPPlan lspPlan) {
 
-            //				Shifting shipments only makes sense for multiple chains
-            if (lspPlan.getLogisticChains().size() < 2) return;
+                        //				Shifting shipments only makes sense for multiple chains
+                        if (lspPlan.getLogisticChains().size() < 2) return;
 
-            for (LogisticChain logisticChain : lspPlan.getLogisticChains()) {
-              logisticChain.getShipmentIds().clear();
-            }
+                        for (LogisticChain logisticChain : lspPlan.getLogisticChains()) {
+                            logisticChain.getShipmentIds().clear();
+                        }
 
-            LSP lsp = lspPlan.getLSP();
-            List<LogisticChain> logisticChains =
-                new ArrayList<>(lsp.getSelectedPlan().getLogisticChains());
+                        LSP lsp = lspPlan.getLSP();
+                        List<LogisticChain> logisticChains =
+                                new ArrayList<>(lsp.getSelectedPlan().getLogisticChains());
 
-            for (LSPShipment shipment : lsp.getShipments()) {
-              int index = MatsimRandom.getRandom().nextInt(logisticChains.size());
-              logisticChains.get(index).addShipmentToChain(shipment);
-            }
-          }
+                        for (LSPShipment shipment : lsp.getShipments()) {
+                            int index = MatsimRandom.getRandom().nextInt(logisticChains.size());
+                            logisticChains.get(index).addShipmentToChain(shipment);
+                        }
+                    }
 
-          @Override
-          public void finishReplanning() {}
-        };
+                    @Override
+                    public void finishReplanning() {}
+                };
 
-    strategy.addStrategyModule(randomModule);
-    return strategy;
-  }
+        strategy.addStrategyModule(randomModule);
+        return strategy;
+    }
 }

src/main/java/org/matsim/freight/logistics/examples/multipleChains/RandomShiftingStrategyFactory.java

@@ -38,6 +38,12 @@
 import org.matsim.freight.logistics.LogisticChain;
 import org.matsim.freight.logistics.shipment.LSPShipment;
 
+/**
+ *  This strategy removes **one** randomly selected shipment from the logistic chain it was assigned to and reassign it to another chain.
+ *  This strategy allows to slowly change the plans and therefore follow the iterative learning process.
+ *  But it is i) slow, because it needs a lot of iterations and ii) has a high chance to get stuck in a local optimum.
+ *  @author nrichter (during his master thesis @VSP)
+ */
 class RandomShiftingStrategyFactory {
 
     private static Random random = null;

src/main/java/org/matsim/freight/logistics/examples/multipleChains/RebalancingStrategyFactory.java

@@ -36,6 +36,12 @@
 import org.matsim.freight.logistics.LogisticChain;
 import org.matsim.freight.logistics.shipment.LSPShipment;
 
+/**
+ *  This strategy removes **one** randomly selected shipment from logistic chain with the most shipments and reassign it to one of the chains with the lowest number of shipments.
+ *  This strategy allows to slowly change the plans and therefore follow the iterative learning process. But is moves towards a solution with all chains having the same number of shipments.
+ *  For me (KMT) the use case is not obvious, when used as only strategy, but it can have its use in a set of strategies.
+ *  @author nrichter (during his master thesis @VSP)
+ */
 class RebalancingStrategyFactory {
   //This is ok so as long as it is **non-public**.
   //Before making it public, it should be configurable either via config or Injection.

src/main/java/org/matsim/freight/logistics/examples/multipleChains/RoundRobinDistributionAllShipmentsStrategyFactory.java

@@ -35,6 +35,13 @@
 import org.matsim.freight.logistics.LogisticChain;
 import org.matsim.freight.logistics.shipment.LSPShipment;
 
+/**
+ *  This strategy removes **all** shipments from the logistic chains and reassigns them.
+ *  The reassignment is done in a round-robin fashion, so that in the hand all chains have the same number of shipments.
+ *  It does not seem to be a very useful strategy in terms of going forward towards a (local) optimum, as long as it is the only one.
+ *
+ *  @author nrichter (during his master thesis @VSP)
+ */
 /*package-private*/ class RoundRobinDistributionAllShipmentsStrategyFactory {
   //This is ok so as long as it is **non-public**.
   //Before making it public, it should be configurable either via config or Injection.