API Reference
==============

This section provides comprehensive documentation for all functions, classes, and methods in the HPFRACC library.

.. note:: **RL / Caputo / Grünwald–Letnikov layout**

   * **Engines** — single numerical implementations in :mod:`hpfracc.algorithms.derivatives`
     (``RiemannLiouville``, ``Caputo``, ``GrunwaldLetnikov``).
   * **``Optimized*`` names** — aliases of those same classes in
     :mod:`hpfracc.algorithms.optimized_methods` (and re-exported at :mod:`hpfracc`).
   * **Adapters** — :mod:`hpfracc.core.fractional_implementations` classes
     (``CaputoDerivative``, ``RiemannLiouvilleDerivative``, …) implement
     :class:`~hpfracc.core.derivatives.BaseFractionalDerivative` and delegate to the engines.
   * **Top-level** ``hpfracc.Caputo``, ``hpfracc.RiemannLiouville``, ``hpfracc.GrunwaldLetnikov``
     refer to the ``*Derivative`` adapters for backward compatibility.
   * **Integrals** — prefer :mod:`hpfracc.core.integrals` for quadrature-based operators;
     :mod:`hpfracc.algorithms.integral_methods` adds FFT-oriented helpers and delegates
     direct RL/Weyl grid paths to ``core.integrals`` (see repository ``CONTRIBUTING.md``).
   * **``import hpfracc.core``** — only :mod:`hpfracc.core.definitions` loads eagerly; other
     ``core`` submodules and re-exports resolve on first use (see ``__getattr__`` in
     :mod:`hpfracc.core`).

Core Module
------------

Fractional Order Definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc
   :members:
   :undoc-members:
   :show-inheritance:

Core Algorithms
~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.algorithms.derivatives
   :members: RiemannLiouville, Caputo, GrunwaldLetnikov
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.algorithms.optimized_methods
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.algorithms.integral_methods
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.algorithms.advanced_methods
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.algorithms.fractional_operator_methods
   :members:
   :undoc-members:
   :show-inheritance:

Fractional Implementations
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.core.fractional_implementations
   :members:
   :undoc-members:
   :show-inheritance:

Core Derivatives
~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.core.derivatives
   :members:
   :undoc-members:
   :show-inheritance:

Core Integrals
~~~~~~~~~~~~~~~

.. automodule:: hpfracc.core.integrals
   :members:
   :undoc-members:
   :show-inheritance:

Machine Learning Module
------------------------

Fractional Autograd Framework
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.spectral_autograd
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.ml.stochastic_memory_sampling
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.ml.probabilistic_fractional_orders
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.ml.variance_aware_training
   :members:
   :undoc-members:
   :show-inheritance:

GPU Optimization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.gpu_optimization
   :members:
   :undoc-members:
   :show-inheritance:

Backend Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.backends
   :members:
   :undoc-members:
   :show-inheritance:

Tensor Operations
~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.tensor_ops
   :members:
   :undoc-members:
   :show-inheritance:

Core ML Components
~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.core
   :members:
   :undoc-members:
   :show-inheritance:

Neural Network Layers
~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.layers
   :members:
   :undoc-members:
   :show-inheritance:

Graph Neural Networks
~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.gnn_layers
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: hpfracc.ml.gnn_models
   :members:
   :undoc-members:
   :show-inheritance:

Loss Functions
~~~~~~~~~~~~~~~

.. automodule:: hpfracc.ml.losses
   :members:
   :undoc-members:
   :show-inheritance:

Optimizers
~~~~~~~~~~~

.. automodule:: hpfracc.ml.optimized_optimizers
   :members:
   :undoc-members:
   :show-inheritance:

Detailed API Documentation
---------------------------

Core Definitions
~~~~~~~~~~~~~~~~~

FractionalOrder
^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.FractionalOrder
   :no-index:
   :members:
   :undoc-members:
   :special-members: __init__, __str__, __repr__


Core Fractional Calculus Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Canonical engines (``algorithms.derivatives``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These are the **single** dispatching implementations used library-wide.

.. autoclass:: hpfracc.algorithms.derivatives.RiemannLiouville
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


.. autoclass:: hpfracc.algorithms.derivatives.Caputo
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


.. autoclass:: hpfracc.algorithms.derivatives.GrunwaldLetnikov
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


OptimizedRiemannLiouville
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.OptimizedRiemannLiouville
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


OptimizedCaputo
^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.OptimizedCaputo
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


OptimizedGrunwaldLetnikov
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.OptimizedGrunwaldLetnikov
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


RiemannLiouvilleDerivative
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.core.fractional_implementations.RiemannLiouvilleDerivative
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

CaputoDerivative
^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.core.fractional_implementations.CaputoDerivative
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

GrunwaldLetnikovDerivative
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.core.fractional_implementations.GrunwaldLetnikovDerivative
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Public package adapters (``hpfracc.*``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``hpfracc.RiemannLiouville``, ``hpfracc.Caputo``, and ``hpfracc.GrunwaldLetnikov`` are the same
``*Derivative`` classes as above (re-exported at package scope).

.. autoclass:: hpfracc.RiemannLiouville
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: hpfracc.Caputo
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: hpfracc.GrunwaldLetnikov
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Backend Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BackendType
^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.backends.BackendType
   :no-index:
   :members:
   :undoc-members:

BackendManager
^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.backends.BackendManager
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Tensor Operations
~~~~~~~~~~~~~~~~~~

TensorOps
^^^^^^^^^^

.. autoclass:: hpfracc.ml.tensor_ops.TensorOps
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Neural Networks
~~~~~~~~~~~~~~~~

FractionalNeuralNetwork
^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.core.FractionalNeuralNetwork
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


Graph Neural Networks
~~~~~~~~~~~~~~~~~~~~~~

FractionalGCN
^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_models.FractionalGCN
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


FractionalGAT
^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_models.FractionalGAT
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

FractionalGraphSAGE
^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_models.FractionalGraphSAGE
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

FractionalGraphUNet
^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_models.FractionalGraphUNet
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

GNN Factory
^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_models.FractionalGNNFactory
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

GNN Layers
^^^^^^^^^^^

FractionalGraphConv
^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_layers.FractionalGraphConv
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


FractionalGraphAttention
^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_layers.FractionalGraphAttention
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


FractionalGraphPooling
^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_layers.FractionalGraphPooling
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


BaseFractionalGNNLayer
^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gnn_layers.BaseFractionalGNNLayer
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Attention Mechanisms
~~~~~~~~~~~~~~~~~~~~~~

FractionalAttention
~~~~~~~~~~~~~~~~~~~~

.. autoclass:: hpfracc.ml.core.FractionalAttention
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


Fractional Autograd Framework (spectral)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Spectral fractional operators live in ``hpfracc.ml.spectral_autograd``. They use FFT-based
kernels and are **not** the same class as ``FractionalNeuralNetwork`` (which applies a
**discrete** Grünwald–Letnikov / L1-Caputo map along a chosen axis; see
``hpfracc.ml.core.FractionalNeuralNetwork`` and ``hpfracc.ml.fractional_derivative_native``).

SpectralFractionalDerivative
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.spectral_autograd.SpectralFractionalDerivative
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

SpectralFractionalLayer
^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.spectral_autograd.SpectralFractionalLayer
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


SpectralFractionalNetwork
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.spectral_autograd.SpectralFractionalNetwork
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


StochasticMemorySampler
^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.stochastic_memory_sampling.StochasticMemorySampler
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


ProbabilisticFractionalLayer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.probabilistic_fractional_orders.ProbabilisticFractionalLayer
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:


VarianceAwareTrainer
^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.variance_aware_training.VarianceAwareTrainer
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

GPU Optimization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GPUProfiler
^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gpu_optimization.GPUProfiler
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

ChunkedFFT
^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gpu_optimization.ChunkedFFT
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

AMPFractionalEngine
^^^^^^^^^^^^^^^^^^^^

.. autoclass:: hpfracc.ml.gpu_optimization.AMPFractionalEngine
   :no-index:
   :members:
   :undoc-members:
   :show-inheritance:

Utility entry points (no duplicate autodoc stubs)
--------------------------------------------------

Fractional-derivative factories live under :py:mod:`hpfracc.core.derivatives` and the algorithm engines
(:py:mod:`hpfracc.algorithms.derivatives`), both covered by ``.. automodule::`` sections earlier in this page.
Backend helpers (:py:mod:`hpfracc.ml.backends`) and tensor factories (:py:mod:`hpfracc.ml.tensor_ops`) are likewise
indexed once via their ``automodule`` blocks to avoid duplicate Sphinx inventory entries.

Model Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::

   Model creation utilities are available through the main ML module.
   See :py:mod:`hpfracc.ml` for factory functions and model constructors.

Configuration
--------------

Default Parameters
~~~~~~~~~~~~~~~~~~~

.. data:: hpfracc.core.definitions.DEFAULT_FRACTIONAL_ORDER
   :annotation: = 0.5

.. data:: hpfracc.ml.backends.DEFAULT_BACKEND
   :annotation: = BackendType.JAX

.. data:: hpfracc.ml.tensor_ops.DEFAULT_DTYPE
   :annotation: = 'float32'

Supported Backends
~~~~~~~~~~~~~~~~~~~~

.. data:: hpfracc.ml.backends.SUPPORTED_BACKENDS
   :annotation: = [BackendType.TORCH, BackendType.JAX, BackendType.NUMBA]

Supported GNN Types
~~~~~~~~~~~~~~~~~~~~~

.. data:: hpfracc.ml.gnn_models.SUPPORTED_GNN_TYPES
   :annotation: = ['gcn', 'gat', 'sage', 'unet']

Supported Derivative Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. data:: hpfracc.core.derivatives.SUPPORTED_METHODS
   :annotation: = ['RL', 'Caputo', 'GL']

Type Information
-----------------

The library uses Python type hints throughout. Key types include:

- **FractionalOrder**: Core class for representing fractional orders
- **BackendType**: Enum for backend selection (TORCH, JAX, NUMBA, AUTO)
- **TensorType**: Union of numpy arrays, PyTorch tensors, and JAX arrays

See the source code for detailed type annotations.

Usage Examples
---------------

Basic Fractional Calculus
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from hpfracc.core.definitions import FractionalOrder
   from hpfracc.core.derivatives import create_fractional_derivative
   import numpy as np

   # Create fractional derivative
   alpha = FractionalOrder(0.5)
   deriv = create_fractional_derivative(alpha, method="RL")

   # Test function
   def f(x):
       return np.exp(-x)

   # Compute derivative
   x = np.linspace(0, 1, 100)
   result = deriv(f, x)

Neural Network Usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from hpfracc.ml import FractionalNeuralNetwork
   from hpfracc.ml.backends import BackendType
   import numpy as np

   # Create model (input_size = feature dimension per row)
   model = FractionalNeuralNetwork(
       input_size=10,
       hidden_sizes=[32, 16],
       output_size=1,
       fractional_order=0.5,
       backend=BackendType.JAX,
       fractional_axis=-1,
   )

   # Forward pass: (batch, input_size); fractional step along last axis by default
   X = np.random.randn(100, 10).astype(np.float32)
   output = model(X, use_fractional=True, method="RL")

GNN Usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from hpfracc.ml import FractionalGNNFactory
   from hpfracc.core.definitions import FractionalOrder
   from hpfracc.ml.backends import BackendType
   import numpy as np

   # Create GNN
   gnn = FractionalGNNFactory.create_model(
       model_type='gcn',
       input_dim=16,
       hidden_dim=32,
       output_dim=4,
       fractional_order=FractionalOrder(0.5),
       backend=BackendType.TORCH
   )

   # Graph data
   node_features = np.random.randn(50, 16)
   edge_index = np.random.randint(0, 50, (2, 100))

   # Forward pass
   output = gnn.forward(node_features, edge_index)

Backend Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from hpfracc.ml.backends import BackendManager, BackendType

   # Check available backends
   available = BackendManager.get_available_backends()
   print(f"Available: {available}")

   # Set backend
   BackendManager.set_backend(BackendType.JAX)

   # Get current backend
   current = BackendManager.get_current_backend()
   print(f"Current: {current}")

Spectral fractional (FFT) usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import torch
   from hpfracc.ml.spectral_autograd import spectral_fractional_derivative
   from hpfracc.ml.stochastic_memory_sampling import StochasticMemorySampler
   from hpfracc.ml.probabilistic_fractional_orders import ProbabilisticFractionalLayer

   # Spectral fractional derivative along last dimension (PyTorch)
   x = torch.randn(32, 128, requires_grad=True)
   y = spectral_fractional_derivative(x, alpha=0.5, dim=-1, kernel_type="riesz")

   # Stochastic memory sampler
   sampler = StochasticMemorySampler(k=32, method="importance")

   # Probabilistic fractional layer
   prob_layer = ProbabilisticFractionalLayer(mean=0.5, std=0.1, learnable=True)

   loss = y.sum()
   loss.backward()
   print(f"Gradients computed: {x.grad is not None}")

GPU Optimization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import torch
   from hpfracc.ml.gpu_optimization import GPUProfiler, ChunkedFFT, gpu_optimization_context

   # GPU profiling
   profiler = GPUProfiler()
   with profiler:
       # Your GPU operations here
       x = torch.randn(1000, 1000, device='cuda')
       result = torch.fft.fft(x)

   # Chunked FFT for large sequences
   chunked_fft = ChunkedFFT(chunk_size=1024)
   x = torch.randn(10000, device='cuda')
   result = chunked_fft.forward(x)

   # GPU optimization context
   with gpu_optimization_context(use_amp=True, chunk_size=512):
       # Your fractional calculus operations here
       pass

Performance Considerations
---------------------------

Backend Selection
~~~~~~~~~~~~~~~~~~

- **PyTorch**: Best for GPU acceleration and complex neural networks
- **JAX**: Best for functional programming and TPU acceleration
- **NUMBA**: Best for CPU optimization and lightweight deployment

Memory Management
~~~~~~~~~~~~~~~~~~

- Use batch processing for large datasets
- Clear intermediate tensors when possible
- Monitor memory usage with large models

Computation Optimization
~~~~~~~~~~~~~~~~~~~~~~~~~~

- Choose appropriate fractional derivative method for your use case
- Use JIT compilation when available
- Profile performance with different backends

Troubleshooting
----------------

Common Issues
~~~~~~~~~~~~~~

**Backend not available**

.. code-block:: python

   # Check available backends
   from hpfracc.ml.backends import BackendManager
   available = BackendManager.get_available_backends()
   print(f"Available: {available}")

**Invalid fractional order**

.. code-block:: python

   # Valid orders: -1 < order < 2
   from hpfracc.core.definitions import FractionalOrder
   try:
       order = FractionalOrder(0.5)  # Valid
   except ValueError as e:
       print(f"Error: {e}")

**Tensor shape mismatch**

.. code-block:: python

   # Ensure input dimensions match model expectations
   model = FractionalNeuralNetwork(input_size=10, hidden_sizes=[8], output_size=1)
   X = np.random.randn(100, 10)  # Correct shape (batch, input_size)
   # X = np.random.randn(100, 5)  # Wrong shape - will fail

Debugging Tips
~~~~~~~~~~~~~~~

1. **Enable debug logging**
2. **Check tensor shapes and types**
3. **Verify backend compatibility**
4. **Test with small datasets first**

For more detailed examples, see :doc:`user_manual/tutorials`.