SearchLibrium 0.0.199__tar.gz → 0.0.201__tar.gz

{searchlibrium-0.0.199/src/SearchLibrium.egg-info → searchlibrium-0.0.201}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SearchLibrium
-Version: 0.0.199
+Version: 0.0.201
 Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
 Author: Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
 Author-email: Zeke Ahern <z.ahern@qut.edu.au>

{searchlibrium-0.0.199 → searchlibrium-0.0.201}/pyproject.toml

@@ -100,7 +100,7 @@ Documentation = "https://pypi.org/project/SearchLibrium/"
 realpython = "SearchLibrium.__main__:main"
 
 [tool.bumpver]
-current_version = "0.0.199"
+current_version = "0.0.201"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
 commit = true

{searchlibrium-0.0.199 → searchlibrium-0.0.201}/src/SearchLibrium/call_meta.py

@@ -95,6 +95,8 @@ def estimate_ctrl(parameters, algorithm='sa', thorough=False, deep=False):
     tuple
         SA  : (tI, tF, max_temp_steps, max_iter)
         HS  : (max_mem, maxiter, max_harm, min_harm, max_pitch, min_pitch)
+        AGDS: (pop_size, maxiter, pc0, pm0)
+        TA  : (max_threshold, max_steps, max_iter)
     """
     ps = _problem_size(parameters)
     c  = ps['complexity']
@@ -132,13 +134,13 @@ def estimate_ctrl(parameters, algorithm='sa', thorough=False, deep=False):
     elif algorithm == 'hs':
         # Harmony memory size and improvisation iterations scale with complexity
         if c < 50:
-            max_mem, maxiter  = max(10,  10 * scale),  max(100,  100 * scale)
+            max_mem, maxiter  = max(20,  20 * scale),  max(100,  100 * scale)
         elif c < 200:
-            max_mem, maxiter  = max(15,  15 * scale),  max(300,  300 * scale)
+            max_mem, maxiter  = max(25,  25 * scale),  max(300,  300 * scale)
         elif c < 600:
-            max_mem, maxiter  = max(20,  20 * scale),  max(500,  500 * scale)
+            max_mem, maxiter  = max(30,  30 * scale),  max(500,  500 * scale)
         else:
-            max_mem, maxiter  = max(25,  25 * scale),  max(800,  800 * scale)
+            max_mem, maxiter  = max(40,  40 * scale),  max(800,  800 * scale)
 
         # Harmony/pitch rates adapt: wider exploration band for bigger problems
         if deep or thorough:
@@ -164,8 +166,34 @@ def estimate_ctrl(parameters, algorithm='sa', thorough=False, deep=False):
         pc0 = 0.9
         ctrl = (pop_size, maxiter, pc0, None)
 
+    elif algorithm == 'ta':
+        # Threshold Accepting: threshold decreases linearly from max_threshold to 0
+        # over max_steps, with max_iter evaluations per step
+        if c < 50:
+            max_threshold = max(500,  500 * scale)
+            max_steps     = max(50,   50 * scale)
+            max_iter      = max(30,   30 * scale)
+        elif c < 200:
+            max_threshold = max(1000, 1000 * scale)
+            max_steps     = max(100,  100 * scale)
+            max_iter      = max(50,   50 * scale)
+        elif c < 600:
+            max_threshold = max(2000, 2000 * scale)
+            max_steps     = max(150,  150 * scale)
+            max_iter      = max(80,   80 * scale)
+        else:
+            max_threshold = max(5000, 5000 * scale)
+            max_steps     = max(200,  200 * scale)
+            max_iter      = max(100,  100 * scale)
+
+        if deep:
+            max_threshold = max(max_threshold, 10000)
+            max_steps = max(max_steps, 300)
+
+        ctrl = (max_threshold, max_steps, max_iter)
+
     else:
-        raise ValueError(f"Unknown algorithm '{algorithm}'. Use 'sa', 'hs' or 'agds'.")
+        raise ValueError(f"Unknown algorithm '{algorithm}'. Use 'sa', 'hs', 'agds', or 'ta'.")
 
     return ctrl
 
@@ -180,6 +208,13 @@ def _describe_ctrl(ctrl, algorithm):
             'number of cooling steps',
             'evaluations per cooling step',
         )
+    elif algorithm == 'ta':
+        names = ('max_threshold', 'max_steps', 'max_iter')
+        hints = (
+            'initial threshold  — higher = more exploration',
+            'number of threshold reduction steps',
+            'evaluations per threshold step',
+        )
     elif algorithm == 'agds':
         names = ('pop_size', 'maxiter', 'pc0', 'pm0')
         hints = (
@@ -326,6 +361,9 @@ def call_siman(parameters, init_sol=None, ctrl=None, thorough=False, deep=False,
         Maximum search depth for production runs.
     **kwargs
         ``id_num``  — run identifier (int, used in log file names).
+        ``max_time`` — maximum wall-clock time in seconds (default: inf).
+        ``max_total_iter`` — maximum total temperature steps (default: 100000).
+        ``calibrate_tI`` — whether to auto-calibrate initial temperature (default: True if ctrl not provided).
         Any other kwargs are forwarded to the SA constructor.
 
     Returns
@@ -383,6 +421,11 @@ def call_sapbil(parameters, init_sol=None, ctrl=None, **kwargs):
         If omitted the values are estimated from the problem size.
     **kwargs
         ``id_num`` — run identifier (int, used in log file names).
+        ``pbil_l_bounds`` — dict of learning rate bounds per decision type
+            (default: thesis-based values from Taco-Morales 2026).
+            Example: {"inclusion": (0.02, 0.25), "random": (0.02, 0.15), ...}
+        ``pbil_p_low`` — minimum probability clamp (default: 0.05).
+        ``pbil_p_high`` — maximum probability clamp (default: 0.95).
         Any other kwargs are forwarded to the SAPBIL constructor.
 
     Returns
@@ -430,6 +473,9 @@ def call_banditsa(parameters, init_sol=None, ctrl=None, **kwargs):
         If omitted the values are estimated from the problem size.
     **kwargs
         ``id_num``  - run identifier (int, used in log file names).
+        ``bandit_prior_alpha`` — Thompson sampling prior alpha (default: 1.0).
+        ``bandit_prior_beta`` — Thompson sampling prior beta (default: 1.0).
+        ``bandit_epsilon`` — epsilon for epsilon-greedy exploration (default: 0.05).
         Any other kwargs are forwarded to the BanditSA constructor.
 
     Returns
@@ -485,6 +531,10 @@ def call_harmony(parameters, init_sol=None, ctrl=None, thorough=False, deep=Fals
         Overrides thorough. Default False.
     **kwargs
         ``id_num`` — run identifier.
+        ``prop_local`` — proportion of iterations before local search (default: 0.8).
+        ``threshold`` — convergence threshold (default: 15).
+        ``generate_plots`` — whether to generate convergence plots (default: False).
+        Any other kwargs are forwarded to the HarmonySearch constructor via set_control_parameters.
 
     Returns
     -------
@@ -509,6 +559,9 @@ def call_harmony(parameters, init_sol=None, ctrl=None, thorough=False, deep=Fals
     print()
 
     solver = HarmonySearch(parameters, ctrl=ctrl, idnum=id_num)
+    # Forward remaining kwargs to set_control_parameters
+    if kwargs:
+        solver.set_control_parameters(**kwargs)
     existing = [init_sol] if init_sol is not None else None
     solver.run_search(existing_sols=existing)
     solver.close_files()
@@ -539,6 +592,9 @@ def call_agds(parameters, init_sol=None, ctrl=None, thorough=False, deep=False,
         Scale up population / generations for a more thorough search.
     **kwargs
         ``id_num`` — run identifier.
+        ``ref_divisions`` — NSGA-III reference point divisions (default: 12).
+        ``generate_plots`` — whether to generate convergence plots (default: False).
+        Any other kwargs are forwarded to the SparseEAAGDS constructor via set_control_parameters.
 
     Returns
     -------
@@ -563,6 +619,9 @@ def call_agds(parameters, init_sol=None, ctrl=None, thorough=False, deep=False,
     print()
 
     solver = SparseEAAGDS(parameters, ctrl=ctrl, idnum=id_num)
+    # Forward remaining kwargs to set_control_parameters
+    if kwargs:
+        solver.set_control_parameters(**kwargs)
     existing = [init_sol] if init_sol is not None else None
     solver.run_search(existing_sols=existing)
     solver.close_files()
@@ -589,6 +648,14 @@ def call_harmony_pbil(parameters, init_sol=None, ctrl=None, **kwargs):
         If omitted the values are estimated from the problem size.
     **kwargs
         ``id_num`` — run identifier.
+        ``pbil_l_bounds`` — dict of learning rate bounds per decision type
+            (default: thesis-based values from Taco-Morales 2026).
+        ``pbil_p_low`` — minimum probability clamp (default: 0.05).
+        ``pbil_p_high`` — maximum probability clamp (default: 0.95).
+        ``prop_local`` — proportion of iterations before local search (default: 0.8).
+        ``threshold`` — convergence threshold (default: 15).
+        ``generate_plots`` — whether to generate convergence plots (default: False).
+        Any other kwargs are forwarded to the HSPBIL constructor.
 
     Returns
     -------
@@ -610,7 +677,7 @@ def call_harmony_pbil(parameters, init_sol=None, ctrl=None, **kwargs):
     print(_describe_ctrl(ctrl, 'hs'))
     print()
 
-    solver = HSPBIL(parameters, init_sol, ctrl, idnum=id_num)
+    solver = HSPBIL(parameters, init_sol, ctrl, idnum=id_num, **kwargs)
     existing = [init_sol] if init_sol is not None else None
     solver.run_search(existing_sols=existing)
     solver.close_files()
@@ -659,6 +726,7 @@ def call_search(parameters, init_sol=None, algorithm='sa', ctrl=None, thorough=F
     >>> best = call_search(params)                        # SA, auto ctrl
     >>> best = call_search(params, algorithm='banditsa')  # BanditSA, auto ctrl
     >>> best = call_search(params, algorithm='hs')        # HS, auto ctrl
+    >>> best = call_search(params, algorithm='ta')        # TA, auto ctrl
     >>> best = call_search(params, thorough=True)         # Thorough SA
     >>> best = call_search(params, algorithm='hs', deep=True)  # Deep HS
     >>> best = call_search(params, ctrl=(500,0.001,80,15))# SA, manual ctrl
@@ -678,13 +746,63 @@ def call_search(parameters, init_sol=None, algorithm='sa', ctrl=None, thorough=F
                             thorough=thorough, deep=deep, **kwargs)
     elif algorithm in ('hspbil', 'harmony_pbil', 'hs_pbil', 'hs+pbil'):
         return call_harmony_pbil(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
+    elif algorithm in ('ta', 'threshold', 'threshold_accepting'):
+        return call_threshold(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
     else:
         raise ValueError(
             f"Unknown algorithm '{algorithm}'. "
-            f"Choose 'sa', 'sapbil', 'banditsa', 'hs', or 'hspbil'."
+            f"Choose 'sa', 'sapbil', 'banditsa', 'hs', 'hspbil', or 'ta'."
         )
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Threshold Accepting
+# ─────────────────────────────────────────────────────────────────────────────
+
+def call_threshold(parameters, init_sol=None, ctrl=None, **kwargs):
+    """
+    Run Threshold Accepting search.
+
+    Parameters
+    ----------
+    parameters : Parameters
+        Problem definition.
+    init_sol : Solution, optional
+        Warm-start solution.
+    ctrl : tuple, optional
+        ``(max_threshold, max_steps, max_iter)``. If omitted the values are estimated
+        from the problem size.
+    **kwargs
+        ``id_num`` — run identifier.
+
+    Returns
+    -------
+    Solution
+        Best solution found.
+    """
+    if ctrl is None:
+        ctrl = kwargs.pop('ctrl', None)
+
+    id_num = kwargs.pop('id_num', None)
+
+    if ctrl is None:
+        ctrl = estimate_ctrl(parameters, algorithm='ta')
+        print(f"[TA] Auto-estimated hyperparameters (problem complexity "
+              f"= {_problem_size(parameters)['complexity']}):")
+    else:
+        print("[TA] Using provided hyperparameters:")
+
+    print(_describe_ctrl(ctrl, 'ta'))
+    print()
+
+    solver = TA(parameters, init_sol, ctrl, id_num, **kwargs)
+    solver.run()
+    solver.close_files()
+    best = solver.return_best()
+    _print_dashboard(solver, best, algorithm='TA')
+    return best
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Parallel SA variants (unchanged interface, improved ctrl handling)
 # ─────────────────────────────────────────────────────────────────────────────

{searchlibrium-0.0.199 → searchlibrium-0.0.201}/src/SearchLibrium/harmony.py

@@ -255,106 +255,96 @@ class HarmonySearch(Search):
     ''' A new solution, could either be built from an existing one '''
     ''' or constructed randomly.                                   '''
     ''' ---------------------------------------------------------- '''
-    def build_solution(self, memory, prop):
+    def build_solution(self, memory, harm_rate):
     # {
-        """ This function decides whether to build a new solution from an existing solution
-        in the harmony memory or to generate a completely new solution, based on a random number and the
-        Harmony Memory Consideration Rate (HMCR). If the random number is less than or equal to prop,
-        it selects a proportion of the features from a randomly chosen existing solution to build the new solution.
-        Otherwise, it generates a completely new solution """
-
-
-        bin = [0,1] # Binary values
-        prob = [1-prop, prop]  # Range
-        new_sol = Solution(nb_crit=self.nb_crit)    # Create a new solution object
-
-        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-        # IS THIS NECESSARY?
-        '''fronts, pareto = None, None
-        if nb_crit > 1: # {
-            memory = self.non_dominant_sorting(memory)
-            fronts = self.get_fronts(memory)
-            pareto = self.get_pareto(fronts, memory)
-        # }'''
-        # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-        if self.param.generator.rand() > prop:
-            new_sol = self.generate_solution()  # Generate a new solution
-        else:
-        # {
-            choice = self.param.generator.choice(len(memory)) # Choose one of the member solutions
-            chosen_sol = memory[choice] # Define reference to the chosen member solution
-
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            # OPTIONAL CODE.
-            # size = len(chosen_sol['asvars'])
-            # new_asvars_index = self.param.generator.choice(bin, size=size, p=prob)
-            # new_asvars = [i for (i, v) in zip(chosen_sol['asvars'], new_asvars_index) if v]
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-            # Randomly select a subset of the variables from the chosen solution
-            size = int((len(chosen_sol['asvars'])) * prop)
-            new_asvars = list(self.param.generator.choice(chosen_sol['asvars'], size=size, replace=False))
-            n_asvars = sorted(list(set().union(new_asvars, self.param.ps_asvars)))
-            new_asvars = self.remove_redundant_asvars(n_asvars, self.param.trans_asvars, self.param.asvarnames)
-            new_asvars = self.remove_collinear_vars(new_asvars)
-            new_asvars = self._apply_mutual_exclusion_filter(new_asvars)
-            new_sol['asvars'] = new_asvars
-
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            # Randomly select a subset of the variables from the chosen solution
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            size = int((len(chosen_sol['isvars'])) * prop)
-            new_isvars = list(self.param.generator.choice(chosen_sol['isvars'], size=size, replace=False))
-            new_isvars = sorted(list(set().union(new_isvars, self.param.ps_isvars)))
-            new_isvars = self.remove_collinear_vars(new_isvars)
-            new_isvars = self._apply_mutual_exclusion_filter(new_isvars)
-            new_sol['isvars'] = new_isvars
-
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            # Include variables in new solution based on the chosen solution
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-            new_randvars = {k: v for k, v in chosen_sol['randvars'].items() if k in new_asvars}
+        """ Build a new solution using Harmony Memory Consideration.
+
+        For each candidate variable, with probability harm_rate (HMCR), copy
+        the value from a randomly selected harmony in memory; otherwise
+        generate a random value. This is the standard HS approach.
+        """
+        new_sol = Solution(nb_crit=self.nb_crit)
+
+        # Collect all candidate variables
+        all_as_candidates = list(self.param.asvarnames or [])
+        all_is_candidates = list(self.param.isvarnames or [])
+
+        # --- AS variables: for each, decide via HMCR ---
+        new_asvars = []
+        for var in all_as_candidates:
+            if self.param.generator.rand() <= harm_rate:
+                # Copy from memory: randomly pick a harmony and take its value for this var
+                if memory:
+                    chosen = self.param.generator.choice(len(memory))
+                    if var in memory[chosen].get('asvars', []):
+                        new_asvars.append(var)
+            else:
+                # Random generation: include with some base probability
+                if self.param.generator.rand() < 0.3:  # base inclusion probability
+                    new_asvars.append(var)
+
+        # Enforce pre-specified
+        new_asvars = sorted(list(set().union(new_asvars, self.param.ps_asvars or [])))
+        new_asvars = self.remove_redundant_asvars(new_asvars, self.param.trans_asvars, self.param.asvarnames)
+        new_asvars = self.remove_collinear_vars(new_asvars)
+        new_asvars = self._apply_mutual_exclusion_filter(new_asvars)
+        new_sol['asvars'] = new_asvars
+
+        # --- IS variables: same HMCR logic ---
+        new_isvars = []
+        for var in all_is_candidates:
+            if self.param.generator.rand() <= harm_rate:
+                if memory:
+                    chosen = self.param.generator.choice(len(memory))
+                    if var in memory[chosen].get('isvars', []):
+                        new_isvars.append(var)
+            else:
+                if self.param.generator.rand() < 0.3:
+                    new_isvars.append(var)
+
+        new_isvars = sorted(list(set().union(new_isvars, self.param.ps_isvars or [])))
+        new_isvars = self.remove_collinear_vars(new_isvars)
+        new_isvars = self._apply_mutual_exclusion_filter(new_isvars)
+        new_sol['isvars'] = new_isvars
+
+        # --- Derived features (randvars, bcvars, corvars) from chosen harmony ---
+        # Pick one reference harmony for derived features
+        if memory and (new_asvars or new_isvars):
+            ref_sol = memory[self.param.generator.choice(len(memory))]
+
+            # Random coefficients: only for variables that are in asvars
+            new_randvars = {k: v for k, v in ref_sol.get('randvars', {}).items() if k in new_asvars}
             new_sol['randvars'] = new_randvars
 
-            new_bcvars = [var for var in chosen_sol['bcvars']
-                            if var in new_asvars and var not in self.param.ps_corvars]
+            # Box-Cox: only for vars in asvars, not in corvars
+            ref_bcvars = ref_sol.get('bcvars', [])
+            new_bcvars = [v for v in ref_bcvars if v in new_asvars and v not in self.param.ps_corvars]
             new_sol['bcvars'] = new_bcvars
 
-            new_corvars = chosen_sol['corvars']
-            if new_corvars:
-                new_corvars = [var for var in chosen_sol['corvars']
-                                if var in new_randvars.keys() and var not in new_bcvars]
-            new_sol['corvars'] = new_corvars
+            # Correlation: only for randvars, not bcvars
+            ref_corvars = ref_sol.get('corvars', [])
+            if ref_corvars:
+                new_corvars = [v for v in ref_corvars if v in new_randvars and v not in new_bcvars]
+                new_sol['corvars'] = new_corvars
+            else:
+                new_sol['corvars'] = []
 
-            # Take fit_intercept from chosen solution
-            new_sol['asc_ind'] = chosen_sol['asc_ind']
+            # Intercept
+            new_sol['asc_ind'] = ref_sol.get('asc_ind', False)
 
-            # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            # Latent class specs
             if getattr(self.param, 'allow_latent_corvars', False):
-                if chosen_sol['class_params_spec'] is not None:
-                # {
-                    class_params_spec = copy.deepcopy(chosen_sol['class_params_spec'])
-                    for ii, class_params in enumerate(class_params_spec):
-                    # {
-                        class_params_index = self.param.generator.choice(bin, size=len(class_params), p=prob)
-                        class_params_spec[ii] = np.array([i for (i, v) in zip(class_params, class_params_index) if v],
-                                                         dtype=class_params.dtype)
-                    # }
-                    new_sol['class_params_spec'] = class_params_spec
-                # }
-                # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-                if chosen_sol['member_params_spec'] is not None:
-                # {
-                    member_params_spec = copy.deepcopy(chosen_sol['member_params_spec'])
-                    for ii, member_params in enumerate(member_params_spec):
-                    # {
-                        member_params_index = self.param.generator.choice(bin, size=len(member_params), p=prob)
-                        member_params_spec[ii] = np.array([i for (i, v) in zip(member_params, member_params_index) if v],
-                                                          dtype=member_params.dtype)
-                    # }
-                    new_sol['member_params_spec'] = member_params_spec
-                # }
-            # }
+                if ref_sol.get('class_params_spec') is not None:
+                    new_sol['class_params_spec'] = copy.deepcopy(ref_sol['class_params_spec'])
+                if ref_sol.get('member_params_spec') is not None:
+                    new_sol['member_params_spec'] = copy.deepcopy(ref_sol['member_params_spec'])
+        else:
+            new_sol['randvars'] = {}
+            new_sol['bcvars'] = []
+            new_sol['corvars'] = []
+            new_sol['asc_ind'] = False
+            new_sol['class_params_spec'] = None
+            new_sol['member_params_spec'] = None
 
         self._enforce_mutual_exclusion(new_sol)
         return new_sol
@@ -425,33 +415,79 @@ class HarmonySearch(Search):
 
     ''' ---------------------------------------------------------- '''
     ''' Function. Performs the pitch adjustment operation to       '''
-    ''' fine-tune a given solution. The process includes adding    '''
-    ''' new features or removing existing ones based on a binary   '''
-    ''' indicator. The resulting solution is evaluated and inserted'''
-    ''' The solutions in memory are then filtered                  '''
+    ''' fine-tune a given solution. In classic HS, this is a       '''
+    ''' small perturbation (x_new = x_old +- bw * rand()). For     '''
+    ''' discrete model specification, we make SMALL changes:       '''
+    ''' toggle one variable, change one distribution, etc.         '''
     ''' ---------------------------------------------------------- '''
     def pitch_adjustment(self, sol, pitch):
     # {
         adjusted_solution = copy.deepcopy(sol)
-        perturbations = [self.perturb_asfeature, self.perturb_isfeature, self.perturb_model_t]
-
-        if self.param.allow_random:
-            perturbations.append(self.perturb_randfeature)
-            if adjusted_solution['randvars']:
-                perturbations.append(self.perturb_distribution)
 
+        # Bandwidth controls how many small changes to make
+        # In standard HS: x_new = x_old + bw * randn()
+        # Here: bw ~ pitch, make 0-2 small changes
+        n_changes = 0
+        if self.param.generator.rand() < pitch:
+            n_changes = 1
+            if self.param.generator.rand() < pitch:
+                n_changes = 2
+
+        # Build list of SMALL adjustment operations
+        small_adjustments = []
+
+        # AS variable: add one missing or remove one present (small toggle)
+        if self.param.asvarnames:
+            missing_as = [v for v in self.param.asvarnames if v not in adjusted_solution.get('asvars', [])]
+            present_as = [v for v in adjusted_solution.get('asvars', []) if v not in self.param.ps_asvars]
+            if missing_as:
+                small_adjustments.append(('add_as', lambda s: self._add_one_asvar(s, missing_as)))
+            if present_as:
+                small_adjustments.append(('rem_as', lambda s: self._remove_one_asvar(s, present_as)))
+
+        # IS variable: similar
+        if self.param.isvarnames:
+            missing_is = [v for v in self.param.isvarnames if v not in adjusted_solution.get('isvars', [])]
+            present_is = [v for v in adjusted_solution.get('isvars', []) if v not in self.param.ps_isvars]
+            if missing_is:
+                small_adjustments.append(('add_is', lambda s: self._add_one_isvar(s, missing_is)))
+            if present_is:
+                small_adjustments.append(('rem_is', lambda s: self._remove_one_isvar(s, present_is)))
+
+        # Random coefficient: change distribution of ONE random var
+        if self.param.allow_random and adjusted_solution.get('randvars'):
+            small_adjustments.append(('chg_dist', self.perturb_distribution))
+
+        # Box-Cox: add/remove one
         if self.param.allow_bcvars:
-            perturbations.append(self.perturb_bcfeature)
-
-        if self.param.allow_corvars and adjusted_solution['randvars']:
-            perturbations.append(self.perturb_corfeature)
-
-        perturbation_count = 1 + int(self.param.generator.rand() < max(0.0, min(1.0, pitch)))
-        perturbation_count = min(perturbation_count, len(perturbations))
-        selected_perturbations = self.param.generator.choice(perturbations, size=perturbation_count, replace=False)
-
-        for perturbation in np.atleast_1d(selected_perturbations):
-            adjusted_solution = perturbation(adjusted_solution)
+            missing_bc = [v for v in adjusted_solution.get('asvars', [])
+                         if v not in adjusted_solution.get('bcvars', []) and v not in self.param.ps_corvars]
+            present_bc = [v for v in adjusted_solution.get('bcvars', []) if v not in self.param.ps_bcvars]
+            if missing_bc:
+                small_adjustments.append(('add_bc', lambda s: self._add_one_bcvar(s, missing_bc)))
+            if present_bc:
+                small_adjustments.append(('rem_bc', lambda s: self._remove_one_bcvar(s, present_bc)))
+
+        # Correlation: add/remove one (needs >=2 randvars)
+        if self.param.allow_corvars and len(adjusted_solution.get('randvars', {})) >= 2:
+            missing_cor = [v for v in adjusted_solution.get('randvars', {})
+                          if v not in adjusted_solution.get('corvars', []) and v not in adjusted_solution.get('bcvars', [])]
+            present_cor = [v for v in adjusted_solution.get('corvars', []) if v not in self.param.ps_corvars]
+            if missing_cor:
+                small_adjustments.append(('add_cor', lambda s: self._add_one_corvar(s, missing_cor)))
+            if present_cor:
+                small_adjustments.append(('rem_cor', lambda s: self._remove_one_corvar(s, present_cor)))
+
+        # Model type change (rare)
+        if self.param.avail_models is not None and len(self.param.avail_models) > 1:
+            small_adjustments.append(('chg_model', self.perturb_model_t))
+
+        # Apply n_changes small adjustments
+        for _ in range(n_changes):
+            if not small_adjustments:
+                break
+            _, adj_fn = self.param.generator.choice(small_adjustments)
+            adjusted_solution = adj_fn(adjusted_solution)
 
         adjusted_solution['randvars'] = self.normalize_randvars(
             adjusted_solution['asvars'],
@@ -463,6 +499,39 @@ class HarmonySearch(Search):
         return adjusted_solution, converged
     # }
 
+    # --- Helper methods for small single-variable adjustments ---
+    def _add_one_asvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_add_asfeature(sol) if hasattr(self, 'perturb_add_asfeature') else sol
+
+    def _remove_one_asvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_remove_asfeature(sol) if hasattr(self, 'perturb_remove_asfeature') else sol
+
+    def _add_one_isvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_add_isfeature(sol) if hasattr(self, 'perturb_add_isfeature') else sol
+
+    def _remove_one_isvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_remove_isfeature(sol) if hasattr(self, 'perturb_remove_isfeature') else sol
+
+    def _add_one_bcvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_add_bcfeature(sol) if hasattr(self, 'perturb_add_bcfeature') else sol
+
+    def _remove_one_bcvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_remove_bcfeature(sol) if hasattr(self, 'perturb_remove_bcfeature') else sol
+
+    def _add_one_corvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_add_corfeature(sol) if hasattr(self, 'perturb_add_corfeature') else sol
+
+    def _remove_one_corvar(self, sol, candidates):
+        var = self.param.generator.choice(candidates)
+        return self.perturb_remove_corfeature(sol) if hasattr(self, 'perturb_remove_corfeature') else sol
+
     ''' ---------------------------------------------------------- '''
     ''' Function. Extracts the best features                       '''
     ''' ---------------------------------------------------------- '''

{searchlibrium-0.0.199 → searchlibrium-0.0.201}/src/SearchLibrium/hspbil.py

@@ -34,14 +34,40 @@ class HSPBIL(HarmonySearch):
 
     Overrides the standard uniform-random pitch perturbations with
     probability-weighted decisions that learn from accepted solutions.
+
+    Parameters
+    ----------
+    param : Parameters
+        Problem definition (from search.py).
+    init_sol : Solution or None
+        Optional warm-start solution.
+    ctrl : tuple
+        ``(max_mem, maxiter, max_harm, min_harm, max_pitch, min_pitch)``
+    idnum : int or str
+        Run identifier for log files.
+    **kwargs
+        Forwarded to the :class:`HarmonySearch` base class constructor.
+        PBIL-specific kwargs:
+        ``pbil_l_bounds`` — dict of learning rate bounds per decision type
+            (default: thesis-based values from Taco-Morales 2026).
+        ``pbil_p_low`` — minimum probability clamp (default: 0.05).
+        ``pbil_p_high`` — maximum probability clamp (default: 0.95).
     """
 
     def __init__(self, param, init_sol, ctrl, idnum=0, **kwargs):
+        # Extract PBIL-specific kwargs before passing to parent
+        pbil_l_bounds = kwargs.pop('pbil_l_bounds', None)
+        pbil_p_low = kwargs.pop('pbil_p_low', None)
+        pbil_p_high = kwargs.pop('pbil_p_high', None)
+
         super().__init__(param, ctrl=ctrl, idnum=idnum)
 
         varnames = list(param.asvarnames or [])
         distributions = list(param.distr or ["n", "ln", "tn", "u", "t"])
-        self.prob_matrix = ProbabilityMatrix(varnames, distributions)
+        self.prob_matrix = ProbabilityMatrix(varnames, distributions,
+                                              l_bounds=pbil_l_bounds,
+                                              p_low=pbil_p_low,
+                                              p_high=pbil_p_high)
 
         self._ps_asvars = set(getattr(param, "ps_asvars", []) or [])
         self._ps_randvars = set(