|
| 1 | +# Copilot Instructions for Linear_Algebra |
| 2 | + |
| 3 | +## Project Architecture |
| 4 | + |
| 5 | +This is a **Julia linear algebra computing project** using DrWatson for reproducibility, focused on geometric transformations and linear algebra operations with visualization capabilities. The codebase follows a **modular mathematical library pattern** with comprehensive testing and documentation. |
| 6 | + |
| 7 | +### Core Components |
| 8 | + |
| 9 | +- **`src/Linear_Algebra.jl`**: Main module with exports for basic operations and transformation matrices |
| 10 | +- **`src/linear_algebra_basic.jl`**: Core linear algebra functions (distances, projections, line operations, intersections) |
| 11 | +- **`src/linear_algebra_transform.jl`**: Matrix transformations (projection, rotation, stretch, reflection matrices) |
| 12 | +- **`test/`**: Comprehensive test suite with CI-compatible plotting tests (49 total tests) |
| 13 | +- **`docs/`**: Documenter.jl setup with cross-repository deployment to math_tech_study |
| 14 | + |
| 15 | +## Critical Development Patterns |
| 16 | + |
| 17 | +### Module Structure |
| 18 | +```julia |
| 19 | +# Main module uses @reexport for clean interface |
| 20 | +@reexport using GeometryBasics, Plots, LinearAlgebra, RationalRoots, Symbolics |
| 21 | +# Comprehensive exports for all functions |
| 22 | +export distance_2_points, center_of_gravity, barycentric_coord, plot_param_line |
| 23 | +# ... matrix functions, line functions, etc. |
| 24 | +``` |
| 25 | + |
| 26 | +### Test Setup (Uses @quickactivate) |
| 27 | +```julia |
| 28 | +# Tests use DrWatson @quickactivate pattern |
| 29 | +using DrWatson, Test |
| 30 | +@quickactivate "Linear_Algebra" |
| 31 | +using Linear_Algebra |
| 32 | +using GeometryBasics, LinearAlgebra |
| 33 | +``` |
| 34 | + |
| 35 | +### CI-Compatible Plotting Pattern |
| 36 | +```julia |
| 37 | +# Environment detection for plotting tests |
| 38 | +if get(ENV, "CI", "false") == "true" || get(ENV, "GITHUB_ACTIONS", "false") == "true" |
| 39 | + # In CI, just test that the function exists |
| 40 | + @test hasmethod(plot_param_line, (typeof(p), typeof(q), Int64)) |
| 41 | +else |
| 42 | + # Local testing - allow plotting but capture any display issues |
| 43 | + try |
| 44 | + points = plot_param_line(p, q, 3) |
| 45 | + # ... test plotting results |
| 46 | + catch e |
| 47 | + # Graceful fallback for plotting failures |
| 48 | + @test hasmethod(plot_param_line, (typeof(p), typeof(q), Int64)) |
| 49 | + end |
| 50 | +end |
| 51 | +``` |
| 52 | + |
| 53 | +## Julia Coding Standards |
| 54 | + |
| 55 | +### Linear Algebra Functions |
| 56 | +1. Use GeometryBasics.Point2f for 2D points consistently |
| 57 | +2. Use regular Arrays ([Float64]) for vectors in calculations |
| 58 | +3. Handle both symbolic and numeric matrix operations |
| 59 | +4. Degrees vs radians: `rotation_matrix(d)` takes degrees, `rotation_matrix_ns(θ)` takes radians |
| 60 | +5. Matrix functions return 2x2 matrices for 2D transformations |
| 61 | +6. Always export new functions in main module |
| 62 | +7. Use clear parameter naming (θ for angles, v/w for vectors, p/q for points) |
| 63 | + |
| 64 | +### Function Categories |
| 65 | +8. **Basic Operations**: Distance, center of gravity, barycentric coordinates |
| 66 | +9. **Vector Operations**: Angle calculations, orthogonality, projections, reflections |
| 67 | +10. **Line Geometry**: Parametric/implicit conversions, distance calculations, intersections |
| 68 | +11. **Matrix Transformations**: Projection, rotation, stretch, reflection matrices |
| 69 | +12. **Symbolic Functions**: Provide both symbolic and numeric versions |
| 70 | + |
| 71 | +### Documentation & Comments |
| 72 | +13. Include detailed comments explaining geometric concepts |
| 73 | +14. Use clear variable names (e.g., `p1`, `p2` for points, `v`, `w` for vectors) |
| 74 | +15. Document angle conventions (degrees vs radians) in function comments |
| 75 | +16. Explain mathematical formulas in comments |
| 76 | +17. Maintain consistency with mathematical notation |
| 77 | + |
| 78 | +### Testing Patterns |
| 79 | +18. **Comprehensive Coverage**: 49 tests covering ~100% of functions |
| 80 | +19. **CI-Safe**: Plotting tests skip in headless environments |
| 81 | +20. **Edge Cases**: Test mathematical edge cases (orthogonal vectors, zero angles, etc.) |
| 82 | +21. **Type Testing**: Verify return types (Point2f, AbstractVector, matrices) |
| 83 | +22. **Numerical Precision**: Use `atol=1e-10` for floating-point comparisons |
| 84 | +23. **Error Handling**: Use try-catch for functions that might fail in CI |
| 85 | + |
| 86 | +### Code Organization |
| 87 | +24. **Two-File Structure**: Basic operations in `linear_algebra_basic.jl`, matrices in `linear_algebra_transform.jl` |
| 88 | +25. **Consistent Naming**: Functions end with descriptive suffixes (`_matrix`, `_line`, `_coord`) |
| 89 | +26. **Symbolic Variants**: Provide `_symbolic` versions for algebraic manipulation |
| 90 | +27. **Export Everything**: All public functions exported from main module |
| 91 | + |
| 92 | +## Dependencies & Performance |
| 93 | + |
| 94 | +**Main Dependencies**: GeometryBasics, Plots, LinearAlgebra, RationalRoots, Symbolics |
| 95 | +**Test Dependencies**: DrWatson, Test, GeometryBasics, LinearAlgebra |
| 96 | + |
| 97 | +### Mathematical Libraries Used |
| 98 | +- **GeometryBasics.jl**: For Point2f types and geometric primitives |
| 99 | +- **LinearAlgebra.jl**: For `norm()`, `dot()`, matrix operations |
| 100 | +- **Symbolics.jl**: For `@variables` in symbolic matrix functions |
| 101 | + - Pattern: `@variables θ`, `@variables λ₁` for symbolic parameters |
| 102 | + - Use `Symbolics.value.(substitute.(expr, var => value))` for evaluation |
| 103 | +- **Plots.jl**: For visualization functions (`scatter!`, `plot!`, `display`) |
| 104 | +- **RationalRoots.jl**: For rational approximations |
| 105 | + |
| 106 | +## Key Workflows |
| 107 | + |
| 108 | +### Running Tests Locally |
| 109 | +```bash |
| 110 | +julia --project=. test/runtests.jl |
| 111 | +``` |
| 112 | + |
| 113 | +### Running Tests in CI Mode |
| 114 | +```bash |
| 115 | +CI=true julia --project=. test/runtests.jl |
| 116 | +``` |
| 117 | + |
| 118 | +### Building Documentation |
| 119 | +```bash |
| 120 | +julia --project=. docs/make.jl |
| 121 | +``` |
| 122 | + |
| 123 | +### CI Considerations |
| 124 | +- Tests automatically detect CI environment via ENV variables |
| 125 | +- Plotting tests skip gracefully in headless mode |
| 126 | +- 49 tests in local mode, 47 tests in CI mode (plotting tests reduced) |
| 127 | +- Test execution time: ~15-16 seconds |
| 128 | + |
| 129 | +## Git Best Practices |
| 130 | + |
| 131 | +- **Never use `git add .`** - Always stage files explicitly by name to avoid accidentally committing development files, notebooks, or temporary files |
| 132 | +- Use `git add <specific-file-path>` to stage only the intended files for commit |
| 133 | +- Feature branch naming: Use descriptive names like `add-tests-fix-notebook` |
| 134 | + |
| 135 | +### Pull Request Creation |
| 136 | +- **ALWAYS push changes first**: Use `git push origin BRANCH_NAME` before creating PR |
| 137 | +- **Do NOT use `gh pr create`** - The GitHub CLI command doesn't work properly in this environment |
| 138 | +- **Use GitHub web interface instead**: Create PR links manually with detailed descriptions |
| 139 | +- **PR Link Format**: `https://github.com/FourMInfo/Linear_Algebra/compare/main...BRANCH_NAME` |
| 140 | +- **Include comprehensive descriptions**: Detail all changes, test coverage, and architectural improvements |
| 141 | +- **Reference issue numbers**: Link to related issues when applicable |
| 142 | + |
| 143 | +## Azure Integration |
| 144 | + |
| 145 | +- Use Azure Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `azure_development-get_best_practices` tool if available |
| 146 | + |
| 147 | +## Project-Specific Conventions |
| 148 | + |
| 149 | +### Mathematical Operations |
| 150 | +- **Point Types**: Use `Point2f(x, y)` for 2D points consistently |
| 151 | +- **Vector Types**: Use `[Float64]` arrays for vector calculations |
| 152 | +- **Angle Conventions**: Document whether functions expect degrees or radians |
| 153 | +- **Matrix Size**: All 2D transformation matrices are 2x2 |
| 154 | +- **Coordinate Systems**: Standard mathematical coordinate system (not screen coordinates) |
| 155 | + |
| 156 | +### Function Naming Patterns |
| 157 | +- **Distance Functions**: `distance_*` (e.g., `distance_2_points`, `distance_to_implicit_line`) |
| 158 | +- **Matrix Functions**: `*_matrix` (e.g., `rotation_matrix`, `projection_matrix`) |
| 159 | +- **Line Functions**: `*_line` (e.g., `explicit_line`, `parametric_to_implicit_line`) |
| 160 | +- **Coordinate Functions**: `*_coord` (e.g., `barycentric_coord`) |
| 161 | + |
| 162 | +### Test Organization |
| 163 | +- **Grouped by Category**: Basic functions, transformation matrices, line geometry, advanced functions |
| 164 | +- **CI Compatibility**: Plotting tests with environment detection |
| 165 | +- **Comprehensive Coverage**: Test both happy path and edge cases |
| 166 | +- **Type Validation**: Verify return types match expectations |
| 167 | + |
| 168 | +### Documentation Structure |
| 169 | +- **Cross-Repository Deployment**: Deploys to math_tech_study repository |
| 170 | +- **Subdirectory Pattern**: Available at study.fourm.info/linear_algebra/ |
| 171 | +- **Auto-docs Integration**: Uses `@autodocs` for automatic function documentation |
| 172 | +- **Mathematical Notation**: Supports LaTeX rendering in documentation |
| 173 | + |
| 174 | +## Function Signature Patterns |
| 175 | + |
| 176 | +### Basic Linear Algebra |
| 177 | +```julia |
| 178 | +distance_2_points(p::Point, q::Point) -> Float64 |
| 179 | +center_of_gravity(p::Point, q::Point, t) -> Point |
| 180 | +vector_angle_cos(p::Vector, q::Vector) -> Float64 |
| 181 | +orthproj(v::Vector, w::Vector) -> Vector |
| 182 | +``` |
| 183 | + |
| 184 | +### Matrix Transformations |
| 185 | +```julia |
| 186 | +rotation_matrix(d::Number) -> Matrix # Takes degrees |
| 187 | +rotation_matrix_ns(θ::Number) -> Matrix # Takes radians |
| 188 | +projection_matrix(x::Vector) -> Matrix |
| 189 | +reflection_matrix(U::Vector) -> Matrix |
| 190 | +``` |
| 191 | + |
| 192 | +### Line Operations |
| 193 | +```julia |
| 194 | +parametric_to_implicit_line(p::Point, v::Vector) -> (Float64, Float64, Float64) |
| 195 | +distance_to_implicit_line(a::Number, b::Number, c::Number, r::Point) -> Float64 |
| 196 | +foot_of_line(P::Point, v::Vector, R::Point) -> Tuple(Point, Float64) |
| 197 | +``` |
0 commit comments