FullControlHPO API

Overview

The FullControlHPO class provides complete control over all MAT-HPO parameters including advanced LLM strategies, RL configurations, and optimization settings. This is the production interface used in the SPNV2 ECG classification system.

Production Ready: This interface is used in real research applications and provides access to all advanced features including LLM enhancement, adaptive strategies, and fine-grained RL parameter control.

️ Class Definition

python

from MAT_HPO_LIB import FullControlHPO

# Basic LLM-enhanced optimization
optimizer = FullControlHPO(
    task_type="time_series_classification",
    max_trials=30,
    llm_enabled=True,
    mixing_strategy="fixed_alpha",
    alpha=0.3
)

Constructor Parameters

Basic Configuration

Parameter	Type	Default	Description
`task_type`	str	"time_series_classification"	Type of optimization task
`max_trials`	int	30	Maximum number of optimization trials
`seed`	int	42	Random seed for reproducibility
`verbose`	bool	True	Enable detailed logging output

LLM Configuration

Parameter	Type	Default	Description
`llm_enabled`	bool	True	Enable LLM enhancement
`llm_model`	str	"llama3.2:3b"	LLM model name (Ollama format)
`llm_base_url`	str	"http://localhost:11434"	LLM service endpoint URL
`mixing_strategy`	str	"fixed_alpha"	LLM mixing strategy: "fixed_alpha" or "adaptive"
`alpha`	float	0.3	LLM/RL mixing ratio (for fixed_alpha strategy)
`slope_threshold`	float	0.01	Performance slope threshold (for adaptive strategy)
`llm_cooldown_episodes`	int	6	Cooldown episodes after LLM intervention (ICBEB: 6, PTBXL: 4)
`min_episodes_before_llm`	int	6	Minimum episodes before first LLM use (ICBEB: 6, PTBXL: 4)

Reinforcement Learning Parameters

Parameter	Type	Default	Recommended (ICBEB/PTBXL)
`replay_buffer_size`	int	1000	150 / 200
`batch_size`	int	64	12 / 16
`actor_lr`	float	0.001	0.0008 / 0.001
`critic_lr`	float	0.002	0.0015 / 0.002
`gamma`	float	0.99	Discount factor
`tau`	float	0.001	Soft update coefficient

System Configuration Parameters

Parameter	Type	Default	Description
`seed`	int	42	Random seed for reproducibility
`device`	str	"cuda"	Device for computation ("cuda" or "cpu")
`verbose`	bool	True	Enable detailed logging output
`output_dir`	str	"./mat_hpo_logs"	Directory for saving optimization logs
`dataset_name`	str	None	Dataset identifier for logging (e.g., "ICBEB_Fold1")
`task_description`	str	None	Human-readable task description

Production Example (SPNV2 ECG Classification)

python

from MAT_HPO_LIB import FullControlHPO
import numpy as np

#  ICBEB Dataset Configuration (9-class cardiac arrhythmia)
optimizer_icbeb = FullControlHPO(
    task_type="time_series_classification",
    max_trials=30,

    # LLM Configuration
    llm_enabled=True,
    llm_model="llama3.2:3b",
    llm_base_url="http://localhost:11434",
    mixing_strategy="adaptive",              # Intelligent adaptive strategy
    alpha=0.3,                              # Initial LLM/RL mixing ratio
    slope_threshold=0.01,                   # Trigger LLM when slope < 0.01
    llm_cooldown_episodes=6,              # ICBEB: 6, PTBXL: 4
    min_episodes_before_llm=6,          # ICBEB: 6, PTBXL: 4

    # ICBEB-optimized RL parameters
    replay_buffer_size=150,              # Smaller buffer for 9-class
    batch_size=12,                        # Conservative batch size
    actor_lr=0.0008,                       # Lower learning rate
    critic_lr=0.0015,                      # Matched to ICBEB complexity

    # System Configuration (from SPNV2)
    seed=42,
    device="cuda",                        # Auto-detect CUDA
    verbose=True,
    output_dir="./mat_hpo_logs",
    dataset_name="ICBEB_Fold1",
    task_description="ECG classification on ICBEB dataset with 9 classes"
)

#  Run optimization (SPNV2 pattern)
results = optimizer_icbeb.optimize(
    X_train, y_train, X_val, y_val,
    X_test, y_test,
    custom_environment=your_environment,
    custom_space=your_hyperparameter_space
)

#  Results analysis
print(f" Best F1: {results['best_performance']['f1']:.4f}")
print(f" Best Hyperparameters: {results['best_hyperparameters']}")
print(f" LLM Usage: {results['llm_usage_stats']['success_rate']:.2%}")

Adaptive Strategy Example

python

#  Adaptive strategy - triggers LLM when RL performance plateaus
optimizer_adaptive = FullControlHPO(
    task_type="time_series_classification",
    max_trials=50,

    # Adaptive LLM strategy
    llm_enabled=True,
    mixing_strategy="adaptive",      # Performance-based triggering
    slope_threshold=0.01,                   # Trigger when slope < 0.01

    # Dataset-specific configuration
    dataset_name="PTBXL",
    task_description="5-class superclass ECG classification",

    # PTBXL-optimized parameters
    replay_buffer_size=200,              # Larger buffer for 5-class
    batch_size=16,                        # Larger batch size
    actor_lr=0.001,                        # Higher learning rate
    critic_lr=0.002                        # Faster convergence
)

#  Custom hyperparameter space (optional)
from MAT_HPO_LIB import HyperparameterSpace

custom_space = HyperparameterSpace()
# Agent 0: Problem-specific parameters
custom_space.add_continuous('focal_gamma', 1.0, 3.0, agent=0)
custom_space.add_continuous('class_weight_scale', 0.5, 2.0, agent=0)

# Agent 1: Architecture parameters
custom_space.add_discrete('hidden_size', [64, 128, 256, 512], agent=1)
custom_space.add_continuous('dropout_rate', 0.0, 0.6, agent=1)

# Agent 2: Training parameters
custom_space.add_continuous('learning_rate', 1e-5, 1e-2, agent=2)
custom_space.add_discrete('batch_size', [16, 32, 64], agent=2)

# Run with custom space
results = optimizer_adaptive.optimize(
    X_train, y_train, X_val, y_val,
    custom_space=custom_space
)

Methods

optimize()

optimize(X_train, y_train, X_val=None, y_val=None, X_test=None, y_test=None, custom_space=None, custom_environment=None) → Dict[str, Any]

Run the complete optimization process with full parameter control.

Parameters:

X_train, y_train: Training data and labels
X_val, y_val: Validation data (auto-split if None)
X_test, y_test: Test data (optional)
custom_space: Custom HyperparameterSpace (optional)
custom_environment: Custom environment (optional)

Returns:

python

{
    'best_hyperparameters': {...},            # Best found hyperparameters
    'best_performance': {
        'f1': 0.8542,                     # Best F1 score
        'accuracy': 0.8234,                 # Best accuracy
        'auc': 0.9012                      # Best AUC
    },
    'optimization_history': [...],       # Full trial history
    'llm_usage_stats': {               # LLM performance statistics
        'success_rate': 0.73,
        'average_improvement': 0.045
    },
    'agent_contributions': {           # Multi-agent analysis
        'agent_0': 0.31,                 # Shapley values
        'agent_1': 0.42,
        'agent_2': 0.27
    }
}

Advanced Configuration

python

# ️ Complete parameter control example
optimizer = FullControlHPO(
    # Basic configuration
    task_type="time_series_classification",
    max_trials=100,

    # LLM configuration
    llm_enabled=True,
    llm_model="llama3.2:3b",
    llm_base_url="http://localhost:11434",
    mixing_strategy="fixed_alpha",
    alpha=0.3,
    slope_threshold=0.01,
    llm_cooldown_episodes=5,
    min_episodes_before_llm=5,

    # Reinforcement learning configuration
    replay_buffer_size=1000,
    gamma=0.99,
    tau=0.001,
    batch_size=64,
    learning_rate=0.001,
    actor_lr=0.001,
    critic_lr=0.002,
    hidden_dim=256,

    # System configuration
    seed=42,
    device="auto",
    verbose=True,
    output_dir="./full_control_results",

    # Dataset configuration
    dataset_name="ECG_Classification",
    task_description="Multi-class cardiac arrhythmia classification",
    custom_prompt_template="""Optimize for ECG classification with focus on:
- Balanced class performance
- Robustness to noise
- Clinical interpretability"""
)

Overview

️ Class Definition

Constructor Parameters

Basic Configuration

LLM Configuration

Reinforcement Learning Parameters

System Configuration Parameters

Production Example (SPNV2 ECG Classification)

Adaptive Strategy Example

Methods

optimize()

Parameters:

Returns:

Advanced Configuration

Next Steps

LLM Strategies Guide

Complete Examples

Hyperparameter Space