add comments to clarify configs

matsim/src/main/java/org/matsim/core/config/groups/ReplanningConfigGroup.java

@@ -275,7 +275,7 @@ private StrategySettings getStrategySettings(final Id<StrategySettings> index, f
 	@Override
 	public final Map<String, String> getComments() {
 		Map<String,String> map = super.getComments();
-		map.put(ReflectiveDelegate.ITERATION_FRACTION_TO_DISABLE_INNOVATION, "fraction of iterations where innovative strategies are switched off.  Something like 0.8 should be good.  E.g. if you run from iteration 400 to iteration 500, innovation is switched off at iteration 480" ) ;
+		map.put(ReflectiveDelegate.ITERATION_FRACTION_TO_DISABLE_INNOVATION, "fraction of iterations where innovative strategies are switched off.  Something like 0.8 should be good.  E.g. if you run from iteration 400 to iteration 500, innovation is switched off at iteration 480. If the ReplanningAnnealer is used, it will also be switched off." ) ;
 		map.put(ReflectiveDelegate.MAX_AGENT_PLAN_MEMORY_SIZE, "maximum number of plans per agent.  ``0'' means ``infinity''.  Currently (2010), ``5'' is a good number");
 
 		StringBuilder strb = new StringBuilder() ;

matsim/src/main/java/org/matsim/core/config/groups/SubtourModeChoiceConfigGroup.java

@@ -32,25 +32,25 @@
 public final class SubtourModeChoiceConfigGroup extends ReflectiveConfigGroup {
 
 	public static final String GROUP_NAME = "subtourModeChoice";
-	
+
 	public final static String MODES = "modes";
 	public final static String CHAINBASEDMODES = "chainBasedModes";
 	public final static String CARAVAIL = "considerCarAvailability";
 	public final static String SINGLE_PROBA = "probaForRandomSingleTripMode";
 	public final static String COORD_DISTANCE = "coordDistance";
 
 	private static final String BEHAVIOR = "behavior";
-	
+
 	private String[] chainBasedModes = new String[] { TransportMode.car, TransportMode.bike };
 	private String[] allModes = new String[] { TransportMode.car, TransportMode.pt, TransportMode.bike, TransportMode.walk };
 	// default is false for backward compatibility
 	private boolean considerCarAvailability = false;
 	private SubtourModeChoice.Behavior behavior = SubtourModeChoice.Behavior.fromSpecifiedModesToSpecifiedModes ;
-	
+
 	private double probaForRandomSingleTripMode = 0. ; // yyyyyy backwards compatibility setting; should be change. kai, may'18
 
 	private double coordDistance = 0;
-	
+
 	public SubtourModeChoiceConfigGroup() {
 		super(GROUP_NAME);
 	}
@@ -67,7 +67,7 @@ private String getChainBaseModesString() {
 
 	private static String toString( final String[] modes ) {
 		// (not same as toString() because of argument!)
-		
+
 		StringBuilder b = new StringBuilder();
 
 		if (modes.length > 0) b.append( modes[ 0 ] );
@@ -106,7 +106,8 @@ public Map<String, String> getComments() {
 		comments.put(CHAINBASEDMODES, "Defines the chain-based modes, seperated by commas" );
 		comments.put(CARAVAIL, "Defines whether car availability must be considered or not. A agent has no car only if it has no license, or never access to a car" );
 		comments.put(SINGLE_PROBA, "Defines the probability of changing a single trip for a unchained mode instead of subtour.");
-		comments.put(COORD_DISTANCE, "If greater than 0, subtours will also consider coordinates to be at the same location when smaller than set distance.");
+		comments.put(COORD_DISTANCE, "If greater than 0, activities that are closer than coordDistance, to each other, will be considered part of the same subtour." +
+			"i.e. if two activities are close to each other, the agent is allowed to use the same 'chain-based' vehicle for both subtours.");
 
 		{
 			StringBuilder msg = new StringBuilder("Only for backwards compatibility.  Defines if only trips from modes list should change mode, or all trips.  Options: ");

matsim/src/main/java/org/matsim/core/replanning/annealing/ReplanningAnnealerConfigGroup.java

@@ -229,7 +229,7 @@ public Map<String, String> getComments() {
             map.put(HALFLIFE,
                     "this parameter enters the exponential and sigmoid formulas. May be an iteration or a share, i.e. 0.5 for halfLife at 50% of iterations.");
             map.put(SHAPE_FACTOR, "see comment of parameter annealType.");
-            map.put(ANNEAL_TYPE, "options: linear, exponential, geometric, msa, sigmoid and disabled (no annealing)." + " sigmoid: 1/(1+e^(shapeFactor*(it - halfLife))); geometric: startValue * shapeFactor^it; msa: startValue / it^shapeFactor. Exponential: startValue / exp(it/halfLife)");
+            map.put(ANNEAL_TYPE, "options: linear, exponential, geometric, msa, sigmoid and disabled (no annealing). sigmoid: 1/(1+e^(shapeFactor*(it - halfLife))); geometric: startValue * shapeFactor^it; msa: startValue / it^shapeFactor. Exponential: startValue / exp(it/halfLife)");
             map.put(ANNEAL_PARAM,
                     "list of config parameters that shall be annealed. Currently supported: globalInnovationRate, BrainExpBeta, PathSizeLogitBeta, learningRate. Default is globalInnovationRate");
             map.put(SUBPOPULATION, "subpopulation to have the global innovation rate adjusted. Not applicable when annealing with other parameters.");

matsim/src/main/java/org/matsim/core/replanning/modules/SubtourModeChoice.java

@@ -33,16 +33,16 @@
  * different mode given a list of possible modes.
  *
  * A subtour is a consecutive subset of a plan which starts and ends at the same link.
- * 
+ *
  * Certain modes are considered only if the choice would not require some resource to appear
  * out of thin air. For example, you can only drive your car back from work if you have previously parked it
  * there. These are called chain-based modes.
- * 
+ *
  * The assumption is that each chain-based mode requires one resource (car, bike, ...) and that this
  * resource is initially positioned at home. Home is the location of the first activity in the plan.
- * 
- * If the plan initially violates this constraint, this module may (!) repair it. 
- * 
+ *
+ * If the plan initially violates this constraint, this module may (!) repair it.
+ *
  * @author michaz
  *
  */
@@ -51,7 +51,27 @@ public class SubtourModeChoice extends AbstractMultithreadedModule {
 	private final double probaForChangeSingleTripMode;
 	private final double coordDist;
 
-	public enum Behavior {fromAllModesToSpecifiedModes, fromSpecifiedModesToSpecifiedModes, betweenAllAndFewerConstraints}
+	public enum Behavior {
+		/**
+		 * Allow agents to switch to specified modes from all other modes.
+		 * This implies that agents might switch to a specified mode, but won't be able to switch back
+		 * to their original mode. This option should not be used.
+		 */
+		@Deprecated
+		fromAllModesToSpecifiedModes,
+
+		/**
+		 * Allow agents switching from one of a specified mode to another specified mode.
+		 * Note, that agents that have an unclosed subtour, are not able to switch mode.
+		 * If you have unclosed/open subtours in your data, consider using {@link #betweenAllAndFewerConstraints}.
+		 */
+		fromSpecifiedModesToSpecifiedModes,
+
+		/**
+		 * Same as "fromSpecifiedModesToSpecifiedModes", but also allow agents with open subtours to switch modes.
+		 */
+		betweenAllAndFewerConstraints
+	}
 
 	private Behavior behavior = Behavior.fromSpecifiedModesToSpecifiedModes;
 
@@ -85,19 +105,19 @@ public SubtourModeChoice(GlobalConfigGroup globalConfigGroup,
 		this.probaForChangeSingleTripMode = probaForChangeSingleTripMode;
 		this.coordDist = coordDist;
 	}
-	
+
 	@Deprecated // only use when backwards compatibility is needed. kai, may'18
 	public final void setBehavior ( Behavior behavior ) {
 		this.behavior = behavior ;
 	}
-	
+
 	protected String[] getModes() {
 		return modes.clone();
 	}
 
 	@Override
 	public PlanAlgorithm getPlanAlgoInstance() {
-		
+
 		final ChooseRandomLegModeForSubtour chooseRandomLegMode =
 				new ChooseRandomLegModeForSubtour(
 						TripStructureUtils.getRoutingModeIdentifier(),