add instructions to resume ABM3 run after a crash

docs/running.md

@@ -12,13 +12,13 @@ Follow the steps below to create an ABM3 scenario directory:
 * Log onto available server and ensure:
     1. Server's C Drive has at least 500 GB worth of space
     2. You are logged onto the Bentley CONNECTION Client license manager software
-* Using the server’s Windows Explorer, navigate to the latest approved ABM3 release. As of March 2025, this is *T:\ABM\release\ABM\version_15_2_2*
+* Using the server’s Windows Explorer, navigate to the latest approved ABM3 release. As of March 2026, this is *T:\ABM\release\ABM\version_15_3_1*
 * Double click on *createStudyAndScenario.bat* and click Run.
 * On pop-up, fill out the fields under *Create an ABM scenario*.
-    * **EMME Version**: As of March 2025, only available version is 4.3.7
+    * **EMME Version**: As of March 2026, EMME version is OpenPaths EMME 25.00.01
     * **Year**: Using drop-down menu, select scenario year you'd like to run
     * **Base**: Whether you would like to run a Build or No Build scenario. Note that the base 2022 year only has the option to run as Base.
-    * **Geography ID**: Leave as 1. As of March 2025, this field has no functionality. 
+    * **Geography ID**: Leave as 1. As of March 2026, this field has no functionality. 
     * **Scenario Folder**: File path you would like to create scenario at. The tool will create the directory if it doesn't already exist. For cases where you point to an exisitng directory, the tool will notify users that location exists to avoid unintended overwriting.
     * **Network Folder**: File path to input network. 
     * **Land Use Folder**: File path to input land use files.
@@ -28,7 +28,7 @@ Follow the steps below to create an ABM3 scenario directory:
 
 ## Running ABM3
 
-To open the EMME application from the created scenario directory, users need to go to the *emme_project* folder, and double-click on the *start_emme_with_virtualenv.bat* file. This opens up the EMME application, where the application prompts the choice of a scenario. It is recommended to select the main highway scenario (Scen. 100) to start off the model run, although other scenarios may be selected as well. 
+To open the EMME application from the created scenario directory, users need to go to the *emme_project* folder, and double-click on the *emme_project.emp* file. This opens up the EMME application, where the application prompts the choice of a scenario. It is recommended to select the main highway scenario (Scen. 100) to start off the model run, although other scenarios may be selected as well. 
 
 Following this step, users should open the *EMME Modeler* by clicking on the gold square icon at the top left of the screen. 
 <br>
@@ -110,20 +110,51 @@ Within the SANDAG workspace, an ABM3 scenario is typically created on an interna
 If the same scenario from above would like to be reran:
 
 * From beginning to end (i.e., from iteration 1):
-    * The modeler simply needs to open the scenario via the *start_emme_with_virtualenv.bat* file (on T Drive), edit (if applicable) the setup in the *Master Run* tool, and launch.
+    * The modeler simply needs to open the scenario via the *emme_project.emp* file (on T Drive), edit (if applicable) the setup in the *Master Run* tool, and launch.
 * Or, starting from the 2nd or 3rd iteration:
-    * The modeler must copy the entire ABM3 scenario to the machine's C Drive (typically under C:\abm_runs\\{username}). In particular, the modeler should ensure the files found within the *emme_project* folder are present on the C Drive before relaunching the scenario.
-    * From there, the modeler may open the scenario via the *start_emme_with_virtualenv.bat* file on the T Drive, edit the setup in the *Master Run* tool, and launch.
+    * The modeler must use the *copyRun* tool to copy the entire ABM3 scenario to the machine's C Drive (typically under C:\abm_runs\\{username}). The *copyRun* tool is required (rather than a manual copy) because with ABM release 15.3, the skims are converted into the OMXZ format for more efficient reading into ActivitySim. This conversion is not performed after final assignment, so manually copying a run without using the *copyRun* tool would result in the resident model failing to run. In particular, the modeler should ensure the files found within the *emme_project* folder are present on the C Drive before relaunching the scenario.
+    * From there, the modeler may open the scenario via the *emme_project.emp* file on the T Drive, edit the setup in the *Master Run* tool, and launch.
 
 Note that under the above two workflows, the original scenario's (on T Drive) outputs will be overwritten when the scenario is copied from the C Drive back to the T Drive. The modeler should consider saving the original scenario's outputs in a different location if wanting to preserve the original data. 
 
 An alternative workflow, that may be useful for development or debugging purposes, involves rerunning the scenario entirely on the C Drive. It should be noted that under this worfklow, the model outputs of the rerun will not be copied back to the T Drive as part of the model run flow (may be copied over manually if desired). To proceed with this workflow:
 
-* The modeler must copy the entire ABM3 scenario to the machine's C Drive (typically under C:\abm_runs\\{username}).
-* Then, the modeler must open the scenario via the *start_emme_with_virtualenv.bat* file on the C Drive. 
+* The modeler must use the *copyRun* tool to copy the entire ABM3 scenario to the machine's C Drive (typically under C:\abm_runs\\{username}). The *copyRun* tool processes the skims into the OMXZ format required for ActivitySim in release 15.3.
+* Then, the modeler must open the scenario via the *emme_project.emp* file on the C Drive. 
 * Lastly, in addition to any desired setup edits under the *Master Run* tool, the modeler must uncheck *Use the local drive during the model run* so that the model run does not attempt to copy scenario files to a different drive.
 
 One other point the modeler should consider when rerunning a scenario is whether model outputs should be loaded onto Azure Data Lake, which is controlled via the *Skip write to datalake* parameter under the *Master Run* tool:
 
 * Unchecking this step will result in model outputs being loaded onto Azure Data Lake under a new scenario ID and will not overwrite the original run's data on Azure Data Lake
-* Checkmarking this step will skip model outputs from being loaded onto Azure Data Lake. This will likely be the preferred approach for scenario reruns related to development or debugging purposes.
+* Checkmarking this step will skip model outputs from being loaded onto Azure Data Lake. This will likely be the preferred approach for scenario reruns related to development or debugging purposes.
+
+### Resuming a Crashed ABM3 Run
+
+*Note: This section mainly relevant to SANDAG users.*
+
+If an ABM3 model run crashes before completion, the modeler should first consult the *EMME Logbook*, which provides detailed error messages to help diagnose the cause of the crash. After investigating the error and fixing any input or script issues, the modeler can resume the run from various points depending on where the crash occurred. The table below provides guidance on which steps to skip in the *Master Run* tool to resume from different crash locations:
+
+| **Crash Location** | **Start from iteration** | **Steps to Skip** |
+|-------------------|-------------------------|-------------------|
+| Import network | 1 | None - rerun from beginning |
+| Bike logsum | 1 | Skip steps before bike logsums |
+| Iter 1 traffic/transit assignment | 1 | Skip steps before Iter 1 traffic/transit assignment |
+| Iter 1 resident model | 1 | Skip steps before Iter 1 ActivitySim Preprocessing |
+| Iter 1 special market model | 1 | Skip steps before Iter 1 ActivitySim Preprocessing, and skip Iter 1 Resident Model |
+| Iter 2 traffic/transit assignment | 2 | Skip steps before Iter 2 traffic/transit assignment |
+| Iter 2 resident model | 2 | Skip steps before Iter 2 ActivitySim Preprocessing |
+| Iter 2 special market model | 2 | Skip steps before Iter 2 special marker model |
+| Iter 3 traffic/transit assignment | 3 | Skip steps before Iter 3 traffic/transit assignment |
+| Iter 3 resident model | 3 | Skip steps before Iter 3 ActivitySim Preprocessing |
+| Iter 3 special market model | 3 | Skip steps before Iter 3 special marker model |
+| Iter 4 traffic/transit assignment | 4 | Skip steps before Iter 4 traffic/transit assignment |
+| Iter 4 write to datalake | 4 | Skip all previous steps and uncheck the box of 'Skip write to datalake' |
+
+**Important Notes:**
+
+* Before resuming a crashed run, verify that the outputs from previously completed steps are present in the scenario directory.
+* When resuming from an iteration other than iteration 1, ensure the *Start from iteration* parameter in the *Master Run* tool is set correctly.
+* For crashes during traffic/transit assignment, it's typically safer to re-run the assignment rather than trying to resume partway through.
+* If uncertain about which steps to skip, consult the *EMME Logbook* to determine exactly which steps completed successfully before the crash.
+* If the `mgra15_based_input{year}.csv` file needs to be updated to fix a model failure, update the file in the T Drive location. This is especially important since this file gets modified during the model run and will be overwritten with the unmodified T Drive version when restarting the run during the copy step.
+

src/asim/configs/airport.CBX/settings.yaml

@@ -79,7 +79,7 @@ input_table_list:
       - tour_type
       - origin
       - destination
-      - emp_trip_mode
+      # - emp_trip_mode
 
 
 # set false to disable variability check in simple_simulate and interaction_simulate

src/asim/configs/airport.CBX/trip_mode_choice.csv

@@ -2,8 +2,8 @@ Label,Description,Expression,PARK_LOC1,PARK_LOC2,PARK_LOC3,PARK_LOC4,PARK_LOC5,P
 res_bus,Resident Bus,@df.purpose_id ==0,,,,,,,-999,-999,-999,,,,,,,,,,,,,,,,,,,
 res_per,Resident Personal,@df.purpose_id ==1,,,,,,,-999,-999,-999,,,,,,,,,,,,,,,,,,,
 non_emp,Non Employee,@df.purpose_id !=5,,,,,,,,,,,,,,,,,,,,,,,,,,,,-999
-emp_walk,Employee Walk,@(df.purpose_id ==5) & (df.emp_trip_mode == 'WALK'),,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,
-emp_tran,Employee Transit,@(df.purpose_id ==5) & (df.emp_trip_mode == 'WALK_PRM'),,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,,-999,-999,-999,-999,-999,-999,-999,-999
+# emp_walk,Employee Walk,@(df.purpose_id ==5) & (df.emp_trip_mode == 'WALK'),,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,
+# emp_tran,Employee Transit,@(df.purpose_id ==5) & (df.emp_trip_mode == 'WALK_PRM'),,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,-999,,-999,-999,-999,-999,-999,-999,-999,-999
 vis_bus,Visitor Bus,@df.purpose_id ==2,-999,-999,-999,-999,-999,,,,,,,,,,,,,,,,,,,,,,,
 vis_per,Visitor Per,@df.purpose_id ==3,-999,-999,-999,-999,-999,,,,,,,,,,,,,,,,,,,,,,,
 taxi_unavailable,Taxi availability,@taxi_available == 0,,,,,,,,,,,,-999,-999,,,,,,,,,,,,,,,

src/asim/configs/airport.CBX/trip_mode_choice.yaml

@@ -204,7 +204,7 @@ TOURS_MERGED_CHOOSER_COLUMNS:
   - tour_mode
   - mode_segment
   - direction
-  - emp_trip_mode
+  # - emp_trip_mode
   - party_size
 
 MODE_CHOICE_LOGSUM_COLUMN_NAME: mode_choice_logsum