refactor: added comments and renamed MATSimApplication.run()

contribs/drt-extensions/src/test/java/org/matsim/contrib/drt/extension/DrtTestScenario.java

@@ -1,6 +1,7 @@
 package org.matsim.contrib.drt.extension;
 
 import com.google.common.collect.Sets;
+import jakarta.annotation.Nullable;
 import org.matsim.api.core.v01.Id;
 import org.matsim.api.core.v01.Scenario;
 import org.matsim.api.core.v01.network.Link;
@@ -17,21 +18,19 @@
 import org.matsim.contrib.vsp.scenario.SnzActivities;
 import org.matsim.core.config.Config;
 import org.matsim.core.config.ConfigUtils;
-import org.matsim.core.config.groups.ScoringConfigGroup;
 import org.matsim.core.config.groups.RoutingConfigGroup;
+import org.matsim.core.config.groups.ScoringConfigGroup;
 import org.matsim.core.controler.Controler;
 import org.matsim.core.controler.OutputDirectoryHierarchy;
 import org.matsim.core.utils.io.IOUtils;
 import org.matsim.examples.ExamplesUtils;
-import org.matsim.simwrapper.SimWrapperModule;
 import org.matsim.modechoice.InformedModeChoiceConfigGroup;
+import org.matsim.simwrapper.SimWrapperModule;
 import org.matsim.testcases.MatsimTestUtils;
 import org.matsim.vehicles.VehicleType;
 
-import jakarta.annotation.Nullable;
 import java.net.URL;
 import java.util.HashSet;
-import java.util.List;
 import java.util.Set;
 import java.util.function.Consumer;
 
@@ -45,11 +44,13 @@ public class DrtTestScenario extends MATSimApplication {
 	private final Consumer<Config> prepareConfig;
 
 	public static void main(String[] args) {
-		run(DrtTestScenario.class, args);
+		start(DrtTestScenario.class, args);
 	}
 
 	public DrtTestScenario() {
-		this(controler -> {}, config -> {});
+		this(controler -> {
+		}, config -> {
+		});
 	}
 
 	public DrtTestScenario(Consumer<Controler> prepareControler, Consumer<Config> prepareConfig) {
@@ -59,8 +60,10 @@ public DrtTestScenario(Consumer<Controler> prepareControler, Consumer<Config> pr
 
 	public DrtTestScenario(@Nullable Config config) {
 		super(config);
-		this.prepareControler = controler -> {};
-		this.prepareConfig = c -> {};
+		this.prepareControler = controler -> {
+		};
+		this.prepareConfig = c -> {
+		};
 	}
 
 	public static Config loadConfig(MatsimTestUtils utils) {
@@ -116,9 +119,9 @@ protected void prepareScenario(Scenario scenario) {
 		}
 
 		scenario.getPopulation()
-				.getFactory()
-				.getRouteFactories()
-				.setRouteFactory(DrtRoute.class, new DrtRouteFactory());
+			.getFactory()
+			.getRouteFactories()
+			.setRouteFactory(DrtRoute.class, new DrtRouteFactory());
 	}
 
 	@Override
@@ -137,14 +140,14 @@ protected void prepareControler(Controler controler) {
 
 		// Add speed limit to av vehicle
 		double maxSpeed = controler.getScenario()
-				.getVehicles()
-				.getVehicleTypes()
-				.get(Id.create("autonomous_vehicle", VehicleType.class))
-				.getMaximumVelocity();
+			.getVehicles()
+			.getVehicleTypes()
+			.get(Id.create("autonomous_vehicle", VehicleType.class))
+			.getMaximumVelocity();
 
 		controler.addOverridingModule(
-				new DvrpModeLimitedMaxSpeedTravelTimeModule("av", config.qsim().getTimeStepSize(),
-						maxSpeed));
+			new DvrpModeLimitedMaxSpeedTravelTimeModule("av", config.qsim().getTimeStepSize(),
+				maxSpeed));
 
 		controler.addOverridingModule(new SimWrapperModule());
 

matsim/src/main/java/org/matsim/api/core/v01/population/Route.java

@@ -48,13 +48,13 @@ public interface Route extends MatsimPopulationObject {
 	public void setEndLinkId(final Id<Link> linkId);
 
 	/**
-	 * @return a serialization of this routes state as a String. Used to write the route to files.
+	 * @return a serialization of this routes state as a String. Used to write the route to files. Does include start and end link.
 	 */
 	public String getRouteDescription();
-	
+
 	/**
 	 * Sets the state of the route based on it's description
-	 * 
+	 *
 	 * @param routeDescription
 	 */
 	public void setRouteDescription(final String routeDescription);
@@ -63,13 +63,14 @@ public interface Route extends MatsimPopulationObject {
 	 * @return an identifier describing the type of this route uniquely. Used when writing the route to files.
 	 */
 	public String getRouteType();
-
-	/** make the clone method public, but do NOT extend Cloneable so that implementations can decide on their own if they support
+
+	/**
+	 * make the clone method public, but do NOT extend Cloneable so that implementations can decide on their own if they support
 	 * Cloneable or use some other way to make a copy..
 	 * <p></p>
 	 * Design comments:<ul>
 	 * <li>Do we really want this?  Martin ("Clean code") argues for the difference between data objects and behavioral objects.  Data objects should
-	 * only be accessed via the interface methods.  I think that "route" is a data object.  In consequence, "copy" and/or "deepCopy" should, in 
+	 * only be accessed via the interface methods.  I think that "route" is a data object.  In consequence, "copy" and/or "deepCopy" should, in
 	 * my view, be static methods. (The argument against this is, I guess, that one might want to add Route implementations that are not
 	 * part of the standard.  Yet given that we want to be able to read/write them in xml, I am not sure how far this carries.)  kai, jan'13
 	 * <li> In our particular situation, "clone" may be considered as a useful approach to our problem (first clone the plan or its elements,

matsim/src/main/java/org/matsim/application/MATSimApplication.java

@@ -42,7 +42,7 @@
  * This class also automatically registers classes from the {@link Prepare} and {@link Analysis} annotations as subcommands.
  * These can be used to build a pipeline with command needed for preparation analysis.
  *
- * @see #run(Class, String...)
+ * @see #start(Class, String...)
  * @see #execute(Class, Config, String...)
  * @see #prepare(Class, Config, String...)
  * @see Prepare
@@ -153,11 +153,11 @@ public Integer call() throws Exception {
 
 		// load config if not present yet.
 		if (config == null) {
-			String path = Objects.requireNonNull( configPath, "No default scenario location given" );
+			String path = Objects.requireNonNull(configPath, "No default scenario location given");
 			List<ConfigGroup> customModules = getCustomModules();
 
-			final Config config1 = ConfigUtils.loadConfig(IOUtils.resolveFileOrResource(path), customModules.toArray(new ConfigGroup[0] ) );
-			Config prepared = prepareConfig( config1 );
+			final Config config1 = ConfigUtils.loadConfig(IOUtils.resolveFileOrResource(path), customModules.toArray(new ConfigGroup[0]));
+			Config prepared = prepareConfig(config1);
 
 			config = prepared != null ? prepared : config1;
 			// (The above lines of code come from inlining so maybe it happened there: I cannot see how prepared could be null but config1 not except if user code returns null which I would consider a bug.  kai, aug'24)
@@ -326,10 +326,18 @@ public String defaultValue(CommandLine.Model.ArgSpec argSpec) throws Exception {
 	}
 
 	/**
-	 * Run the application class and terminates when done.
-	 * This should never be used in tests and only in main methods.
+	 * @deprecated use {@link MATSimApplication#start(Class, String...)} instead
 	 */
+	@Deprecated
 	public static void run(Class<? extends MATSimApplication> clazz, String... args) {
+		start(clazz, args);
+	}
+
+	/**
+	 * Start the application class and terminates when done.
+	 * This should never be used in tests and only in main methods.
+	 */
+	public static void start(Class<? extends MATSimApplication> clazz, String... args) {
 		MATSimApplication app = newInstance(clazz, null);
 
 		// GUI does not pass any argument
@@ -370,6 +378,14 @@ public static void run(Class<? extends MATSimApplication> clazz, String... args)
 		System.exit(code);
 	}
 
+	/**
+	 * @deprecated use {@link MATSimApplication#startWithDefaults(Class, String[], String...)} instead
+	 */
+	@Deprecated
+	public static void runWithDefaults(Class<? extends MATSimApplication> clazz, String[] args, String... defaultArgs) {
+		startWithDefaults(clazz, args, defaultArgs);
+	}
+
 	/**
 	 * <p>Convenience method to run a scenario from code or automatically with gui when desktop application is detected.
 	 * This method may also be used to predefine some default arguments.</p>
@@ -385,7 +401,7 @@ public static void run(Class<? extends MATSimApplication> clazz, String... args)
 	 * <p>defaultArgs could be used to provide defaults when calling this method here; they would go in addition to what is coming in from "upstream" which is typically the command line.</p>
 	 *
 	 * <p>There are many execution paths that can be reached from this class, but a typical one for matsim-scenarios seems to be:<ul>
-	 * <li> This method runs MATSimApplication.run( TheScenarioClass.class , args ).</li>
+	 * <li> This method runs MATSimApplication.start( TheScenarioClass.class , args ).</li>
 	 * <li> That run class will instantiate an instance of TheScenarioClass (*), then do some args consistenty checking, then call the piccoli execute method. </li>
 	 * <li> The piccoli execute method will essentially call the "call" method of MATSimApplication. </li>
 	 * <li> I think that in the described execution path, this.config in that call method will initially be null.  (The ctor of MATSimApplication was called via reflection at (*); I think that it was called there without a config argument.) </li>
@@ -408,7 +424,7 @@ public static void run(Class<? extends MATSimApplication> clazz, String... args)
 	 * @param args        pass arguments from the main method
 	 * @param defaultArgs predefined default arguments that will always be present
 	 */
-	public static void runWithDefaults(Class<? extends MATSimApplication> clazz, String[] args, String... defaultArgs) {
+	public static void startWithDefaults(Class<? extends MATSimApplication> clazz, String[] args, String... defaultArgs) {
 
 		if (ApplicationUtils.isRunFromDesktop() && args.length == 0) {
 
@@ -420,7 +436,7 @@ public static void runWithDefaults(Class<? extends MATSimApplication> clazz, Str
 			}
 
 			// args are empty when run from desktop and is not used
-			run(clazz, "gui");
+			start(clazz, "gui");
 
 		} else {
 			// run if no other command is present
@@ -443,7 +459,7 @@ public static void runWithDefaults(Class<? extends MATSimApplication> clazz, Str
 
 			log.info("Running {} with: {}", clazz.getSimpleName(), String.join(" ", args));
 
-			run(clazz, args);
+			start(clazz, args);
 		}
 	}
 

matsim/src/main/java/org/matsim/core/population/routes/AbstractNetworkRoute.java

@@ -103,7 +103,7 @@ public NetworkRoute getSubRoute(Id<Link> fromLinkId, Id<Link> toLinkId) {
 		} else {
 			for (int i = 0, n = route.size(); (i < n) && (fromIndex < 0); i++) {
 				if (fromLinkId.equals(route.get(i))) {
-					fromIndex = i+1;
+					fromIndex = i + 1;
 				}
 			}
 			if (fromIndex < 0 && fromLinkId.equals(this.getEndLinkId())) {
@@ -119,7 +119,7 @@ public NetworkRoute getSubRoute(Id<Link> fromLinkId, Id<Link> toLinkId) {
 		} else {
 			for (int i = fromIndex, n = route.size(); (i < n) && (toIndex < 0); i++) {
 				if (fromLinkId.equals(route.get(i))) {
-					fromIndex = i+1; // in case of a loop, cut it short
+					fromIndex = i + 1; // in case of a loop, cut it short
 				}
 				if (toLinkId.equals(route.get(i))) {
 					toIndex = i;
@@ -151,6 +151,9 @@ public void setVehicleId(Id<Vehicle> vehicleId) {
 		this.vehicleId = vehicleId;
 	}
 
+	/**
+	 * Returns a String representation of the route in form of a sequence of link Ids. The first Id is the start link Id, the last Id is the end link Id.
+	 */
 	@Override
 	public String getRouteDescription() {
 		StringBuilder desc = new StringBuilder(100);

matsim/src/main/java/org/matsim/core/population/routes/LinkNetworkRouteImpl.java

@@ -20,15 +20,15 @@
 
 package org.matsim.core.population.routes;
 
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-
 import org.matsim.api.core.v01.Id;
 import org.matsim.api.core.v01.network.Link;
 import org.matsim.core.network.NetworkUtils;
 import org.matsim.vehicles.Vehicle;
 
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
 /**
  * Implementation of {@link NetworkRoute} which internally stores the route as a series of {@link Link}s.
  *
@@ -37,7 +37,8 @@
 final class LinkNetworkRouteImpl extends AbstractRoute implements NetworkRoute {
 
 	/*package*/ final static String ROUTE_TYPE = "links";
-
+
+	// These Lists do NOT contain the start and end link even though they are present in the route in population xml v6. paul, dec'25.
 	private ArrayList<Id<Link>> route = new ArrayList<>();
 	private List<Id<Link>> safeRoute = Collections.unmodifiableList(this.route);
 	private double travelCost = Double.NaN;
@@ -46,15 +47,15 @@ final class LinkNetworkRouteImpl extends AbstractRoute implements NetworkRoute {
 	LinkNetworkRouteImpl(final Id<Link> startLinkId, final Id<Link> endLinkId) {
 		super(startLinkId, endLinkId);
 	}
-	
+
 	LinkNetworkRouteImpl(final Id<Link> startLinkId, final List<Id<Link>> linkIds, final Id<Link> endLinkId) {
 		super(startLinkId, endLinkId);
 		setLinkIds(startLinkId, linkIds, endLinkId);
 	}
-	
+
 	LinkNetworkRouteImpl(final Id<Link> startLinkId, final Id<Link>[] linkIds, final Id<Link> endLinkId) {
 		super(startLinkId, endLinkId);
-        Collections.addAll(this.route, linkIds);
+		Collections.addAll(this.route, linkIds);
 		this.route.trimToSize();
 	}
 
@@ -90,7 +91,7 @@ public NetworkRoute getSubRoute(Id<Link> fromLinkId, Id<Link> toLinkId) {
 		} else {
 			for (int i = 0, n = this.route.size(); (i < n) && (fromIndex < 0); i++) {
 				if (fromLinkId.equals(this.route.get(i))) {
-					fromIndex = i+1;
+					fromIndex = i + 1;
 				}
 			}
 			if (fromIndex < 0 && fromLinkId.equals(this.getEndLinkId())) {
@@ -106,7 +107,7 @@ public NetworkRoute getSubRoute(Id<Link> fromLinkId, Id<Link> toLinkId) {
 		} else {
 			for (int i = fromIndex, n = this.route.size(); (i < n) && (toIndex < 0); i++) {
 				if (fromLinkId.equals(this.route.get(i))) {
-					fromIndex = i+1; // in case of a loop, cut it short
+					fromIndex = i + 1; // in case of a loop, cut it short
 				}
 				if (toLinkId.equals(this.route.get(i))) {
 					toIndex = i;
@@ -167,14 +168,14 @@ public String getRouteDescription() {
 			desc.append(" ");
 			desc.append(linkId.toString());
 		}
-		// If the start links equals the end link additionally check if its is a round trip. 
+		// If the start links equals the end link additionally check if its is a round trip.
 		if (!this.getEndLinkId().equals(this.getStartLinkId()) || this.getLinkIds().size() > 0) {
 			desc.append(" ");
 			desc.append(this.getEndLinkId().toString());
 		}
 		return desc.toString();
 	}
-	
+
 	@Override
 	public void setRouteDescription(String routeDescription) {
 		List<Id<Link>> linkIds = NetworkUtils.getLinkIds(routeDescription);
@@ -190,17 +191,17 @@ public void setRouteDescription(String routeDescription) {
 		}
 		this.setLinkIds(startLinkId, linkIds, endLinkId);
 	}
-	
+
 	@Override
 	public String getRouteType() {
 		return ROUTE_TYPE;
 	}
-	
+
 	@Override
 	public String toString() {
 		String str = super.toString();
-		str += " linkIds=" + this.getLinkIds() ;
-		str += " travelCost=" + this.getTravelCost() ;
-		return str ;
+		str += " linkIds=" + this.getLinkIds();
+		str += " travelCost=" + this.getTravelCost();
+		return str;
 	}
 }