Overflow protection for NL

activitysim/abm/models/atwork_subtour_frequency.py

@@ -117,6 +117,7 @@ def atwork_subtour_frequency(
         trace_label=trace_label,
         trace_choice_name="atwork_subtour_frequency",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     # convert indexes to alternative names

activitysim/abm/models/auto_ownership.py

@@ -75,6 +75,7 @@ def auto_ownership_simulate(
         trace_choice_name="auto_ownership",
         log_alt_losers=log_alt_losers,
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     if estimator:

activitysim/abm/models/free_parking.py

@@ -118,6 +118,7 @@ def free_parking(
         trace_label=trace_label,
         trace_choice_name="free_parking_at_work",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     free_parking_alt = model_settings.FREE_PARKING_ALT

activitysim/abm/models/joint_tour_composition.py

@@ -123,6 +123,7 @@ def joint_tour_composition(
         trace_label=trace_label,
         trace_choice_name="composition",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     # convert indexes to alternative names

activitysim/abm/models/joint_tour_frequency.py

@@ -112,6 +112,7 @@ def joint_tour_frequency(
         trace_label=trace_label,
         trace_choice_name="joint_tour_frequency",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     # convert indexes to alternative names

activitysim/abm/models/joint_tour_participation.py

@@ -414,6 +414,7 @@ def joint_tour_participation(
         trace_choice_name="participation",
         custom_chooser=participants_chooser,
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     # choice is boolean (participate or not)

activitysim/abm/models/mandatory_tour_frequency.py

@@ -134,6 +134,7 @@ def mandatory_tour_frequency(
         trace_label=trace_label,
         trace_choice_name="mandatory_tour_frequency",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     # convert indexes to alternative names

activitysim/abm/models/stop_frequency.py

@@ -214,6 +214,7 @@ def stop_frequency(
             trace_label=tracing.extend_trace_label(trace_label, segment_name),
             trace_choice_name="stops",
             estimator=estimator,
+            overflow_protection=model_settings.overflow_protection,
         )
 
         # convert indexes to alternative names

activitysim/abm/models/telecommute_frequency.py

@@ -99,6 +99,7 @@ def telecommute_frequency(
         trace_label=trace_label,
         trace_choice_name="telecommute_frequency",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     choices = pd.Series(model_spec.columns[choices.values], index=choices.index)

activitysim/abm/models/transit_pass_ownership.py

@@ -93,6 +93,7 @@ def transit_pass_ownership(
         trace_label=trace_label,
         trace_choice_name="transit_pass_ownership",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     if estimator:

activitysim/abm/models/transit_pass_subsidy.py

@@ -92,6 +92,7 @@ def transit_pass_subsidy(
         trace_label=trace_label,
         trace_choice_name="transit_pass_subsidy",
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     if estimator:

activitysim/abm/models/trip_mode_choice.py

@@ -277,6 +277,7 @@ def trip_mode_choice(
             trace_label=segment_trace_label,
             trace_choice_name="trip_mode_choice",
             estimator=estimator,
+            overflow_protection=model_settings.overflow_protection,
         )
 
         if state.settings.trace_hh_id:

activitysim/abm/models/util/mode.py

@@ -34,6 +34,7 @@ def mode_choice_simulate(
     trace_choice_name,
     trace_column_names=None,
     estimator: Optional[Estimator] = None,
+    overflow_protection: bool = False,
 ):
     """
     common method for  both tour_mode_choice and trip_mode_choice
@@ -70,6 +71,7 @@ def mode_choice_simulate(
         trace_choice_name=trace_choice_name,
         estimator=estimator,
         trace_column_names=trace_column_names,
+        overflow_protection=overflow_protection,
     )
 
     # for consistency, always return dataframe, whether or not logsums were requested
@@ -170,6 +172,7 @@ def run_tour_mode_choice_simulate(
         trace_choice_name=trace_choice_name,
         trace_column_names=trace_column_names,
         estimator=estimator,
+        overflow_protection=model_settings.overflow_protection,
     )
 
     return choices

activitysim/abm/models/vehicle_allocation.py

@@ -236,6 +236,7 @@ def vehicle_allocation(
             trace_label=trace_label,
             trace_choice_name="vehicle_allocation",
             estimator=estimator,
+            overflow_protection=model_settings.overflow_protection,
         )
 
         # matching alt names to choices

activitysim/abm/models/vehicle_type_choice.py

@@ -500,6 +500,7 @@ def iterate_vehicle_type_choice(
                 trace_label=trace_label,
                 trace_choice_name="vehicle_type",
                 estimator=estimator,
+                overflow_protection=model_settings.overflow_protection,
             )
         else:
             raise NotImplementedError(simulation_type)

activitysim/abm/models/work_from_home.py

@@ -152,6 +152,7 @@ def work_from_home(
             trace_label=trace_label,
             trace_choice_name="work_from_home",
             estimator=estimator,
+            overflow_protection=model_settings.overflow_protection,
         )
 
         if iterations_target_percent is not None:

activitysim/core/configuration/logit.py

@@ -133,6 +133,16 @@ def nests_are_for_nl(cls, nests, values):
                 raise ValueError("NESTS cannot be provided for a MNL model")
         return nests
 
+    overflow_protection: bool = False
+    """Whether to use overflow protection in the probability calculation.
+
+    Overflow protection will shift the utility values to avoid numerical
+    overflow when exponentiating the utility values to calculate probabilities.
+    It will also protect against underflow if the utility values are very
+    negative.  Ideally, model specifications will be constructed to avoid
+    overflow, but this option is provided as a safety net.
+    """
+
 
 class TemplatedLogitComponentSettings(LogitComponentSettings):
     """

activitysim/core/interaction_sample.py

@@ -132,6 +132,7 @@ def _interaction_sample(
     trace_label=None,
     zone_layer=None,
     chunk_sizer=None,
+    overflow_protection: bool | None = None,
 ):
     """
     Run a MNL simulation in the situation in which alternatives must
@@ -178,6 +179,15 @@ def _interaction_sample(
         'maz' zone layer in a one-zone model, but you can use the 'taz' layer in
         a two- or three-zone model (e.g. for destination pre-sampling).
 
+    overflow_protection : bool, optional
+        If True, use overflow-protected exponentiation and normalization to
+        compute probabilities, which will help prevent problems if the utility
+        values are very large in magnitude (positive or negative).  If False,
+        overflow-protected exponentiation and normalization will not be used,
+        and the model might fail if the utility values are very large in magnitude.
+        If None (the default), overflow-protection is turned on if
+        `allow_zero_probs` is False, and left off otherwise.
+
     Returns
     -------
     choices_df : pandas.DataFrame
@@ -402,6 +412,9 @@ def _interaction_sample(
 
     state.tracing.dump_df(DUMP, utilities, trace_label, "utilities")
 
+    if overflow_protection is None:
+        overflow_protection = not allow_zero_probs
+
     # convert to probabilities (utilities exponentiated and normalized to probs)
     # probs is same shape as utilities, one row per chooser and one column for alternative
     probs = logit.utils_to_probs(
@@ -410,7 +423,7 @@ def _interaction_sample(
         allow_zero_probs=allow_zero_probs,
         trace_label=trace_label,
         trace_choosers=choosers,
-        overflow_protection=not allow_zero_probs,
+        overflow_protection=overflow_protection,
     )
     chunk_sizer.log_df(trace_label, "probs", probs)
 

activitysim/core/interaction_sample_simulate.py

@@ -31,6 +31,7 @@ def _interaction_sample_simulate(
     skip_choice=False,
     *,
     chunk_sizer: chunk.ChunkSizer,
+    overflow_protection: bool | None = None,
 ):
     """
     Run a MNL simulation in the situation in which alternatives must
@@ -72,6 +73,15 @@ def _interaction_sample_simulate(
         the index is same as choosers
         and the series value is the alternative df index of chosen alternative
 
+    overflow_protection : bool, optional
+        If True, use overflow-protected exponentiation and normalization to
+        compute probabilities, which will help prevent problems if the utility
+        values are very large in magnitude (positive or negative).  If False,
+        overflow-protected exponentiation and normalization will not be used,
+        and the model might fail if the utility values are very large in magnitude.
+        If None (the default), overflow-protection is turned on if
+        `allow_zero_probs` is False, and left off otherwise.
+
     Returns
     -------
     if want_logsums is False:
@@ -251,6 +261,9 @@ def _interaction_sample_simulate(
             column_labels=["alternative", "utility"],
         )
 
+    if overflow_protection is None:
+        overflow_protection = not allow_zero_probs
+
     # convert to probabilities (utilities exponentiated and normalized to probs)
     # probs is same shape as utilities, one row per chooser and one column for alternative
     if want_logsums:
@@ -260,7 +273,7 @@ def _interaction_sample_simulate(
             allow_zero_probs=allow_zero_probs,
             trace_label=trace_label,
             trace_choosers=choosers,
-            overflow_protection=not allow_zero_probs,
+            overflow_protection=overflow_protection,
             return_logsums=True,
         )
         chunk_sizer.log_df(trace_label, "logsums", logsums)
@@ -271,7 +284,7 @@ def _interaction_sample_simulate(
             allow_zero_probs=allow_zero_probs,
             trace_label=trace_label,
             trace_choosers=choosers,
-            overflow_protection=not allow_zero_probs,
+            overflow_protection=overflow_protection,
         )
     chunk_sizer.log_df(trace_label, "probs", probs)
 

activitysim/core/logit.py

@@ -131,7 +131,7 @@ def utils_to_probs(
     exponentiated=False,
     allow_zero_probs=False,
     trace_choosers=None,
-    overflow_protection: bool = True,
+    overflow_protection: bool = False,
     return_logsums: bool = False,
 ):
     """
@@ -158,7 +158,7 @@ def utils_to_probs(
         by report_bad_choices because it can't deduce hh_id from the interaction_dataset
         which is indexed on index values from alternatives df
 
-    overflow_protection : bool, default True
+    overflow_protection : bool, default False
         Always shift utility values such that the maximum utility in each row is
         zero.  This constant per-row shift should not fundamentally alter the
         computed probabilities, but will ensure that an overflow does not occur
@@ -194,10 +194,8 @@ def utils_to_probs(
                 raise ValueError(
                     "cannot prevent expected overflow with allow_zero_probs"
                 )
-    else:
-        overflow_protection = overflow_protection or (
-            utils_arr.dtype == np.float32 and utils_arr.max() > 85
-        )
+    elif overflow_protection is None:
+        overflow_protection = utils_arr.dtype == np.float32 and utils_arr.max() > 85
 
     if overflow_protection:
         # exponentiated utils will overflow, downshift them