Project 4: Starter Code Structure

COMP 536 | Short Projects

This page gives you the repo contract for Project 4. Use it as a scaffold, not as a substitute for understanding the project.

Quick Start

From your repo root, these commands should eventually work:

python run.py test
python run.py validate
python run.py make-figures

If those three commands run cleanly, your project is already in good shape.

Graduate students should also support an HMC execution path, whether that is an extra command such as python run.py run-hmc or a clearly documented script-based workflow. The three commands above are the common baseline for everyone.

Repo Structure

Your submission should follow a structure like this:

project4_inference/
├── run.py
├── src/
│   ├── __init__.py
│   ├── cosmology.py
│   ├── likelihood.py
│   ├── mcmc.py
│   ├── diagnostics.py
│   ├── hmc.py                 # Graduate required, optional undergrad
│   └── viz.py
├── data/
│   ├── jla_mub.txt
│   └── jla_mub_covmatrix.txt
├── outputs/
│   ├── chains/
│   ├── figures/
│   └── results/
├── tests/
│   ├── test_cosmology.py
│   ├── test_mcmc.py
│   ├── test_diagnostics.py
│   └── test_hmc.py            # Graduate required, optional undergrad
├── README.md
├── research_memo.pdf
├── growth_memo.pdf
└── requirements.txt

What Each Module Owns

File	Responsibility
run.py	Thin command-line entry point
src/cosmology.py	Distance-modulus calculations and forward-model helpers
src/likelihood.py	Data loading, prior, likelihood, posterior
src/mcmc.py	Reusable Metropolis-Hastings sampler
src/diagnostics.py	Acceptance summaries, autocorrelation, ESS, split-\(\hat{R}\)
src/hmc.py	Hamiltonian Monte Carlo implementation for the graduate lane
src/viz.py	Plotting utilities used by make-figures

The big software-engineering goal is to keep the sampler code general and the cosmology code local. Do not hard-wire cosmology logic directly into the sampler.

Suggested run.py Contract

Keep run.py simple. It should dispatch to your modules rather than containing real scientific logic itself.

"""COMP 536 Project 4 command-line interface."""
import argparse
import subprocess
import sys
from pathlib import Path


def main():
    parser = argparse.ArgumentParser(
        description="COMP 536 Project 4: Bayesian inference with MCMC"
    )
    parser.add_argument(
        "command",
        choices=["test", "validate", "make-figures"],
        help="test | validate | make-figures",
    )
    args = parser.parse_args()

    Path("outputs/chains").mkdir(parents=True, exist_ok=True)
    Path("outputs/figures").mkdir(parents=True, exist_ok=True)
    Path("outputs/results").mkdir(parents=True, exist_ok=True)

    if args.command == "test":
        sys.exit(subprocess.call(["pytest", "-v"]))

    if args.command == "validate":
        # TODO: run forward-model checks and toy-Gaussian checks
        raise NotImplementedError

    if args.command == "make-figures":
        # TODO: generate final Project 4 figures
        raise NotImplementedError


if __name__ == "__main__":
    main()

Validation Requirements

Your validate command should eventually include checks like:

• forward-model sanity checks, including the worked example at \(z = 0.5\)
• toy-Gaussian Metropolis-Hastings validation
• graduate students: HMC energy or gradient sanity checks

The point of validate is to catch scientific mistakes before you spend time polishing figures.

Minimum Test Coverage

You do not need a giant test suite, but you do need a useful one.

At minimum, aim to cover:

• test_cosmology.py: boundary conditions and worked-example checks
• test_mcmc.py: toy-Gaussian recovery and acceptance behavior
• test_diagnostics.py: core diagnostic functions on small synthetic chains
• test_hmc.py: graduate lane only, gradient and energy checks

README Expectations

Your README.md should tell me:

• what problem the repo solves
• how to install dependencies
• how to run test, validate, and make-figures
• where the main outputs appear

Think of the README as the guide for a tired collaborator who just cloned your repo and wants to know how to trust your work.