SearchLibrium 0.0.126__tar.gz → 0.0.128__tar.gz

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: SearchLibrium
-Version: 0.0.126
+Version: 0.0.128
 Summary: A Python package for econometric models driven by search
 Author: Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
 Author-email: Zeke Ahern <z.ahern@qut.edu.au>
 Project-URL: Homepage, https://pypi.org/project/SearchLibrium/
+Project-URL: Repository, https://github.com/zahern/HypothesisX
+Project-URL: Issues, https://github.com/zahern/HypothesisX/issues
+Project-URL: Documentation, https://pypi.org/project/SearchLibrium/
 Keywords: econometric models,search,discrete choice,logit,probit
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -41,8 +44,9 @@ Requires-Dist: pytest; extra == "dev"
 [![Python](https://img.shields.io/pypi/pyversions/SearchLibrium.svg)](https://pypi.org/project/SearchLibrium/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml/badge.svg)](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml)
+[![GitHub](https://img.shields.io/badge/GitHub-HypothesisX-lightgrey?logo=github)](https://github.com/zahern/HypothesisX)
 
-**Automated discrete choice model search powered by Simulated Annealing, Harmony Search, and JAX-accelerated MLE.**
+**Automated discrete choice model search powered by Simulated Annealing, Bandit-guided SA, Harmony Search, SA+PBIL, HS+PBIL, Parallel SA, and JAX-accelerated MLE.**
 
 SearchLibrium searches over model specifications — which variables to include, whether parameters should be random, which transformations to apply, and which model class to use — and returns the best converged, all-significant model according to your chosen criterion (BIC, AIC, log-likelihood, MAE, or multi-objective combinations).
 
@@ -122,16 +126,19 @@ A **run dashboard** is printed automatically at the end of every search, showing
 
 ## How the search works
 
-The search uses **Simulated Annealing (SA)** to explore the space of model specifications:
+The search uses **metaheuristic optimisation** (SA, BanditSA, Harmony Search,
+SA+PBIL, HS+PBIL, or parallel variants) to explore the space of model
+specifications:
 
 ```text
 generate starting solution
-  └─ for each SA temperature step
+  └─ for each iteration / temperature step / improvisation
        └─ perturb current specification → guaranteed distinct from current
             ├─ fit model with JAX-accelerated MLE
             ├─ run backward elimination (remove insignificant vars, refit)
-            ├─ accept if converged + Metropolis criterion satisfied
-            └─ update best solution
+            ├─ accept if converged + acceptance criterion satisfied
+            │    (Metropolis, dominance, or pitch adjustment)
+            └─ update best solution / harmony memory
 print dashboard
 ```
 
@@ -433,27 +440,42 @@ python -m SearchLibrium --test_search_nest  # run nested logit search
 
 ## Search algorithms
 
-Both algorithms share a **consistent interface** through `call_search`:
+All algorithms share a **consistent interface**.  The library auto-estimates
+hyperparameters from problem size when you omit `ctrl`:
 
 ```python
-from SearchLibrium import call_search, estimate_ctrl
-
-# Auto-estimate hyperparameters from problem size (recommended)
-best = call_search(params)                            # SA by default
-best = call_search(params, algorithm='hs')            # Harmony Search
-
-# Manual hyperparameters
-best = call_search(params, ctrl=(1000, 0.001, 100, 20))           # SA
-best = call_search(params, algorithm='hs',
-                   ctrl=(20, 500, 0.9, 0.6, 0.85, 0.3))          # HS
-
-# Inspect auto-estimated ctrl before running
+from SearchLibrium import (call_search, call_siman, call_harmony, call_sapbil,
+                            call_banditsa, call_harmony_pbil,
+                            call_parsa, call_parcopsa, estimate_ctrl)
+
+# Unified entry point — auto hyperparameters (recommended)
+best = call_search(params)                              # SA (default)
+best = call_search(params, algorithm='hs')              # Harmony Search
+best = call_search(params, algorithm='sapbil')          # SA + PBIL
+best = call_search(params, algorithm='banditsa')        # Bandit-guided SA
+best = call_search(params, algorithm='hspbil')          # HS + PBIL
+
+# Inspect auto-estimated hyperparameters before running
 ctrl = estimate_ctrl(params, algorithm='sa')
 print(ctrl)
 ```
 
+### Algorithm reference
+
+| Function | Description | Population-based | Key idea |
+| -------- | ----------- | :---: | -------- |
+| `call_siman` | Simulated Annealing | | Metropolis acceptance with temperature cooling |
+| `call_banditsa` | Bandit-guided SA | | Thompson Sampling to choose perturbation actions |
+| `call_sapbil` | SA + PBIL | ✓ | Probability matrix learns from accepted solutions to bias perturbations |
+| `call_harmony` | Harmony Search | ✓ | Memory-based improvisation with pitch adjustment |
+| `call_harmony_pbil` | HS + PBIL | ✓ | Harmony Search with PBIL-guided pitch perturbation |
+| `call_parsa` | Parallel SA | | Multiple independent SA solvers running in parallel |
+| `call_parcopsa` | Parallel Cooperative SA | ✓ | Parallel SA with periodic best-solution sharing |
+
 ### Simulated Annealing (`call_siman` / `algorithm='sa'`)
 
+Control tuple: `(tI, tF, max_temp_steps, max_iter)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `tI` | Initial temperature — higher → more exploration |
@@ -467,12 +489,14 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 
 ### Harmony Search (`call_harmony` / `algorithm='hs'`)
 
+Control tuple: `(max_mem, maxiter, max_harm, min_harm, max_pitch, min_pitch)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `max_mem` | Harmony memory size (population) |
 | `maxiter` | Improvisation iterations |
-| `max_harm` | Max harmony consideration rate |
-| `min_harm` | Min harmony consideration rate |
+| `max_harm` | Max harmony memory consideration rate |
+| `min_harm` | Min harmony memory consideration rate |
 | `max_pitch` | Max pitch adjustment rate |
 | `min_pitch` | Min pitch adjustment rate |
 
@@ -480,6 +504,44 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 best = call_harmony(params, ctrl=(20, 400, 0.9, 0.6, 0.85, 0.3), id_num=1)
 ```
 
+### SA + PBIL (`call_sapbil` / `algorithm='sapbil'`)
+
+Population-Based Incremental Learning coupled with Simulated Annealing.
+Maintains a probability matrix over the search decisions (inclusion,
+randomness, distribution, correlation, Box-Cox) and updates it from
+accepted solutions using a temperature-coupled learning rate.
+
+```python
+best = call_sapbil(params, id_num=1)
+```
+
+### HS + PBIL (`call_harmony_pbil` / `algorithm='hspbil'`)
+
+Harmony Search with PBIL-guided pitch adjustment.  Instead of uniform-random
+perturbations during pitch adjustment, the PBIL probability matrix guides
+add/remove decisions based on learned probabilities.
+
+```python
+best = call_harmony_pbil(params, id_num=1)
+```
+
+### Bandit-guided SA (`call_banditsa` / `algorithm='banditsa'`)
+
+Uses Thompson Sampling over a multi-armed bandit of perturbation actions
+(add asvar, remove asvar, change distribution, ...).  Actions that
+historically led to accepted solutions are more likely to be chosen again.
+
+```python
+best = call_banditsa(params, id_num=1)
+```
+
+### Parallel SA variants
+
+```python
+best = call_parsa(params, nthrds=4)       # 4 independent SA solvers
+best = call_parcopsa(params, nthrds=8)    # 8 SA solvers sharing best periodically
+```
+
 ### Auto hyperparameter estimation
 
 If `ctrl` is omitted, the library estimates appropriate defaults from the
@@ -489,8 +551,6 @@ problem complexity (`n_vars × n_alts × n_models`, doubled for random params):
 from SearchLibrium import estimate_ctrl
 ctrl_sa = estimate_ctrl(params, algorithm='sa')
 ctrl_hs = estimate_ctrl(params, algorithm='hs')
-print('SA ctrl:', ctrl_sa)
-print('HS ctrl:', ctrl_hs)
 ```
 
 Complexity buckets:
@@ -504,6 +564,64 @@ Complexity buckets:
 
 
 
+---
+
+## Constraints
+
+Use `ConstraintBuilder` to enforce model structure rules during the search:
+
+```python
+from SearchLibrium import Parameters, ConstraintBuilder, call_siman
+
+constraints = ConstraintBuilder()
+
+# ── Inclusion / exclusion ──
+constraints.force_include('TIME', 'COST')      # must always appear
+constraints.never_include('ID', 'DUMMY')       # must never appear
+
+# ── Mutually exclusive groups ──
+# At most ONE variable from each group may appear in any solution.
+# The search will never add a partner if a group member is already
+# present, and will remove extras if they slip through.
+constraints.mutually_exclusive('SPEED', 'TIME')                  # speed OR time, never both
+constraints.mutually_exclusive('LOG_INCOME', 'INCOME_DUMMY')     # independent group
+
+# ── Minimum behavioural content ──
+# Require at least N variables from a pool without locking in which ones.
+constraints.min_behavioral(2, 'PRICE', 'BIKELANE', 'DIST6', 'RECRE')
+
+# ── Random-parameter rules ──
+constraints.force_random('TIME', distribution='n')    # must have random parameter
+constraints.exclude_random('HEADWAY')                 # must never be random
+
+# ── Attach constraints to the Parameters object ──
+params = Parameters(
+    criterions   = [("bic", -1)],
+    df           = df,
+    varnames     = varnames,
+    asvarnames   = varnames,
+    choice_set   = choice_set,
+    choices      = df["CHOICE"].values,
+    alt_var      = df["alt"].values,
+    choice_id    = df["custom_id"].values,
+    ind_id       = df["ID"].values,
+    base_alt     = "SM",
+    models       = ["multinomial", "mixed_logit"],
+    allow_random = True,
+    p_val        = 0.05,
+    pre_spec_constraints = constraints.dict(),   # ◄ attach here
+)
+
+best = call_siman(params, id_num=1)
+```
+
+The constraint enforcement happens at every stage:
+- **Solution generation** — filtered so violations are never created
+- **Perturbation / mutation** — blocked from adding violating variables
+- **Post-evaluation cleanup** — extra members are removed if somehow present
+
+---
+
 ## License
 
 MIT — see [LICENSE](LICENSE) for details.

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/README.md

@@ -4,8 +4,9 @@
 [![Python](https://img.shields.io/pypi/pyversions/SearchLibrium.svg)](https://pypi.org/project/SearchLibrium/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml/badge.svg)](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml)
+[![GitHub](https://img.shields.io/badge/GitHub-HypothesisX-lightgrey?logo=github)](https://github.com/zahern/HypothesisX)
 
-**Automated discrete choice model search powered by Simulated Annealing, Harmony Search, and JAX-accelerated MLE.**
+**Automated discrete choice model search powered by Simulated Annealing, Bandit-guided SA, Harmony Search, SA+PBIL, HS+PBIL, Parallel SA, and JAX-accelerated MLE.**
 
 SearchLibrium searches over model specifications — which variables to include, whether parameters should be random, which transformations to apply, and which model class to use — and returns the best converged, all-significant model according to your chosen criterion (BIC, AIC, log-likelihood, MAE, or multi-objective combinations).
 
@@ -85,16 +86,19 @@ A **run dashboard** is printed automatically at the end of every search, showing
 
 ## How the search works
 
-The search uses **Simulated Annealing (SA)** to explore the space of model specifications:
+The search uses **metaheuristic optimisation** (SA, BanditSA, Harmony Search,
+SA+PBIL, HS+PBIL, or parallel variants) to explore the space of model
+specifications:
 
 ```text
 generate starting solution
-  └─ for each SA temperature step
+  └─ for each iteration / temperature step / improvisation
        └─ perturb current specification → guaranteed distinct from current
             ├─ fit model with JAX-accelerated MLE
             ├─ run backward elimination (remove insignificant vars, refit)
-            ├─ accept if converged + Metropolis criterion satisfied
-            └─ update best solution
+            ├─ accept if converged + acceptance criterion satisfied
+            │    (Metropolis, dominance, or pitch adjustment)
+            └─ update best solution / harmony memory
 print dashboard
 ```
 
@@ -396,27 +400,42 @@ python -m SearchLibrium --test_search_nest  # run nested logit search
 
 ## Search algorithms
 
-Both algorithms share a **consistent interface** through `call_search`:
+All algorithms share a **consistent interface**.  The library auto-estimates
+hyperparameters from problem size when you omit `ctrl`:
 
 ```python
-from SearchLibrium import call_search, estimate_ctrl
-
-# Auto-estimate hyperparameters from problem size (recommended)
-best = call_search(params)                            # SA by default
-best = call_search(params, algorithm='hs')            # Harmony Search
-
-# Manual hyperparameters
-best = call_search(params, ctrl=(1000, 0.001, 100, 20))           # SA
-best = call_search(params, algorithm='hs',
-                   ctrl=(20, 500, 0.9, 0.6, 0.85, 0.3))          # HS
-
-# Inspect auto-estimated ctrl before running
+from SearchLibrium import (call_search, call_siman, call_harmony, call_sapbil,
+                            call_banditsa, call_harmony_pbil,
+                            call_parsa, call_parcopsa, estimate_ctrl)
+
+# Unified entry point — auto hyperparameters (recommended)
+best = call_search(params)                              # SA (default)
+best = call_search(params, algorithm='hs')              # Harmony Search
+best = call_search(params, algorithm='sapbil')          # SA + PBIL
+best = call_search(params, algorithm='banditsa')        # Bandit-guided SA
+best = call_search(params, algorithm='hspbil')          # HS + PBIL
+
+# Inspect auto-estimated hyperparameters before running
 ctrl = estimate_ctrl(params, algorithm='sa')
 print(ctrl)
 ```
 
+### Algorithm reference
+
+| Function | Description | Population-based | Key idea |
+| -------- | ----------- | :---: | -------- |
+| `call_siman` | Simulated Annealing | | Metropolis acceptance with temperature cooling |
+| `call_banditsa` | Bandit-guided SA | | Thompson Sampling to choose perturbation actions |
+| `call_sapbil` | SA + PBIL | ✓ | Probability matrix learns from accepted solutions to bias perturbations |
+| `call_harmony` | Harmony Search | ✓ | Memory-based improvisation with pitch adjustment |
+| `call_harmony_pbil` | HS + PBIL | ✓ | Harmony Search with PBIL-guided pitch perturbation |
+| `call_parsa` | Parallel SA | | Multiple independent SA solvers running in parallel |
+| `call_parcopsa` | Parallel Cooperative SA | ✓ | Parallel SA with periodic best-solution sharing |
+
 ### Simulated Annealing (`call_siman` / `algorithm='sa'`)
 
+Control tuple: `(tI, tF, max_temp_steps, max_iter)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `tI` | Initial temperature — higher → more exploration |
@@ -430,12 +449,14 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 
 ### Harmony Search (`call_harmony` / `algorithm='hs'`)
 
+Control tuple: `(max_mem, maxiter, max_harm, min_harm, max_pitch, min_pitch)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `max_mem` | Harmony memory size (population) |
 | `maxiter` | Improvisation iterations |
-| `max_harm` | Max harmony consideration rate |
-| `min_harm` | Min harmony consideration rate |
+| `max_harm` | Max harmony memory consideration rate |
+| `min_harm` | Min harmony memory consideration rate |
 | `max_pitch` | Max pitch adjustment rate |
 | `min_pitch` | Min pitch adjustment rate |
 
@@ -443,6 +464,44 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 best = call_harmony(params, ctrl=(20, 400, 0.9, 0.6, 0.85, 0.3), id_num=1)
 ```
 
+### SA + PBIL (`call_sapbil` / `algorithm='sapbil'`)
+
+Population-Based Incremental Learning coupled with Simulated Annealing.
+Maintains a probability matrix over the search decisions (inclusion,
+randomness, distribution, correlation, Box-Cox) and updates it from
+accepted solutions using a temperature-coupled learning rate.
+
+```python
+best = call_sapbil(params, id_num=1)
+```
+
+### HS + PBIL (`call_harmony_pbil` / `algorithm='hspbil'`)
+
+Harmony Search with PBIL-guided pitch adjustment.  Instead of uniform-random
+perturbations during pitch adjustment, the PBIL probability matrix guides
+add/remove decisions based on learned probabilities.
+
+```python
+best = call_harmony_pbil(params, id_num=1)
+```
+
+### Bandit-guided SA (`call_banditsa` / `algorithm='banditsa'`)
+
+Uses Thompson Sampling over a multi-armed bandit of perturbation actions
+(add asvar, remove asvar, change distribution, ...).  Actions that
+historically led to accepted solutions are more likely to be chosen again.
+
+```python
+best = call_banditsa(params, id_num=1)
+```
+
+### Parallel SA variants
+
+```python
+best = call_parsa(params, nthrds=4)       # 4 independent SA solvers
+best = call_parcopsa(params, nthrds=8)    # 8 SA solvers sharing best periodically
+```
+
 ### Auto hyperparameter estimation
 
 If `ctrl` is omitted, the library estimates appropriate defaults from the
@@ -452,8 +511,6 @@ problem complexity (`n_vars × n_alts × n_models`, doubled for random params):
 from SearchLibrium import estimate_ctrl
 ctrl_sa = estimate_ctrl(params, algorithm='sa')
 ctrl_hs = estimate_ctrl(params, algorithm='hs')
-print('SA ctrl:', ctrl_sa)
-print('HS ctrl:', ctrl_hs)
 ```
 
 Complexity buckets:
@@ -467,6 +524,64 @@ Complexity buckets:
 
 
 
+---
+
+## Constraints
+
+Use `ConstraintBuilder` to enforce model structure rules during the search:
+
+```python
+from SearchLibrium import Parameters, ConstraintBuilder, call_siman
+
+constraints = ConstraintBuilder()
+
+# ── Inclusion / exclusion ──
+constraints.force_include('TIME', 'COST')      # must always appear
+constraints.never_include('ID', 'DUMMY')       # must never appear
+
+# ── Mutually exclusive groups ──
+# At most ONE variable from each group may appear in any solution.
+# The search will never add a partner if a group member is already
+# present, and will remove extras if they slip through.
+constraints.mutually_exclusive('SPEED', 'TIME')                  # speed OR time, never both
+constraints.mutually_exclusive('LOG_INCOME', 'INCOME_DUMMY')     # independent group
+
+# ── Minimum behavioural content ──
+# Require at least N variables from a pool without locking in which ones.
+constraints.min_behavioral(2, 'PRICE', 'BIKELANE', 'DIST6', 'RECRE')
+
+# ── Random-parameter rules ──
+constraints.force_random('TIME', distribution='n')    # must have random parameter
+constraints.exclude_random('HEADWAY')                 # must never be random
+
+# ── Attach constraints to the Parameters object ──
+params = Parameters(
+    criterions   = [("bic", -1)],
+    df           = df,
+    varnames     = varnames,
+    asvarnames   = varnames,
+    choice_set   = choice_set,
+    choices      = df["CHOICE"].values,
+    alt_var      = df["alt"].values,
+    choice_id    = df["custom_id"].values,
+    ind_id       = df["ID"].values,
+    base_alt     = "SM",
+    models       = ["multinomial", "mixed_logit"],
+    allow_random = True,
+    p_val        = 0.05,
+    pre_spec_constraints = constraints.dict(),   # ◄ attach here
+)
+
+best = call_siman(params, id_num=1)
+```
+
+The constraint enforcement happens at every stage:
+- **Solution generation** — filtered so violations are never created
+- **Perturbation / mutation** — blocked from adding violating variables
+- **Post-evaluation cleanup** — extra members are removed if somehow present
+
+---
+
 ## License
 
 MIT — see [LICENSE](LICENSE) for details.

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/pyproject.toml

@@ -65,12 +65,15 @@ dev = [
 
 [project.urls]
 Homepage = "https://pypi.org/project/SearchLibrium/"
+Repository = "https://github.com/zahern/HypothesisX"
+Issues = "https://github.com/zahern/HypothesisX/issues"
+Documentation = "https://pypi.org/project/SearchLibrium/"
 
 [project.scripts]
 realpython = "SearchLibrium.__main__:main"
 
 [tool.bumpver]
-current_version = "0.0.126"
+current_version = "0.0.128"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
 commit = true

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/src/SearchLibrium/__init__.py

@@ -113,7 +113,7 @@ try:
     from . import misc
     from .sapbil import SAPBIL, ProbabilityMatrix
     from .hspbil import HSPBIL
-    from .call_meta import call_harmony, call_harmony_pbil, call_siman, call_parsa, call_search, call_sapbil, estimate_ctrl
+    from .call_meta import call_harmony, call_harmony_pbil, call_siman, call_parsa, call_search, call_sapbil, call_banditsa, call_parcopsa, estimate_ctrl
     from .predict import DestinationPredictor, predict_destination_components, predict_aggregate_destination_flows
 
 except ImportError as e:
@@ -135,7 +135,7 @@ except ImportError as e:
     from search import Parameters
     from sapbil import SAPBIL, ProbabilityMatrix
     from hspbil import HSPBIL
-    from call_meta import call_siman, call_harmony, call_harmony_pbil, call_search, call_sapbil, estimate_ctrl
+    from call_meta import call_siman, call_harmony, call_harmony_pbil, call_search, call_sapbil, call_banditsa, call_parsa, call_parcopsa, estimate_ctrl
     from predict import DestinationPredictor, predict_destination_components, predict_aggregate_destination_flows
 try:
     from .main import print_ascii_art_logo

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/src/SearchLibrium/constraints_builder.py

@@ -104,6 +104,37 @@ class ConstraintBuilder:
         self._print(f"Never include: {variables}")
         return self
     
+    def mutually_exclusive(self, *variables: str) -> 'ConstraintBuilder':
+        """
+        Declare that at most one variable from this group may be included
+        in any model specification.  The search will never add a variable
+        from the group if another member of the group is already present,
+        and will remove extra members if they slip in.
+
+        You may call this method multiple times to define several
+        independent groups.  Each call creates a separate exclusion set.
+
+        Parameters
+        ----------
+        *variables : str
+            Variable names forming a mutually exclusive group
+
+        Returns
+        -------
+        ConstraintBuilder
+            Self for method chaining
+
+        Example
+        -------
+        >>> constraints.mutually_exclusive('SPEED', 'TIME')
+        >>> constraints.mutually_exclusive('LOG_INCOME', 'INCOME_DUMMY')
+        """
+        if 'mutually_exclusive' not in self._constraints:
+            self._constraints['mutually_exclusive'] = []
+        self._constraints['mutually_exclusive'].append(list(variables))
+        self._print(f"Mutually exclusive group: {variables}")
+        return self
+
     def min_behavioral(self, min_count: int, *variables: str) -> 'ConstraintBuilder':
         """
         Require at least ``min_count`` variables from a behavioural pool

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/src/SearchLibrium/search.py

@@ -1718,6 +1718,7 @@ class Search():
         asvars = [self.param.avail_asvars[i] for i in asvar_select_pos]
         asvars.extend(self.param.ps_asvars)
         asvars = self.remove_redundant_asvars(asvars, self.param.trans_asvars, self.param.asvarnames)
+        asvars = self._apply_mutual_exclusion_filter(asvars)
         return asvars
     # }
 
@@ -1731,7 +1732,7 @@ class Search():
         isvar_select_pos = [i for i, x in enumerate(ind_availisvar) if x == 1]
         isvars = [self.param.avail_isvars[i] for i in isvar_select_pos]
         isvars.extend(self.param.ps_isvars)
-        #asvars = self.remove_redundant_asvars(asvars, self.param.trans_isvars, self.param.avarnames)
+        isvars = self._apply_mutual_exclusion_filter(isvars)
         return isvars
     # }
 
@@ -2025,9 +2026,12 @@ class Search():
             if 'randvars' in solution:
                 solution['randvars'] = {k: v for k, v in solution['randvars'].items() if k not in never_rand}
         
+        # ── Mutual-exclusion constraint ──
+        self._enforce_mutual_exclusion(solution)
+
         # ── Min-behavioural constraint (soft: at least n from a pool) ──
         self._enforce_min_behavioral(solution)
-        
+
         return solution
     
     def _get_forced_vars(self):
@@ -2087,6 +2091,75 @@ class Search():
                 protected.update(current)
         return protected
 
+    def _apply_mutual_exclusion_filter(self, varlist):
+        """Given a list of variables, keep at most one per mutual-exclusion group.
+
+        For each group the first variable encountered is kept; subsequent
+        members are dropped.
+        """
+        groups = self._get_mutual_exclusion_groups()
+        if not groups:
+            return varlist
+        blocked = set()
+        for group in groups:
+            seen_first = False
+            for v in varlist:
+                if v in group:
+                    if seen_first:
+                        blocked.add(v)
+                    else:
+                        seen_first = True
+        return [v for v in varlist if v not in blocked]
+
+    def _get_mutual_exclusion_groups(self):
+        """Return the list of mutually-exclusive variable groups, or [].
+
+        Each group is a list[str]; at most one member of each group may
+        appear in a solution.
+        """
+        if not hasattr(self, 'pres_spec_constr') or self.pres_spec_constr is None:
+            return []
+        return self.pres_spec_constr.get('mutually_exclusive', [])
+
+    def _get_excluded_by_mutual_group(self, already_present: set):
+        """Return the set of variables that are blocked because a partner
+        from the same mutually-exclusive group is *already_present*.
+        """
+        excluded = set()
+        for group in self._get_mutual_exclusion_groups():
+            gset = set(group)
+            if gset & already_present:
+                excluded.update(gset)
+        return excluded
+
+    def _enforce_mutual_exclusion(self, solution):
+        """Ensure at most one variable per mutually-exclusive group is present.
+
+        If more than one is found, keep the first (arbitrary) and
+        remove the rest from asvars, isvars, and class/member specs.
+        """
+        groups = self._get_mutual_exclusion_groups()
+        if not groups:
+            return
+        all_v = self._all_vars_in_solution(solution)
+        for group in groups:
+            present = [v for v in group if v in all_v]
+            if len(present) <= 1:
+                continue
+            keep = set(present[:1])
+            remove = set(present[1:])
+            for v in remove:
+                if 'asvars' in solution and v in solution['asvars']:
+                    solution['asvars'] = [x for x in solution['asvars'] if x != v]
+                if 'isvars' in solution and v in solution['isvars']:
+                    solution['isvars'] = [x for x in solution['isvars'] if x != v]
+                if 'randvars' in solution and v in solution['randvars']:
+                    del solution['randvars'][v]
+                if 'bcvars' in solution and v in solution['bcvars']:
+                    solution['bcvars'] = [x for x in solution['bcvars'] if x != v]
+                if 'corvars' in solution and v in solution['corvars']:
+                    solution['corvars'] = [x for x in solution['corvars'] if x != v]
+
     def _apply_latent_class_constraints(self, solution, lc_constraints):
         """Apply constraints specific to latent class models."""
         # Example: force variables to appear only in certain classes
@@ -2415,6 +2488,8 @@ class Search():
     def perturb_add_asfeature(self, solution):
     # {
         candidate = [var for var in self.param.asvarnames if var not in solution['asvars']]
+        blocked = self._get_excluded_by_mutual_group(set(solution.get('asvars', [])) | set(solution.get('isvars', [])))
+        candidate = [v for v in candidate if v not in blocked]
         if len(candidate) > 0:
             new_asvar = self.random_choice(candidate)
             solution = self.add_asvar(new_asvar, solution)
@@ -2488,6 +2563,8 @@ class Search():
     def perturb_add_isfeature(self, solution):
     # {
         candidate = [var for var in self.param.isvarnames if var not in solution['isvars']]
+        blocked = self._get_excluded_by_mutual_group(set(solution.get('asvars', [])) | set(solution.get('isvars', [])))
+        candidate = [v for v in candidate if v not in blocked]
         if len(candidate) > 0:
         # {
             add_isvar = self.random_choice(candidate)

searchlibrium-0.0.128/src/SearchLibrium/version.txt

@@ -0,0 +1 @@
+0.0.128

{searchlibrium-0.0.126 → searchlibrium-0.0.128}/src/SearchLibrium.egg-info/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: SearchLibrium
-Version: 0.0.126
+Version: 0.0.128
 Summary: A Python package for econometric models driven by search
 Author: Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
 Author-email: Zeke Ahern <z.ahern@qut.edu.au>
 Project-URL: Homepage, https://pypi.org/project/SearchLibrium/
+Project-URL: Repository, https://github.com/zahern/HypothesisX
+Project-URL: Issues, https://github.com/zahern/HypothesisX/issues
+Project-URL: Documentation, https://pypi.org/project/SearchLibrium/
 Keywords: econometric models,search,discrete choice,logit,probit
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -41,8 +44,9 @@ Requires-Dist: pytest; extra == "dev"
 [![Python](https://img.shields.io/pypi/pyversions/SearchLibrium.svg)](https://pypi.org/project/SearchLibrium/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml/badge.svg)](https://github.com/zahern/HypothesisX/actions/workflows/ci.yml)
+[![GitHub](https://img.shields.io/badge/GitHub-HypothesisX-lightgrey?logo=github)](https://github.com/zahern/HypothesisX)
 
-**Automated discrete choice model search powered by Simulated Annealing, Harmony Search, and JAX-accelerated MLE.**
+**Automated discrete choice model search powered by Simulated Annealing, Bandit-guided SA, Harmony Search, SA+PBIL, HS+PBIL, Parallel SA, and JAX-accelerated MLE.**
 
 SearchLibrium searches over model specifications — which variables to include, whether parameters should be random, which transformations to apply, and which model class to use — and returns the best converged, all-significant model according to your chosen criterion (BIC, AIC, log-likelihood, MAE, or multi-objective combinations).
 
@@ -122,16 +126,19 @@ A **run dashboard** is printed automatically at the end of every search, showing
 
 ## How the search works
 
-The search uses **Simulated Annealing (SA)** to explore the space of model specifications:
+The search uses **metaheuristic optimisation** (SA, BanditSA, Harmony Search,
+SA+PBIL, HS+PBIL, or parallel variants) to explore the space of model
+specifications:
 
 ```text
 generate starting solution
-  └─ for each SA temperature step
+  └─ for each iteration / temperature step / improvisation
        └─ perturb current specification → guaranteed distinct from current
             ├─ fit model with JAX-accelerated MLE
             ├─ run backward elimination (remove insignificant vars, refit)
-            ├─ accept if converged + Metropolis criterion satisfied
-            └─ update best solution
+            ├─ accept if converged + acceptance criterion satisfied
+            │    (Metropolis, dominance, or pitch adjustment)
+            └─ update best solution / harmony memory
 print dashboard
 ```
 
@@ -433,27 +440,42 @@ python -m SearchLibrium --test_search_nest  # run nested logit search
 
 ## Search algorithms
 
-Both algorithms share a **consistent interface** through `call_search`:
+All algorithms share a **consistent interface**.  The library auto-estimates
+hyperparameters from problem size when you omit `ctrl`:
 
 ```python
-from SearchLibrium import call_search, estimate_ctrl
-
-# Auto-estimate hyperparameters from problem size (recommended)
-best = call_search(params)                            # SA by default
-best = call_search(params, algorithm='hs')            # Harmony Search
-
-# Manual hyperparameters
-best = call_search(params, ctrl=(1000, 0.001, 100, 20))           # SA
-best = call_search(params, algorithm='hs',
-                   ctrl=(20, 500, 0.9, 0.6, 0.85, 0.3))          # HS
-
-# Inspect auto-estimated ctrl before running
+from SearchLibrium import (call_search, call_siman, call_harmony, call_sapbil,
+                            call_banditsa, call_harmony_pbil,
+                            call_parsa, call_parcopsa, estimate_ctrl)
+
+# Unified entry point — auto hyperparameters (recommended)
+best = call_search(params)                              # SA (default)
+best = call_search(params, algorithm='hs')              # Harmony Search
+best = call_search(params, algorithm='sapbil')          # SA + PBIL
+best = call_search(params, algorithm='banditsa')        # Bandit-guided SA
+best = call_search(params, algorithm='hspbil')          # HS + PBIL
+
+# Inspect auto-estimated hyperparameters before running
 ctrl = estimate_ctrl(params, algorithm='sa')
 print(ctrl)
 ```
 
+### Algorithm reference
+
+| Function | Description | Population-based | Key idea |
+| -------- | ----------- | :---: | -------- |
+| `call_siman` | Simulated Annealing | | Metropolis acceptance with temperature cooling |
+| `call_banditsa` | Bandit-guided SA | | Thompson Sampling to choose perturbation actions |
+| `call_sapbil` | SA + PBIL | ✓ | Probability matrix learns from accepted solutions to bias perturbations |
+| `call_harmony` | Harmony Search | ✓ | Memory-based improvisation with pitch adjustment |
+| `call_harmony_pbil` | HS + PBIL | ✓ | Harmony Search with PBIL-guided pitch perturbation |
+| `call_parsa` | Parallel SA | | Multiple independent SA solvers running in parallel |
+| `call_parcopsa` | Parallel Cooperative SA | ✓ | Parallel SA with periodic best-solution sharing |
+
 ### Simulated Annealing (`call_siman` / `algorithm='sa'`)
 
+Control tuple: `(tI, tF, max_temp_steps, max_iter)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `tI` | Initial temperature — higher → more exploration |
@@ -467,12 +489,14 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 
 ### Harmony Search (`call_harmony` / `algorithm='hs'`)
 
+Control tuple: `(max_mem, maxiter, max_harm, min_harm, max_pitch, min_pitch)`
+
 | Parameter | Meaning |
 | --------- | ------- |
 | `max_mem` | Harmony memory size (population) |
 | `maxiter` | Improvisation iterations |
-| `max_harm` | Max harmony consideration rate |
-| `min_harm` | Min harmony consideration rate |
+| `max_harm` | Max harmony memory consideration rate |
+| `min_harm` | Min harmony memory consideration rate |
 | `max_pitch` | Max pitch adjustment rate |
 | `min_pitch` | Min pitch adjustment rate |
 
@@ -480,6 +504,44 @@ best = call_siman(params, ctrl=(1000, 0.001, 100, 20), id_num=1)
 best = call_harmony(params, ctrl=(20, 400, 0.9, 0.6, 0.85, 0.3), id_num=1)
 ```
 
+### SA + PBIL (`call_sapbil` / `algorithm='sapbil'`)
+
+Population-Based Incremental Learning coupled with Simulated Annealing.
+Maintains a probability matrix over the search decisions (inclusion,
+randomness, distribution, correlation, Box-Cox) and updates it from
+accepted solutions using a temperature-coupled learning rate.
+
+```python
+best = call_sapbil(params, id_num=1)
+```
+
+### HS + PBIL (`call_harmony_pbil` / `algorithm='hspbil'`)
+
+Harmony Search with PBIL-guided pitch adjustment.  Instead of uniform-random
+perturbations during pitch adjustment, the PBIL probability matrix guides
+add/remove decisions based on learned probabilities.
+
+```python
+best = call_harmony_pbil(params, id_num=1)
+```
+
+### Bandit-guided SA (`call_banditsa` / `algorithm='banditsa'`)
+
+Uses Thompson Sampling over a multi-armed bandit of perturbation actions
+(add asvar, remove asvar, change distribution, ...).  Actions that
+historically led to accepted solutions are more likely to be chosen again.
+
+```python
+best = call_banditsa(params, id_num=1)
+```
+
+### Parallel SA variants
+
+```python
+best = call_parsa(params, nthrds=4)       # 4 independent SA solvers
+best = call_parcopsa(params, nthrds=8)    # 8 SA solvers sharing best periodically
+```
+
 ### Auto hyperparameter estimation
 
 If `ctrl` is omitted, the library estimates appropriate defaults from the
@@ -489,8 +551,6 @@ problem complexity (`n_vars × n_alts × n_models`, doubled for random params):
 from SearchLibrium import estimate_ctrl
 ctrl_sa = estimate_ctrl(params, algorithm='sa')
 ctrl_hs = estimate_ctrl(params, algorithm='hs')
-print('SA ctrl:', ctrl_sa)
-print('HS ctrl:', ctrl_hs)
 ```
 
 Complexity buckets:
@@ -504,6 +564,64 @@ Complexity buckets:
 
 
 
+---
+
+## Constraints
+
+Use `ConstraintBuilder` to enforce model structure rules during the search:
+
+```python
+from SearchLibrium import Parameters, ConstraintBuilder, call_siman
+
+constraints = ConstraintBuilder()
+
+# ── Inclusion / exclusion ──
+constraints.force_include('TIME', 'COST')      # must always appear
+constraints.never_include('ID', 'DUMMY')       # must never appear
+
+# ── Mutually exclusive groups ──
+# At most ONE variable from each group may appear in any solution.
+# The search will never add a partner if a group member is already
+# present, and will remove extras if they slip through.
+constraints.mutually_exclusive('SPEED', 'TIME')                  # speed OR time, never both
+constraints.mutually_exclusive('LOG_INCOME', 'INCOME_DUMMY')     # independent group
+
+# ── Minimum behavioural content ──
+# Require at least N variables from a pool without locking in which ones.
+constraints.min_behavioral(2, 'PRICE', 'BIKELANE', 'DIST6', 'RECRE')
+
+# ── Random-parameter rules ──
+constraints.force_random('TIME', distribution='n')    # must have random parameter
+constraints.exclude_random('HEADWAY')                 # must never be random
+
+# ── Attach constraints to the Parameters object ──
+params = Parameters(
+    criterions   = [("bic", -1)],
+    df           = df,
+    varnames     = varnames,
+    asvarnames   = varnames,
+    choice_set   = choice_set,
+    choices      = df["CHOICE"].values,
+    alt_var      = df["alt"].values,
+    choice_id    = df["custom_id"].values,
+    ind_id       = df["ID"].values,
+    base_alt     = "SM",
+    models       = ["multinomial", "mixed_logit"],
+    allow_random = True,
+    p_val        = 0.05,
+    pre_spec_constraints = constraints.dict(),   # ◄ attach here
+)
+
+best = call_siman(params, id_num=1)
+```
+
+The constraint enforcement happens at every stage:
+- **Solution generation** — filtered so violations are never created
+- **Perturbation / mutation** — blocked from adding violating variables
+- **Post-evaluation cleanup** — extra members are removed if somehow present
+
+---
+
 ## License
 
 MIT — see [LICENSE](LICENSE) for details.

searchlibrium-0.0.126/src/SearchLibrium/version.txt

@@ -1 +0,0 @@
-0.0.126