Merge pull request #7 from ChrisRackauckas-Claude/reorganize-docs-methods

Reorganize documentation to present Risch as one method choice

Author: ChrisRackauckas

docs/make.jl

@@ -17,6 +17,12 @@ makedocs(
         "Manual" => [
             "manual/getting_started.md",
             "manual/basic_usage.md",
+        ],
+        "Integration Methods" => [
+            "methods/overview.md",
+            "methods/risch.md",
+        ],
+        "Algorithm Details" => [
             "manual/rational_functions.md",
             "manual/transcendental_functions.md",
         ],

docs/src/api.md

@@ -10,6 +10,21 @@ CurrentModule = SymbolicIntegration
 integrate
 ```
 
+## Integration Methods
+
+### Available Methods
+
+```@docs
+RischMethod
+```
+
+### Method Traits
+
+```@docs
+method_supports_rational
+method_supports_transcendental
+```
+
 ## Algorithm Overview
 
 SymbolicIntegration.jl implements the complete symbolic integration algorithms from Manuel Bronstein's book "Symbolic Integration I: Transcendental Functions".

docs/src/index.md

@@ -35,35 +35,60 @@ julia> using Pkg; Pkg.add("SymbolicIntegration")
 ## Quick Start
 
 ```julia
-# Using Symbolics.jl (recommended)
 using SymbolicIntegration, Symbolics
 
 @variables x
 
-# Basic polynomial integration
+# Basic polynomial integration (uses default RischMethod)
 integrate(x^2, x)  # Returns (1//3)*(x^3)
 
-# Rational function integration  
+# Rational function integration with complex roots
 f = (x^3 + x^2 + x + 2)/(x^4 + 3*x^2 + 2)
 integrate(f, x)  # Returns (1//2)*log(2 + x^2) + atan(x)
 
 # Transcendental functions
 integrate(exp(x), x)    # Returns exp(x)
 integrate(log(x), x)    # Returns -x + x*log(x)
-integrate(1/x, x)       # Returns log(x)
 
 # Complex root integration (arctangent cases)
 integrate(1/(x^2 + 1), x)  # Returns atan(x)
 
-# More complex examples
-f = 1/(x*log(x))
-integrate(f, x)  # Returns log(log(x))
+# Method selection and configuration
+integrate(f, x, RischMethod())  # Explicit method choice
+integrate(f, x, RischMethod(use_algebraic_closure=true))  # With options
 ```
 
 
+## Integration Methods
+
+SymbolicIntegration.jl provides multiple integration algorithms through a flexible method dispatch system:
+
+### RischMethod (Default)
+The complete Risch algorithm for elementary function integration:
+- **Exact results**: Guaranteed correct symbolic integration
+- **Complex roots**: Produces exact arctangent terms  
+- **Complete coverage**: Rational and transcendental functions
+- **Configurable**: Options for performance vs completeness
+
+```julia
+# Default method
+integrate(f, x)  
+
+# Explicit method with options
+integrate(f, x, RischMethod(use_algebraic_closure=true))
+```
+
+### Future Methods
+The framework supports additional integration algorithms:
+- **HeuristicMethod**: Fast pattern-matching integration
+- **NumericalMethod**: Numerical integration fallbacks
+- **SymPyMethod**: SymPy backend compatibility
+
+[→ See complete methods documentation](methods/overview.md)
+
 ## Algorithm Coverage
 
-This package implements the complete suite of algorithms from Bronstein's book:
+The **RischMethod** implements the complete suite of algorithms from Bronstein's book:
 
 - **Rational Function Integration** (Chapter 2)
   - Hermite reduction

docs/src/manual/basic_usage.md

@@ -12,7 +12,15 @@ using SymbolicIntegration, Symbolics
 
 ## The `integrate` Function
 
-The main function for symbolic integration is `integrate(expr, var)`:
+The main function for symbolic integration uses method dispatch to choose algorithms:
+
+```julia
+# Default method (RischMethod)
+integrate(expr, var)
+
+# Explicit method selection
+integrate(expr, var, method)
+```
 
 ```julia
 # Basic polynomial integration
@@ -57,6 +65,38 @@ integrate(cos(x), x)   # sin(x)
 integrate(tan(x), x)   # -log(cos(x))
 ```
 
+## Method Selection
+
+SymbolicIntegration.jl supports multiple integration methods through method dispatch:
+
+### Default Method (RischMethod)
+```julia
+# These are equivalent
+integrate(f, x)
+integrate(f, x, RischMethod())
+```
+
+### Method Configuration
+```julia
+# Configure method behavior
+risch_exact = RischMethod(use_algebraic_closure=true, catch_errors=false)
+integrate(1/(x^2 + 1), x, risch_exact)  # atan(x) with strict error handling
+
+risch_robust = RischMethod(use_algebraic_closure=true, catch_errors=true)  
+integrate(difficult_function, x, risch_robust)  # Graceful error handling
+```
+
+### Method Comparison
+```julia
+# For exact results with full complex root handling
+integrate(f, x, RischMethod(use_algebraic_closure=true))
+
+# For faster computation (may miss some arctangent terms)
+integrate(f, x, RischMethod(use_algebraic_closure=false))
+```
+
+See the [Integration Methods](../methods/overview.md) section for complete details on available methods and their capabilities.
+
 ## Error Handling
 
 SymbolicIntegration.jl will throw appropriate errors for unsupported cases:

docs/src/methods/overview.md

@@ -0,0 +1,31 @@
+# Integration Methods Overview
+
+SymbolicIntegration.jl uses a flexible method dispatch system that allows you to choose different integration algorithms based on your needs.
+
+## Available Methods
+
+### RischMethod (Default)
+
+The **Risch method** is the complete algorithm for symbolic integration of elementary functions, based on Manuel Bronstein's algorithms.
+
+```julia
+# Default usage
+integrate(f, x)  # Automatically uses RischMethod
+
+# Explicit usage  
+integrate(f, x, RischMethod())
+
+# With configuration
+integrate(f, x, RischMethod(use_algebraic_closure=true, catch_errors=false))
+```
+
+**Capabilities:**
+- ✅ Rational functions with exact arctangent terms
+- ✅ Exponential and logarithmic functions  
+- ✅ Trigonometric functions (via transformation)
+- ✅ Complex root handling
+- ✅ Integration by parts
+
+**Best for:** Complete symbolic integration with guaranteed correctness
+
+[→ See detailed Risch documentation](risch.md)

docs/src/methods/risch.md

@@ -0,0 +1,200 @@
+# Risch Method
+
+The Risch method is a complete algorithm for symbolic integration of elementary functions. It implements the algorithms from Manuel Bronstein's "Symbolic Integration I: Transcendental Functions".
+
+## Overview
+
+The Risch method is currently the primary integration method in SymbolicIntegration.jl. It provides exact symbolic integration for:
+
+- **Rational functions**: Using the Rothstein-Trager method
+- **Exponential functions**: Using differential field towers
+- **Logarithmic functions**: Integration by parts and substitution
+- **Trigonometric functions**: Transformation to exponential form
+- **Complex root handling**: Exact arctangent terms
+
+## Usage
+
+```julia
+using SymbolicIntegration, Symbolics
+@variables x
+
+# Default method (uses RischMethod automatically)
+integrate(x^2, x)  # (1//3)*(x^3)
+
+# Explicit Risch method
+integrate(1/(x^2 + 1), x, RischMethod())  # atan(x)
+
+# Risch method with options
+risch = RischMethod(use_algebraic_closure=true, catch_errors=false)
+integrate(f, x, risch)
+```
+
+## Configuration Options
+
+### Constructor
+```julia
+RischMethod(; use_algebraic_closure=true, catch_errors=true)
+```
+
+### Options
+
+#### `use_algebraic_closure::Bool` (default: `true`)
+Controls whether the algorithm uses algebraic closure for finding complex roots.
+
+- **`true`**: Finds complex roots, produces exact arctangent terms
+- **`false`**: Only rational roots, faster for simple cases
+
+```julia
+# With complex roots (produces atan terms)
+integrate(1/(x^2 + 1), x, RischMethod(use_algebraic_closure=true))  # atan(x)
+
+# Without complex roots (may miss arctangent terms)  
+integrate(1/(x^2 + 1), x, RischMethod(use_algebraic_closure=false))  # May return 0
+```
+
+#### `catch_errors::Bool` (default: `true`)
+Controls error handling behavior.
+
+- **`true`**: Returns unevaluated integrals for unsupported cases
+- **`false`**: Throws exceptions for algorithmic failures
+
+```julia
+# Graceful error handling
+integrate(unsupported_function, x, RischMethod(catch_errors=true))  # Returns ∫(f, x)
+
+# Strict error handling  
+integrate(unsupported_function, x, RischMethod(catch_errors=false))  # Throws exception
+```
+
+## Algorithm Components
+
+The Risch method implementation includes:
+
+### Rational Function Integration (Chapter 2)
+- **Hermite reduction**: Simplifies rational functions
+- **Rothstein-Trager method**: Finds logarithmic parts
+- **Partial fraction decomposition**: Handles complex denominators
+- **Complex root finding**: Produces arctangent terms
+
+### Transcendental Function Integration (Chapters 5-6)
+- **Differential field towers**: Handles nested transcendental functions
+- **Risch algorithm**: Complete method for elementary functions
+- **Primitive cases**: Direct integration
+- **Hyperexponential cases**: Exponential function handling
+
+### Supporting Algorithms
+- **Expression analysis**: Converts symbolic expressions to algebraic form
+- **Field extensions**: Builds differential field towers
+- **Root finding**: Complex and rational root computation
+- **Result conversion**: Transforms back to symbolic form
+
+## Function Classes Supported
+
+### Polynomial Functions
+```julia
+integrate(x^n, x)           # x^(n+1)/(n+1)
+integrate(3*x^2 + 2*x + 1, x)  # x^3 + x^2 + x
+```
+
+### Rational Functions
+```julia
+integrate(1/x, x)               # log(x)
+integrate(1/(x^2 + 1), x)       # atan(x)
+integrate((x+1)/(x+2), x)       # x - log(2 + x)
+```
+
+### Exponential Functions
+```julia
+integrate(exp(x), x)            # exp(x)
+integrate(x*exp(x), x)          # -exp(x) + x*exp(x)
+integrate(exp(x^2)*x, x)        # (1/2)*exp(x^2)
+```
+
+### Logarithmic Functions
+```julia
+integrate(log(x), x)            # -x + x*log(x)
+integrate(1/(x*log(x)), x)      # log(log(x))
+integrate(log(x)^2, x)          # x*log(x)^2 - 2*x*log(x) + 2*x
+```
+
+### Trigonometric Functions
+```julia
+integrate(sin(x), x)            # Transformed to exponential form
+integrate(cos(x), x)            # Transformed to exponential form  
+integrate(tan(x), x)            # Uses differential field extension
+```
+
+## Limitations
+
+The Risch method, following Bronstein's book, does not handle:
+
+- **Algebraic functions**: `√x`, `x^(1/3)`, etc.
+- **Non-elementary functions**: Functions without elementary antiderivatives
+- **Special functions**: Bessel functions, hypergeometric functions, etc.
+
+For these cases, the algorithm will:
+- Return unevaluated integrals if `catch_errors=true`
+- Throw appropriate exceptions if `catch_errors=false`
+
+## Performance Considerations
+
+### When to Use Different Options
+
+- **Research/verification**: `catch_errors=false` for strict algorithmic behavior
+- **Production applications**: `catch_errors=true` for robust operation
+- **Complex analysis**: `use_algebraic_closure=true` for complete results
+- **Simple computations**: `use_algebraic_closure=false` for faster execution
+
+### Complexity
+- **Polynomial functions**: O(n) where n is degree
+- **Rational functions**: Depends on degree and factorization complexity
+- **Transcendental functions**: Exponential in tower height
+
+## Examples
+
+### Basic Usage
+```julia
+@variables x
+
+# Simple cases
+integrate(x^3, x, RischMethod())                    # (1//4)*(x^4)
+integrate(1/x, x, RischMethod())                    # log(x)
+integrate(exp(x), x, RischMethod())                 # exp(x)
+```
+
+### Advanced Cases
+```julia
+# Complex rational function with arctangent
+f = (3*x - 4*x^2 + 3*x^3)/(1 + x^2)
+integrate(f, x, RischMethod())  # -4x + 4atan(x) + (3//2)*(x^2)
+
+# Integration by parts
+integrate(log(x), x, RischMethod())  # -x + x*log(x)
+
+# Nested transcendental functions
+integrate(1/(x*log(x)), x, RischMethod())  # log(log(x))
+```
+
+### Method Configuration
+```julia
+# For research (strict error handling)
+research_risch = RischMethod(use_algebraic_closure=true, catch_errors=false)
+
+# For production (graceful error handling)
+production_risch = RischMethod(use_algebraic_closure=true, catch_errors=true)
+
+# For simple cases (faster computation)
+simple_risch = RischMethod(use_algebraic_closure=false, catch_errors=true)
+```
+
+## Algorithm References
+
+The implementation follows:
+
+- **Manuel Bronstein**: "Symbolic Integration I: Transcendental Functions", 2nd ed., Springer 2005
+- **Chapter 1**: General algorithms (polynomial operations, resultants)
+- **Chapter 2**: Rational function integration
+- **Chapters 5-6**: Transcendental function integration (Risch algorithm)
+- **Additional chapters**: Parametric problems, coupled systems
+
+This provides a complete, reference implementation of the Risch algorithm for elementary function integration.