Neural Network Simulator - Project Type A

Team: Spice-Devs | Course: Machine Learning (2025, Academic Year 25/26), Code: 654AA
Authors: Israel Fitsum Yohannes, Shaikh Asif Hossain
Date: 22 Jan 2026

---

Project Overview

This project implements a modular Neural Network simulator from scratch using Python and NumPy (Project Type A). It addresses two distinct machine learning challenges:

1. Classification: Solving the MONK binary classification tasks.
2. Regression: Solving the ML-CUP25 multi-target regression challenge.

The simulator features custom implementations of Multi-Layer Perceptrons (MLP), Backpropagation (MSE/MEE loss), GD with Momentum, L2 Regularization, and model selection techniques (Grid Search, Hold-out).

---

Folder Structure

Ensure your directory follows this structure before running:

project_root/
│
├── datasets/                   # Place datasets here
│   ├── cup/                    # ML-CUP25-TR.csv, ML-CUP25-TS.csv
│   └── monk/                   # monks-1.train/.test, monks-2..., monks-3...
│
├── final_model/                # Trained models (.npz) and configs (.json)
├── results/                    # Final blind test predictions (.csv)
├── plot/                       # Learning curve plots (CUP & MONK)
├── cup_hyperparameters/        # Generated grid search & top 3 configs
├── monk_hyperparameters/       # Configs for MONK tasks
├── cup_parameters/             # Internal test metrics
├── notebooks/                  # Experimentation notebooks
│
├── main.py                     # CLI Entry Point
├── monk_model.py               # Classification Model
├── cup_model.py                # Regression Model
├── grid_search.py              # Grid search
├── utils.py                    # Utilities
└── README.md                   # Project Info

---

Requirements

• Python 3.x
• Libraries:
  • numpy: Core matrix operations.
  • pandas: Data loading and CSV management.
  • matplotlib: Plotting learning curves.

Installation:

pip install numpy pandas matplotlib

How to Run

The project is controlled via a Command Line Interface (CLI) in main.py.

• 1. Open a terminal in the project root directory.
• 2. Run the script:

python main.py

• 3. Select a task from the menu:

  • Option 1 (MONK Tasks): * Trains Monk 1, 2, and 3 models.
    • Generates learning curves in plot/monk/
    • Saves final models to final_model/

  

  • Option 2 (ML-CUP Task): * Loads and shuffles CUP data (Seed=42).
    • Splits data: Train (70%), Validation (15%), Internal Test (15%).
    • Evaluates top 3 configurations and selects the best.
    • Retrains on Development set (Train+Val) and evaluates on Internal Test.
    • Performs final Blind Test prediction on full data.
    • Output: results/Spice-Devs_ML-CUP25-TS.csv (Submission File).