blnetwork 0.1.0__tar.gz

blnetwork-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yue Liang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blnetwork-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+global-exclude *.pyc
+global-exclude __pycache__/*
+exclude .gitignore
+prune .git
+prune .github

blnetwork-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: blnetwork
+Version: 0.1.0
+Summary: Behavior Learning (BL): Learning Hierarchical Optimization Structures from Data
+Author-email: Yue Liang <yue.liang@student.uni-tuebingen.de>
+License: MIT License
+        
+        Copyright (c) 2026 Yue Liang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/YueLiang-hye/Behavior-Learning
+Project-URL: Issues, https://github.com/YueLiang-hye/Behavior-Learning/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scikit-learn>=1.3
+Dynamic: license-file
+
+# Behavior Learning (BL)
+
+Behavior Learning (BL) is a general-purpose machine learning framework grounded in behavioral science. It unifies predictive performance and intrinsic interpretability within a single modeling paradigm. BL learns explicit optimization structures from data by parameterizing a compositional utility function built from interpretable modular blocks. Each block represents a Utility Maximization Problem (UMP), a foundational framework of decision-making and optimization. BL supports architectures ranging from a single UMP to hierarchical compositions, enabling expressive yet structurally transparent models. Unlike post-hoc explanation methods, BL provides interpretability by design while maintaining strong empirical performance on high-dimensional tasks.
+
+## Installation
+blnetwork can be installed via PyPI or directly from GitHub. 
+
+**Pre-requisites:**
+
+```
+Python 3.10.9 or higher
+pip
+```
+
+**For developers**
+
+```
+git clone https://github.com/YueLiang-hye/Behavior-Learning.git
+cd blnetwork
+pip install -e .
+```
+
+**Installation via github**
+
+```
+pip install git+https://github.com/YueLiang-hye/Behavior-Learning.git
+```
+
+**Installation via PyPI:**
+```
+pip install blnetwork
+```
+
+Requirements
+
+```python
+# python==3.10.9
+torch>=2.2
+numpy>=1.26
+pandas>=2.0
+scikit-learn>=1.3
+```
+
+After activating the virtual environment, you can install specific package requirements as follows:
+```python
+pip install -r requirements.txt
+```
+
+**Optional: Conda Environment Setup**
+For those who prefer using Conda:
+```
+conda create --name blnetwork-env python=3.10.9
+conda activate blnetwork-env
+pip install git+https://github.com/YueLiang-hye/Behavior-Learning.git  # For GitHub installation
+# or
+pip install blnetwork  # For PyPI installation
+```
+
+## Computation Requirements
+
+BL is implemented in PyTorch and supports both CPU and GPU training.
+
+- Small-scale tabular examples run on a single CPU within a few minutes.
+- High-dimensional settings may benefit from GPU acceleration (e.g., NVIDIA L40).
+
+For most tabular tasks, CPU training is sufficient.
+
+## Examples
+
+Start with the notebooks in [`examples/`](./examples/):
+
+- [Example 1: Boston Housing (continuous)](./examples/Example_1_boston_housing.ipynb)
+- [Example 2: Breast Cancer (classification)](./examples/Example_2_breast_cancer.ipynb)
+
+## Advice on hyperparameter tuning
+In many cases, BL can achieve comparable (or slightly better) performance than an MLP baseline using roughly one third of the hidden width.
+
+Other hyperparameters can be initialized based on standard MLP tuning, and then refined for the specific task.
+
+## Contact
+If you have any questions, please contact yue.liang@student.uni-tuebingen.de

blnetwork-0.1.0/README.md

@@ -0,0 +1,81 @@
+# Behavior Learning (BL)
+
+Behavior Learning (BL) is a general-purpose machine learning framework grounded in behavioral science. It unifies predictive performance and intrinsic interpretability within a single modeling paradigm. BL learns explicit optimization structures from data by parameterizing a compositional utility function built from interpretable modular blocks. Each block represents a Utility Maximization Problem (UMP), a foundational framework of decision-making and optimization. BL supports architectures ranging from a single UMP to hierarchical compositions, enabling expressive yet structurally transparent models. Unlike post-hoc explanation methods, BL provides interpretability by design while maintaining strong empirical performance on high-dimensional tasks.
+
+## Installation
+blnetwork can be installed via PyPI or directly from GitHub. 
+
+**Pre-requisites:**
+
+```
+Python 3.10.9 or higher
+pip
+```
+
+**For developers**
+
+```
+git clone https://github.com/YueLiang-hye/Behavior-Learning.git
+cd blnetwork
+pip install -e .
+```
+
+**Installation via github**
+
+```
+pip install git+https://github.com/YueLiang-hye/Behavior-Learning.git
+```
+
+**Installation via PyPI:**
+```
+pip install blnetwork
+```
+
+Requirements
+
+```python
+# python==3.10.9
+torch>=2.2
+numpy>=1.26
+pandas>=2.0
+scikit-learn>=1.3
+```
+
+After activating the virtual environment, you can install specific package requirements as follows:
+```python
+pip install -r requirements.txt
+```
+
+**Optional: Conda Environment Setup**
+For those who prefer using Conda:
+```
+conda create --name blnetwork-env python=3.10.9
+conda activate blnetwork-env
+pip install git+https://github.com/YueLiang-hye/Behavior-Learning.git  # For GitHub installation
+# or
+pip install blnetwork  # For PyPI installation
+```
+
+## Computation Requirements
+
+BL is implemented in PyTorch and supports both CPU and GPU training.
+
+- Small-scale tabular examples run on a single CPU within a few minutes.
+- High-dimensional settings may benefit from GPU acceleration (e.g., NVIDIA L40).
+
+For most tabular tasks, CPU training is sufficient.
+
+## Examples
+
+Start with the notebooks in [`examples/`](./examples/):
+
+- [Example 1: Boston Housing (continuous)](./examples/Example_1_boston_housing.ipynb)
+- [Example 2: Breast Cancer (classification)](./examples/Example_2_breast_cancer.ipynb)
+
+## Advice on hyperparameter tuning
+In many cases, BL can achieve comparable (or slightly better) performance than an MLP baseline using roughly one third of the hidden width.
+
+Other hyperparameters can be initialized based on standard MLP tuning, and then refined for the specific task.
+
+## Contact
+If you have any questions, please contact yue.liang@student.uni-tuebingen.de

blnetwork-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blnetwork"
+version = "0.1.0"
+description = "Behavior Learning (BL): Learning Hierarchical Optimization Structures from Data"
+readme = "README.md"
+requires-python = ">=3.10.9"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Yue Liang", email = "yue.liang@student.uni-tuebingen.de" }
+]
+
+
+dependencies = [
+  "torch>=2.2",
+  "numpy>=1.26",
+  "pandas>=2.1",
+  "scikit-learn>=1.3"
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://github.com/YueLiang-hye/Behavior-Learning"
+Issues = "https://github.com/YueLiang-hye/Behavior-Learning/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["blnetwork*"]
+
+exclude = ["__pycache__*"]

blnetwork-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blnetwork-0.1.0/src/blnetwork/export.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from typing import List, Optional, Tuple, Dict
+
+import numpy as np
+import torch
+import sys
+import io
+import torch.nn.functional as F
+
+def _fmt_num(x: float, ndigits: int = 4) -> str:
+    s = f"{x:.{ndigits}f}"
+    s = s.rstrip("0").rstrip(".")
+    return s if s != "" else "0"
+
+
+def _safe_numpy(t):
+    if t is None:
+        return None
+    if torch.is_tensor(t):
+        return t.detach().cpu().numpy()
+    return np.asarray(t)
+
+
+def _get_bl_unit(block):
+    unit = getattr(block, "unit", None)
+    if unit is None:
+        raise AttributeError("Block has no attribute 'unit' (expected BLBlock.unit).")
+    return unit
+
+
+def _get_lambdas(unit):
+    lam = unit.lam 
+    if getattr(unit, "constrain_lambda", False):
+        eps = float(getattr(unit, "eps", 1e-8))
+        lam = F.softplus(lam) + eps
+    
+    lam_u = _safe_numpy(lam[0])
+    lam_c = _safe_numpy(lam[1])
+    lam_t = _safe_numpy(lam[2])
+    
+    return lam_u, lam_c, lam_t
+
+
+def _get_backbone(model):
+    backbone = getattr(model, "backbone", None)
+    if backbone is not None:
+        return backbone
+    if hasattr(model, "blocks"):
+        return model
+    raise AttributeError("Cannot find backbone. Expected model.backbone or model.blocks.")
+
+
+def _get_blocks(model) -> list:
+    backbone = _get_backbone(model)
+    blocks = getattr(backbone, "blocks", None)
+    if blocks is None:
+        raise AttributeError("Backbone has no attribute 'blocks'.")
+    return list(blocks)
+
+
+def _get_hidden_dims(model) -> Optional[Tuple[int, ...]]:
+    backbone = _get_backbone(model)
+    v = getattr(backbone, "hidden_dims", None)
+    if v is None:
+        return None
+    return tuple(map(int, v))
+
+
+def _get_output_linears(model) -> Dict[str, torch.nn.Linear]:
+    outs: Dict[str, torch.nn.Linear] = {}
+
+    lin = getattr(model, "linear_out", None)
+    if lin is not None and hasattr(lin, "weight"):
+        outs["Output Layer (Discrete)"] = lin
+        return outs
+
+    head = getattr(model, "head", None)
+    if head is None:
+        return outs
+    
+    if isinstance(head, torch.nn.Linear):
+        outs["Output Layer"] = head
+        return outs
+
+    lin = getattr(head, "linear", None)
+    if lin is not None and hasattr(lin, "weight"):
+        outs["Output Layer"] = lin
+
+    return outs
+
+
+def _emit_part_lines(
+    part_name: str,
+    lam_val: float,
+    w_row: np.ndarray,
+    b_val: float,
+    feature_names: List[str],
+    ndigits: int = 4,
+    tol: float = 0.0,
+) -> List[str]:
+    lines = []
+    lines.append(f"{part_name}")
+    lines.append(f"lambda {_fmt_num(float(lam_val), ndigits)}")
+
+    for name, w in zip(feature_names, w_row):
+        w = float(w)
+        if abs(w) > tol:
+            lines.append(f"----{name}     {_fmt_num(w, ndigits)}")
+
+    if abs(float(b_val)) > tol:
+        lines.append(f"----C     {_fmt_num(float(b_val), ndigits)}")
+
+    return lines
+
+
+def _print_blocks(
+    block,
+    feature_names: List[str],
+    layer_idx: int,
+    ndigits: int = 4,
+    tol: float = 0.0,
+) -> int:
+
+    unit = _get_bl_unit(block)
+
+    num_basis = int(unit.lin_u.out_features)
+
+    lam_u, lam_c, lam_t = _get_lambdas(unit)
+
+    w_u = _safe_numpy(unit.lin_u.weight)
+    b_u = _safe_numpy(unit.lin_u.bias)
+    w_c = _safe_numpy(unit.lin_c.weight)
+    b_c = _safe_numpy(unit.lin_c.bias)
+    w_t = _safe_numpy(unit.lin_t.weight)
+    b_t = _safe_numpy(unit.lin_t.bias)
+
+    for j in range(num_basis):
+        block_id = j + 1
+        print(f"--B{layer_idx}{block_id}")
+
+        # U part
+        lines = _emit_part_lines(
+            "U",
+            lam_val=float(lam_u[j]),
+            w_row=w_u[j],
+            b_val=float(b_u[j]),
+            feature_names=feature_names,
+            ndigits=ndigits,
+            tol=tol,
+        )
+        for ln in lines:
+            print(ln)
+
+        # C part
+        lines = _emit_part_lines(
+            "C",
+            lam_val=float(lam_c[j]),
+            w_row=w_c[j],
+            b_val=float(b_c[j]),
+            feature_names=feature_names,
+            ndigits=ndigits,
+            tol=tol,
+        )
+        for ln in lines:
+            print(ln)
+
+        # T part
+        lines = _emit_part_lines(
+            "T",
+            lam_val=float(lam_t[j]),
+            w_row=w_t[j],
+            b_val=float(b_t[j]),
+            feature_names=feature_names,
+            ndigits=ndigits,
+            tol=tol,
+        )
+        for ln in lines:
+            print(ln)
+
+        print("")  
+
+    return num_basis
+
+
+def _print_core(model, blocks, hidden_dims, feat_names, ndigits, tol, title="BL Model Structure"):
+    print("=" * 72)
+    print(title)
+    print("=" * 72)
+
+    print(f"hidden_dims = {hidden_dims}")
+    print(f"feature_dim = {len(feat_names)}")
+    print("")
+
+    current_feat_names = feat_names
+    
+    for layer_idx, block in enumerate(blocks, start=1):
+        num_basis = _print_blocks(
+            block=block,
+            feature_names=current_feat_names,
+            layer_idx=layer_idx,
+            ndigits=ndigits,
+            tol=tol,
+        )
+
+        if layer_idx < len(blocks):
+            current_feat_names = [f"B{layer_idx}{i+1}" for i in range(num_basis)]
+
+    outs = _get_output_linears(model)
+    if len(outs) > 0:
+        print("=" * 72)
+        print("OUTPUT LINEAR(S)")
+        print("=" * 72)
+        for name, lin in outs.items():
+            w = _safe_numpy(lin.weight)
+            b = _safe_numpy(lin.bias) if lin.bias is not None else None
+            print(name)
+            if getattr(w, "size", 0) and w.size <= 16:
+                w_flat = [float(x) for x in w.reshape(-1)]
+                w_fmt = ", ".join(_fmt_num(x, ndigits) for x in w_flat)
+                print(f"weight values = [{w_fmt}]")
+
+            if b is None:
+                print("bias = None")
+            else:
+                if getattr(b, "size", 0) and b.size <= 16:
+                    b_flat = [float(x) for x in b.reshape(-1)]
+                    b_fmt = ", ".join(_fmt_num(x, ndigits) for x in b_flat)
+                    print(f"bias values = [{b_fmt}]")
+            print("")
+
+def export_structure(
+    model,
+    df=None,
+    feature_names=None,
+    txt_path: Optional[str] = None,
+    ndigits: int = 4,
+    tol: float = 0.0,
+    title: str = "BL Model Structure",
+):
+
+    blocks = _get_blocks(model)
+    hidden_dims = _get_hidden_dims(model)
+
+    if feature_names is not None:
+        feat_names = list(feature_names)
+    elif df is not None:
+        feat_names = list(df.columns)
+    else:
+        unit0 = _get_bl_unit(blocks[0])
+        if not hasattr(unit0, "lin_u"):
+            raise AttributeError("Cannot infer input dim from BLUnit. Expected 'lin_u'.")
+        in_dim = int(unit0.lin_u.in_features)
+        feat_names = [f"x{i+1}" for i in range(in_dim)]
+
+    if txt_path is None:
+        _print_core(model, blocks, hidden_dims, feat_names, ndigits, tol, title)
+        return
+
+    old = sys.stdout
+    buf = io.StringIO()
+    sys.stdout = buf
+    try:
+        _print_core(model, blocks, hidden_dims, feat_names, ndigits, tol, title)
+    finally:
+        sys.stdout = old
+
+    with open(txt_path, "w", encoding="utf-8") as f:
+        f.write(buf.getvalue())

blnetwork-0.1.0/src/blnetwork/inference/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .continuous import predict_continuous
+from .discrete import predict_class_discrete, predict_proba_discrete
+
+__all__ = [
+	"predict_continuous",
+	"predict_class_discrete",
+	"predict_proba_discrete",
+]

blnetwork-0.1.0/src/blnetwork/inference/continuous.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from ..training import utils as U  
+
+
+@torch.no_grad()
+def predict_continuous(
+    predictor: nn.Module,
+    x: torch.Tensor,
+    *,
+    device: str | torch.device | None = None,
+    return_cpu: bool = True,
+) -> torch.Tensor:
+
+    predictor.eval()
+    dev = U.resolve_device(model=predictor, tensor=x, device=device)
+    y_hat = predictor(x.to(dev))
+    return y_hat.detach().cpu() if return_cpu else y_hat.detach()

blnetwork-0.1.0/src/blnetwork/inference/discrete.py

@@ -0,0 +1,40 @@
+import torch
+import torch.nn.functional as F
+
+from ..training import utils as U  
+
+
+@torch.no_grad()
+def predict_proba_discrete(
+    model,
+    x: torch.Tensor,
+    *,
+    temperature: float = 1.0,
+    device: str | torch.device | None = None,
+    return_cpu: bool = False,
+) -> torch.Tensor:
+    
+    dev = U.resolve_device(model, x, device)
+    x = x.to(dev)
+
+    scores = model.logits(x) if hasattr(model, "logits") else model(x)
+    logits = scores / float(temperature)
+    probs = F.softmax(logits, dim=1)
+
+    return probs.cpu() if return_cpu else probs
+
+
+@torch.no_grad()
+def predict_class_discrete(
+    model,
+    x: torch.Tensor,
+    *,
+    temperature: float = 1.0,
+    device: str | torch.device | None = None,
+    return_cpu: bool = True,
+) -> torch.Tensor:
+    probs = predict_proba_discrete(
+        model, x, temperature=temperature, device=device, return_cpu=False
+    )
+    pred = probs.argmax(dim=1)
+    return pred.cpu() if return_cpu else pred

blnetwork-0.1.0/src/blnetwork/model/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .bldeep import BLDeep
+
+__all__ = [
+    "BLDeep"
+]