Initial submission

.gitignore

@@ -3,5 +3,25 @@
 *.jpeg
 *.gif
 *.bmp
+*.csv
+
+
+*/.ipynb_checkpoints/*
+profile/*
+torch_profile/*
+loss_history/*
+loss_tracking/*
+**/__pycache__/**
+temp.txt
+
+# Plan files
+*[Pp][Ll][Aa][Nn]*.md
+
+# C++ build and vcpkg manifest artifacts
+cpp/build/
+cpp/build-xcode/
+cpp/build-coverage/
+cpp/vcpkg_installed/
+cpp/.vcpkg-root
+
 
-**/__pycache__/**

.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python.defaultInterpreterPath": "/Library/Frameworks/Python.framework/Versions/3.11/bin/python3"
+}

README.md

@@ -41,20 +41,21 @@ We will review submissions on a rolling basis.
  8   | Shashank Shriram  | 0.0000     | 0.3312          |  11.32      |   🏎️💥               |
 | 9    | Gabriel Del Monte  | 0.0000      | 0.3427          | 606.07      |                                                              |
 | 10    | Aleksey  Valouev| 0.0000      | 0.3577          | 118.98      |                      |        
-| 11   | Mohul Shukla    | 0.0000      | 0.5048          | 54.60s      |                      |
-| 12    | Ryan Hulke      | 0.0000      | 0.5226          | 166.24      |                      |
-| 13    | Neel  Shah      | 0.0000      | 0.5445          | 45.40       |  Zero overlaps on all tests, adaptive schedule + early stop |
-| 14   | Nawel Asgar    | 0.0000     | 0.5675          | 81.49      | Adaptive penalty scaling with cubic gradients and design-size optimization
-| 15   | Shiva Baghel     | 0.0000     | 0.5885          | 491.00      | Stable zero-overlap with balanced optimization      |
-| 16   | Vansh Jain      | 0.0000      | 0.9352          | 86.36       |                      |
-| 17    | Akash Pai       | 0.0006      | 0.4933          | 326.25s     |                      |
-| 18    | Zade Mahayni     | 0.00665     | 0.5157          |  127.4     | Will try again tomorrow |
-| 19    | Nithin Yanna    | 0.0148      | 0.5034          | 247.30s     | aggressive overlap penalty with quadratic scaling |
-| 20    | Sean Ko         | 0.0271      |  .5138          | 31.83s      | lr increase, decrease epoch, increase lambda overlap and decreased lambda wire_length + log penalty loss |
-| 21    | Keya Gohil    | 0.0155      | 0.4678         | 1513.07     | Still working |
-| 22    | Prithvi Seran   | 0.0499      | 0.4890          | 398.58      |                      |
-| 23    | partcl example  | 0.8         | 0.4             | 5           | example              |
-| 24    | Add Yours!      |             |                 |             |                      |
+| 11    | Green Table     | 0.0000      | 0.476           | 57.35       |                      |
+| 12   | Mohul Shukla    | 0.0000      | 0.5048          | 54.60s       |                      |
+| 13    | Ryan Hulke      | 0.0000      | 0.5226          | 166.24      |                      |
+| 14    | Neel  Shah      | 0.0000      | 0.5445          | 45.40       |  Zero overlaps on all tests, adaptive schedule + early stop |
+| 15   | Nawel Asgar    | 0.0000     | 0.5675          | 81.49      | Adaptive penalty scaling with cubic gradients and design-size optimization
+| 16   | Shiva Baghel     | 0.0000     | 0.5885          | 491.00      | Stable zero-overlap with balanced optimization      |
+| 17   | Vansh Jain      | 0.0000      | 0.9352          | 86.36       |                      |
+| 18    | Akash Pai       | 0.0006      | 0.4933          | 326.25s     |                      |
+| 19    | Zade Mahayni     | 0.00665     | 0.5157          |  127.4     | Will try again tomorrow |
+| 20    | Nithin Yanna    | 0.0148      | 0.5034          | 247.30s     | aggressive overlap penalty with quadratic scaling |
+| 21    | Sean Ko         | 0.0271      |  .5138          | 31.83s      | lr increase, decrease epoch, increase lambda overlap and decreased lambda wire_length + log penalty loss |
+| 22    | Keya Gohil    | 0.0155      | 0.4678         | 1513.07     | Still working |
+| 23    | Prithvi Seran   | 0.0499      | 0.4890          | 398.58      |                      |
+| 24    | partcl example  | 0.8         | 0.4             | 5           | example              |
+| 25    | Add Yours!      |             |                 |             |                      |
 
 > **To add your results:**  
 > Insert a new row in the table above with your name, overlap, wirelength, and any notes. Ensure you sort by overlap.

arg_parse_util.py

@@ -0,0 +1,245 @@
+import argparse
+
+from benchmark_test_cases import TEST_CASES_BY_ID
+from learning_rate_scheduler_util import SCHEDULER_CHOICES
+
+
+def _positive_int(value):
+    parsed_value = int(value)
+    if parsed_value < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return parsed_value
+
+
+def parse_args():
+    """Parse command line arguments for optional profiling."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--profile",
+        action="store_true",
+        help="Enable cProfile and dump results to the profile directory.",
+    )
+    parser.add_argument(
+        "--profile-tag",
+        default="",
+        help="Optional tag to include in the profile output filename.",
+    )
+    parser.add_argument(
+        "--torch-profile",
+        action="store_true",
+        help="Enable torch.profiler trace capture during training.",
+    )
+    parser.add_argument(
+        "--torch-profile-wait",
+        type=int,
+        default=1,
+        help="Number of initial training steps to skip before torch profiler warmup.",
+    )
+    parser.add_argument(
+        "--torch-profile-warmup",
+        type=int,
+        default=1,
+        help="Number of warmup steps for torch profiler.",
+    )
+    parser.add_argument(
+        "--torch-profile-active",
+        type=int,
+        default=3,
+        help="Number of active recording steps for torch profiler.",
+    )
+    parser.add_argument(
+        "--torch-profile-repeat",
+        type=int,
+        default=1,
+        help="Number of wait/warmup/active cycles to record. Use 0 to repeat until the run ends.",
+    )
+    parser.add_argument(
+        "--torch-profile-record-shapes",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable or disable input-shape recording in torch profiler.",
+    )
+    parser.add_argument(
+        "--torch-profile-memory",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable or disable memory tracking in torch profiler.",
+    )
+    parser.add_argument(
+        "--torch-profile-with-stack",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable or disable stack trace capture in torch profiler.",
+    )
+    parser.add_argument(
+        "--torch-profile-acc-events",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Accumulate profiler events across schedule cycles to avoid cycle-reset warnings.",
+    )
+    parser.add_argument(
+        "--num-epochs",
+        type=int,
+        default=1000,
+        help="Number of optimization epochs for a regular training run.",
+    )
+    parser.add_argument(
+        "--num-macros",
+        type=int,
+        default=3,
+        help="Number of macro cells to generate for a placement run.",
+    )
+    parser.add_argument(
+        "--num-std-cells",
+        type=int,
+        default=10,
+        help="Number of standard cells to generate for a placement run.",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=42,
+        help="Random seed used to generate and initialize the placement problem.",
+    )
+    parser.add_argument(
+        "--device",
+        choices=("auto", "cpu", "cuda", "mps"),
+        default="auto",
+        help="Torch device to use. 'auto' selects cuda, then mps, then cpu.",
+    )
+    parser.add_argument(
+        "--test-case-id",
+        type=int,
+        choices=sorted(TEST_CASES_BY_ID),
+        help="Optional benchmark test case to load. Overrides --num-macros, --num-std-cells, and --seed.",
+    )
+    parser.add_argument(
+        "--lr",
+        type=float,
+        default=0.1,
+        help="Learning rate for the Adam optimizer.",
+    )
+    parser.add_argument(
+        "--lambda-wirelength",
+        type=float,
+        default=3.0,
+        help="Weight applied to the wirelength term.",
+    )
+    parser.add_argument(
+        "--lambda-overlap",
+        type=float,
+        default=1.0,
+        help="Weight applied to the overlap term.",
+    )
+    parser.add_argument(
+        "--scheduler",
+        choices=SCHEDULER_CHOICES,
+        default="plateau",
+        help="Learning-rate scheduler to use during training.",
+    )
+    parser.add_argument(
+        "--scheduler-patience",
+        type=int,
+        default=50,
+        help="Patience for ReduceLROnPlateau.",
+    )
+    parser.add_argument(
+        "--scheduler-factor",
+        type=float,
+        default=0.5,
+        help="Decay factor for ReduceLROnPlateau.",
+    )
+    parser.add_argument(
+        "--scheduler-eta-min",
+        type=float,
+        default=1e-4,
+        help="Minimum learning rate for cosine annealing.",
+    )
+    parser.add_argument(
+        "--scheduler-step-size",
+        type=int,
+        default=100,
+        help="Step size in epochs for StepLR.",
+    )
+    parser.add_argument(
+        "--scheduler-gamma",
+        type=float,
+        default=0.95,
+        help="Gamma decay used by StepLR and ExponentialLR.",
+    )
+    parser.add_argument(
+        "--optuna",
+        action="store_true",
+        help="Run Optuna hyperparameter search instead of a single training run.",
+    )
+    parser.add_argument(
+        "--optuna-trials",
+        type=int,
+        default=25,
+        help="Number of Optuna trials to execute.",
+    )
+    parser.add_argument(
+        "--optuna-epochs",
+        type=int,
+        default=400,
+        help="Number of epochs per Optuna trial.",
+    )
+    parser.add_argument(
+        "--optuna-study-name",
+        default="placement_hparam_search",
+        help="Study name used by Optuna.",
+    )
+    parser.add_argument(
+        "--optuna-storage",
+        default="",
+        help="Optional Optuna storage URL, for example sqlite:///optuna.db.",
+    )
+    parser.add_argument(
+        "--track-loss-history",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable or disable loss-history collection and persistence.",
+    )
+    parser.add_argument(
+        "--track-overlap-metrics",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Enable or disable per-epoch overlap-metric collection for loss tracking.",
+    )
+    parser.add_argument(
+        "--early-stop",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable or disable overlap-first early stopping during training.",
+    )
+    parser.add_argument(
+        "--early-stop-patience",
+        type=_positive_int,
+        default=75,
+        help="Patience before stopping when overlap stops improving.",
+    )
+    parser.add_argument(
+        "--early-stop-min-delta",
+        type=float,
+        default=1e-4,
+        help="Minimum improvement required to reset early-stop patience.",
+    )
+    parser.add_argument(
+        "--early-stop-overlap-threshold",
+        type=float,
+        default=1e-4,
+        help="Treat overlap below this value as effectively zero for early stopping.",
+    )
+    parser.add_argument(
+        "--early-stop-zero-overlap-patience",
+        type=_positive_int,
+        default=25,
+        help="Extra patience after zero-overlap is reached to keep reducing wirelength.",
+    )
+    parser.add_argument(
+        "--workers",
+        type=_positive_int,
+        default=4,
+        help="Number of worker processes for test.py. Use 1 to run serially.",
+    )
+    return parser.parse_args()

benchmark_test_cases.py

@@ -0,0 +1,35 @@
+"""Shared benchmark configurations for placement test cases."""
+
+ACTIVE_TEST_CASES = [
+    # Small designs
+    (1, 2, 20, 1001),
+    (2, 3, 25, 1002),
+    (3, 2, 30, 1003),
+    # Medium designs
+    (4, 3, 50, 1004),
+    (5, 4, 75, 1005),
+    (6, 5, 100, 1006),
+    # Large designs
+    (7, 5, 150, 1007),
+    (8, 7, 150, 1008),
+    (9, 8, 200, 1009),
+    (10, 10, 2000, 1010),
+]
+
+OPTIONAL_TEST_CASES = [
+    # Realistic designs
+    (11, 10, 10000, 1011),
+    (12, 10, 100000, 1012),
+]
+
+TEST_CASES = ACTIVE_TEST_CASES + OPTIONAL_TEST_CASES
+
+TEST_CASES_BY_ID = {
+    test_id: {
+        "test_id": test_id,
+        "num_macros": num_macros,
+        "num_std_cells": num_std_cells,
+        "seed": seed,
+    }
+    for test_id, num_macros, num_std_cells, seed in TEST_CASES
+}