How higisx/recovnet works
Project Type and Purpose
• This is an open-source research codebase implementing and comparing three solution methods (Genetic Algorithm, Gurobi solver, and a deep reinforcement learning model called ReCovNet) for the Maximal Coverage Billboard Location Problem (MCBLP).
• It combines combinatorial optimization, deep learning (PyTorch/TensorFlow), and GIS data processing.
High-Level Component Analysis
• Data Layer: raw problem instances (data/MCLP_origin/*.pkl, data/real/*.shp/.csv)
• Problem Definition Layer: classes and state representations under problems/MCLP (problem_MCLP.py, state_MCLP.py)
• Algorithmic Solvers:
• GA module (Algorithm/GA.py and Billboard_MCLP_GA.ipynb)
• Gurobi solver notebooks (Billboard_MCLP_solver.ipynb)
• ReCovNet deep RL module (nets/*.py for attention_model, graph_encoder, reinforce_baselines; Billboard_MCLP_DRL.ipynb)
• Orchestration Scripts: train.py, run.py, eval.py, generalization.py, options.py
• Utilities: reusable helpers under utils/ (data loading, boolean masks, logging, common functions)
• Output & Logging:
• logs/ for TensorBoard event files
• output/ for trained model checkpoints and run configs
• results/ for evaluation outputs
Relationships and Data Flow
• Data files → data_utils → Problem classes → State objects → Solver modules
• Solver modules (GA, Gurobi, ReCovNet) invoke problem API to evaluate candidate solutions or step through episodes
• During ReCovNet training: nets/graph_encoder and attention_model take state representation → produce action distributions → env stepping via state_MCLP → training loop in train.py → checkpoints to output/ and scalars to logs/
• eval.py and generalization.py consume trained models and problem instances → produce final results under results/
• Jupyter notebooks serve as interactive entry points to launch each solver
Architectural Patterns and Design Principles
• Modular separation of concerns: data ingestion, problem modeling, solver implementations, utilities, orchestration, and evaluation
• Plugin-style solver architecture: problems/MCLP defines a solver interface, allowing GA, Gurobi, and ReCovNet to be swapped or compared
• ML training pipeline: separation between model definition (nets/), training loop (train.py), configuration (options.py), and logging (utils/log_utils.py, tensorboardX)