diff --git a/docs/make.jl b/docs/make.jl index c8397e3..de8ab6d 100644 --- a/docs/make.jl +++ b/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", ], diff --git a/docs/src/api.md b/docs/src/api.md index 6e02c49..b1a849f 100644 --- a/docs/src/api.md +++ b/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". diff --git a/docs/src/index.md b/docs/src/index.md index b8049ec..c4624e9 100644 --- a/docs/src/index.md +++ b/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 diff --git a/docs/src/manual/basic_usage.md b/docs/src/manual/basic_usage.md index f91b780..749cb60 100644 --- a/docs/src/manual/basic_usage.md +++ b/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: diff --git a/docs/src/methods/overview.md b/docs/src/methods/overview.md new file mode 100644 index 0000000..76ccbfc --- /dev/null +++ b/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) diff --git a/docs/src/methods/risch.md b/docs/src/methods/risch.md new file mode 100644 index 0000000..62b4bfe --- /dev/null +++ b/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. \ No newline at end of file