dlspit 1.0.0__py3-none-any.whl

dl_experiments/__init__.py

@@ -0,0 +1,56 @@
+"""
+dl_experiments
+==============
+A pip-installable collection of Deep Learning experiment modules.
+
+Quick start
+-----------
+    import dl_experiments
+    dl_experiments.main()            # run all experiments
+
+    dl_experiments.main("1a")        # run a single experiment
+    dl_experiments.main("4", "5")    # run multiple experiments
+
+    dl_experiments.list_experiments()  # see all available keys
+"""
+
+from .utils.registry import list_experiments, run_experiment
+
+__version__ = "1.0.0"
+__author__  = "Pratham"
+__all__     = ["main", "list_experiments", "run_experiment", "__version__"]
+
+
+def main(*experiments: str) -> None:
+    """
+    Orchestrate and run DL experiments.
+
+    Parameters
+    ----------
+    *experiments : str
+        Experiment keys to run (e.g. "1a", "2b", "10").
+        If none are provided, ALL experiments are run in order.
+
+    Examples
+    --------
+    >>> import dl_experiments
+    >>> dl_experiments.main()         # run all
+    >>> dl_experiments.main("1a")     # run only Exp 1a
+    >>> dl_experiments.main("4","5")  # run Exp 4 and 5
+    """
+    keys = list(experiments) if experiments else list_experiments()
+
+    print("=" * 60)
+    print("  Deep Learning Experiments Suite")
+    print(f"  Running: {', '.join(keys)}")
+    print("=" * 60)
+
+    for key in keys:
+        try:
+            run_experiment(key)
+        except Exception as exc:          # noqa: BLE001
+            print(f"\n  [ERROR] Experiment {key!r} failed: {exc}")
+
+    print("\n" + "=" * 60)
+    print("  All done!")
+    print("=" * 60)

dl_experiments/__main__.py

@@ -0,0 +1,40 @@
+"""
+Allows:  python -m dl_experiments [exp_keys ...]
+"""
+import argparse
+import sys
+
+from . import list_experiments, main
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(
+        prog="dl_experiments",
+        description="Run Deep Learning experiment modules.",
+    )
+    parser.add_argument(
+        "experiments",
+        nargs="*",
+        metavar="EXP",
+        help=(
+            "Experiment keys to run (e.g. 1a 2b 10). "
+            f"Available: {', '.join(list_experiments())}. "
+            "Omit to run ALL."
+        ),
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List available experiment keys and exit.",
+    )
+    args = parser.parse_args()
+
+    if args.list:
+        print("Available experiments:", ", ".join(list_experiments()))
+        sys.exit(0)
+
+    main(*args.experiments)
+
+
+if __name__ == "__main__":
+    cli()

dl_experiments/experiments/__init__.py

@@ -0,0 +1,32 @@
+"""DL experiment modules."""
+from . import (
+    exp1a_mcculloch_pitts,
+    exp1b_mlp_binary,
+    exp2a_activations,
+    exp2b_backprop_mnist,
+    exp3_regularisation,
+    exp4_cnn,
+    exp5_resnet,
+    exp6_rnn,
+    exp7_lstm,
+    exp8_transformer,
+    exp9_gan,
+    exp9b_vae,
+    exp10_transfer,
+)
+
+__all__ = [
+    "exp1a_mcculloch_pitts",
+    "exp1b_mlp_binary",
+    "exp2a_activations",
+    "exp2b_backprop_mnist",
+    "exp3_regularisation",
+    "exp4_cnn",
+    "exp5_resnet",
+    "exp6_rnn",
+    "exp7_lstm",
+    "exp8_transformer",
+    "exp9_gan",
+    "exp9b_vae",
+    "exp10_transfer",
+]

dl_experiments/experiments/exp10_transfer.py

@@ -0,0 +1,220 @@
+import numpy as np
+
+# =============================================================================
+# EXPERIMENT 10: Transfer Learning with MobileNetV2 on CIFAR-10
+# =============================================================================
+#
+# THEORY:
+# Transfer Learning reuses a neural network pre-trained on a large dataset
+# as a starting point for a new, related task.
+# This dramatically reduces training time and data requirements.
+#
+# ---- Why Transfer Learning? ----
+# Training deep CNNs from scratch requires:
+#   - Millions of labeled images
+#   - Days/weeks of GPU compute
+# Transfer Learning solves this: a model pre-trained on ImageNet already knows
+# how to detect edges, textures, shapes, and high-level objects.
+# We just need to adapt the FINAL layers to our specific classes.
+#
+# ---- MobileNetV2 ----
+# Lightweight CNN architecture designed for efficiency on mobile/edge devices.
+# Pre-trained on ImageNet: 1.2 million images, 1000 classes.
+# Key innovation: Depthwise Separable Convolutions
+#   - Standard Conv: applies filter across all channels simultaneously
+#   - Depthwise Conv: applies ONE filter per channel (much fewer parameters)
+#   - Pointwise Conv: 1x1 convolution to combine channels
+#   - Result: ~8-9x fewer parameters with similar accuracy vs standard Conv
+#
+# ---- Transfer Learning Strategy (2 Phases) ----
+#
+# Phase 1 - Feature Extraction (Frozen Base):
+#   base_model.trainable = False
+#   Only the new Dense(10, softmax) head is trained.
+#   The pre-trained MobileNetV2 features are used as fixed feature extractors.
+#   Fast and safe: ImageNet knowledge is preserved.
+#
+# Phase 2 - Fine-Tuning (Unfrozen):
+#   base_model.trainable = True
+#   ALL layers are trainable, but with a very small learning rate (1e-5).
+#   The entire network adapts to the new domain (CIFAR-10).
+#   Small lr prevents catastrophic forgetting of pre-trained features.
+#
+# ---- preprocess_input (MobileNetV2 Preprocessing) ----
+# MobileNetV2 was trained with specific pixel normalization:
+#   preprocess_input scales pixels from [0,255] to [-1, 1]
+# MUST use this for correct behavior with pre-trained MobileNetV2 weights.
+#
+# ---- Dataset: CIFAR-10 (built-in, no external download needed) ----
+# 60,000 color images (32x32 RGB) in 10 classes:
+#   airplane, automobile, bird, cat, deer, dog, frog, horse, ship, truck
+# 2,000 training samples used here for speed.
+#
+# ---- GlobalAveragePooling2D ----
+# Converts (7, 7, 1280) feature maps from MobileNetV2 base -> (1280,) vector.
+# More efficient than Flatten: fewer parameters, less overfitting.
+#
+# ---- Evaluation Metrics ----
+# Classification Report: Precision, Recall, F1-score per class
+#   Precision = TP / (TP + FP): of all predicted positive, how many are correct?
+#   Recall    = TP / (TP + FN): of all actual positive, how many did we find?
+#   F1-score  = 2 * (P * R) / (P + R): harmonic mean of precision and recall
+#
+# =============================================================================
+# IF YOUR OWN IMAGE DATASET (changing from CIFAR-10):
+#
+# Option A: Images in folders (recommended):
+#   Replace the CIFAR-10 loading block with:
+#
+#   IMG_SIZE = (96, 96)  # MobileNetV2 min is 32x32, recommended 96x96+
+#   train_dataset = tf.keras.preprocessing.image_dataset_from_directory(
+#       "path/to/your/train_images/",   # Each subfolder = one class
+#       image_size=IMG_SIZE,
+#       batch_size=BATCH_SIZE
+#   )
+#   test_dataset = tf.keras.preprocessing.image_dataset_from_directory(
+#       "path/to/your/test_images/",
+#       image_size=IMG_SIZE,
+#       batch_size=BATCH_SIZE
+#   )
+#   class_names = train_dataset.class_names  # Auto-detected from folder names
+#
+# 🔴 CHANGE 1: Number of output classes
+#       Dense(num_classes, activation='softmax')
+#       loss='sparse_categorical_crossentropy'
+#
+# 🔴 CHANGE 2: EPOCHS - increase for small datasets (10-20+)
+# =============================================================================
+
+
+def run():
+    print("\n=== Exp 10: Transfer Learning with MobileNetV2 on CIFAR-10 ===")
+
+    try:
+        import tensorflow as tf
+        from tensorflow.keras.applications import MobileNetV2
+        from tensorflow.keras.applications.mobilenet_v2 import preprocess_input
+        from tensorflow.keras import layers, models
+    except ImportError:
+        print("  [SKIP] tensorflow not installed. Install with: pip install tensorflow")
+        return
+
+    try:
+        from sklearn.metrics import classification_report, confusion_matrix
+    except ImportError:
+        print("  [SKIP] scikit-learn not installed. Install with: pip install scikit-learn")
+        return
+
+    # ==============================
+    # 1. PARAMETERS
+    # ==============================
+    # MobileNetV2 requires at least 32x32; using 96x96 is faster than 224x224
+    IMG_SIZE   = (96, 96)
+    BATCH_SIZE = 32
+    EPOCHS     = 3
+    N_TRAIN    = 2000   # Use subset for speed; increase for better accuracy
+
+    CLASS_NAMES = [
+        'airplane', 'automobile', 'bird', 'cat', 'deer',
+        'dog', 'frog', 'horse', 'ship', 'truck'
+    ]
+
+    # ==============================
+    # 2. LOAD & PREPROCESS CIFAR-10
+    # ==============================
+    (x_train, y_train), (x_test, y_test) = tf.keras.datasets.cifar10.load_data()
+
+    # Use a small subset for speed
+    x_train, y_train = x_train[:N_TRAIN], y_train[:N_TRAIN]
+    x_test,  y_test  = x_test[:500],      y_test[:500]
+
+    # Resize images from 32x32 to IMG_SIZE for MobileNetV2
+    x_train = tf.image.resize(x_train.astype("float32"), IMG_SIZE)
+    x_test  = tf.image.resize(x_test.astype("float32"),  IMG_SIZE)
+
+    # MobileNetV2-specific preprocessing: scales pixels to [-1, 1]
+    x_train = preprocess_input(x_train)
+    x_test  = preprocess_input(x_test)
+
+    # Flatten labels from (N,1) -> (N,)
+    y_train = y_train.flatten()
+    y_test  = y_test.flatten()
+
+    # ==============================
+    # 3. MODEL (TRANSFER LEARNING)
+    # ==============================
+    # Load MobileNetV2 pre-trained on ImageNet
+    # include_top=False: exclude the final 1000-class Dense layer
+    base_model = MobileNetV2(
+        input_shape=(IMG_SIZE[0], IMG_SIZE[1], 3),
+        include_top=False,
+        weights='imagenet'
+    )
+
+    # Phase 1: FREEZE the base model
+    base_model.trainable = False
+
+    model = models.Sequential([
+        base_model,                              # Pre-trained MobileNetV2 feature extractor
+        layers.GlobalAveragePooling2D(),         # Spatial average: (7,7,1280) -> (1280,)
+        layers.Dense(10, activation='softmax')   # 10-class CIFAR-10 output
+    ])
+
+    # ==============================
+    # 4. COMPILE (Phase 1)
+    # ==============================
+    model.compile(
+        optimizer='adam',
+        loss='sparse_categorical_crossentropy',
+        metrics=['accuracy']
+    )
+
+    # ==============================
+    # 5. TRAIN PHASE 1 (Feature Extraction)
+    # ==============================
+    print("\n--- Phase 1: Feature Extraction (frozen base) ---")
+    model.fit(
+        x_train, y_train,
+        validation_data=(x_test, y_test),
+        epochs=EPOCHS,
+        batch_size=BATCH_SIZE,
+        verbose=1
+    )
+
+    # ==============================
+    # 6. FINE-TUNING (Phase 2)
+    # ==============================
+    base_model.trainable = True   # Unfreeze all layers
+
+    model.compile(
+        optimizer=tf.keras.optimizers.Adam(1e-5),  # Very small lr to preserve features
+        loss='sparse_categorical_crossentropy',
+        metrics=['accuracy']
+    )
+
+    print("\n--- Phase 2: Fine-Tuning (unfrozen, lr=1e-5) ---")
+    model.fit(
+        x_train, y_train,
+        validation_data=(x_test, y_test),
+        epochs=2,
+        batch_size=BATCH_SIZE,
+        verbose=1
+    )
+
+    # ==============================
+    # 7. EVALUATION
+    # ==============================
+    y_pred_probs = model.predict(x_test, verbose=0)
+    y_pred = np.argmax(y_pred_probs, axis=1)
+
+    print("\nClassification Report:")
+    print(classification_report(y_test, y_pred, target_names=CLASS_NAMES))
+
+    cm = confusion_matrix(y_test, y_pred)
+    print("Confusion Matrix (rows=Actual, cols=Predicted):")
+    # Print header
+    header = "       " + "  ".join(f"{n[:4]:>4}" for n in CLASS_NAMES)
+    print(header)
+    for i, row in enumerate(cm):
+        row_str = "  ".join(f"{v:>4}" for v in row)
+        print(f"{CLASS_NAMES[i][:7]:<7}  {row_str}")

dl_experiments/experiments/exp1a_mcculloch_pitts.py

@@ -0,0 +1,94 @@
+# =============================================================================
+# EXPERIMENT 1a: McCulloch-Pitts (MP) Neuron Model
+# =============================================================================
+#
+# THEORY:
+# The McCulloch-Pitts (MP) Neuron (1943) is the earliest mathematical model
+# of a biological neuron. It is a simple binary threshold unit.
+#
+# How it works:
+#   - Takes binary inputs (0 or 1)
+#   - Each input is multiplied by a weight (can be +1 for excitatory or -1 for inhibitory)
+#   - Computes a weighted sum: net = w1*x1 + w2*x2 + ...
+#   - Applies a threshold function: output = 1 if net >= theta, else 0
+#
+# Limitations:
+#   - Weights and threshold (theta) are FIXED (not learned automatically)
+#   - Only works with binary inputs and binary outputs
+#   - Cannot represent continuous / real-valued data
+#
+# This experiment implements XOR and XNOR using multi-layer MP neurons,
+# demonstrating that non-linear functions need multiple neurons (layers).
+#
+# XOR Truth Table:    XNOR Truth Table:
+#   0,0 -> 0            0,0 -> 1
+#   0,1 -> 1            0,1 -> 0
+#   1,0 -> 1            1,0 -> 0
+#   1,1 -> 0            1,1 -> 1
+#
+# =============================================================================
+# IF CSV DATA IS GIVEN:
+# This code does NOT use any dataset (it uses hardcoded logic).
+# But if you want to test MP neuron on binary inputs from a CSV file:
+#
+#   import pandas as pd
+#   df = pd.read_csv('your_data.csv')
+#   # CSV must have columns for inputs and expected output, e.g.:
+#   # x1, x2, label
+#   # 0,  0,   0
+#   # 0,  1,   1
+#   inputs = list(zip(df['x1'], df['x2']))
+#   # Then call mp_neuron() or xor() / xnor() for each row
+#   # NOTE: MP neuron only works with binary (0/1) inputs.
+#   #       If your CSV has continuous values, you must binarize them first:
+#   #       e.g., x1 = 1 if x1 > threshold else 0
+# =============================================================================
+
+
+def run():
+    print("\n=== Exp 1a: McCulloch-Pitts Neuron (XOR & XNOR) ===")
+
+    # Core MP Neuron function
+    # x1, x2   : binary inputs (0 or 1)
+    # w1, w2   : weights (positive = excitatory, negative = inhibitory)
+    # theta    : threshold - if weighted sum >= theta, neuron fires (output=1)
+    def mp_neuron(x1, x2, w1, w2, theta):
+        # Compute weighted sum of inputs
+        # If the sum meets or exceeds the threshold, neuron fires (outputs 1)
+        return 1 if (w1 * x1 + w2 * x2) >= theta else 0
+
+    # XOR Gate using 2 MP neurons in hidden layer + 1 output neuron
+    # XOR is a non-linearly separable function -> needs multiple MP neurons
+    def xor(x1, x2):
+        # h1 fires when x1=1, x2=0  (x1 ON, x2 inhibitory)
+        h1 = mp_neuron(x1, x2, 1, -1, 1)
+
+        # h2 fires when x1=0, x2=1  (x2 ON, x1 inhibitory)
+        h2 = mp_neuron(x1, x2, -1, 1, 1)
+
+        # Output fires when either h1 OR h2 fires (but not both -> XOR)
+        y = mp_neuron(h1, h2, 1, 1, 1)
+        return y
+
+    # XNOR Gate using 2 MP neurons in hidden layer + 1 output neuron
+    # XNOR is the complement of XOR: outputs 1 when both inputs are same
+    def xnor(x1, x2):
+        # h1 fires when both x1=1 AND x2=1 (requires both: threshold=2)
+        h1 = mp_neuron(x1, x2, 1, 1, 2)
+
+        # h2 fires when both x1=0 AND x2=0 (negative weights, threshold=0)
+        # -1*0 + -1*0 = 0 >= 0 -> fires; -1*1 + -1*0 = -1 < 0 -> doesn't fire
+        h2 = mp_neuron(x1, x2, -1, -1, 0)
+
+        # Output fires when either h1 OR h2 fires
+        y = mp_neuron(h1, h2, 1, 1, 1)
+        return y
+
+    # All possible binary input combinations
+    inputs = [(0, 0), (0, 1), (1, 0), (1, 1)]
+
+    # Test both gates on all input combinations and print results
+    print(f"{'x1':>4} {'x2':>4} {'XOR':>6} {'XNOR':>6}")
+    print("-" * 24)
+    for x1, x2 in inputs:
+        print(f"{x1:>4} {x2:>4} {xor(x1, x2):>6} {xnor(x1, x2):>6}")

dl_experiments/experiments/exp1b_mlp_binary.py

@@ -0,0 +1,113 @@
+# =============================================================================
+# EXPERIMENT 1b: Multi-Layer Perceptron (MLP) for Binary Classification
+# =============================================================================
+#
+# THEORY:
+# A Multi-Layer Perceptron (MLP) is a fully-connected feedforward neural network.
+# It extends the MP Neuron by LEARNING the weights automatically via backpropagation.
+#
+# Architecture used here:
+#   Input Layer  : 2 neurons (for 2 input features x1, x2)
+#   Hidden Layer : 8 neurons with ReLU activation
+#   Output Layer : 1 neuron with Sigmoid activation (binary output)
+#
+# Key Concepts:
+#   - ReLU (Rectified Linear Unit): f(x) = max(0, x)
+#       Helps avoid vanishing gradient; most common hidden-layer activation.
+#   - Sigmoid: f(x) = 1 / (1 + e^(-x))
+#       Squashes output to (0, 1) -> ideal for binary classification probability.
+#   - Binary Cross-Entropy Loss: measures error between predicted probability
+#       and true binary label (0 or 1).
+#   - Adam Optimizer: adaptive learning rate optimizer; combines momentum and
+#       RMSProp. Works well in practice without much tuning.
+#
+# Dataset here is XNOR truth table (manual, hardcoded):
+#   Inputs : X = [[0,0],[1,0],[0,1],[1,1]]
+#   Labels : y = [1, 0, 0, 1]   <- XNOR pattern
+#
+# =============================================================================
+# IF CSV DATA IS GIVEN (Binary Classification):
+#
+#   import pandas as pd
+#   df = pd.read_csv('your_data.csv')
+#   # Your CSV should look like:
+#   #  feature1, feature2, label
+#   #  0.5,      1.2,      1
+#   #  3.1,      0.8,      0
+#
+#   X = df[['feature1', 'feature2']].values   # shape: (n_samples, 2)
+#   y = df['label'].values                     # shape: (n_samples,)
+#
+#   # If you have MORE than 2 features, change input_shape accordingly:
+#   #   input_shape = (number_of_features,)
+#   # e.g., if 5 features: input_shape = (5,)
+#
+#   # If you have more than 2 CLASSES, change:
+#   #   - Output layer: Dense(num_classes, activation='softmax')
+#   #   - Loss: 'sparse_categorical_crossentropy'
+#   #   - Labels y: integer class indices (0, 1, 2, ..., num_classes-1)
+#
+#   # Then replace the X and y definitions below with the above.
+# =============================================================================
+
+import numpy as np
+
+
+def run():
+    print("\n=== Exp 1b: MLP for Binary Classification (XNOR) ===")
+
+    try:
+        import tensorflow as tf
+    except ImportError:
+        print("  [SKIP] tensorflow not installed. Install with: pip install tensorflow")
+        return
+
+    # ------------------------------------------------------------------
+    # Dataset: XNOR truth table (binary inputs -> binary output)
+    # X: input pairs, y: expected XNOR output
+    # ------------------------------------------------------------------
+    X = np.array([[0, 0], [1, 0], [0, 1], [1, 1]])   # shape: (4, 2)
+    y = np.array([1, 0, 0, 1])                         # shape: (4,) -> XNOR labels
+
+    # ------------------------------------------------------------------
+    # Model Definition: Sequential MLP
+    # ------------------------------------------------------------------
+    model = tf.keras.Sequential([
+        # Hidden layer: 8 neurons, ReLU activation
+        # input_shape=(2,) means 2 input features
+        # CHANGE input_shape if your CSV has different number of features
+        tf.keras.layers.Dense(8, activation="relu", input_shape=(2,)),
+
+        # Output layer: 1 neuron, Sigmoid -> outputs probability in (0,1)
+        # For binary classification: threshold at 0.5 to get 0 or 1
+        tf.keras.layers.Dense(1, activation="sigmoid")
+    ])
+
+    # ------------------------------------------------------------------
+    # Compile: define optimizer, loss, and evaluation metric
+    # ------------------------------------------------------------------
+    model.compile(
+        optimizer='adam',                   # Adam: adaptive gradient optimizer
+        loss='binary_crossentropy',         # Standard loss for binary classification
+        metrics=['accuracy']                # Track accuracy during training
+    )
+
+    # ------------------------------------------------------------------
+    # Train the model on dataset X, y for 200 epochs (silent)
+    # ------------------------------------------------------------------
+    model.fit(X, y, epochs=200, verbose=0)
+
+    # ------------------------------------------------------------------
+    # Predict: get raw sigmoid probabilities and convert to binary labels
+    # ------------------------------------------------------------------
+    pred = model.predict(X, verbose=0)
+    pred_binary = (pred > 0.5).astype(int).flatten()
+
+    print(f"{'x1':>4} {'x2':>4} {'Label':>7} {'Pred':>6} {'Prob':>8}")
+    print("-" * 35)
+    for i in range(len(X)):
+        x1, x2 = X[i]
+        print(f"{int(x1):>4} {int(x2):>4} {y[i]:>7} {pred_binary[i]:>6} {pred[i][0]:>8.4f}")
+
+    acc = float((pred_binary == y).mean())
+    print(f"\nFinal accuracy: {acc*100:.1f}%")