nuaim 1.0.0

NUAIM - Black-Box Generator for Meta-Variable Optimization.

NUAIM - Black-Box Generator for Meta-Variable Optimization

NUAIM is a Python package designed for Black-Box Optimization (BBO). It acts as a black-box generator for meta-variable (or hierarchical variable) optimization, a feature that is rarely available in black-box generators. With NUAIM, you can explore and optimize complex neural network architectures and hyperparameters in a structured and extensible way.

✨ Features

• 🧠 Black-Box Generator: Generate and evaluate neural network architectures as black-box functions for optimization.
• 📊 Meta-Variable Optimization: Supports hierarchical variables, enabling optimization of both architecture and hyperparameters.
• 🔧 Flexible Hyperparameter Management: Easily customize optimizers, learning rates, and other parameters.
• 📈 Detailed Performance Metrics: Logs training time, forward pass time, and accuracy for each model.
• 🎯 Preset Configurations: Ready-to-use presets for MLPs, CNNs, Transformers, and hybrid architectures.
• 🔄 Modular Design: Clean and extensible architecture for research and experimentation.
• 📝 Rich Logging: Save results in table and JSON formats for easy analysis.
• 🚀 Easy Integration: Simple Python API for seamless integration into your workflows.

🚀 Quick Start

Installation

Install NUAIM using pip:

pip install nuaim

Basic Usage

What is Possible with sample_instance

The sample_instance method allows you to:

• Train multiple models with different configurations
• Log results in various formats (table, JSON, or both)
• Track training and forward pass times

Optional parameters for sample_instance:

• dataset_frac: Fraction of the dataset to use (default: 1)
• num_samples: Number of models to sample (default: 5)
• max_epochs: Maximum number of training epochs (default: 1000)
• filename: Name of the file to save results (default: None)
• log_dir: Directory to save logs (default: "logs")
• verbose: Whether to print progress (default: True)
• output_format: Format of the output ("table", "json", or "both", default: "both")
• track_train_time: Track training time (default: True)
• track_forward_time: Track forward pass time (default: True)
• custom_params: Custom hyperparameters (default: None)

Simple Implementation of sample_instance

from nuaim import ModelFactory

# Create a model factory with a preset configuration
factory = ModelFactory("BasicMLP")

# Train multiple models and get results
results = factory.sample_instance(
    num_samples=10,
    max_epochs=20,
    filename="experiment_results",
    log_dir="./logs",
    output_format="both",  # "table", "json", or "both"
    track_train_time=True,
    track_forward_time=True
)

print(f"Best accuracy: {results['best_accuracy']:.4f}")
print(f"Average accuracy: {results['average_accuracy']:.4f}")

What is Possible with factory.train

The factory.train method allows you to:

• Train a single model with specific hyperparameters
• Customize training parameters like epochs and verbosity
• TBD -> Append results to log file

Optional parameters for train:

• hyper_params: Dictionary of hyperparameters for the model (default: None)
• max_epochs: Maximum number of training epochs (default: 1000)
• verbose: Whether to print progress in (default: True)

Simple Implementation of factory.train

# Generate random hyperparameters for a model
hyperparams = factory.generate_random_model_dict()

# Train the model and get accuracy
accuracy = factory.train(
    hyper_params=hyperparams,
    max_epochs=10,
    verbose=True
)

print(f"Model accuracy: {accuracy:.4f}")

📖 Available Presets

NUAIM includes several built-in preset configurations for different levels of complexity:

Basic Presets

• BasicMLP: Simple multi-layer perceptron configurations
• BasicCNN: Basic convolutional neural networks
• BasicTransformer: Simple transformer architectures

Advanced Presets

• AdvancedMLP: Complex MLP with advanced optimization
• AdvancedCNN: Advanced CNN architectures
• AdvancedTransformer: Multi-head attention mechanisms

Hard Presets

• HardMLP: Complex MLP with extensive hyperparameter spaces
• HardCNN-MLP: Hybrid CNN-MLP architectures
• HardTransformer: Advanced transformer configurations

Complete Preset

• Complete: Comprehensive search space with all layer types.

🔬 Research Applications

NUAIM is ideal for:

• Black-Box Optimization (BBO): Treat neural network architectures as black-box functions for optimization.
• Meta-Variable Optimization: Optimize hierarchical variables like architecture and hyperparameters.
• Neural Architecture Search (NAS): Automate the discovery of optimal architectures.
• Hyperparameter Tuning: Systematically explore hyperparameter spaces.
• Model Benchmarking: Compare different architectures and configurations.

🤝 Contributing

We welcome contributions! Please feel free to:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ for the research community