jboat 0.0.1

BOAT: A Compositional Operation Toolbox for Gradient-based Bi-Level Optimization

A Compositional Operation Toolbox for Gradient-based Bi-Level Optimization

Home | Installation | Docs | Tutorials | Examples

JBOAT is a compositional OperAtion-level Toolbox for gradient-based BLO. Unlike existing libraries that typically encapsulate fixed solver routines, JBOAT factorizes the BLO workflow into atomic, reusable primitives. Through a unified constraint reconstruction perspective, it empowers researchers to automatically compose over 85+ solver variants from a compact set of 17 gradient operations.

This is the Jittor-based version of JBOAT (jboat). It leverages Jittor’s Just-In-Time (JIT) compilation and efficient CUDA/cuDNN backends to significantly accelerate large-scale gradient-based BLO experiments.

🔑 Key Features

• 🧩 Compositional Operation-Level Abstraction: Deconstructs BLO solvers into three modular stages: Gradient Mapping (GM), Numerical Approximation (NA), and First-Order (FO).
• ⚡ Accelerated JIT Execution: Built on Jittor, enabling meta-operator fusion and high-performance execution on NVIDIA GPUs.
• 🏭 Generative Solver Construction: Supports dynamic serialization of operations. Users can recover classical algorithms or discover novel hybrid solvers simply by changing configurations.
• 🛠 Configuration-Driven: Define complex optimization strategies via simple JSON configurations, decoupling algorithmic logic from model definitions.
• ✅ Comprehensive Testing: Achieves 99% code coverage through rigorous testing with pytest, ensuring software robustness.

📚 Supported Operation Libraries

JBOAT implements 17 atomic gradient operations organized into three modular libraries. These primitives can be dynamically serialized to generate over 85+ solver variants, covering the full spectrum of BLO methodologies.

Library	Functional Role	Supported Atomic Operations
GM-OL (Gradient Mapping)	Reconstructs the LL iterative trajectory. Customizes the dynamic mapping rules ($\mathcal{T}_k$) to shape the optimization path and variable coupling.	• NGD (Naive Gradient Descent) • GDA (Gradient Descent Aggregation) • DI (Dynamic Initialization) • DM (Dual Multiplier / KKT)
NA-OL (Numerical Approx.)	Resolves the auxiliary gradient bottleneck. Approximates the implicit gradients or hyper-gradients via automatic differentiation, numerical inversion, or truncation.	• RAD (Reverse-AD / Unrolled) • RGT (Reverse Gradient Truncation) • PTT (Pessimistic Trajectory Truncation) • FD (Finite Difference / DARTS) • CG (Conjugate Gradient) • NS (Neumann Series) • IGA (Implicit Gradient Approximation) • IAD (Init-based AD / MAML) • FOA (First-Order Approx. / Reptile)
FO-OL (First-Order)	Constructs single-level surrogates. Reformulates the nested problem into first-order objectives using value-functions or penalties, avoiding Hessian computations.	• VSO (Value-Function Sequential) • VFO (Value-Function First-Order) • MESO (Moreau Envelope) • PGDO (Penalty Gradient Descent)

🔨 Installation

JBOAT is built on top of Jittor. Please ensure Jittor is installed correctly before installing JBOAT.

1. Install Jittor

Follow the Official Installation Guide or use the commands below:

Linux (Ubuntu / CentOS)

sudo apt install python3.8-dev libomp-dev
python3.8 -m pip install jittor
# Verify installation (Optional)
python3.8 -m jittor.test.test_example

Windows

python -m pip install jittor
python -m jittor.test.test_core

macOS

brew install libomp
python3.8 -m pip install jittor

2. Install jboat

Once Jittor is ready, install jboat via PyPI or Source:

# Install from PyPI
pip install jboat

# Or install from Source (Specific Branch)
git clone https://github.com/vis-opt-group/JBOAT.git
cd JBOAT
pip install -e .

⚡ How to Use JBOAT

JBOAT separates the problem definition from the solver configuration. Below is a Jittor-based example.

1. Load Configurations

import json
import jboat as boat

# Load algorithmic configurations
with open("configs/boat_config.json", "r") as f:
    boat_config = json.load(f)

# Load objective configurations
with open("configs/loss_config.json", "r") as f:
    loss_config = json.load(f)

2. Define Models and Optimizers

Use standard Jittor models and optimizers.

import jittor as jit

# Define models
upper_model = MyUpperModel()
lower_model = MyLowerModel()

# Define optimizers (Jittor syntax)
upper_opt = jit.nn.Adam(upper_model.parameters(), lr=1e-3)
lower_opt = jit.nn.SGD(lower_model.parameters(), lr=1e-2)

3. Customize & Initialize Problem

Inject runtime objects into the configuration.

# Configure JBOAT with Jittor models/optimizers
boat_config["lower_level_model"] = lower_model
boat_config["upper_level_model"] = upper_model
boat_config["lower_level_opt"] = lower_opt
boat_config["upper_level_opt"] = upper_opt

# Initialize the JBOAT core
b_optimizer = boat.Problem(boat_config, loss_config)

4. Build Solvers

Inject runtime objects into the configuration.

# Pass optimizers explicitly if needed by the solver backend
b_optimizer.build_ll_solver(lower_opt)
b_optimizer.build_ul_solver(upper_opt)

5. Run Optimization Loop

# Training loop
for x_itr in range(1000):
    # Prepare data (Jittor Arrays or dicts)
    ul_feed_dict = {"data": ul_data, "target": ul_target}
    ll_feed_dict = {"data": ll_data, "target": ll_target}
    
    # Run one iteration
    loss, run_time = b_optimizer.run_iter(ll_feed_dict, ul_feed_dict, current_iter=x_itr)
    
    if x_itr % 100 == 0:
        print(f"Iter {x_itr}: UL Loss {loss:.4f}")

🌍 Applications

JBOAT covers a wide spectrum of BLO applications, categorized by the optimization target:

• Data-Centric: Data Hyper-Cleaning, Synthetic Data Reweighting, Diffusion Model Guidance.
• Model-Centric: Neural Architecture Search (NAS), LLM Prompt Optimization, Parameter Efficient Fine-Tuning (PEFT).
• Strategy-Centric: Meta-Learning, Hyperparameter Optimization (HO), Reinforcement Learning from Human Feedback (RLHF).

📝 Citation

If you find JBOAT useful in your research, please consider citing our paper:

@article{liu2025boat,
  title={BOAT: A Compositional Operation Toolbox for Gradient-based Bi-Level Optimization},
  author={Liu, Yaohua and Pan, Jibao and Jiao, Xianghao and Gao, Jiaxin and Liu, Zhu and Liu, Risheng},
  journal={Submitted to Journal of Machine Learning Research (JMLR)},
  year={2025}
}

License

MIT License

Copyright (c) 2024 Yaohua Liu

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.