Files
mcm-mfp/CLAUDE.md
2026-01-17 11:26:04 +08:00

3.8 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a mathematical modeling competition (MCM/ICM) project for the 2021 "Where and When" problem about optimizing mobile food distribution for the Food Bank of the Southern Tier (FBST). The project involves analyzing 2019 visit data from 70 regular MFP sites to design an optimized 2021 visit schedule.

Problem Context

  • Organization: FBST serves six counties in New York State
  • Service: Mobile Food Pantry (MFP) program delivering nutritious food to underserved communities
  • Capacity: 3 trucks available, typically 2 operational per day
  • Visit specs: Each visit lasts ~2 hours, serves 200-250 families
  • 2019 data: 70 regular sites with 722 total visits
  • Goal: Optimize 2021 schedule based on 2019 statistics

Tasks (Complete 3/4)

  • Task 1: Propose effective & fair schedule for all 70 sites (frequency based on demand)
  • Task 2 OR 3: Either (a) reduce optimized site locations, or (b) schedule for longer client travel feasibility; OR implement two-site truck routing
  • Task 4: 1-page executive summary

Data Sources

  • prob/MFP Regular Sites 2019.xlsx - Main dataset with:
    • Site Name, latitude, longitude
    • Number of Visits in 2019
    • Average Demand per Visit
    • StDev(Demand per Visit)
  • prob/full_bilingual.md - Bilingual problem statement (English/Chinese)

Code Structure

Analysis Scripts

  • analyze_visits.py - Correlation and regression analysis

    • Reads Excel data using pandas
    • Pearson correlation between average demand and visit frequency
    • Linear regression analysis
    • Standard deviation analysis (coefficient of variation)
    • Multi-variate regression (demand + std_dev)
    • Outputs: analysis_result.png
  • plot_sites.py - Geographic visualization

    • Reads Excel data and plots site locations
    • Color-codes by visit frequency using viridis colormap
    • Latitude correction for proper aspect ratio
    • Outputs: sites_map.png

Dependencies

# Core libraries
pandas numpy scipy matplotlib scikit-learn

# Excel support
openpyxl xlrd

Running Analysis

# Run visit frequency analysis
python analyze_visits.py

# Generate geographic map
python plot_sites.py

Latex Template

Location: latex-template/

cd latex-template
xelatex mcmthesis-demo.tex    # Compile once
biber mcmthesis-demo          # Run references
xelatex mcmthesis-demo.tex    # Compile twice more

Key template elements:

  • Document class: mcmthesis with MCM/ICM formatting
  • Uses APA bibliography style with biblatex/biber
  • Includes abstract, table of contents, sections, appendices
  • "Report on Use of AI" section required per competition rules
  • Problem selection: Set problem=\textcolor{red}{A}/{B}/{C}/{D}/{E}/{F} in mcmsetup

Key Modeling Considerations

From analyze_visits.py findings:

  • Low correlation between average demand per visit and total visit frequency
  • Scheduling decisions should consider both mean demand AND demand variability (standard deviation)
  • The coefficient of variation (CV = std_dev/mean) helps identify sites with irregular attendance

Fairness vs Effectiveness Metrics

  • Effectiveness: Overall service quality across all clients
  • Fairness: Equity in service distribution across different communities
  • Avoid concentration of visits in few high-demand areas

Scheduling Constraints

  • Max 2 trucks per day
  • Each visit ~2 hours
  • Schedule published months in advance
  • No pre-registration required (post-pandemic model)

Development Notes

  • Python scripts use Chinese comments for analysis context
  • Data file paths relative to project root
  • Visualizations saved to root directory
  • Latex compilation requires XeLaTeX (for Chinese support in CTeX)