|
| 1 | +# Learning to Control Class - Course Repository |
| 2 | + |
| 3 | +Special Topics on Optimal Control and Learning — Fall 2025 (ISYE 8803 VAN) at Georgia Institute of Technology. This is a Julia-based educational repository containing course materials delivered through interactive Pluto notebooks covering optimal control, numerical optimization, reinforcement learning, and PDE-constrained optimization. |
| 4 | + |
| 5 | +**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Repository Setup and Environment |
| 10 | +- **Clone and navigate**: `git clone <repo-url> && cd LearningToControlClass` |
| 11 | +- **Julia requirement**: Julia 1.10+ required. Check with `julia --version` |
| 12 | +- **Install Julia**: Download from https://julialang.org/downloads (use current stable release for your OS) |
| 13 | + |
| 14 | +### Documentation Build |
| 15 | +- **CRITICAL**: Documentation builds quickly but package installs can be slow |
| 16 | +- **Setup symlink for docs** (required first time): |
| 17 | + ```bash |
| 18 | + ln -s ../../class01 docs/src/class01 |
| 19 | + ``` |
| 20 | +- **Build docs**: |
| 21 | + ```bash |
| 22 | + cd docs/ |
| 23 | + julia --project=. -e 'using Pkg; Pkg.instantiate()' # Takes 60-90 seconds. NEVER CANCEL. |
| 24 | + cd .. # Return to repo root |
| 25 | + julia --project=docs/ docs/make.jl # Takes ~10 seconds |
| 26 | + ``` |
| 27 | +- **TIMEOUT WARNING**: Use 120+ second timeout for `Pkg.instantiate()` - network issues can cause delays |
| 28 | +- **Documentation output**: Generated in `docs/build/` directory |
| 29 | + |
| 30 | +### Working with Class Materials |
| 31 | +- **Each class has its own Julia environment** in `classXX/` folders with `Project.toml` and `Manifest.toml` files |
| 32 | +- **Install class dependencies**: |
| 33 | + ```bash |
| 34 | + cd class01/ # or any other classXX folder |
| 35 | + julia --project=. -e 'using Pkg; Pkg.instantiate()' |
| 36 | + ``` |
| 37 | +- **CRITICAL TIMING**: Package installation takes 15-30 minutes on first run. NEVER CANCEL. Set timeout to 45+ minutes. |
| 38 | +- **Network limitations**: If package downloads fail due to network issues, document the limitation but continue with available functionality |
| 39 | + |
| 40 | +### Running Pluto Notebooks (Interactive Learning Environment) |
| 41 | +- **Start Pluto server**: |
| 42 | + ```bash |
| 43 | + cd class01/ # or target class folder |
| 44 | + julia --project=. |
| 45 | + julia> using Pluto |
| 46 | + julia> Pluto.run() |
| 47 | + ``` |
| 48 | +- **Pluto startup time**: ~30-60 seconds. NEVER CANCEL. |
| 49 | +- **Access**: Pluto opens web interface typically at http://localhost:1234 |
| 50 | +- **Open existing notebooks**: Enter full path to `.jl` file (e.g., `background_materials/math_basics.jl`) in Pluto interface |
| 51 | +- **Available notebooks per class**: `*.jl` files in `background_materials/` and class root directories |
| 52 | + |
| 53 | +### Repository Structure Navigation |
| 54 | +``` |
| 55 | +/ |
| 56 | +├── .github/workflows/documentation.yml # CI for docs |
| 57 | +├── docs/ # Documentation generation |
| 58 | +│ ├── Project.toml # Docs dependencies |
| 59 | +│ └── make.jl # Build script |
| 60 | +├── classXX/ # Individual class materials |
| 61 | +│ ├── Project.toml # Class-specific dependencies |
| 62 | +│ ├── Manifest.toml # Locked dependency versions |
| 63 | +│ ├── classXX.md # Class overview and instructions |
| 64 | +│ ├── background_materials/ # Pluto notebooks (.jl files) |
| 65 | +│ └── *.html # Pre-generated notebook exports |
| 66 | +└── README.md # Course overview |
| 67 | +``` |
| 68 | + |
| 69 | +## Validation and Testing |
| 70 | + |
| 71 | +### Manual Validation Scenarios |
| 72 | +**ALWAYS test these workflows after making changes:** |
| 73 | + |
| 74 | +1. **Basic Julia functionality**: |
| 75 | + ```bash |
| 76 | + julia -e 'println("Julia version: ", VERSION); using LinearAlgebra; println("Basic packages work!")' |
| 77 | + ``` |
| 78 | + |
| 79 | +2. **Documentation build validation**: |
| 80 | + ```bash |
| 81 | + # Ensure symlink exists first: |
| 82 | + ln -s ../../class01 docs/src/class01 # Only needed once |
| 83 | + julia --project=docs/ docs/make.jl |
| 84 | + # Should complete in ~10 seconds without errors |
| 85 | + # Verify docs/build/ directory contains generated HTML |
| 86 | + ``` |
| 87 | + |
| 88 | +4. **Class environment validation** (may fail due to network limitations): |
| 89 | + ```bash |
| 90 | + cd class01/ |
| 91 | + julia --project=. -e 'using Pkg; Pkg.status()' |
| 92 | + # Should show all required packages listed (some may not be installed due to network issues) |
| 93 | + # Package loading may fail with "Artifact not found" errors - this is expected |
| 94 | + ``` |
| 95 | + |
| 96 | +4. **Pluto notebook basic test** (may fail due to network limitations): |
| 97 | + ```bash |
| 98 | + cd class01/ |
| 99 | + julia --project=. -e 'using Pluto; println("Pluto loaded successfully!")' |
| 100 | + # May fail with "Artifact not found" errors due to network restrictions |
| 101 | + # Document the limitation but continue with available functionality |
| 102 | + ``` |
| 103 | + |
| 104 | +### Common Validation Commands |
| 105 | +- **Check Julia installation**: `julia --version` |
| 106 | +- **Package status**: `julia --project=. -e 'using Pkg; Pkg.status()'` |
| 107 | +- **Precompile packages**: `julia --project=. -e 'using Pkg; Pkg.precompile()'` |
| 108 | +- **Documentation links**: Verify generated links in `docs/build/index.html` |
| 109 | + |
| 110 | +## Development Workflow |
| 111 | + |
| 112 | +### Making Changes to Course Materials |
| 113 | +- **Edit Pluto notebooks**: Modify `.jl` files directly or through Pluto interface |
| 114 | +- **Update documentation**: Modify markdown files in class directories |
| 115 | +- **Regenerate docs**: Run `julia --project=docs/ docs/make.jl` after changes |
| 116 | +- **No traditional tests**: This is educational content - validation is through successful notebook execution |
| 117 | + |
| 118 | +### Git Workflow Notes |
| 119 | +- **Standard Git commands**: `git add`, `git commit`, `git push` work normally |
| 120 | +- **GitHub Actions**: Documentation automatically builds on push to main branch |
| 121 | +- **Class materials**: Each class is self-contained with its own dependencies |
| 122 | + |
| 123 | +## Common Issues and Troubleshooting |
| 124 | + |
| 125 | +### Expected Network Limitations |
| 126 | +- **Package downloads frequently fail**: Due to firewall/network restrictions accessing pkg.julialang.org and GitHub binary artifacts |
| 127 | +- **"Artifact not found" errors**: Common for packages requiring binary dependencies (OpenSSL, graphics libraries, etc.) |
| 128 | +- **Pluto may not fully load**: Depends on HTTP package which requires network artifacts |
| 129 | +- **Document these limitations**: Note which specific packages fail but continue with available functionality |
| 130 | + |
| 131 | +### Package Installation Issues |
| 132 | +- **Network timeouts**: Common due to downloading large binary dependencies |
| 133 | +- **Manifest version warnings**: Normal when using different Julia versions than original (1.10.5 vs 1.11.6) |
| 134 | +- **Failed downloads**: Document which packages fail but continue with available functionality |
| 135 | + |
| 136 | +### Performance Expectations |
| 137 | +- **Documentation build**: ~10 seconds - NEVER CANCEL |
| 138 | +- **Package installation**: 15-30 minutes first time - NEVER CANCEL, timeout 45+ minutes |
| 139 | +- **Pluto startup**: 30-60 seconds - NEVER CANCEL (when it works) |
| 140 | +- **Julia REPL startup**: 5-10 seconds |
| 141 | + |
| 142 | +### Repository Limitations |
| 143 | +- **No comprehensive test suite**: Educational repository focused on interactive learning |
| 144 | +- **No linting/formatting tools**: Julia ecosystem tools available but not configured |
| 145 | +- **Network dependencies**: Some functionality requires internet access for package downloads |
| 146 | +- **Interactive UI testing**: Cannot fully test Pluto web interface in automated environments |
| 147 | + |
| 148 | +## Key Learning Workflows |
| 149 | + |
| 150 | +### File Types and Purposes |
| 151 | +- **`.jl` files**: Pluto notebook source files (can be read as text, edited directly) |
| 152 | +- **`.html` files**: Pre-generated static exports of notebooks (viewable in browser) |
| 153 | +- **`.md` files**: Course documentation and instructions |
| 154 | +- **`Project.toml`**: Julia package requirements for each class |
| 155 | +- **`Manifest.toml`**: Exact package versions (locked dependencies) |
| 156 | + |
| 157 | +### For Students/Users |
| 158 | +1. **Setup**: Install Julia → Clone repo → Navigate to class folder → Install dependencies |
| 159 | +2. **Learning**: Start Pluto → Open notebook → Work through interactive exercises |
| 160 | +3. **Exploration**: Try different classes, modify examples, experiment with code |
| 161 | +4. **Fallback**: If Pluto fails, read `.jl` files directly or view `.html` exports |
| 162 | + |
| 163 | +### For Contributors/Developers |
| 164 | +1. **Content changes**: Edit `.jl` notebooks or `.md` documentation |
| 165 | +2. **Build verification**: Regenerate docs to ensure no broken links |
| 166 | +3. **Cross-class testing**: Verify changes don't break other class environments |
| 167 | +4. **Documentation updates**: Keep class instructions synchronized with changes |
| 168 | + |
| 169 | +**REMEMBER**: This is primarily an educational repository. Success is measured by students being able to run interactive notebooks and learn optimal control concepts, not by traditional software metrics like test coverage or build speed. |
0 commit comments