How azizanlab/hardnet works
Project Type and Purpose
• This is a research‐oriented machine learning framework (“HardNet”) for constructing neural networks with built-in hard constraint enforcement.
• It includes code for dataset generation, model implementations (HardNet‐Aff, HardNet‐Cvx, various baselines), experiment orchestration, evaluation, and visualization.
File Structure Analysis
• Top-level scripts:
• hardnet_aff.py, hardnet_cvx.py – core model training entry points
• baseline_*.py – alternative methods for comparison
• test_nets.py – evaluation harness
• run_expers.sh – batch experiment runner
• exp_*.ipynb – Jupyter notebooks for interactive experiments and visualization
• datasets/ – code to generate and load different problem datasets (cbf, opt, pwc, pwcbox, pwcfull)
• utils.py & default_args.py – shared utilities and common configuration
• requirements.txt – Python dependencies
• LICENSE, README.md, .gitignore – documentation and project metadata
Key Components
A. Data Generation & Loading
• Subcomponents per problem type (cbf, opt, pwc, etc.)
• Scripts: datasets/*/make_dataset.py; problem definitions (.py)
B. Model Implementations
• HardNet modules: hardnet_aff.py, hardnet_cvx.py
• Baseline modules: baseline_nn.py, baseline_dc3.py, baseline_opt.py, baseline_cbfqp.py
• Default configuration via default_args.py
C. Experiment Orchestration
• run_expers.sh: loops over seeds & problem types, invokes Python scripts
• Command-line arguments parsed in each script
D. Evaluation & Metrics
• test_nets.py: loads trained models, computes performance statistics
• Outputs saved under expDir for later analysis
E. Visualization & Reporting
• Jupyter notebooks exp_*.ipynb: read results, generate plots and tables
F. Shared Utilities & Environment
• utils.py: data loaders, logging, metric computation
• requirements.txt → external libraries (e.g., PyTorch, NumPy)
Relationships & Data Flow
1. Data Generation → Dataset artifacts on disk
2. Training Script (hardnet_* or baseline_*)
• Reads dataset
• Applies utils for batching, logging
• Trains model → saves checkpoints & logs
3. Evaluation (test_nets.py)
• Loads checkpoints
• Computes metrics → writes summary files
4. Visualization (notebooks)
• Reads summary files
• Renders plots, tables for the paper
5. Batch Orchestration (run_expers.sh)
• Automates step 2 and 3 across multiple seeds & problem types
Architectural Patterns & Design Principles
• Modular Pipeline: clear separation of data, training, evaluation, and visualization
• Configurable via command-line arguments and default_args.py
• Reusability: shared utilities (utils.py) across scripts
• Extensibility: adding a new problem type only requires a new dataset subfolder and update to script arguments