""" User Guide ========== Welcome to the HPFRACC User Guide! This comprehensive guide will help you get started with the High-Performance Fractional Calculus Library v3.0.0, featuring **Neural Fractional SDE Solvers**, revolutionary intelligent backend selection, complete Fractional Autograd Framework, machine learning integration, and advanced optimization capabilities. Installation ----------- Basic Installation ~~~~~~~~~~~~~~~~~~ Install the core library: .. code-block:: bash pip install hpfracc Installation with GPU Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For GPU acceleration with intelligent backend selection: **Recommended Installation for CUDA 12.8 (PyTorch) and CUDA 12 (JAX):** .. code-block:: bash # Install PyTorch with CUDA 12.8 first pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cu128 # Then install JAX with CUDA 12 support pip install --upgrade "jax[cuda12]" # Install HPFRACC with GPU extras pip install hpfracc[gpu] **Note:** JAX's CUDA 12 wheels are built with CUDA 12.3 but are compatible with CUDA ≥12.1, which includes CUDA 12.8. CUDA libraries are backward compatible, so JAX will work correctly with PyTorch's CUDA 12.8 installation. **Alternative (simpler but may have version conflicts):** .. code-block:: bash pip install hpfracc[gpu] Installation with Machine Learning Dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For full machine learning capabilities including PyTorch, JAX, and NUMBA with intelligent backend selection: .. code-block:: bash pip install hpfracc[ml] Development Installation ~~~~~~~~~~~~~~~~~~~~~~~~ For development and contribution: .. code-block:: bash git clone https://github.com/dave2k77/fractional_calculus_library.git cd fractional_calculus_library pip install -e .[dev] pip install -e .[ml] Requirements ~~~~~~~~~~~~ - **Python**: 3.9+ (dropped 3.8 support) - **Required**: NumPy, SciPy, Matplotlib - **Optional**: PyTorch, JAX, Numba (for acceleration) - **GPU**: CUDA-compatible GPU (optional) Quick Start ---------- Intelligent Backend Selection (v2.2.0) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The revolutionary intelligent backend selection automatically optimizes performance: .. code-block:: python import hpfracc from hpfracc.ml.intelligent_backend_selector import IntelligentBackendSelector from hpfracc.ml.intelligent_backend_selector import WorkloadCharacteristics # Create intelligent backend selector selector = IntelligentBackendSelector(enable_learning=True) # Define workload characteristics workload = WorkloadCharacteristics( operation_type="fractional_derivative", data_size=10000, data_shape=(100, 100), requires_gradient=True ) # Select optimal backend automatically backend = selector.select_backend(workload) print(f"Selected backend: {backend}") # Use with fractional operations frac_deriv = hpfracc.create_fractional_derivative(alpha=0.5, definition="caputo") result = frac_deriv(f, x) # Automatically uses optimal backend Spectral Autograd Framework ~~~~~~~~~~~~~~~~~~~~~~~~~~ The spectral autograd framework is the core innovation that enables gradient flow through fractional derivatives: .. code-block:: python import torch from hpfracc.ml import SpectralFractionalDerivative, BoundedAlphaParameter # Create input with gradient support x = torch.randn(32, requires_grad=True) alpha = 0.5 # fractional order # Apply spectral fractional derivative result = SpectralFractionalDerivative.apply(x, alpha, -1, "fft") # Gradients flow properly through fractional derivatives loss = torch.sum(result) loss.backward() print(f"Input gradient norm: {x.grad.norm().item():.6f}") Learnable Fractional Orders ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use bounded parameterization for adaptive fractional orders: .. code-block:: python # Create learnable alpha parameter alpha_param = BoundedAlphaParameter(alpha_init=1.0) # Use in computation alpha_val = alpha_param() result = SpectralFractionalDerivative.apply(x, alpha_val, -1, "fft") # Alpha gradients are computed automatically loss = torch.sum(result) loss.backward() print(f"Alpha value: {alpha_val.item():.4f}") print(f"Alpha gradient: {alpha_param.rho.grad.item():.6f}") Basic Fractional Calculus Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Fractional Derivatives ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: python from hpfracc import FractionalOrder, optimized_riemann_liouville import numpy as np # Define fractional order alpha = FractionalOrder(0.5) # Create a test function def f(x): return np.sin(x) # Compute fractional derivative x = np.linspace(0, 2*np.pi, 100) result = optimized_riemann_liouville(x, f(x), alpha) print(f"Fractional derivative of sin(x) with order {alpha}:") print(result[:5]) # Show first 5 values Fractional Integrals ^^^^^^^^^^^^^^^^^^^ .. code-block:: python from hpfracc import FractionalOrder, riemann_liouville_integral import numpy as np # Define fractional order alpha = FractionalOrder(0.5) # Create a test function def f(x): return x**2 # Compute fractional integral x = np.linspace(0, 5, 100) result = riemann_liouville_integral(x, f(x), alpha) print(f"Fractional integral of x² with order {alpha}:") print(result[:5]) # Show first 5 values Advanced Fractional Operators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HPFRACC provides a comprehensive collection of fractional operators beyond the classical definitions: .. code-block:: python from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.fractional_implementations import create_riesz_fisher_operator import numpy as np # Novel derivatives cf_derivative = create_fractional_derivative('caputo_fabrizio', 0.5) ab_derivative = create_fractional_derivative('atangana_baleanu', 0.5) # Advanced methods weyl_derivative = create_fractional_derivative('weyl', 0.5) marchaud_derivative = create_fractional_derivative('marchaud', 0.5) # Special operators rf_operator = create_riesz_fisher_operator(0.5) # Derivative behavior rf_integral = create_riesz_fisher_operator(-0.5) # Integral behavior # Test function def f(x): return np.exp(-x**2) x = np.linspace(-2, 2, 100) # Compute results cf_result = cf_derivative.compute(f, x) rf_result = rf_operator.compute(f, x) print(f"Caputo-Fabrizio result shape: {cf_result.shape}") print(f"Riesz-Fisher result shape: {rf_result.shape}") Special Functions ^^^^^^^^^^^^^^^^ .. code-block:: python from hpfracc.special import ( gamma_function, beta_function, binomial_coefficient, mittag_leffler_function ) import numpy as np # Gamma function x = 2.5 gamma_val = gamma_function(x) print(f"Γ({x}) = {gamma_val}") # Beta function a, b = 2.0, 3.0 beta_val = beta_function(a, b) print(f"B({a}, {b}) = {beta_val}") # Binomial coefficient n, k = 5, 2 binomial_val = binomial_coefficient(n, k) print(f"({n} choose {k}) = {binomial_val}") # Mittag-Leffler function alpha, z = 0.5, 1.0 ml_val = mittag_leffler_function(alpha, z) print(f"E_{alpha}({z}) = {ml_val}") Backend Management ~~~~~~~~~~~~~~~~~ HPFRACC supports multiple computation backends: .. code-block:: python from hpfracc.ml.backends import BackendManager, BackendType # Check available backends available = BackendManager.get_available_backends() print(f"Available backends: {available}") # Set preferred backend BackendManager.set_backend(BackendType.JAX) # Get current backend current = BackendManager.get_current_backend() print(f"Current backend: {current}") Core Features ------------ Fractional Derivatives ~~~~~~~~~~~~~~~~~~~~~ HPFRACC provides multiple definitions of fractional derivatives: **Riemann-Liouville Definition:** .. code-block:: python from hpfracc import FractionalOrder, optimized_riemann_liouville # Create Riemann-Liouville fractional derivative alpha = FractionalOrder(0.5) # Apply to function def f(x): return np.sin(x) x = np.linspace(0, 2*np.pi, 100) result = optimized_riemann_liouville(x, f(x), alpha) **Caputo Definition:** .. code-block:: python from hpfracc import optimized_caputo # Create Caputo fractional derivative result = optimized_caputo(x, f(x), alpha) **Grünwald-Letnikov Definition:** .. code-block:: python from hpfracc import optimized_grunwald_letnikov # Create Grünwald-Letnikov fractional derivative result = optimized_grunwald_letnikov(x, f(x), alpha) Fractional Integrals ~~~~~~~~~~~~~~~~~~~ HPFRACC supports various types of fractional integrals: **Riemann-Liouville Integral:** .. code-block:: python from hpfracc import riemann_liouville_integral # Create Riemann-Liouville fractional integral alpha = FractionalOrder(0.5) # Apply to function def f(x): return x**2 x = np.linspace(0, 5, 100) result = riemann_liouville_integral(x, f(x), alpha) **Caputo Integral:** .. code-block:: python from hpfracc.core.integrals import CaputoIntegral # Create Caputo fractional integral (supports all orders α ≥ 0) # For 0 < α < 1 integral_05 = CaputoIntegral(0.5) result = integral_05(f, x) # For α ≥ 1 (newly implemented) integral_15 = CaputoIntegral(1.5) result = integral_15(f, x) **Note**: Caputo integral now supports all fractional orders α ≥ 0. For 0 < α < 1, it equals the Riemann-Liouville integral. For α ≥ 1, it uses a decomposition method. Weyl and Hadamard integrals are available but require specific implementations. Special Functions ~~~~~~~~~~~~~~~~ **Gamma and Beta Functions:** .. code-block:: python from hpfracc.special import gamma_function, beta_function # Gamma function x = np.linspace(0.1, 5, 100) gamma_vals = [gamma_function(xi) for xi in x] # Beta function a, b = 2.0, 3.0 beta_val = beta_function(a, b) **Binomial Coefficients:** .. code-block:: python from hpfracc.special import binomial_coefficient, generalized_binomial # Standard binomial coefficient n, k = 5, 2 binomial_val = binomial_coefficient(n, k) # Fractional binomial coefficient alpha = 0.5 frac_binomial_val = generalized_binomial(alpha, k) **Mittag-Leffler Functions:** .. code-block:: python from hpfracc.special import mittag_leffler_function # One-parameter Mittag-Leffler function alpha = 0.5 z = np.linspace(-5, 5, 100) ml_vals = [mittag_leffler_function(alpha, zi) for zi in z] # Green's functions have been removed from this release # They will be re-implemented in future releases with improved stability # Focus on implemented methods # They will be re-implemented in future releases with improved stability Mathematical Utilities ~~~~~~~~~~~~~~~~~~~~~ HPFRACC provides various mathematical utilities: **Validation Functions:** .. code-block:: python from hpfracc.core.utilities import ( validate_fractional_order, validate_function, validate_tensor_input ) # Validate fractional order is_valid = validate_fractional_order(0.5) # True is_valid = validate_fractional_order(-1.0) # False # Validate function def test_func(x): return x**2 is_valid = validate_function(test_func) # True is_valid = validate_function("not a function") # False # Validate tensor input import numpy as np tensor = np.random.randn(10, 5) is_valid = validate_tensor_input(tensor) # True **Mathematical Functions:** .. code-block:: python from hpfracc.core.utilities import ( factorial_fractional, binomial_coefficient, pochhammer_symbol, hypergeometric_series ) # Fractional factorial x = 2.5 factorial_val = factorial_fractional(x) # Binomial coefficient n, k = 5, 2 binomial_val = binomial_coefficient(n, k) # Pochhammer symbol a, n = 0.5, 3 pochhammer_val = pochhammer_symbol(a, n) # Hypergeometric series a, b, c, z = 1, 1, 1, 0.5 hypergeometric_val = hypergeometric_series(a, b, c, z) **Performance Monitoring:** .. code-block:: python from hpfracc.core.utilities import ( timing_decorator, memory_usage_decorator, PerformanceMonitor ) # Timing decorator @timing_decorator def expensive_function(n): return sum(i**2 for i in range(n)) result = expensive_function(10000) # Memory usage decorator @memory_usage_decorator def memory_intensive_function(n): return np.random.randn(n, n) result = memory_intensive_function(1000) # Performance monitor monitor = PerformanceMonitor() with monitor.timer("computation"): result = expensive_function(10000) print(f"Computation time: {monitor.get_timing('computation')}") Fractional Neural Networks ~~~~~~~~~~~~~~~~~~~~~~~~~ Create and use fractional neural networks: .. code-block:: python from hpfracc.ml import FractionalNeuralNetwork from hpfracc.core.definitions import FractionalOrder from hpfracc.ml.backends import BackendType import numpy as np # Create a fractional neural network model = FractionalNeuralNetwork( input_dim=10, hidden_dims=[64, 32, 16], output_dim=1, fractional_order=FractionalOrder(0.5), activation='relu', dropout_rate=0.2 ) # Generate sample data X = np.random.randn(1000, 10) y = np.sum(X**2, axis=1) + 0.1 * np.random.randn(1000) # Train the model history = model.fit( X, y, epochs=100, batch_size=32, learning_rate=0.001, verbose=True ) # Make predictions predictions = model.predict(X) Graph Neural Networks ~~~~~~~~~~~~~~~~~~~~ Work with fractional graph neural networks: .. code-block:: python from hpfracc.ml.gnn_layers import FractionalGraphConvolution from hpfracc.core.definitions import FractionalOrder import numpy as np import networkx as nx # Create a graph G = nx.erdos_renyi_graph(20, 0.3) adj_matrix = nx.adjacency_matrix(G).toarray() # Create node features node_features = np.random.randn(20, 5) # Create fractional graph convolution layer fractional_order = FractionalOrder(0.5) fgc_layer = FractionalGraphConvolution( input_dim=5, output_dim=3, fractional_order=fractional_order, activation='relu' ) # Apply fractional graph convolution output_features = fgc_layer(adj_matrix, node_features) Advanced Usage ------------- Error Analysis and Validation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Numerical Error Analysis:** .. code-block:: python from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder import numpy as np def analytical_solution(x, alpha): """Analytical solution for D^α sin(x).""" return np.sin(x + alpha * np.pi / 2) # Compare numerical and analytical solutions x = np.linspace(0, 2*np.pi, 100) alpha = 0.5 # Numerical solution deriv = create_fractional_derivative(FractionalOrder(alpha), method="RL") numerical = deriv(lambda x: np.sin(x), x) # Analytical solution analytical = analytical_solution(x, alpha) # Compute error error = np.mean(np.abs((numerical - analytical) / analytical)) print(f"Relative error: {error:.6f}") **Convergence Analysis:** .. code-block:: python # HPM solver removed - focusing on implemented methods # Focus on implemented methods: SDE solvers, fractional operators, and ML integration print("HPM solver removed - focusing on implemented methods") Performance Optimization ~~~~~~~~~~~~~~~~~~~~~~~ **GPU Acceleration:** .. code-block:: python from hpfracc.ml.backends import BackendManager, BackendType from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder import time def benchmark_cpu_vs_gpu(data_size): # Generate data x = np.linspace(0, 10, data_size) signal = np.sin(2*np.pi*x) + 0.1*np.random.randn(data_size) # CPU computation BackendManager.set_backend(BackendType.NUMPY) deriv_cpu = create_fractional_derivative(FractionalOrder(0.5), method="RL") start_time = time.time() result_cpu = deriv_cpu(lambda x: signal, x) cpu_time = time.time() - start_time # GPU computation (if available) if BackendManager.is_backend_available(BackendType.TORCH): BackendManager.set_backend(BackendType.TORCH) deriv_gpu = create_fractional_derivative(FractionalOrder(0.5), method="RL") start_time = time.time() result_gpu = deriv_gpu(lambda x: signal, x) gpu_time = time.time() - start_time print(f"CPU time: {cpu_time:.4f}s") print(f"GPU time: {gpu_time:.4f}s") print(f"Speedup: {cpu_time/gpu_time:.2f}x") **Memory Optimization:** .. code-block:: python from hpfracc.core.utilities import memory_usage_decorator import numpy as np @memory_usage_decorator def memory_intensive_computation(data_size): # Generate large dataset x = np.linspace(0, 10, data_size) signal = np.sin(2*np.pi*x) + 0.1*np.random.randn(data_size) # Create multiple fractional derivatives derivatives = [] for alpha in [0.1, 0.3, 0.5, 0.7, 0.9]: from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder deriv = create_fractional_derivative(FractionalOrder(alpha), method="RL") result = deriv(lambda x: signal, x) derivatives.append(result) return derivatives # Test memory usage result = memory_intensive_computation(10000) Signal Processing Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Fractional Signal Processing:** .. code-block:: python from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder import numpy as np from scipy.fft import fft, fftfreq # Generate test signal t = np.linspace(0, 10, 1000) signal = np.sin(2*np.pi*t) + 0.5*np.sin(4*np.pi*t) + 0.1*np.random.randn(len(t)) # Apply fractional derivatives alpha_values = [0.1, 0.3, 0.5, 0.7, 0.9] derivatives = {} for alpha in alpha_values: deriv = create_fractional_derivative(FractionalOrder(alpha), method="RL") derivatives[alpha] = deriv(lambda x: signal, t) # Frequency domain analysis fft_original = np.abs(fft(signal)) fft_derivatives = {} for alpha in alpha_values: fft_derivatives[alpha] = np.abs(fft(derivatives[alpha])) Image Processing Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Fractional Image Processing:** .. code-block:: python from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder import numpy as np from scipy import ndimage # Create a test image x, y = np.meshgrid(np.linspace(-2, 2, 100), np.linspace(-2, 2, 100)) image = np.sin(x) * np.cos(y) + 0.1 * np.random.randn(100, 100) # Apply fractional derivatives in x and y directions alpha = 0.5 deriv_x = create_fractional_derivative(FractionalOrder(alpha), method="RL") deriv_y = create_fractional_derivative(FractionalOrder(alpha), method="RL") # Compute fractional gradients gradient_x = np.zeros_like(image) gradient_y = np.zeros_like(image) for i in range(image.shape[0]): gradient_x[i, :] = deriv_x(lambda x: image[i, :], np.arange(image.shape[1])) for j in range(image.shape[1]): gradient_y[:, j] = deriv_y(lambda y: image[:, j], np.arange(image.shape[0])) # Compute gradient magnitude gradient_magnitude = np.sqrt(gradient_x**2 + gradient_y**2) Configuration and Settings ------------------------- Precision Settings ~~~~~~~~~~~~~~~~~ .. code-block:: python from hpfracc.core.utilities import ( get_default_precision, set_default_precision, get_available_methods, get_method_properties ) # Get current precision settings precision = get_default_precision() print(f"Current precision: {precision}") # Set precision set_default_precision(64) # Use 64-bit precision # Get available methods methods = get_available_methods() print(f"Available methods: {methods}") # Get method properties properties = get_method_properties("riemann_liouville") print(f"Riemann-Liouville properties: {properties}") Logging Configuration ~~~~~~~~~~~~~~~~~~~~ .. code-block:: python from hpfracc.core.utilities import setup_logging, get_logger # Setup logging logger = setup_logging(level="INFO", log_file="hpfracc.log") # Get logger for specific module logger = get_logger("hpfracc.core.derivatives") # Use logger logger.info("Starting fractional derivative computation") logger.debug("Computing with alpha=0.5") logger.warning("Large data size detected") logger.error("Computation failed") Troubleshooting -------------- Common Issues ~~~~~~~~~~~~ **Import Errors:** .. code-block:: python # If you get import errors, check your installation import hpfracc print(hpfracc.__version__) # Check available backends from hpfracc.ml.backends import BackendManager available = BackendManager.get_available_backends() print(f"Available backends: {available}") **Memory Issues:** .. code-block:: python # For large computations, use memory-efficient processing from hpfracc.core.utilities import memory_usage_decorator import gc @memory_usage_decorator def process_large_data(data, chunk_size=1000): results = [] for i in range(0, len(data), chunk_size): chunk = data[i:i+chunk_size] # Process chunk chunk_result = process_chunk(chunk) results.append(chunk_result) # Clear memory del chunk gc.collect() return np.concatenate(results) **Performance Issues:** .. code-block:: python # Use GPU acceleration when available from hpfracc.ml.backends import BackendManager, BackendType # Try different backends backends_to_try = [BackendType.TORCH, BackendType.JAX, BackendType.NUMBA] for backend in backends_to_try: if BackendManager.is_backend_available(backend): BackendManager.set_backend(backend) print(f"Using backend: {backend}") break **Validation Errors:** .. code-block:: python from hpfracc.core.utilities import validate_fractional_order, validate_function # Validate inputs before computation alpha = 0.5 if not validate_fractional_order(alpha): raise ValueError(f"Invalid fractional order: {alpha}") def f(x): return x**2 if not validate_function(f): raise ValueError("Invalid function") Best Practices ------------- **Code Organization:** .. code-block:: python # Organize your code with proper imports import numpy as np from hpfracc.core.definitions import FractionalOrder from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.integrals import create_fractional_integral from hpfracc.special import gamma_function, mittag_leffler_function # Use consistent naming conventions alpha = FractionalOrder(0.5) x = np.linspace(0, 10, 100) # Create reusable functions def compute_fractional_derivative(f, alpha, method="RL"): deriv = create_fractional_derivative(alpha, method=method) return deriv(f, x) **Error Handling:** .. code-block:: python import numpy as np from hpfracc.core.utilities import validate_fractional_order def safe_fractional_derivative(f, alpha, method="RL"): """Safely compute fractional derivative with error handling.""" try: # Validate inputs if not validate_fractional_order(alpha): raise ValueError(f"Invalid fractional order: {alpha}") # Create derivative from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder deriv = create_fractional_derivative(FractionalOrder(alpha), method=method) # Compute result x = np.linspace(0, 10, 100) result = deriv(f, x) return result except Exception as e: print(f"Error computing fractional derivative: {e}") return None **Performance Optimization:** .. code-block:: python from hpfracc.core.utilities import timing_decorator from hpfracc.ml.backends import BackendManager, BackendType @timing_decorator def optimized_computation(data, alpha, method="RL"): """Optimized computation with backend selection.""" # Choose best available backend if BackendManager.is_backend_available(BackendType.TORCH): BackendManager.set_backend(BackendType.TORCH) elif BackendManager.is_backend_available(BackendType.JAX): BackendManager.set_backend(BackendType.JAX) else: BackendManager.set_backend(BackendType.NUMPY) # Perform computation from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder deriv = create_fractional_derivative(FractionalOrder(alpha), method=method) return deriv(lambda x: data, np.arange(len(data))) **Documentation and Testing:** .. code-block:: python def well_documented_function(f, alpha, method="RL"): """ Compute fractional derivative with comprehensive documentation. Parameters: ----------- f : callable Function to differentiate alpha : float Fractional order (0 < alpha < 2) method : str, optional Method to use ("RL", "Caputo", "GL") Returns: -------- numpy.ndarray Fractional derivative values Raises: ------- ValueError If alpha is not in valid range TypeError If f is not callable Examples: -------- >>> def f(x): return np.sin(x) >>> result = well_documented_function(f, 0.5) """ # Input validation if not validate_fractional_order(alpha): raise ValueError(f"Invalid fractional order: {alpha}") if not validate_function(f): raise TypeError("f must be callable") # Computation from hpfracc.core.derivatives import create_fractional_derivative from hpfracc.core.definitions import FractionalOrder deriv = create_fractional_derivative(FractionalOrder(alpha), method=method) x = np.linspace(0, 10, 100) return deriv(f, x) This comprehensive user guide covers all the major features of HPFRACC, from basic usage to advanced applications. For more detailed examples and tutorials, see the Examples & Tutorials section. """