Add comprehensive test suite for basic_maths.jl

.github/copilot-instructions.md

@@ -0,0 +1,118 @@
+# Copilot Instructions for Math_Foundations
+
+## Project Architecture
+
+This is a **Julia scientific computing project** using DrWatson for reproducibility, focused on mathematical foundations with visualization capabilities. The codebase follows a **modular mathematical library pattern** with comprehensive testing and documentation.
+
+### Core Components
+
+- **`src/Math_Foundations.jl`**: Main module with smart environment detection for CI/interactive plotting
+- **`src/basic_maths.jl`**: Mathematical functions (roots, polynomials, hyperbolas, financial calculations)
+- **`test/`**: Dual Project.toml setup - optimized dependencies for CI performance
+- **`docs/`**: Documenter.jl setup with mathematical sections (Algebra, Geometry, etc.)
+
+## Critical Development Patterns
+
+### Environment-Aware Module Loading
+```julia
+# The module automatically detects CI vs interactive environments
+if haskey(ENV, "CI") || get(ENV, "GKSwstype", "") == "100"
+    ENV["GKSwstype"] = "100"  # Headless plotting
+    gr(show=false)
+end
+```
+
+### Test Setup (Important: No @quickactivate)
+```julia
+# DON'T use @quickactivate in tests - use explicit load path
+push!(LOAD_PATH, joinpath(@__DIR__, "..", "src"))
+using Math_Foundations
+```
+
+### Plotting Functions Pattern
+All plotting functions auto-save with timestamps to `plots/` directory:
+```julia
+savefig("plots/"* Dates.format(now(),"yyyymmdd-HHMMSS") * "functionname.png")
+```
+
+## Julia Coding Standards
+
+### Mathematical Functions
+1. Use standard Julia mathematical conventions
+2. Prioritize numerical stability in calculations
+3. Handle negative numbers appropriately (see `nth_root`)
+4. Return complex numbers for even roots of negative numbers
+5. Include comprehensive edge case testing
+6. Always export new functions in main module
+7. Use Unicode symbols (a₂, a₁, a₀) in function parameters
+
+### Documentation & Comments
+8. Include detailed comments explaining mathematical concepts
+9. Use LaTeX math notation with Latexify.jl integration
+10. Ensure all examples include explanatory text
+11. Maintain the notebook-based structure with markdown explanations
+
+### Testing Patterns
+12. Include unit tests for all functions
+13. Use Julia's built-in testing framework
+14. Use `@test` for assertions in unit tests
+15. Use `@testset` to group related tests by function
+16. Use `@test_throws` to test for expected errors
+17. Use `@test_broken` to mark tests that are known to fail
+18. Group tests with comprehensive edge cases (54+ tests)
+
+### Code Organization
+19. Follow the pattern of existing code in basic_maths.jl
+20. Use consistent naming conventions for variables and functions
+21. Ensure all code is well-documented and follows Julia's style guide
+22. Use the Julia standard library for basic operations
+23. Avoid using external libraries unless necessary
+
+## Dependencies & Performance
+
+**Heavy Dependencies** (main Project.toml): Nemo (~500MB), Makie, Symbolics, GLMakie
+**Optimized Test Dependencies** (test/Project.toml): Only essential packages for CI speed
+
+### Mathematical Libraries Used
+- **Symbolics.jl**: For `@variables x` in hyperbola functions
+  - Pattern: Follow the @variables pattern seen in our notebooks
+  - Prefer simplify(expr, expand=true) for algebraic expressions
+- **Polynomials.jl**: For polynomial root finding (`plot_parabola_roots_polynomial`)
+- **AMRVW.jl**: Alternative root finding method
+- **Nemo.jl**: Number theory (imported but verify usage before adding tests)
+  - Use polynomial_ring(ZZ, [vars]) for creating polynomial rings
+  - Prefer factor() over manual factorization
+
+## Key Workflows
+
+### Running Tests Locally
+```bash
+julia --project=. --color=yes -e "include(\"test/runtests.jl\")"
+```
+
+### Building Documentation
+```bash
+julia --project=. docs/make.jl
+```
+
+### CI Considerations
+- Tests run in headless mode with optimized dependency cache
+- Multi-layer caching strategy in `.github/workflows/CI.yml`
+- Plots directory must exist for plotting tests to pass
+- Configure headless mode before plotting in tests
+
+## Git Best Practices
+
+- **Never use `git add .`** - Always stage files explicitly by name to avoid accidentally committing development files, notebooks, or temporary files
+- Use `git add <specific-file-path>` to stage only the intended files for commit
+
+## Azure Integration
+
+- 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
+
+## Project-Specific Conventions
+
+- **DrWatson Integration**: Use `projectdir()`, `srcdir()` for paths (except in tests)
+- **Mathematical Notation**: Use Unicode symbols (a₂, a₁, a₀) in function parameters
+- **Test Organization**: Group tests by function with comprehensive edge cases (54+ tests)
+- **Documentation**: Use LaTeX math notation with Latexify.jl integration

.github/workflows/CI.yml

@@ -48,8 +48,31 @@ jobs:
         with:
           version: '1'
           arch: x64
+
+      # Enhanced caching for docs job
+      - name: Cache Julia packages (docs)
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.julia
+            ~/.julia/compiled
+            ~/.julia/packages
+          key: julia-docs-${{ runner.os }}-${{ hashFiles('**/Project.toml', '**/Manifest.toml') }}
+          restore-keys: |
+            julia-docs-${{ runner.os }}-
+            julia-${{ runner.os }}-
+
       - uses: julia-actions/cache@v1
+        continue-on-error: true
+
       - uses: julia-actions/julia-buildpkg@v1
+        continue-on-error: true
+
+      # Retry build for docs if needed
+      - name: Retry docs build on failure
+        if: failure()
+        run: |
+          julia --project=. -e "using Pkg; Pkg.instantiate()"
 
       - name: Generate documentation and deploy
         run: >

notebooks/Basics.ipynb

@@ -11,36 +11,7 @@
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mPrecompiling DrWatson [634d3b9d-ee7a-5ddf-bec9-22491ea816e1] (cache misses: wrong dep version loaded (2), incompatible header (6))\n",
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mPrecompiling Math_Foundations [60a1b6a0-5642-50e0-92f2-3fdeb326bb73] (cache misses: wrong dep version loaded (2))\n",
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mAssuming ((1//128)*(√((5120//1)*(a^4)) - (80//1)*(a^2))) != 0\n",
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mAssuming ((1//128)*(√((5120//1)*(a^4)) - (80//1)*(a^2))) != 0\n"
-     ]
-    },
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "Welcome to Nemo version 0.49.5\n",
-      "\n",
-      "Nemo comes with absolutely no warranty whatsoever\n"
-     ]
-    },
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mPrecompiling FileIOExt [f5f51d8f-5827-5d2e-939b-192fcd6ec70c] (cache misses: wrong dep version loaded (4), incompatible header (10))\n",
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mPrecompiling IJuliaExt [2f4121a4-3b3a-5ce6-9c5e-1f2673ce168a] (cache misses: wrong dep version loaded (2), incompatible header (6))\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Set up Revise.jl for automatic code reloading\n",
     "# This only needs to be run once at the beginning of your notebook session\n",
@@ -2656,16 +2627,7 @@
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mAssuming ((1//128)*(√((5120//1)*(a^4)) - (80//1)*(a^2))) != 0\n",
-      "\u001b[36m\u001b[1m[ \u001b[22m\u001b[39m\u001b[36m\u001b[1mInfo: \u001b[22m\u001b[39mAssuming ((1//128)*(√((5120//1)*(a^4)) - (80//1)*(a^2))) != 0\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Set up Revise.jl for automatic code reloading\n",
     "# This only needs to be run once at the beginning of your notebook session\n",
@@ -3249,133 +3211,20 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "#### Sine Function\n",
-    "\n",
-    "The sine function, denoted as $\\sin(x)$, is a periodic function that describes the y-coordinate of a point on the unit circle corresponding to an angle $x$ measured in radians. It has a range of $[-1, 1]$ and a period of $2\\pi$.\n",
-    "\n",
-    "#### Cosine Function\n",
-    "\n",
-    "The cosine function, denoted as $cos(x)$, is also a periodic function that describes the x-coordinate of a point on the unit circle corresponding to an angle $x$ measured in radians. It has a range of $[-1, 1]$ and a period of $2\\pi$.\n",
-    "\n",
-    "#### Tangent Function\n",
-    "\n",
-    "The tangent function, denoted as $\\tan(x)$, is the ratio of the sine and cosine functions:\n",
-    "$$\\tan(x) = \\frac{\\sin(x)}{\\cos(x)}$$\n",
-    "It is periodic with a period of $\\pi$ and has vertical asymptotes where $\\cos(x) = 0$."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Sine and Cosine Laws\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Sine Law\n",
-    "\n",
-    "The Sine Law states that in any triangle, the ratio of the length of a side to the sine of the angle opposite that side is constant. This can be expressed as:\n",
-    "$$\\frac{a}{\\sin(\\alpha)} = \\frac{b}{\\sin(\\beta)} = \\frac{c}{\\sin(\\gamma)}$$\n",
-    "\n",
-    "Where:\n",
-    "- $a, b, c$ are the lengths of the sides of the triangle\n",
-    "- $\\alpha, \\beta, \\gamma$ are the angles opposite those sides\n",
-    "- This law is useful for finding unknown sides or angles in a triangle when you have enough information.\n",
-    "\n",
-    "#### Cosine Law\n",
-    "\n",
-    "The Cosine Law relates the lengths of the sides of a triangle to the cosine of one of its angles. It can be expressed as:\n",
-    "$$c^2 = a^2 + b^2 - 2ab \\cdot \\cos(\\gamma)$$\n",
-    "\n",
-    "Where:\n",
-    "- $c$ is the length of the side opposite angle $\\gamma$\n",
-    "- $a$ and $b$ are the lengths of the other two sides\n",
-    "- $\\gamma$ is the angle opposite side $c$\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Trigonometric Identities"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "#### Pythagorean Identities\n",
-    "The Pythagorean identities are fundamental relationships in trigonometry that relate the sine, cosine, and tangent functions. They are derived from the Pythagorean theorem applied to the unit circle. The Pythagorean identities relate the squares of the sine and cosine functions to 1:\n",
-    "$$\\sin^2(x) + \\cos^2(x) = 1$$\n",
-    "$$1 + \\tan^2(x) = \\sec^2(x)$$\n",
-    "$$1 + \\cot^2(x) = \\csc^2(x)$$\n",
-    "\n",
-    "#### Angle Sum and Difference Identities or Addition Theorems\n",
-    "The angle sum and difference identities, also known as addition theorems, express the sine, cosine, and tangent of the sum or difference of two angles in terms of the sine and cosine of the individual angles. These identities are useful for simplifying trigonometric expressions and solving equations.\n",
-    "\n",
-    "##### Sine\n",
-    "\n",
-    "$$\\sin(a + b) = \\sin(a)\\cos(b) + \\cos(a)\\sin(b)$$\n",
-    "$$\\sin(a - b) = \\sin(a)\\cos(b) - \\cos(a)\\sin(b)$$\n",
-    "\n",
-    "##### Cosine\n",
-    "\n",
-    "$$\\cos(a + b) = \\cos(a)\\cos(b) - \\sin(a)\\sin(b)$$\n",
-    "$$\\cos(a - b) = \\cos(a)\\cos(b) + \\sin(a)\\sin(b)$$\n",
-    "\n",
-    "##### Tangent\n",
-    "\n",
-    "$$\\tan(a + b) = \\frac{\\tan(a) + \\tan(b)}{1 - \\tan(a)\\tan(b)}$$\n",
-    "$$\\tan(a - b) = \\frac{\\tan(a) - \\tan(b)}{1 + \\tan(a)\\tan(b)}$$\n",
-    "\n",
-    "\n",
-    "##### Derivation of the Tangent Addition Theorem\n",
-    "\n",
-    "###### Step 1: Use the definition of tangent\n",
-    "Since $\\tan(\\theta) = \\frac{\\sin(\\theta)}{\\cos(\\theta)}$, we have:\n",
-    "\n",
-    "$$\\tan(a + b) = \\frac{\\sin(a + b)}{\\cos(a + b)}$$\n",
-    "\n",
-    "###### Step 2: Substitute the addition formulas\n",
-    "From the sine and cosine addition theorems:\n",
-    "\n",
-    "$\\sin(a + b) = \\sin(a)\\cos(b) + \\cos(a)\\sin(b)$\n",
-    "\n",
-    "$\\cos(a + b) = \\cos(a)\\cos(b) - \\sin(a)\\sin(b)$\n",
-    "\n",
-    "Substituting these into our expression:\n",
-    "\n",
-    "$$\\tan(a + b) = \\frac{\\sin(a)\\cos(b) + \\cos(a)\\sin(b)}{\\cos(a)\\cos(b) - \\sin(a)\\sin(b)}$$\n",
-    "\n",
-    "###### Step 3: Divide both numerator and denominator by $\\cos(a)\\cos(b)$\n",
-    "$$\\tan(a + b) = \\frac{\\frac{\\sin(a)\\cos(b)}{\\cos(a)\\cos(b)} + \\frac{\\cos(a)\\sin(b)}{\\cos(a)\\cos(b)}}{\\frac{\\cos(a)\\cos(b)}{\\cos(a)\\cos(b)} - \\frac{\\sin(a)\\sin(b)}{\\cos(a)\\cos(b)}}$$\n",
-    "\n",
-    "###### Step 4: Simplify using the definition of tangent\n",
-    "$$\\tan(a + b) = \\frac{\\frac{\\sin(a)}{\\cos(a)} + \\frac{\\sin(b)}{\\cos(b)}}{1 - \\frac{\\sin(a)}{\\cos(a)}\\frac{\\sin(b)}{\\cos(b)}}$$\n",
-    "\n",
-    "$$\\tan(a + b) = \\frac{\\tan(a) + \\tan(b)}{1 - \\tan(a)\\tan(b)}$$\n",
-    "\n",
-    "This is the tangent addition theorem, which allows you to find the tangent of a sum of angles in terms of the tangents of the individual angles.\n",
-    "\n"
-   ]
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Julia 1.11.5",
+   "display_name": "Julia 1.11.6",
    "language": "julia",
    "name": "julia-1.11"
   },
   "language_info": {
    "file_extension": ".jl",
    "mimetype": "application/julia",
    "name": "julia",
-   "version": "1.11.5"
+   "version": "1.11.6"
   }
  },
  "nbformat": 4,