SearchLibrium 0.0.87__tar.gz → 0.0.89__tar.gz

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SearchLibrium
-Version: 0.0.87
+Version: 0.0.89
 Summary: A Python package for econometric models driven by search
 Author: Alexander Paz Prithvi Beeramole, Robert Burdett
 Author-email: Zeke Ahern <z.ahern@qut.edu.au>

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/pyproject.toml

@@ -59,7 +59,7 @@ Homepage = "https://github.com/zahern/HypothesisX"
 realpython = "SearchLibrium.__main__:main"
 
 [tool.bumpver]
-current_version = "0.0.87"
+current_version = "0.0.89"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
 commit = true

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/src/SearchLibrium/Halton.py

@@ -67,7 +67,7 @@ import scipy.stats as ss
 class Halton:
     """Class for generating Halton sequences and Halton-based draws."""
 
-    def __init__(self, primes=None, drop=100, shuffled=False):
+    def __init__(self, primes=None, drop=100, shuffled=False, antithetic=False):
         self.primes = primes or [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47,
                                  53, 59, 61, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109,
                                  113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173,
@@ -76,15 +76,24 @@ class Halton:
                                  307, 311]
         self.drop = drop
         self.shuffled = shuffled
+        self.antithetic = antithetic
 
     def generate_draws(self, sample_size, n_draws, n_vars):
-        """Generate Halton draws for multiple variables using different primes."""
+        """Generate Halton draws for multiple variables using different primes.
+
+        When ``antithetic=True``, draws of size ``n_draws // 2`` are generated
+        then mirrored (1 - u) to produce negatively-correlated antithetic pairs.
+        For normal-based distributions this halves variance at zero extra cost.
+        """
+        base = n_draws // 2 if self.antithetic else n_draws
         draws = [
-            self.halton_seq(sample_size * n_draws, prime=self.primes[i % len(self.primes)]).reshape(sample_size,
-                                                                                                    n_draws)
+            self.halton_seq(sample_size * base, prime=self.primes[i % len(self.primes)]).reshape(sample_size, base)
             for i in range(n_vars)
         ]
-        return np.stack(draws, axis=1)  # (N, Kr, R)
+        draws = np.stack(draws, axis=1)  # (N, Kr, R_base)
+        if self.antithetic:
+            draws = np.concatenate([draws, 1.0 - draws], axis=2)  # (N, Kr, n_draws)
+        return draws
 
     def halton_seq(self, length, prime):
         """Generates a scrambled Halton sequence for a given prime number."""
@@ -159,11 +168,17 @@ class Draws:
         draws = np.atleast_3d(draws)
         return draws
 
+    # Clip uniform draws away from 0/1 to prevent norm.ppf -> ±inf.
+    # This matters especially for antithetic draws where the complement of a
+    # small Halton value is very close to 1.
+    _PPF_CLIP = 1e-10
+
     def evaluate_distribution(self, distr, values):
         """Transform uniform values to the specified distribution."""
         for k, distr_k in enumerate(distr):
             if distr_k in ['n', 'ln', 'tn']:  # Normal-based
-                values[:, k, :] = ss.norm.ppf(values[:, k, :])
+                u = np.clip(values[:, k, :], self._PPF_CLIP, 1.0 - self._PPF_CLIP)
+                values[:, k, :] = ss.norm.ppf(u)
             elif distr_k == 't':  # Triangular
                 values_k = values[:, k, :]
                 values[:, k, :] = (np.sqrt(2 * values_k) - 1) * (values_k <= .5) + \

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/src/SearchLibrium/MixedLogit.py

@@ -51,9 +51,11 @@ class MixedLogit(DiscreteChoiceModel):
             n_vars (int): Number of variables.
         """
         if n_vars == 0:
-            return np.ndarray((1,0,1))
-        draws_s = Draws(k=n_vars, halton_opts=None)
-        draws = draws_s.generate_draws(sample_size, n_draws, n_vars)
+            return np.ndarray((1, 0, 1))
+        # Use self.halton_opts so options like antithetic/shuffled are respected.
+        opts = self.halton_opts or {}
+        draws_s = Draws(k=n_vars, halton_opts=opts)
+        draws = draws_s.generate_draws(sample_size, n_draws)
         return draws
 
 
@@ -210,7 +212,6 @@ class MixedLogit(DiscreteChoiceModel):
         means_1 = np.mean(self.y, axis=3)  # means_1[i,j] = avg(y[i,j,:])
         means_2 = np.mean(means_1, axis=1)  # means_2[i] = avg(means_1[i,:])
         self.obs_prob = np.mean(means_2, axis=0)  # obs_prob = avg(means_2[:])
-        print(f'observed probs debug{self.obs_prob}')
         # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         # DEFINE MEMBER FUNCTIONS TO APPLY
         # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -230,8 +231,6 @@ class MixedLogit(DiscreteChoiceModel):
         #print(f"self.rvtrans: {self.rvtransdist}")
         self.rvdist = [item for item in self.rvdist if item is not False]
         self.rvtransdist = [item for item in self.rvtransdist if item is not False]
-        print(f"self.randvars: {self.rvdist}")
-        print(f"self.rvtrans: {self.rvtransdist}")
         draws = self.generate_draws(self.N, self.n_draws, len(self.rvdist))
         drawstrans = self.generate_draws(self.N, self.n_draws, len(self.rvtransdist))
         self.draws, self.drawstrans = draws, drawstrans  # Record generated values
@@ -282,13 +281,30 @@ class MixedLogit(DiscreteChoiceModel):
             # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
             arr = self.init_coeff[:lower]
-            rep = np.repeat(0.1, self.Kchol + self.Kbw)  # Array of 0.1s
+
+            # Better scale initialisation: use half the absolute value of the MNL
+            # mean estimates for the corresponding random variable, floored at 0.05.
+            # This gives BFGS a much better starting point than a flat 0.1 when
+            # coefficients are very small (e.g. cost in money units) or very large.
+            br_means = arr[self.Kf + 2 * self.Kftrans: self.Kf + 2 * self.Kftrans + self.Kr]
+
+            # Cholesky elements (correlated random vars) — keep at 0.1; the diagonal
+            # scaling is embedded in off-diagonal terms and is harder to infer.
+            chol_init = np.repeat(0.1, self.Kchol)
+
+            # Bandwidth (std dev) for non-correlated random vars.
+            bw_means = br_means[self.correlationLength:]
+            bw_init = np.maximum(np.abs(bw_means) * 0.5, 0.05)
+
+            rep = np.concatenate([chol_init, bw_init])
             self.init_coeff = np.concatenate((arr, rep, self.init_coeff[lower:upper],))
 
             if self.Krtrans:  # CHECK ">0"
                 # {
-                rep = np.repeat(0.1, self.Krtrans)  # An array with 0.1 repeated Krtrans times
-                self.init_coeff = np.concatenate((self.init_coeff, rep, self.init_coeff[-self.Krtrans:]))
+                # Similarly scale random-transformed std devs from MNL means.
+                rtrans_means = self.init_coeff[lower:upper]
+                rtrans_scale_init = np.maximum(np.abs(rtrans_means) * 0.5, 0.05)
+                self.init_coeff = np.concatenate((self.init_coeff, rtrans_scale_init, self.init_coeff[-self.Krtrans:]))
             # }
         # }
 

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/src/SearchLibrium/__init__.py

@@ -12,6 +12,11 @@ from addicty import Dict
 
 import os
 
+try:
+    from banditsa import BanditSA, PerturbationBandit
+except ImportError:
+    from .banditsa import BanditSA, PerturbationBandit
+
 def new_features():
     '''ADDICTY DICT'''
     '''vars you want to ensure are included'''
@@ -103,7 +108,8 @@ try:
     from .search import Parameters
 
     from . import misc
-    from .call_meta import call_harmony, call_siman, call_parsa, call_search, estimate_ctrl
+    from .sapbil import SAPBIL, ProbabilityMatrix
+    from .call_meta import call_harmony, call_siman, call_parsa, call_search, call_sapbil, estimate_ctrl
 
 except ImportError as e:
     from _choice_model import DiscreteChoiceModel
@@ -121,7 +127,8 @@ except ImportError as e:
     from RandomP import RandomParameters
     from constraints_builder import ConstraintBuilder, create_constraints
     from search import Parameters
-    from call_meta import call_siman, call_harmony, call_search, estimate_ctrl
+    from sapbil import SAPBIL, ProbabilityMatrix
+    from call_meta import call_siman, call_harmony, call_search, call_sapbil, estimate_ctrl
 try:
     from .main import print_ascii_art_logo
 except Exception:

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/src/SearchLibrium/_choice_model.py

@@ -391,7 +391,6 @@ class DiscreteChoiceModel(ABC):
         # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         non_sigs = self.num_of_exceeding_pvalues(self.pvalues, 0.0)
         #print('log like is before', self.loglik)
-        print('apply p val')
         self.loglik -= non_sigs*self.pval_penalty # penalise the non-sigs
         logging.info('applying pval')
         #print('log like is', self.loglik)

searchlibrium-0.0.89/src/SearchLibrium/banditsa.py

@@ -0,0 +1,300 @@
+"""Bandit-guided Simulated Annealing for SearchLibrium.
+
+This module provides:
+- PerturbationBandit: Thompson-sampling policy over perturbation action types
+- BanditSA: SA variant that uses the bandit to pick perturbation actions
+"""
+
+import logging
+
+import numpy as np
+
+try:
+    from siman import SA
+except ImportError:
+    from .siman import SA
+
+
+class PerturbationBandit:
+    """Thompson Sampling over perturbation action-type arms."""
+
+    def __init__(self, arm_names, prior_alpha=1.0, prior_beta=1.0, epsilon=0.05, rng=None):
+        self.arm_names = list(arm_names)
+        self.n_arms = len(self.arm_names)
+        self.alpha = np.full(self.n_arms, float(prior_alpha), dtype=float)
+        self.beta = np.full(self.n_arms, float(prior_beta), dtype=float)
+        self.counts = np.zeros(self.n_arms, dtype=int)
+        self.epsilon = float(epsilon)
+        self.rng = rng if rng is not None else np.random.default_rng()
+
+    def select_arm(self, available_indices):
+        if not available_indices:
+            raise ValueError("No available bandit arms to select from.")
+
+        if self.rng.random() < self.epsilon:
+            return int(self.rng.choice(available_indices))
+
+        samples = {
+            idx: self.rng.beta(self.alpha[idx], self.beta[idx])
+            for idx in available_indices
+        }
+        return max(samples, key=samples.get)
+
+    def update(self, arm_index, reward):
+        reward = float(reward)
+        self.counts[arm_index] += 1
+
+        if reward >= 0.0:
+            self.alpha[arm_index] += 1.0 + reward
+        else:
+            self.beta[arm_index] += 1.0 + abs(reward)
+
+    def summary(self):
+        rows = []
+        total = np.maximum(self.alpha + self.beta, 1e-12)
+        means = self.alpha / total
+        for idx, name in enumerate(self.arm_names):
+            rows.append(
+                {
+                    "arm": name,
+                    "alpha": float(self.alpha[idx]),
+                    "beta": float(self.beta[idx]),
+                    "mean": float(means[idx]),
+                    "count": int(self.counts[idx]),
+                }
+            )
+        rows.sort(key=lambda row: row["mean"], reverse=True)
+        return rows
+
+
+class BanditSA(SA):
+    """SA variant with Thompson-sampling perturbation selection."""
+
+    def __init__(
+        self,
+        param,
+        init_sol,
+        ctrl,
+        idnum=0,
+        bandit_prior_alpha=1.0,
+        bandit_prior_beta=1.0,
+        bandit_epsilon=0.05,
+        **kwargs,
+    ):
+        super().__init__(param, init_sol, ctrl, idnum=idnum, **kwargs)
+
+        self._actions = self._build_action_table()
+        self.bandit = PerturbationBandit(
+            arm_names=[name for name, _ in self._actions],
+            prior_alpha=bandit_prior_alpha,
+            prior_beta=bandit_prior_beta,
+            epsilon=bandit_epsilon,
+        )
+        self.bandit_history = []
+
+    def _build_action_table(self):
+        return [
+            ("add_asfeature", self.perturb_add_asfeature),
+            ("remove_asfeature", self.perturb_remove_asfeature),
+            ("add_isfeature", self.perturb_add_isfeature),
+            ("remove_isfeature", self.perturb_remove_isfeature),
+            ("add_randfeature", self.perturb_add_randfeature),
+            ("remove_randfeature", self.perturb_remove_randfeature),
+            ("add_bcfeature", self.perturb_add_bcfeature),
+            ("remove_bcfeature", self.perturb_remove_bcfeature),
+            ("add_corfeature", self.perturb_add_corfeature),
+            ("remove_corfeature", self.perturb_remove_corfeature),
+            ("change_model", self.perturb_model_t),
+            ("change_distribution", self.perturb_distribution),
+        ]
+
+    def _available_arm_indices(self, sol):
+        available = []
+
+        if self.param.asvarnames and len(sol.get("asvars", [])) < len(self.param.asvarnames):
+            available.append(0)  # add_asfeature
+        if len(sol.get("asvars", [])) > 1:
+            available.append(1)  # remove_asfeature
+
+        if self.param.isvarnames:
+            is_candidates = [v for v in self.param.isvarnames if v not in sol.get("isvars", [])]
+            if is_candidates:
+                available.append(2)  # add_isfeature
+        if sol.get("isvars"):
+            available.append(3)  # remove_isfeature
+
+        if self.param.allow_random:
+            add_r_candidates = [
+                v for v in sol.get("asvars", []) if v not in sol.get("randvars", {})
+            ]
+            if add_r_candidates:
+                available.append(4)  # add_randfeature
+
+            rem_r_candidates = [
+                v for v in sol.get("randvars", {}) if v not in self.param.ps_randvars
+            ]
+            if rem_r_candidates:
+                available.append(5)  # remove_randfeature
+
+            dist_candidates = [
+                v for v in sol.get("randvars", {}) if v not in self.param.ps_randvars
+            ]
+            if dist_candidates and len(getattr(self.param, "distr", []) or []) > 1:
+                available.append(11)  # change_distribution
+
+        if self.param.allow_bcvars:
+            add_bc_candidates = [
+                v
+                for v in sol.get("asvars", [])
+                if v not in sol.get("bcvars", []) and v not in self.param.ps_corvars
+            ]
+            if add_bc_candidates:
+                available.append(6)  # add_bcfeature
+
+            rem_bc_candidates = [
+                v for v in sol.get("bcvars", []) if v not in self.param.ps_bcvars
+            ]
+            if rem_bc_candidates:
+                available.append(7)  # remove_bcfeature
+
+        if self.param.allow_corvars and self.param.allow_random:
+            cor_eligible = [
+                v for v in sol.get("randvars", {}) if v not in sol.get("bcvars", [])
+            ]
+            if len(cor_eligible) >= 2:
+                available.append(8)  # add_corfeature
+
+            rem_cor_candidates = [
+                v for v in sol.get("corvars", []) if v not in self.param.ps_corvars
+            ]
+            if rem_cor_candidates:
+                available.append(9)  # remove_corfeature
+
+        if self.param.avail_models is not None and len(self.param.avail_models) > 1:
+            available.append(10)  # change_model
+
+        return sorted(set(available))
+
+    def _compute_bandit_reward(self, old_obj, new_obj, accepted, converged):
+        if not converged:
+            return -1.0
+
+        sign = self.param.sign_crit(0)
+        # Positive value means objective improved under current criterion direction.
+        delta = sign * (new_obj - old_obj)
+        scale = max(abs(old_obj), 1.0)
+        normalized = delta / scale
+
+        if accepted:
+            if normalized > 0:
+                return min(1.0, 0.1 + 10.0 * normalized)
+            return max(-1.0, 10.0 * normalized)
+
+        return -0.2
+
+    def _apply_selected_action(self, sol):
+        baseline_sig = self.setup_signature(sol)
+        max_attempts = 12
+        last_arm_idx = None
+
+        for _ in range(max_attempts):
+            candidate = self.copy_solution(sol)
+            available = self._available_arm_indices(candidate)
+            if not available:
+                return sol, None, False
+
+            arm_idx = self.bandit.select_arm(available)
+            last_arm_idx = arm_idx
+            _, action = self._actions[arm_idx]
+            result = action(candidate)
+            if result is not None:
+                candidate = result
+
+            candidate = self.apply_constraints(candidate)
+            candidate = self.repair_solution_for_clarity(candidate)
+            if self.setup_signature(candidate) != baseline_sig:
+                return candidate, arm_idx, True
+
+        return sol, last_arm_idx, False
+
+    def perturb_solution(self, sol):
+        curr_score = [sol.obj(i) for i in range(self.nb_crit)]
+
+        new_sol, arm_idx, changed = self._apply_selected_action(sol)
+        if not changed:
+            if arm_idx is not None:
+                self.bandit.update(arm_idx, -0.5)
+                self.bandit_history.append(
+                    {
+                        "step": int(self.step),
+                        "arm": self._actions[arm_idx][0],
+                        "accepted": False,
+                        "converged": False,
+                        "reward": -0.5,
+                        "reason": "no_change",
+                    }
+                )
+            return self.current_sol
+
+        new_sol, converged = self.evaluate(new_sol)
+        if not converged:
+            self.not_converged += 1
+            reward = self._compute_bandit_reward(curr_score[0], curr_score[0], False, False)
+            self.bandit.update(arm_idx, reward)
+            self.bandit_history.append(
+                {
+                    "step": int(self.step),
+                    "arm": self._actions[arm_idx][0],
+                    "accepted": False,
+                    "converged": False,
+                    "reward": float(reward),
+                    "reason": "non_converged",
+                }
+            )
+            return self.current_sol
+
+        new_score = [new_sol.obj(i) for i in range(self.nb_crit)]
+        accepted = bool(self.accept_change(curr_score, new_score))
+
+        if accepted:
+            self.no_impr = 0
+            self.accepted += 1
+            self.current_sol = new_sol
+            self.update_best(new_sol)
+        else:
+            self.not_accepted += 1
+
+        reward = self._compute_bandit_reward(curr_score[0], new_score[0], accepted, converged)
+        self.bandit.update(arm_idx, reward)
+        self.bandit_history.append(
+            {
+                "step": int(self.step),
+                "arm": self._actions[arm_idx][0],
+                "accepted": bool(accepted),
+                "converged": bool(converged),
+                "reward": float(reward),
+                "old_obj": float(curr_score[0]),
+                "new_obj": float(new_score[0]),
+            }
+        )
+
+        self.log_kpi(new_sol, self.debug_file, accepted)
+        return self.current_sol
+
+    def finalise(self):
+        super().finalise()
+
+        lines = ["Bandit arm summary (sorted by posterior mean):"]
+        for row in self.bandit.summary():
+            lines.append(
+                "  {arm:<20s} mean={mean:.4f} alpha={alpha:.2f} beta={beta:.2f} count={count}".format(
+                    **row
+                )
+            )
+
+        for line in lines:
+            print(line)
+            try:
+                print(line, file=self.results_file)
+            except Exception:
+                logging.debug("Unable to write bandit summary to results_file")

{searchlibrium-0.0.87 → searchlibrium-0.0.89}/src/SearchLibrium/call_meta.py

@@ -21,11 +21,15 @@
 try:
     from harmony import*
     from siman import*
+    from banditsa import*
     from threshold import*
+    from sapbil import SAPBIL, ProbabilityMatrix
 except ImportError:
     from .harmony import*
     from .siman import*
+    from .banditsa import*
     from .threshold import*
+    from .sapbil import SAPBIL, ProbabilityMatrix
 
 import numpy as np
 
@@ -301,6 +305,99 @@ def call_siman(parameters, init_sol=None, ctrl=None, **kwargs):
     return best
 
 
+def call_sapbil(parameters, init_sol=None, ctrl=None, **kwargs):
+    """
+    Run SA+PBIL (Simulated Annealing coupled with Population-Based Incremental
+    Learning) search.
+
+    Parameters
+    ----------
+    parameters : Parameters
+        Problem definition (variables, data, criteria, models).
+    init_sol : Solution, optional
+        Warm-start solution.  None = generate automatically.
+    ctrl : tuple, optional
+        ``(tI, tF, max_temp_steps, max_iter)``.
+        If omitted the values are estimated from the problem size.
+    **kwargs
+        ``id_num`` — run identifier (int, used in log file names).
+        Any other kwargs are forwarded to the SAPBIL constructor.
+
+    Returns
+    -------
+    Solution
+        Best converged, all-significant 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="sa")
+        print(
+            f"[SA+PBIL] Auto-estimated hyperparameters (problem complexity "
+            f"= {_problem_size(parameters)['complexity']}):"
+        )
+    else:
+        print("[SA+PBIL] Using provided hyperparameters:")
+
+    print(_describe_ctrl(ctrl, "sa"))
+    print()
+
+    solver = SAPBIL(parameters, init_sol, ctrl, id_num, **kwargs)
+    solver.run()
+    solver.close_files()
+    best = solver.return_best()
+    _print_dashboard(solver, best, algorithm="SA+PBIL")
+    return best
+
+
+def call_banditsa(parameters, init_sol=None, ctrl=None, **kwargs):
+    """
+    Run Bandit-guided Simulated Annealing (Thompson Sampling on perturbation arms).
+
+    Parameters
+    ----------
+    parameters : Parameters
+        Problem definition (variables, data, criteria, models).
+    init_sol : Solution, optional
+        Warm-start solution. None = generate automatically.
+    ctrl : tuple, optional
+        ``(tI, tF, max_temp_steps, max_iter)``.
+        If omitted the values are estimated from the problem size.
+    **kwargs
+        ``id_num``  - run identifier (int, used in log file names).
+        Any other kwargs are forwarded to the BanditSA constructor.
+
+    Returns
+    -------
+    Solution
+        Best converged, all-significant 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='sa')
+        print(f"[BanditSA] Auto-estimated hyperparameters (problem complexity "
+              f"= {_problem_size(parameters)['complexity']}):")
+    else:
+        print("[BanditSA] Using provided hyperparameters:")
+
+    print(_describe_ctrl(ctrl, 'sa'))
+    print()
+
+    solver = BanditSA(parameters, init_sol, ctrl, id_num, **kwargs)
+    solver.run()
+    solver.close_files()
+    best = solver.return_best()
+    _print_dashboard(solver, best, algorithm='BanditSA')
+    return best
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Harmony Search
 # ─────────────────────────────────────────────────────────────────────────────
@@ -364,8 +461,9 @@ def call_search(parameters, init_sol=None, algorithm='sa', ctrl=None, **kwargs):
         Problem definition.
     init_sol : Solution, optional
         Warm-start solution.
-    algorithm : {'sa', 'hs'}
+    algorithm : {'sa', 'banditsa', 'hs'}
         ``'sa'``  — Simulated Annealing  (default)
+        ``'banditsa'`` — Bandit-guided Simulated Annealing
         ``'hs'``  — Harmony Search
     ctrl : tuple, optional
         Algorithm-specific control tuple.  Auto-estimated if omitted.
@@ -383,6 +481,7 @@ def call_search(parameters, init_sol=None, algorithm='sa', ctrl=None, **kwargs):
     Examples
     --------
     >>> 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, ctrl=(500,0.001,80,15))# SA, manual ctrl
     >>> best = call_search(params, algorithm='hs',
@@ -391,12 +490,16 @@ def call_search(parameters, init_sol=None, algorithm='sa', ctrl=None, **kwargs):
     algorithm = algorithm.lower().strip()
     if algorithm in ('sa', 'siman', 'simulated_annealing'):
         return call_siman(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
+    elif algorithm in ('sapbil', 'sa_pbil', 'sa+pbil', 'pbil'):
+        return call_sapbil(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
+    elif algorithm in ('banditsa', 'bandit_sa', 'bandit-simulated-annealing', 'bsa'):
+        return call_banditsa(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
     elif algorithm in ('hs', 'harmony', 'harmony_search'):
         return call_harmony(parameters, init_sol=init_sol, ctrl=ctrl, **kwargs)
     else:
         raise ValueError(
             f"Unknown algorithm '{algorithm}'. "
-            f"Choose 'sa' (Simulated Annealing) or 'hs' (Harmony Search)."
+            f"Choose 'sa', 'sapbil', 'banditsa', or 'hs'."
         )