SearchLibrium 0.0.70
A wrapper for Searchlogit with extended functionality for ABM models.
Requires Python: >=3.9

# SearchLibrium
## Econometric Models driven by Search and built on SearchLogit and MetaCountRegresssor

This repository contains the SearchLibrium package, which is a Python library designed for econometric models driven by search. It builds upon the foundations of SearchLogit and MetaCountRegressor, providing a robust framework for estimating data count models.


```python
!pip install SearchLibrium --upgrade

```

    Looking in indexes: https://pypi.org/simple, https://pypi.ngc.nvidia.com
    Requirement already satisfied: SearchLibrium in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (0.0.27)
    Collecting SearchLibrium
      Downloading searchlibrium-0.0.28-py3-none-any.whl.metadata (1.3 kB)
    Requirement already satisfied: numpy>2.0.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (2.2.6)
    Requirement already satisfied: pandas>=2.0.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (2.3.1)
    Requirement already satisfied: scikit-learn>=1.3.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (1.7.1)
    Requirement already satisfied: statsmodels in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (0.14.5)
    Requirement already satisfied: pyfiglet in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (1.0.3)
    Requirement already satisfied: addicty in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (2023.9.3)
    Requirement already satisfied: matplotlib in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from SearchLibrium) (3.10.5)
    Requirement already satisfied: python-dateutil>=2.8.2 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from pandas>=2.0.0->SearchLibrium) (2.9.0.post0)
    Requirement already satisfied: pytz>=2020.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from pandas>=2.0.0->SearchLibrium) (2025.2)
    Requirement already satisfied: tzdata>=2022.7 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from pandas>=2.0.0->SearchLibrium) (2025.2)
    Requirement already satisfied: six>=1.5 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from python-dateutil>=2.8.2->pandas>=2.0.0->SearchLibrium) (1.17.0)
    Requirement already satisfied: scipy>=1.8.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from scikit-learn>=1.3.1->SearchLibrium) (1.15.3)
    Requirement already satisfied: joblib>=1.2.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from scikit-learn>=1.3.1->SearchLibrium) (1.5.1)
    Requirement already satisfied: threadpoolctl>=3.1.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from scikit-learn>=1.3.1->SearchLibrium) (3.6.0)
    Requirement already satisfied: pyyaml in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from addicty->SearchLibrium) (6.0.2)
    Requirement already satisfied: yamllint in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from addicty->SearchLibrium) (1.37.1)
    Requirement already satisfied: contourpy>=1.0.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (1.3.2)
    Requirement already satisfied: cycler>=0.10 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (0.12.1)
    Requirement already satisfied: fonttools>=4.22.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (4.59.1)
    Requirement already satisfied: kiwisolver>=1.3.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (1.4.9)
    Requirement already satisfied: packaging>=20.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (25.0)
    Requirement already satisfied: pillow>=8 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (11.3.0)
    Requirement already satisfied: pyparsing>=2.3.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib->SearchLibrium) (3.2.3)
    Requirement already satisfied: patsy>=0.5.6 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from statsmodels->SearchLibrium) (1.0.1)
    Requirement already satisfied: pathspec>=0.5.3 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from yamllint->addicty->SearchLibrium) (0.12.1)
    Downloading searchlibrium-0.0.28-py3-none-any.whl (146 kB)
    Installing collected packages: SearchLibrium
      Attempting uninstall: SearchLibrium
        Found existing installation: SearchLibrium 0.0.27
        Uninstalling SearchLibrium-0.0.27:
          Successfully uninstalled SearchLibrium-0.0.27
    Successfully installed SearchLibrium-0.0.28
    


```python




import SearchLibrium as sl

```

    Looking in indexes: https://pypi.org/simple, https://pypi.ngc.nvidia.com
    Requirement already satisfied: matplotlib in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (3.10.5)
    Requirement already satisfied: contourpy>=1.0.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (1.3.2)
    Requirement already satisfied: cycler>=0.10 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (0.12.1)
    Requirement already satisfied: fonttools>=4.22.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (4.59.1)
    Requirement already satisfied: kiwisolver>=1.3.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (1.4.9)
    Requirement already satisfied: numpy>=1.23 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (2.2.6)
    Requirement already satisfied: packaging>=20.0 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (25.0)
    Requirement already satisfied: pillow>=8 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (11.3.0)
    Requirement already satisfied: pyparsing>=2.3.1 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (3.2.3)
    Requirement already satisfied: python-dateutil>=2.7 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from matplotlib) (2.9.0.post0)
    Requirement already satisfied: six>=1.5 in c:\users\ahernz\source\searchlibrium\.venv\lib\site-packages (from python-dateutil>=2.7->matplotlib) (1.17.0)
    

    ERROR: Invalid requirement: '#todo': Expected package name at the start of dependency specifier
        #todo
        ^
    

    Current version: unknown
    
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. ..
                  .............................................................................
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .*@:. .. .. .. ..  .  .  .. .. 
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .:@@@@@@ .. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. .@@@@  .+@@  .. .. .. .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  .  .. *@@@@@=. .. .@@=. .. .. ..  .  .  .. .. 
                  ...................................@@@@@@%........@@@........................
                   .. ..  .  .  .. .. .. .. .. .. ..@@@%@@...  .  . *@@ .. .. .. .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  ..@@%-@@... .. .. .+@@. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. @@@.@@.. ..  .  . @%. .. .. .. .. .. .. .. ..
                   .. ..  .  .  .. .. .. .. .. ..#@@ =@@.. ..  .  .:@@  .. .. .. .. .. .. .. ..
                  .. .. .. .. .. :%*@@@@@@@.  .  @@*.@@-. .. .. .. @@-.. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .#@@. .. @@@-. ..@@. @@:.. ..  .  @@%.  .. .. .. .. .. .. .. ..
                   .. ..  .  .  .. ..-@@@@@@@@@@:@@+@@@@@@-..  .%@@# .  .. .. .. .. .. .. .. ..
                  .. .. .. .. ..@@@@@@@@-  .  :@@@@@@@....@@@@@@@@... .. .. .. ..  .  .  .. .. 
                   .. ..  .  .  @@..@@@@@@@ .. .*@@: .. .. .@@@@%@@@@@# .. .. .. .. .. .. .. ..
                  .................-@@@@:@@:.....@@..........@@@@%.=@@@@@*.....................
                  .. .. .. .. .. ..@@@@@@@@.  . %@@ .. .. .. @@@.. %@@..%@@=.. ..  .  .  .. .. 
                   .. ..  .  .  .. @@*=@@.. ...@@@.. .. .. ..@@:  .@@.  .@@@@... .. .. .. .. ..
                  .. .. .. .. .. ..#@@ ..  .%@@@@*  .. .. ..@@@ ..@@+ ..-@@.@@#..  .  .  .. .. 
                  .. .. .. .. .. .. #@@@@@@@@#.:@%  .. .. %@@=. .@@#. ..@@- .@@#.  .  .  .. .. 
                   .. ..  .  .  .. .. .-=:. .. .-@@# ..*@@@@.  .@@=  ..@@+ ..@@@ .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  . *%@@@@@@@ .@@@. ..-@@:.. %@@@@  .  .  .. .. 
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. @@@@@ .. .@@@. ..@@@.%@. .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. *@@#.  -@@#  .#@@@ .@@:. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. @@@@@@@. ..@@%....@@. .  .  .. .. 
                  .............................................%@@@@*#@@@#..=%@@-..............
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .%@@@@@@@@@@@@ .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. .. ..@@.  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .  .. .. @@ .. .. .. .. ..
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .  .. .. *. .. .. .. .. ..
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .. .. 
                   .. ..  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. ..
                  .............................................................................
                  .. .. .. .. .. .. .. ..  .  .  .  .. .. .. .. .. .. .. .. .. ..  .  .  .. .. 
    
    Welcome to SearchLibrium
    


```python
# Test the main functionality of SearchLibrium for nested search
sl.main.test_nested_search()
```

    No id applied to SA algorithm, creating random run ID
       Unnamed: 0  individual   mode choice  wait  vcost  travel  gcost  income  \
    0           1           1    air     no    69     59     100     70      35   
    1           2           1  train     no    34     31     372     71      35   
    2           3           1    bus     no    35     25     417     70      35   
    3           4           1    car    yes     0     10     180     30      35   
    4           5           2    air     no    64     58      68     68      30   
    
       size  AV  CHOICE  
    0     1   1       0  
    1     1   1       0  
    2     1   1       0  
    3     1   1       1  
    4     2   1       0  
    [INFO] Control parameters (ctrl): (100, 0.001, 2, 20)
    
    [INFO] To change the control parameters, pass the 'ctrl' argument as a tuple:
      Example: ctrl=(200, 0.01, 10, 50)
      - tI: Initial temperature (higher = more exploration).
      - tF: Final temperature (lower = more exploitation).
      - max_temp_steps: Number of temperature steps.
      - max_iter: Number of iterations per temperature step.
    
    SA[1] - Generating a starting solution
    SA[1]. Attempt=0
    
    ***** New Best Solution Found *****
    Solution Number: 0
    Objective Values: 533.17
    
    Model Summary:
    
    Choice Model: Nested Logit
    --------------------------------------------------
    WARNING: Convergence was not reached during estimation. The given estimates may not be reliable
    **************************************************
    Estimation time= 0.0 seconds
    
    Proportion of alternatives: observed choice
    [0.27619048 0.3        0.14285714 0.28095238]
    
    Proportion of alternatives: predicted choice
    [0.27940301 0.17501344 0.12502983 0.42055373]
    
    Table.
    ---------------------------------------------------------------------------
    Coefficient              Estimate      Std.Err.         z-val         P>|z|
    ---------------------------------------------------------------------------
    gcost               -0.0350466357  0.0060412480 -171.3299376864             0 ***
    wait                -0.0874383983  0.0064088322 -169.6780879755             0 ***
    vcost                0.0630758986  0.0064233443 -145.8623518304             0 ***
    income               0.1000000000  1.0000000000 -0.9000000000         0.368    
    lambda_Nest1         2.2559517922  0.1120656499 11.2072860252             0 ***
    lambda_Nest2         2.7622588959  0.1182633223 14.9011448433             0 ***
    ---------------------------------------------------------------------------
    Significance:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
    
    LOGLIK = -250.544; AIC = 513.087; BIC = 533.170; ADJLIK RATIO: 0.119
    ***********************************
    
    SA[1]. Starting solution:  [533.17000501]
    step number 1
    SA[1]. Progress @ Step=1; Curr=[533.17]; Best=[533.17]; Elapsed Time=0.35
    Solver[1]. Search complete
    Solver[1]. Finalising
    ***************
    {'asvars': ['gcost', 'wait', 'vcost', 'income'], 'isvars': [], 'bcvars': [], 'corvars': [], 'bctrans': False, 'cor': False, 'randvars': {}, 'model_n': np.str_('nested_logit'), 'asc_ind': False, 'bic': np.float64(533.170005006407), 'loglik': np.float64(-250.54367991105107), 'mae': None, 'aic': np.float64(513.0873598221021), 'is_initial_sol': False, 'converged': True, 'coeff': array([-0.03504664, -0.0874384 ,  0.0630759 ,  0.1       ,  2.25595179,
            2.7622589 ]), 'sol_num': 0, 'insig': None, 'obj': array([533.17000501]), 'model': <SearchLibrium.multinomial_nested.NestedLogit object at 0x000001ABCF2AA290>, 'class_num': None}
    ***************
    


```python
# what is happening under the hood..
import inspect

print(inspect.getsource(sl.main.test_nested_search))
```

    def test_nested_search():
        #preview_dataset()
        try:
            from call_meta import call_siman
            from search import  Parameters
        except ImportError:
            from .call_meta import call_siman
            from .search import Parameters
        # Define nests and lambdas for nested logit
    
        #train_df = pd.read_csv(problem_set.travel_mode)
        train_df = prepare_dataset('travel_mode')
        print(train_df.head())
        nests = {"Nest1": [0, 1], "Nest2": [2, 3]}
        lambdas = {"Nest1": 0.8, "Nest2": 1.0}
        varnames = ['gcost', 'wait', 'vcost', 'travel', 'income']
        # Initialize Parameters
        params = Parameters(
            criterions=[("bic", -1)],  # Minimize BIC
            df=train_df,
            choice_set = np.unique(train_df['CHOICE']),
            choices = train_df['CHOICE'],
            choice_id=train_df['individual'],
            varnames=varnames,
            asvarnames=varnames,
            alt_var=train_df['mode'],
            avail=train_df['AV'],
            base_alt='air',
            models=["nested_logit"],  # Include nested_logit
            nests=nests,
            lambdas=lambdas
        )
        init_sol = None
        # supply id number so to overwrite logfiles.
        call_siman(params, init_sol, id_num=1)