more comments

Makefile

@@ -61,7 +61,9 @@ input/network.osm: $(NETWORK)
 
 input/sumo.net.xml: input/network.osm
 
+#	create sumo network from osm network
 	$(SUMO_HOME)/bin/netconvert --geometry.remove --ramps.guess --ramps.no-split\
+#	roadTypes are taken either from the general file "osmNetconvert.typ.xml" or from the german one "osmNetconvertUrbanDe.ty.xml"
 	 --type-files $(SUMO_HOME)/data/typemap/osmNetconvert.typ.xml,$(SUMO_HOME)/data/typemap/osmNetconvertUrbanDe.typ.xml\
 	 --tls.guess-signals true --tls.discard-simple --tls.join --tls.default-type actuated\
 	 --junctions.join --junctions.corner-detail 5\
@@ -73,11 +75,14 @@ input/sumo.net.xml: input/network.osm
 	 --osm-files $< -o=$@
 
 
+# transform sumo network to matsim network and clean it afterwards
+# free-speed-factor 0.75 (standard is 0.9): see VSP WP 24-08. lausitz is mix between rural and city (~0.7 - 0.8)
 input/$V/$N-$V-network.xml.gz: input/sumo.net.xml
 	$(sc) prepare network-from-sumo $< --output $@ --free-speed-factor 0.75
 	$(sc) prepare clean-network $@ --output $@ --modes car --modes bike
 
 
+#add pt to network from german wide gtfs, but only for area of shp file
 input/$V/$N-$V-network-with-pt.xml.gz: input/$V/$N-$V-network.xml.gz
 	$(sc) prepare transit-from-gtfs --network $<\
 	 --output=input/$V\
@@ -90,6 +95,7 @@ input/$V/$N-$V-network-with-pt.xml.gz: input/$V/$N-$V-network.xml.gz
 	 --shp $(shared)/data/network-area/network-area.shp\
 	 --shp $(shared)/data/germany-area/germany-area.shp\
 
+# extract lausitz long haul freight traffic trips from german wide file
 input/plans-longHaulFreight.xml.gz: input/$V/$N-$V-network.xml.gz
 	$(sc) prepare extract-freight-trips ../public-svn/matsim/scenarios/countries/de/german-wide-freight/v2/german_freight.25pct.plans.xml.gz\
 	 --network ../public-svn/matsim/scenarios/countries/de/german-wide-freight/v2/germany-europe-network.xml.gz\
@@ -99,13 +105,17 @@ input/plans-longHaulFreight.xml.gz: input/$V/$N-$V-network.xml.gz
 	 --cut-on-boundary\
 	 --output $@
 
+# trajectory-to-plans formerly was a collection of methods to prepare a given population
+# now, most of the functions of this class do have their own class (downsample, splitduration types...)
+# it basically only transforms the old attribute format to the new one
 input/$V/prepare-100pct.plans.xml.gz:
 	$(sc) prepare trajectory-to-plans\
 	 --name prepare --sample-size 1 --output input/$V\
 	 --max-typical-duration 0\
 	 --population $(shared)/matsim-input-files/senozon/20230111_teilmodell_lausitz/population.xml.gz\
 	 --attributes  $(shared)/matsim-input-files/senozon/20230111_teilmodell_lausitz/additionalPersonAttributes.xml.gz
 
+	# resolve senozon aggregated grid coords (activities): distribute them based on landuse.shp
 	$(sc) prepare resolve-grid-coords\
 	 input/$V/prepare-100pct.plans.xml.gz\
 	 --input-crs $(CRS)\
@@ -115,35 +125,46 @@ input/$V/prepare-100pct.plans.xml.gz:
 
 input/$V/$N-$V-100pct.plans-initial.xml.gz: input/plans-longHaulFreight.xml.gz input/$V/prepare-100pct.plans.xml.gz
 
+#	generate some short distance trips, which in senozon data generally are missing
+# trip range 700m because:
+# when adding 1km trips (default value), too many trips of bin 1km-2km were also added.
+#the range value is beeline, so the trip distance (routed) often is higher than 1km
 	$(sc) prepare generate-short-distance-trips\
  	 --population input/$V/prepare-100pct.plans.xml.gz\
  	 --input-crs $(CRS)\
 	 --shp input/shp/lausitz.shp --shp-crs $(CRS)\
 	 --range 700\
  	 --num-trips 324430
 
+#	adapt coords of activitzies in the wider network such that they are closer to a link
+# 	such that agents do not have to walk as far as before
 	$(sc) prepare adjust-activity-to-link-distances input/$V/prepare-100pct.plans-with-trips.xml.gz\
 	 --shp input/shp/lausitz.shp --shp-crs $(CRS)\
      --scale 1.15\
      --input-crs $(CRS)\
      --network input/$V/$N-$V-network.xml.gz\
      --output input/$V/prepare-100pct.plans-adj.xml.gz
 
+#	change modes in subtours with chain based AND non-chain based by choosing mode for subtour randomly
 	$(sc) prepare fix-subtour-modes --coord-dist 100 --input input/$V/prepare-100pct.plans-adj.xml.gz --output $@
 
+#	set car availability for agents below 18 to false, standardize some person attrs, set home coords, set income
 	$(sc) prepare population $@ --output $@
 
+#	split activity types to type_duration for the scoring to take into account the typical duration
 	$(sc) prepare split-activity-types-duration\
 		--input $@\
 		--exclude commercial_start,commercial_end,freight_start,freight_end\
 		--output $@
 
+#	merge person and freight pops
 	$(sc) prepare merge-populations $@ $< --output $@
 
 	$(sc) prepare downsample-population $@\
     	 --sample-size 1\
     	 --samples 0.25 0.1 0.01\
 
+# create matsim counts file
 input/$V/$N-$V-counts-bast.xml.gz: input/2019_A_S.zip input/2019_B_S.zip input/Jawe2019.csv input/$V/$N-$V-network-with-pt.xml.gz
 
 	$(sc) prepare counts-from-bast\
@@ -156,6 +177,7 @@ input/$V/$N-$V-counts-bast.xml.gz: input/2019_A_S.zip input/2019_B_S.zip input/J
 		--output $@
 
 check: input/$V/$N-$V-100pct.plans-initial.xml.gz
+	#commuter analysis, still TODO
 	$(sc) analysis commuter\
 	 --population $<\
  	 --input-crs $(CRS)\

input/v1.0/lausitz-v1.0-25pct.config.xml

@@ -74,8 +74,10 @@
 		<param name="useLanes" value="false"/>
 
 		<param name="vehiclesSource" value="modeVehicleTypesFromVehiclesData"/>
+		<!-- this setting is consistent with drt / dvrp necessities
+		if using drt + set to false it can happen that drt travel times estimates are not as precise as needed.
+		see comments in DvrpConfigGroup.checkConsistency-->
 		<param name="insertingWaitingVehiclesBeforeDrivingVehicles" value="true"/>
-<!--		TODO: ask TS check if this is consistent with drt, if so comment it here!-->
 	</module>
 
 	<module name="simwrapper" >
@@ -160,8 +162,10 @@
 	</module>
 
 	<module name="travelTimeCalculator">
+		<!-- This parameter decides which modes are analyzed, when separateModes = false && filterModes = true. The 2 latter parameters are only here for backwards compability.
+		standard is separateModes = true (see below), so analyzedModes is ignored.
+		In case of separateModes = false && filterModes = true: travel time measurement for all vehicle types together (seperatemodes = false), BUT filtered (filterModes = true) for the modes in analyzedModes-->
 		<param name="analyzedModes" value="car,freight"/>
-<!--		is this correct? Clarify!-->
 
 		<param name="separateModes" value="true"/>
 		<param name="calculateLinkToLinkTravelTimes" value="false"/>

src/main/java/org/matsim/run/LausitzScenario.java

@@ -123,8 +123,9 @@ public void install() {
 
 				bind(ScoringParametersForPerson.class).to(IncomeDependentUtilityOfMoneyPersonScoringParameters.class).asEagerSingleton();
 
-//				addControlerListenerBinding().to(ModeChoiceCoverageControlerListener.class);
-// 				for what do we need this?? -sme0524
+//				this is only a "nice to have" analysis to check whether agents had the chance to try out all the modes.
+//				the analysis is added to ModeStatsModule in matsim-libs PR3285
+				addControlerListenerBinding().to(ModeChoiceCoverageControlerListener.class);
 				addTravelTimeBinding(TransportMode.ride).to(networkTravelTime());
 				addTravelDisutilityFactoryBinding(TransportMode.ride).to(carTravelDisutilityFactoryKey());