SearchLibrium 0.0.270__tar.gz → 0.0.271__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. {searchlibrium-0.0.270/src/SearchLibrium.egg-info → searchlibrium-0.0.271}/PKG-INFO +1 -1
  2. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/pyproject.toml +1 -1
  3. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/mh_choice_estimator.py +155 -24
  4. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/numba_rrm.py +32 -1
  5. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/rrm.py +129 -2
  6. searchlibrium-0.0.271/src/SearchLibrium/version.txt +1 -0
  7. {searchlibrium-0.0.270 → searchlibrium-0.0.271/src/SearchLibrium.egg-info}/PKG-INFO +1 -1
  8. searchlibrium-0.0.270/src/SearchLibrium/version.txt +0 -1
  9. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/LICENSE +0 -0
  10. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/MANIFEST.in +0 -0
  11. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/README.md +0 -0
  12. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/setup.cfg +0 -0
  13. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/BEHier.py +0 -0
  14. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/Halton.py +0 -0
  15. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/MixedLogit.py +0 -0
  16. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/MixedLogitGSE.py +0 -0
  17. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/Mode_Activity_Nested.py +0 -0
  18. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/RandomP.py +0 -0
  19. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/SEARCH_SM_MARIO.py +0 -0
  20. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/Two_Level_Nest.py +0 -0
  21. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/__init__.py +0 -0
  22. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/__main__.py +0 -0
  23. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/_choice_model.py +0 -0
  24. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/_device.py +0 -0
  25. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/abm.py +0 -0
  26. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/accessibility.py +0 -0
  27. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/banditsa.py +0 -0
  28. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/boxcox_functions.py +0 -0
  29. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/call_meta.py +0 -0
  30. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/constraints_builder.py +0 -0
  31. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/coupled_solver.py +0 -0
  32. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/data/Swissmetro_final.csv +0 -0
  33. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/data/TravelMode.csv +0 -0
  34. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/data/electricity.csv +0 -0
  35. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/destination_distances.py +0 -0
  36. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/harmony.py +0 -0
  37. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/hspbil.py +0 -0
  38. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/jax_utils.py +0 -0
  39. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/larch_compat.py +0 -0
  40. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/larch_models.py +0 -0
  41. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/latent_class.py +0 -0
  42. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/latent_spec.py +0 -0
  43. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/lc_rail_guard.py +0 -0
  44. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/logistic_regression.py +0 -0
  45. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/main.py +0 -0
  46. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/main_debug.py +0 -0
  47. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/mdcev.py +0 -0
  48. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/misc.py +0 -0
  49. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/mixed_logit.py +0 -0
  50. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/mixed_nested.py +0 -0
  51. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/mixedrrm.py +0 -0
  52. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/multinomial_logit.py +0 -0
  53. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/multinomial_nested.py +0 -0
  54. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/multinomial_probit.py +0 -0
  55. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/numba_engine.py +0 -0
  56. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/numba_mxl.py +0 -0
  57. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/ordered_logit.py +0 -0
  58. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/ordered_logit_mixed.py +0 -0
  59. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/predict.py +0 -0
  60. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/regularization.py +0 -0
  61. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/sample_data.py +0 -0
  62. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/sapbil.py +0 -0
  63. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/search.py +0 -0
  64. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/selection_models.py +0 -0
  65. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/setup.py +0 -0
  66. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/siman.py +0 -0
  67. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/skims.py +0 -0
  68. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/sparseea_agds.py +0 -0
  69. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/test_lc_de.py +0 -0
  70. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/test_mario_searches.py +0 -0
  71. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/test_sapbil_vs_banditsa.py +0 -0
  72. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/threshold.py +0 -0
  73. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium/zero_inflated_ordered_probit.py +0 -0
  74. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium.egg-info/SOURCES.txt +0 -0
  75. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium.egg-info/dependency_links.txt +0 -0
  76. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium.egg-info/entry_points.txt +0 -0
  77. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium.egg-info/requires.txt +0 -0
  78. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/src/SearchLibrium.egg-info/top_level.txt +0 -0
  79. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_destination_distances.py +0 -0
  80. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_jax_mask_equivalence.py +0 -0
  81. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_larch_integration.py +0 -0
  82. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_lc_smart_init.py +0 -0
  83. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_mh_choice_estimator.py +0 -0
  84. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_mxl_random_starts.py +0 -0
  85. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_per_alternative_random.py +0 -0
  86. {searchlibrium-0.0.270 → searchlibrium-0.0.271}/tests/test_zero_inflated_ordered_probit.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: SearchLibrium
3
- Version: 0.0.270
3
+ Version: 0.0.271
4
4
  Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
5
5
  Author: Zeke Ahern, Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
6
6
  Maintainer-email: Zeke Ahern <z.ahern@qut.edu.au>
@@ -132,7 +132,7 @@ Documentation = "https://pypi.org/project/SearchLibrium/"
132
132
  realpython = "SearchLibrium.__main__:main"
133
133
 
134
134
  [tool.bumpver]
135
- current_version = "0.0.270"
135
+ current_version = "0.0.271"
136
136
  version_pattern = "MAJOR.MINOR.PATCH"
137
137
  commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
138
138
  commit = true
@@ -212,12 +212,18 @@ class IdentificationReport:
212
212
  eigenvalues: np.ndarray
213
213
  suggested_drop: tuple[str, ...] = ()
214
214
  weak_directions: tuple[dict, ...] = ()
215
+ # Features that do not vary within a case. In a conditional logit such a
216
+ # column is a case-level constant and cancels from the probability, so it
217
+ # is unidentified whatever the information matrix looks like -- see the
218
+ # constant-column pass in identify_weak_features.
219
+ constant_features: tuple[str, ...] = ()
215
220
 
216
221
  def as_dict(self) -> dict:
217
222
  return {
218
223
  "condition_number": float(self.condition_number),
219
224
  "eigenvalues": [float(v) for v in np.asarray(self.eigenvalues).ravel()],
220
225
  "suggested_drop": list(self.suggested_drop),
226
+ "constant_features": list(self.constant_features),
221
227
  "weak_directions": [
222
228
  {
223
229
  "eigenvalue": float(d["eigenvalue"]),
@@ -241,6 +247,7 @@ def identify_weak_features(
241
247
  offset_col: str = "log_correction",
242
248
  max_drop: int | None = None,
243
249
  protected: Sequence[str] = (),
250
+ constant_tol: float = 1e-10,
244
251
  ) -> IdentificationReport:
245
252
  """Find structurally weak directions in a long choice-set frame.
246
253
 
@@ -248,6 +255,16 @@ def identify_weak_features(
248
255
  ``possible_overspec.py``) for the sampled MNL used here: eigendecompose the
249
256
  scaled exact information matrix at ``beta`` (zeros when omitted) and return
250
257
  one feature per near-null direction as ``suggested_drop``.
258
+
259
+ A separate pass catches features that are CONSTANT WITHIN A CASE. Those are
260
+ case-level constants in a conditional logit -- they cancel from the
261
+ probability -- so the estimator leaves them at the ridge (coefficient ~0)
262
+ however much the column varies across cases. The eigen test cannot see
263
+ them: it rescales by ``sqrt(diag(info))``, and for such a column that
264
+ diagonal is its own numerical residue, so the column reports a unit
265
+ "self-correlation" and no weak direction. The share of a feature's
266
+ variation that lies within cases is the direct test, and any feature below
267
+ ``constant_tol`` of it is reported in ``constant_features``.
251
268
  """
252
269
  frame = data if isinstance(data, ChoiceSetFrame) else ChoiceSetFrame.from_long(
253
270
  data, feature_cols, case_col=case_col, alt_col=alt_col,
@@ -260,35 +277,75 @@ def identify_weak_features(
260
277
  else:
261
278
  beta_vec = np.asarray(beta, dtype=float).reshape(-1)
262
279
  info, _, _ = frame.information(beta_vec)
263
- diag = np.clip(np.diag(info), 1e-300, None)
264
- scale = np.sqrt(diag)
265
- scaled = info / np.outer(scale, scale)
266
- evals, evecs = np.linalg.eigh(0.5 * (scaled + scaled.T))
267
- condition = float(evals[-1] / max(evals[0], 1e-300))
268
- weak = np.flatnonzero(evals < float(tol))
269
280
  protected_set = {str(p) for p in (protected or ())}
270
281
  drops: list[str] = []
271
282
  directions: list[dict] = []
283
+
284
+ # ── Case-constant columns (before the eigen pass) ──────────────────────
285
+ # Within-case variation is the only variation a conditional logit can use.
286
+ # A column without it is unidentified whatever the information matrix says
287
+ # -- and what it says is numerical noise: the row is a difference of two
288
+ # ~equal quantities, so its diagonal is a residue and the scaled matrix
289
+ # picks up huge NEGATIVE eigenvalues that then masquerade as weak
290
+ # directions. Identify the constant columns first and run the eigen pass on
291
+ # the remaining submatrix, so those artifacts cannot produce a drop list
292
+ # (and cannot displace the real loaders by already-claimed names).
293
+ d = frame.dimension
294
+ s1 = np.zeros(d)
295
+ s2 = np.zeros(d)
296
+ within_ss = np.zeros(d)
297
+ n_rows = 0
298
+ for x in frame.x:
299
+ xi = np.asarray(x, dtype=float)
300
+ if xi.ndim != 2 or xi.shape[0] < 2:
301
+ continue
302
+ s1 += xi.sum(axis=0)
303
+ s2 += (xi * xi).sum(axis=0)
304
+ n_rows += xi.shape[0]
305
+ within_ss += ((xi - xi.mean(axis=0)) ** 2).sum(axis=0)
306
+ total_ss = np.clip(s2 - (s1 * s1) / max(n_rows, 1), 0.0, None)
307
+ share = np.divide(within_ss, total_ss,
308
+ out=np.zeros(d), where=total_ss > 0)
309
+ # ``where=total_ss > 0`` leaves the share at 0 for a column with no variance
310
+ # at all, which is equally unidentified, so one test covers both.
311
+ constant_mask = share <= float(constant_tol)
312
+ constant = [names[j] for j in np.flatnonzero(constant_mask)
313
+ if names[j] not in protected_set]
314
+ for name in constant:
315
+ directions.append({"eigenvalue": 0.0, "loadings": {name: 1.0}})
316
+ drops.extend(constant)
317
+
318
+ keep = np.flatnonzero(~constant_mask)
319
+ keep_names = [names[j] for j in keep]
320
+ sub = info[np.ix_(keep, keep)]
321
+ diag = np.clip(np.diag(sub), 1e-300, None)
322
+ scale = np.sqrt(diag)
323
+ scaled = sub / np.outer(scale, scale)
324
+ evals, evecs = np.linalg.eigh(0.5 * (scaled + scaled.T))
325
+ condition = float(evals[-1] / max(evals[0], 1e-300)) if evals.size else float("nan")
326
+ weak = np.flatnonzero(evals < float(tol))
327
+
272
328
  for idx in weak:
273
329
  # Unscale the direction: v_j = evec_j / sqrt(info_jj).
274
330
  v = evecs[:, idx] / scale
275
331
  v = v / (np.linalg.norm(v) + 1e-300)
276
332
  order = np.argsort(-np.abs(v))
277
- top = {names[j]: float(v[j]) for j in order[: min(8, len(order))]}
333
+ top = {keep_names[j]: float(v[j]) for j in order[: min(8, len(order))]}
278
334
  directions.append({"eigenvalue": float(evals[idx]), "loadings": top})
279
335
  # Never drop user-protected features (e.g. explicitly requested
280
336
  # behavioural interactions); fall through to the next-largest loader.
281
337
  j = next((int(k) for k in order
282
- if names[int(k)] not in protected_set), None)
338
+ if keep_names[int(k)] not in protected_set), None)
283
339
  if j is None:
284
340
  continue
285
- if abs(v[j]) >= float(loading_threshold) and names[j] not in drops:
286
- drops.append(names[j])
341
+ if abs(v[j]) >= float(loading_threshold) and keep_names[j] not in drops:
342
+ drops.append(keep_names[j])
287
343
  if max_drop is not None and len(drops) > int(max_drop):
288
344
  drops = drops[: int(max_drop)]
289
345
  return IdentificationReport(
290
346
  condition_number=condition, eigenvalues=evals,
291
- suggested_drop=tuple(drops), weak_directions=tuple(directions))
347
+ suggested_drop=tuple(drops), weak_directions=tuple(directions),
348
+ constant_features=tuple(constant))
292
349
 
293
350
 
294
351
  class GaussianRandomWalkProposal:
@@ -1338,12 +1395,23 @@ def _fit_membership_gammas(case_X, resp, l2: float = 1.0, maxiter: int = 200,
1338
1395
 
1339
1396
 
1340
1397
  def _fit_frame_mnl(frame: "ChoiceSetFrame", x0, *, prior_scale: float = 5.0,
1341
- bounds: float = 15.0, maxiter: int = 500, tol: float = 1e-9):
1398
+ bounds: float = 15.0, maxiter: int = 500, tol: float = 1e-9,
1399
+ grad_tol: float = 1e-6, retries: int = 2):
1342
1400
  """Weighted MNL fit on a (copied) frame: L-BFGS-B on the analytic gradient.
1343
1401
 
1344
1402
  Mirrors larch's ``minimize(logloss, jac=d_logloss, bounds=pbounds)`` with
1345
1403
  a weak N(0, prior_scale^2) ridge so unidentified directions are bounded.
1346
1404
  The Manski-Lerman offset travels inside the frame, so it is exact here.
1405
+
1406
+ ``ftol`` alone is a relative decrease test, so L-BFGS-B can stop with a
1407
+ large gradient and still report success -- and can stop short of the
1408
+ optimum when it runs out of iterations. The fit is therefore re-started
1409
+ from its own solution while the gradient is too large, keeping the better
1410
+ objective value, and the returned result carries the evidence
1411
+ (``grad_inf``, ``grad_tol``, ``fit_message``) alongside ``success``, which
1412
+ is true when either scipy succeeded or the gradient shows a stationary
1413
+ point. The threshold is per observation, since the likelihood scales with
1414
+ the sample.
1347
1415
  """
1348
1416
  from scipy.optimize import minimize
1349
1417
  d = frame.dimension
@@ -1355,10 +1423,49 @@ def _fit_frame_mnl(frame: "ChoiceSetFrame", x0, *, prior_scale: float = 5.0,
1355
1423
  g = grad - prior_prec * np.asarray(beta, dtype=float)
1356
1424
  return -total, -g
1357
1425
 
1358
- res = minimize(nll, np.asarray(x0, dtype=float), jac=True,
1359
- method="L-BFGS-B",
1360
- bounds=[(-float(bounds), float(bounds))] * d,
1361
- options={"maxiter": int(maxiter), "ftol": float(tol)})
1426
+ try:
1427
+ g_tol = float(grad_tol) * max(int(frame.n_cases), 1)
1428
+ except Exception:
1429
+ g_tol = float(grad_tol)
1430
+
1431
+ def _run(start, n_iter):
1432
+ # ftol is a relative-decrease test on an objective of order 1e3, so on
1433
+ # its own it stops while the gradient is still ~1e-2. Stop on the
1434
+ # gradient; ftol is only kept as a floating-point floor.
1435
+ return minimize(nll, np.asarray(start, dtype=float), jac=True,
1436
+ method="L-BFGS-B",
1437
+ bounds=[(-float(bounds), float(bounds))] * d,
1438
+ options={"maxiter": int(n_iter),
1439
+ "ftol": min(float(tol), 1e-15),
1440
+ "gtol": g_tol})
1441
+
1442
+ res = _run(x0, maxiter)
1443
+ left = int(retries)
1444
+ while left > 0:
1445
+ g = np.asarray(nll(np.asarray(res.x, dtype=float))[1], dtype=float)
1446
+ g_inf = float(np.max(np.abs(g))) if g.size else float("nan")
1447
+ if not np.isfinite(g_inf) or g_inf <= g_tol:
1448
+ break
1449
+ left -= 1
1450
+ try:
1451
+ retry = _run(res.x, max(2 * int(maxiter), int(maxiter)))
1452
+ except Exception:
1453
+ break
1454
+ if not np.isfinite(float(getattr(retry, "fun", np.inf))) \
1455
+ or float(retry.fun) > float(res.fun) - 1e-9:
1456
+ break # no progress: keep what we had
1457
+ res = retry
1458
+
1459
+ try:
1460
+ g = np.asarray(nll(np.asarray(res.x, dtype=float))[1], dtype=float)
1461
+ g_inf = float(np.max(np.abs(g))) if g.size else float("nan")
1462
+ except Exception:
1463
+ g_inf = float("nan")
1464
+ res.grad_inf = g_inf
1465
+ res.grad_tol = g_tol
1466
+ res.fit_message = str(getattr(res, "message", "") or "")
1467
+ res.converged_evidence = bool(np.isfinite(g_inf) and g_inf <= g_tol)
1468
+ res.success = bool(getattr(res, "success", False) or res.converged_evidence)
1362
1469
  return np.asarray(res.x, dtype=float), float(-res.fun), res
1363
1470
 
1364
1471
 
@@ -1572,10 +1679,22 @@ def estimate_dest_choice_lc(
1572
1679
  p = np.clip(p, float(share_floor) / n_classes, None)
1573
1680
  p /= p.sum(axis=1, keepdims=True)
1574
1681
  new_shares = p.mean(axis=0)
1575
- # M-step: weighted MNL per class + membership gammas
1576
- betas = [_fit_frame_mnl(_weighted_frame(frame, p[:, c]), betas[c],
1577
- prior_scale=prior_scale, bounds=bounds)[0]
1578
- for c in range(n_classes)]
1682
+ # M-step: weighted MNL per class + membership gammas.
1683
+ # Keep each fit's first-order optimality: the optimizer flag only
1684
+ # says the M-step stopped, the gradient says it stopped at an
1685
+ # optimum, and without it the reported class solution carries no
1686
+ # evidence about the M-steps at all.
1687
+ # NB: warm start from the previous iteration's betas, so build the
1688
+ # new vectors in a separate list rather than clearing `betas` first.
1689
+ _prev = betas
1690
+ betas = []
1691
+ mstep_grad = []
1692
+ for c in range(n_classes):
1693
+ _b, _, _r = _fit_frame_mnl(_weighted_frame(frame, p[:, c]),
1694
+ _prev[c], prior_scale=prior_scale,
1695
+ bounds=bounds)
1696
+ betas.append(_b)
1697
+ mstep_grad.append(float(getattr(_r, "grad_inf", float("nan"))))
1579
1698
  if case_X is not None:
1580
1699
  gammas = _fit_membership_gammas(case_X, p, l2=membership_l2, standardize=True)
1581
1700
  shares = new_shares
@@ -1618,14 +1737,16 @@ def estimate_dest_choice_lc(
1618
1737
  _rank = (bool(converged), fit_ll)
1619
1738
  if best is None or _rank > (bool(best[4]), best[0]):
1620
1739
  best = (fit_ll, betas, shares, p, converged, iterations,
1621
- None if gammas is None else np.asarray(gammas).copy())
1622
- fit_ll, betas, shares, resp, converged, iterations, gammas = best
1740
+ None if gammas is None else np.asarray(gammas).copy(),
1741
+ mstep_grad)
1742
+ fit_ll, betas, shares, resp, converged, iterations, gammas, mstep_grad = best
1623
1743
  if case_X is None:
1624
1744
  # label switching only reorders the fixed-share solution; with a
1625
1745
  # membership equation the reference class structure must be kept.
1626
1746
  order = np.argsort(-np.asarray(shares))
1627
1747
  betas = [betas[i] for i in order]
1628
1748
  resp = np.asarray(resp)[:, order]
1749
+ mstep_grad = [mstep_grad[i] for i in order]
1629
1750
  # Derive the reported shares from the SAME responsibilities that ship with
1630
1751
  # the result. `shares` carried out of the EM loop was the mean of the
1631
1752
  # share_floor-CLIPPED responsibilities, while the returned `resp` is the
@@ -1643,13 +1764,16 @@ def estimate_dest_choice_lc(
1643
1764
  converged, iterations, frame, responsibilities=resp,
1644
1765
  membership_coefs=gammas, membership_vars=memb_cols,
1645
1766
  crash_cols=crash_cols, restart_lls=restart_lls,
1646
- bounds=float(bounds), share_floor=float(share_floor))
1767
+ bounds=float(bounds), share_floor=float(share_floor),
1768
+ mstep_grad_inf=mstep_grad,
1769
+ mstep_grad_tol=1e-6 * frame.n_cases)
1647
1770
 
1648
1771
 
1649
1772
  def _lc_result(method, names, betas, ses, shares, fit_ll, _unused, converged,
1650
1773
  iterations, frame, labels=None, responsibilities=None,
1651
1774
  membership_coefs=None, membership_vars=None, crash_cols=None,
1652
- restart_lls=None, bounds=15.0, share_floor=0.05) -> dict:
1775
+ restart_lls=None, bounds=15.0, share_floor=0.05,
1776
+ mstep_grad_inf=None, mstep_grad_tol=None) -> dict:
1653
1777
  n_classes = len(betas)
1654
1778
  k_params = n_classes * frame.dimension + (n_classes - 1)
1655
1779
  if membership_vars:
@@ -1671,6 +1795,13 @@ def _lc_result(method, names, betas, ses, shares, fit_ll, _unused, converged,
1671
1795
  "converged": bool(converged),
1672
1796
  "iterations": int(iterations),
1673
1797
  }
1798
+ if mstep_grad_inf is not None:
1799
+ _mg = [float(v) for v in mstep_grad_inf]
1800
+ _mt = None if mstep_grad_tol is None else float(mstep_grad_tol)
1801
+ out["mstep_grad_inf"] = _mg
1802
+ out["mstep_grad_tol"] = _mt
1803
+ out["mstep_stationary"] = [bool(_mt is not None and np.isfinite(v)
1804
+ and v <= _mt) for v in _mg]
1674
1805
  try:
1675
1806
  from .lc_rail_guard import lc_result_rail as _lc_rail
1676
1807
  except Exception:
@@ -319,8 +319,39 @@ def fit_rrm_numba(model, start=None, compute_inference=True):
319
319
  result = _sp_min(_obj, start, jac=True, method='BFGS',
320
320
  options={'maxiter': int(getattr(model, 'maxiter', 2000) or 2000),
321
321
  'gtol': 1e-6, 'disp': False})
322
+ # Same contract as the pure-scipy path: re-polish while the gradient is
323
+ # still large, then judge convergence on first-order optimality instead of
324
+ # scipy's success flag (BFGS reports precision loss after it has already
325
+ # converged, which used to mark every RRM fit as failed).
326
+ #
327
+ # The gradient here is a central difference of the njit likelihood, which
328
+ # is noisy on the near-collinear period design, so the polish and the final
329
+ # verdict use the analytic numpy gradient: both engines then land on the
330
+ # same optimum and agree on whether it is one.
331
+ def _analytic_grad(x):
332
+ try:
333
+ return model.get_loglike_gradient(
334
+ np.asarray(x, dtype=float), np.ones(M, dtype=float) * 1e-10)[1]
335
+ except Exception:
336
+ return None
337
+
338
+ def _obj_exact(b):
339
+ b = np.ascontiguousarray(np.asarray(b, dtype=np.float64))
340
+ f, g = model.get_loglike_gradient(b, np.ones(M, dtype=float) * 1e-10)
341
+ return float(f), np.asarray(g, dtype=np.float64)
342
+
343
+ try:
344
+ try:
345
+ from rrm import assess_convergence as _assess, polish_result as _polish
346
+ except ImportError:
347
+ from .rrm import assess_convergence as _assess, polish_result as _polish
348
+ n_obs = int(len(y_idx))
349
+ result = _polish(_obj_exact, result, grad_fun=_analytic_grad, n_obs=n_obs)
350
+ model.converged, model.grad_norm_inf, model.fit_message = _assess(
351
+ result, n_obs=n_obs, grad=_analytic_grad(result.x))
352
+ except Exception:
353
+ model.converged = bool(getattr(result, 'success', False))
322
354
  model.coeff_est = result.x
323
- model.converged = result.success
324
355
  model.beta = result.x
325
356
  try:
326
357
  model.post_process(compute_inference=compute_inference)
@@ -46,6 +46,124 @@ import numpy as np
46
46
  from numpy.typing import NDArray
47
47
  from scipy import stats
48
48
  from scipy.optimize import minimize
49
+
50
+ # ── Convergence assessment ─────────────────────────────────────────────────
51
+ # scipy's BFGS reports success=False with "Desired error not necessarily
52
+ # achieved due to precision loss" once the line search can no longer improve
53
+ # at float64 precision. That happens AFTER the optimum has been reached, so
54
+ # treating result.success as the convergence verdict marks good fits as
55
+ # failures. Downstream that is expensive: the ABM pipeline (stage4 Schedule
56
+ # Placement) labels the model 'optimizer_stopped' and down-weights its period
57
+ # probabilities (blend_alpha 0.08-0.35), so a converged RRM contributes almost
58
+ # nothing to the simulated schedule. All 8 RRM timing models in runs
59
+ # 27284748/27293944 hit this.
60
+ #
61
+ # The verdict below is first-order optimality (scaled gradient at the
62
+ # solution), with a short re-polish when the gradient is still large, which is
63
+ # what actually recovers fits that stalled in the line search.
64
+ RRM_GRAD_TOL = 1e-6 # on the MEAN log-likelihood gradient, per obs
65
+ RRM_POLISH_ATTEMPTS = 2
66
+ RRM_POLISH_MAXITER = 2000
67
+
68
+
69
+ def grad_tolerance(n_obs=None, gtol=None):
70
+ """Absolute gradient threshold for a sample of ``n_obs`` observations.
71
+
72
+ The likelihood is a sum, so its gradient grows with the sample size: a
73
+ fixed absolute threshold is strict on small samples and meaningless on
74
+ large ones. The criterion used here is that the gradient of the *mean* log
75
+ likelihood is below ``RRM_GRAD_TOL``. At that point the remaining
76
+ log-likelihood gain is far below what any reported digit could show.
77
+ """
78
+ if gtol is not None:
79
+ return float(gtol)
80
+ try:
81
+ n = int(n_obs or 0)
82
+ except Exception:
83
+ n = 0
84
+ return float(RRM_GRAD_TOL * max(n, 1))
85
+
86
+
87
+ def _grad_inf_norm(result, n_params=None, grad=None):
88
+ """Largest absolute gradient component at the reported solution.
89
+
90
+ ``grad`` overrides ``result.jac`` so callers holding a more accurate
91
+ gradient (the analytic numpy one, or the numba engine's finite-difference
92
+ estimate at a nearly-collinear solution) can supply it.
93
+ """
94
+ try:
95
+ jac = (np.asarray(grad, dtype=float) if grad is not None
96
+ else np.asarray(result.jac, dtype=float)).ravel()
97
+ if jac.size == 0 or not np.all(np.isfinite(jac)):
98
+ return float('nan')
99
+ return float(np.max(np.abs(jac)))
100
+ except Exception:
101
+ return float('nan')
102
+
103
+
104
+ def assess_convergence(result, gtol=None, n_obs=None, grad=None):
105
+ """Decide convergence from the evidence, not only ``result.success``.
106
+
107
+ Returns ``(converged, grad_inf, message)``. A fit counts as converged when
108
+ scipy says so, or when the gradient is small enough to be at a stationary
109
+ point even though the line search gave up on precision. Unknown gradients
110
+ fall back to scipy's verdict rather than claiming success.
111
+ """
112
+ tol = grad_tolerance(n_obs, gtol)
113
+ grad = _grad_inf_norm(result, grad=grad)
114
+ msg = str(getattr(result, 'message', '') or '')
115
+ success = bool(getattr(result, 'success', False))
116
+ if success:
117
+ return True, grad, msg
118
+ if np.isfinite(grad) and grad <= tol:
119
+ return True, grad, msg + ' [accepted: scaled gradient below tolerance]'
120
+ return False, grad, msg
121
+
122
+
123
+ def polish_result(fun, result, gtol=None, attempts=None, maxiter=None,
124
+ grad_fun=None, n_obs=None):
125
+ """Re-run BFGS from the reported solution while the gradient is too large.
126
+
127
+ The first BFGS call already did the work; this only rescues fits that
128
+ stopped early with a usable point. The best objective value wins, so a
129
+ polish pass can never return a worse fit than the one it started from.
130
+
131
+ ``grad_fun(x)`` supplies a more accurate gradient than ``result.jac`` for
132
+ the stopping test (the numba engine's finite differences are noisy where
133
+ the specification is nearly collinear, which would otherwise keep the
134
+ retry loop running at a point that is already optimal).
135
+ """
136
+ tol = grad_tolerance(n_obs, gtol)
137
+ n_left = int(RRM_POLISH_ATTEMPTS if attempts is None else attempts)
138
+ n_iter = int(RRM_POLISH_MAXITER if maxiter is None else maxiter)
139
+ best = result
140
+ best_f = float(getattr(result, 'fun', np.inf))
141
+
142
+ def _stopping_grad(res):
143
+ if grad_fun is None:
144
+ return None
145
+ try:
146
+ return grad_fun(res.x)
147
+ except Exception:
148
+ return None
149
+
150
+ while n_left > 0:
151
+ ok, grad, _msg = assess_convergence(best, tol, grad=_stopping_grad(best))
152
+ if ok:
153
+ break
154
+ n_left -= 1
155
+ try:
156
+ retry = minimize(fun, np.asarray(best.x, dtype=float), jac=True,
157
+ method='BFGS', tol=1e-8,
158
+ options={'maxiter': n_iter,
159
+ 'gtol': max(tol, 1e-6), 'disp': False})
160
+ except Exception:
161
+ break
162
+ f_new = float(getattr(retry, 'fun', np.inf))
163
+ if not np.isfinite(f_new) or f_new > best_f + 1e-9:
164
+ break # no progress: keep what we had
165
+ best, best_f = retry, f_new
166
+ return best
49
167
  import pandas as pd
50
168
  from time import time
51
169
  try:
@@ -635,8 +753,11 @@ class RandomRegret(DiscreteChoiceModel):
635
753
  self.fit_start_time = _time()
636
754
  result = sp_min(_obj, start, jac=True, method='BFGS',
637
755
  options={'maxiter': 2000, 'gtol': 1e-6, 'disp': False})
756
+ result = polish_result(_obj, result, maxiter=2000,
757
+ n_obs=self.nb_samples)
638
758
  self.coeff_est = result.x
639
- self.converged = result.success
759
+ self.converged, self.grad_norm_inf, self.fit_message = \
760
+ assess_convergence(result, n_obs=self.nb_samples)
640
761
  self.beta = result.x
641
762
  self.post_process()
642
763
  return
@@ -688,8 +809,14 @@ class RandomRegret(DiscreteChoiceModel):
688
809
  jac=True,
689
810
  options={'maxiter': getattr(self, 'maxiter', 2000)},
690
811
  )
812
+ # Re-polish while the gradient is still large, then judge convergence
813
+ # on first-order optimality rather than scipy's precision-loss flag
814
+ # (see assess_convergence above).
815
+ _polish_fun = lambda _x: self.get_loglike_gradient(_x, delta)
816
+ result = polish_result(_polish_fun, result, n_obs=self.nb_samples)
691
817
  self.coeff_est = result.x
692
- self.converged =result.success
818
+ self.converged, self.grad_norm_inf, self.fit_message = \
819
+ assess_convergence(result, n_obs=self.nb_samples)
693
820
  self.beta = result.x # Extract results
694
821
  self.post_process(compute_inference=compute_inference)
695
822
  # }
@@ -0,0 +1 @@
1
+ 0.0.271
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: SearchLibrium
3
- Version: 0.0.270
3
+ Version: 0.0.271
4
4
  Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
5
5
  Author: Zeke Ahern, Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
6
6
  Maintainer-email: Zeke Ahern <z.ahern@qut.edu.au>
@@ -1 +0,0 @@
1
- 0.0.270
File without changes