diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ade164..4e50394 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,20 +2,20 @@ Thank you for taking the time to contribute! -The following is a set of guidelines for contributing to *differint*. These are just guidelines, not rules, so use your best judgement and feel free to propose changes to this document in a pull request. +The following is a set of guidelines for contributing to *differintP*. These are just guidelines, not rules, so use your best judgement and feel free to propose changes to this document in a pull request. ## Getting Started -*differint* requires Python 3+ and NumPy. If you are new to NumPy, please head over to [this](https://docs.scipy.org/doc/numpy-dev/user/quickstart.html) guide. +*differint* requires Python 3.10+ and NumPy. If you are new to NumPy, please head over to [this](https://docs.scipy.org/doc/numpy-dev/user/quickstart.html) guide. The gpu accelarated functions use [Cupy](), you will need cupy, cuda enabled gpu and cuda toolkit, All tests are writen with pytest ## Community -* The whole *differint* documentation, including installation and testing, can be read [here](https://github.com/snimpids/differint). +* The whole *differintP* documentation, including installation and testing, can be read [here](https://github.com/iparsw/differintP). -* If you have any questions regarding *differint*, open an [issue](https://github.com/snimpids/differint/issues/new/). +* If you have any questions regarding *differint*, open an [issue](https://github.com/iparsw/differintP/issues/new/). ## Issue -Ensure the bug was not already reported by searching on GitHub under [issues](https://github.com/snimpids/differint/issues). If you're unable to find an open issue addressing the bug, open a [new issue](https://github.com/snimpids/differint/issues/new). +Ensure the bug was not already reported by searching on GitHub under [issues](https://github.com/iparsw/differintP/issues). If you're unable to find an open issue addressing the bug, open a [new issue](https://github.com/iparsw/differintP/issues/new). Please consider the following points while opening an issue. For example: @@ -24,9 +24,4 @@ For example: * The operating system. ## Pull Requests -Pull Requests are always welcome. - -1. When you edit the code, please run `npm run test` to check the formatting of your code before you `git commit`. -2. Ensure the PR description clearly describes the problem and solution. It should include: - * The operating system on which you tested. - * The relevant issue number, if applicable. +Pull Requests are always welcome. \ No newline at end of file diff --git a/README.md b/README.md index 9fdd391..536c1d2 100644 --- a/README.md +++ b/README.md @@ -2,119 +2,119 @@ - There is also a faster version (but more limited) implemented in c++ [diffeintC](https://github.com/iparsw/differintC) -## differint -This package is used for numerically calculating fractional derivatives and integrals (differintegrals). Options for varying definitions of the differintegral are available, including the Grunwald-Letnikov (GL), the 'improved' Grunwald-Letnikov (GLI), the Riemann-Liouville (RL), and the Caputo (L1, L2, and L2C). Through the API, you can compute differintegrals at a point or over an array of function values. +# differintP -See below for an example of how to use this package, or check out the [wiki](https://github.com/differint/differint/wiki) for references, signatures, and examples for each function. +**differintP** is a modern, pure Python library for **fractional calculus**—that is, for numerical differentiation and integration of arbitrary (non-integer) order. +It is a high-performance fork and major modernization of the original [differint](https://github.com/differint/differint) library, with many optimizations, expanded features, and a strong emphasis on speed, completeness, and code clarity. -## Motivation -There is little in the way of readily available, easy-to-use code for numerical fractional calculus. What is currently available are functions that are generally either smart parts of a much larger package, or only offer one numerical algorithm. The *differint* package offers a variety of algorithms for computing differintegrals and several auxiliary functions relating to generalized binomial coefficients. +> **Highlights** +> - Orders of differentiation and integration: any real (fractional) value +> - Fast, vectorized, and JIT-accelerated core routines (NumPy + Numba) +> - GPU support (optional, via CuPy) +> - Array and pointwise (endpoint) fractional derivative functions +> - Covers Grünwald-Letnikov, Riemann-Liouville, Caputo, Weyl, Riesz, CRONE, and more +> - Accurate for both smooth and non-smooth functions +> - Extensive tests and clear, modern codebase +> - MIT License -## Installation -This project requires Python 3+ and NumPy to run. +--- -Installation from the Python Packaging index (https://pypi.python.org/pypi) is simple using pip. +## 🚀 Quick Install -```python +```bash pip install differintP -``` +```` + +* Optional: for GPU acceleration, also install [CuPy](https://docs.cupy.dev/en/stable/install.html): + + ```bash + pip install cupy-cuda12x # or cupy-cuda11x, depending on your CUDA + ``` + +--- + +## ✨ Features + +* **Fast Fractional Derivatives**: Grünwald-Letnikov (`GL`, `GLpoint`), Riemann-Liouville (`RL`, `RLpoint`), Caputo (`CaputoL1point`, etc.) +* **Modern Implementations**: All methods rewritten for clarity, speed, and extensibility +* **Advanced/Research Methods**: + + * **Weyl** (Fourier/spectral, periodic) + * **Riesz** (symmetric, physical applications) + * **CRONE** (for edge detection and signal processing) +* **GPU-accelerated GL**: `GL_gpu` (if CuPy is installed) +* **High test coverage**: Pytest, with analytical ground truths for common functions -## Included Files -Core File | Description ---------- | ----------- -differint/differint.py | Contains algorithms for fractional differentiation and integration. -tests/test.py | Testing suite containing all unit tests. - -Both of the above files have corresponding `__init__.py` files. - -Setup File | Description ----------- | ----------- -.gitignore | List of files to ignore during `git` push/pull requests. -CONTRIBUTING.md | Instructions for potential contributors to the *differint* project. -LICENSE | MIT license agreement. -MANIFEST.in | Selects the README file for uploading to PyPi. -README.md | This README file. -README.rst | This README file in ReStructuredText format. -__init__.py | `__init__` file for overall package. -changelog.txt | List of updates to package. -setup.py | Script for downloading package from `pip`. - -## Example Usage -Taking a fractional derivative is easy with the *differint* package. Let's take the 1/2 derivative of the square root function on the interval [0,1], using the Riemann-Liouville definition of the fractional derivative. +--- + +## 📚 Usage Example ```python import numpy as np -import differint.differint as df +from differintP import GL, GLpoint, Weyl, Riesz -def f(x): - return x**0.5 +# Fractional derivative of order 0.5 of sqrt(x) on [0, 1] +x = np.linspace(0, 1, 100) +df_gl = GL(0.5, np.sqrt, 0, 1, 100) # Array version +df_point = GLpoint(0.5, np.sqrt, 0, 1, 100) # Endpoint value -DF = df.RL(0.5, f) -print(DF) +# Weyl and Riesz derivatives of sin(x) on [0, 2*pi] +x2 = np.linspace(0, 2*np.pi, 256, endpoint=False) +df_weyl = Weyl(0.5, np.sin, 0, 2*np.pi, 256) +df_riesz = Riesz(0.5, np.sin, 0, 2*np.pi, 256) ``` -You can also specify the endpoints of the domain and the number of points used as follows. +See the [wiki](https://github.com/iparsw/differintP/wiki) for detailed documentation and advanced use. -```python -DF = df.RL(0.5, f, 0, 1, 128) -``` +--- -For a description of all functions, their signatures, and more usage examples, see the project's [wiki](https://github.com/differint/differint/wiki). +## 📑 Documentation -## Tests -All tests can be run with nose from the command line. Setup will automatically install nose if it is not present on your machine. +* **Function Reference**: See the [Wiki](https://github.com/iparsw/differintP/wiki) for math, options, and examples for all supported methods. +* **Benchmarks**: [BENCHMARK.md](https://github.com/iparsw/differintC/blob/main/BENCHMARK.md) for speed/performance notes. +* **Importing**: Import main algorithms directly, See the [Wiki](https://github.com/iparsw/differintP/wiki/Namespaces). -```python -python setup.py tests -``` +Of course! Here’s a suggested section for accuracy tests, following your README’s style: -Alternatively, you can run the test script directly. +--- -```python -cd /differint/tests/ -python test.py +## ✅ Accuracy Tests + +To verify the correctness and numerical accuracy of all algorithms, see the interactive **accuracy test notebook**: +[**accuracy\_test.ipynb**](https://github.com/iparsw/differintP/blob/master/accuracy_test.ipynb) + +This notebook compares numerical results to analytical ground truth for a variety of functions and methods, and serves as a practical demonstration and benchmark reference. + +--- + +## 🧑‍💻 Development and Testing + +* **Python ≥ 3.10** required +* All code is in pure Python; C++ not required +* **All tests use [pytest](https://pytest.org/)** for fast, expressive, and modern testing + +To run the full test suite: + +```bash +pytest tests/ ``` -## API Reference -In this section we cover the usage of the various functions within the *differint* package. - -Main Function | Usage -------------- | ----- -[GLpoint](https://github.com/differint/differint/wiki/GLpoint) | Computes the GL differintegral at a point -[GL](https://github.com/differint/differint/wiki/GL) | Computes the GL differintegral over an entire array of function values using the Fast Fourier Transform -[GLI](https://github.com/differint/differint/wiki/GLI) | Computes the improved GL differintegral over an entire array of function values -[CRONE](https://github.com/differint/differint/wiki/CRONE) | Calculates the GL derivative approximation using the CRONE operator. -[RLpoint](https://github.com/differint/differint/wiki/RLpoint) | Computes the RL differintegral at a point -[RL](https://github.com/differint/differint/wiki/RL) | Computes the RL differintegral over an entire array of function values using matrix methods -[CaputoL1point](https://github.com/differint/differint/wiki/CaputoL1point) | Computes the Caputo differintegral at a point using the L1 algorithm -[CaputoL2point](https://github.com/differint/differint/wiki/CaputoL2point) | Computes the Caputo differintegral at a point using the L2 algorithm -[CaputoL2Cpoint](https://github.com/differint/differint/wiki/CaputoL2Cpoint) | Computes the Caputo differintegral at a point using the L2C algorithm -[PCsolver](https://github.com/differint/differint/wiki/PCsolver) | Solves IVPs for fractional ODEs of the form ${}^CD^\alpha[y(x)]=f(x,y(x))$ using the predictor-corrector method - -Auxiliary Function | Usage ------------------- | ----- -[isInteger](https://github.com/differint/differint/wiki/isInteger) | Determine if a number is an integer -[isPositiveInteger](https://github.com/differint/differint/wiki/isPositiveInteger) | Determine if a number is an integer, and if it is greater than 0 -[checkValues](https://github.com/differint/differint/wiki/checkValues) | Used to check for valid algorithm input types -[GLIinterpolat](https://github.com/differint/differint/wiki/GLIinterpolat) | Define interpolating coefficients for the improved GL algorithm -[functionCheck](https://github.com/differint/differint/wiki/functionCheck) | Determines if algorithm function input is callable or an array of numbers -[poch](https://github.com/differint/differint/wiki/poch) | Computes the Pochhammer symbol -[Gamma](https://github.com/differint/differint/wiki/Gamma) | Computes the gamma function, an extension of the factorial to complex numbers -[Beta](https://github.com/differint/differint/wiki/Beta) | Computes the beta function, a function related to the binomial coefficient -[MittagLeffler](https://github.com/differint/differint/wiki/MittagLeffler) | Computes the two parameter Mittag-Leffler function, which is important in the solution of fractional ODEs -[GLcoeffs](https://github.com/differint/differint/wiki/GLcoeffs) | Determines the convolution filter composed of generalized binomial coefficients used in the GL algorithm -[RLcoeffs](https://github.com/differint/differint/wiki/RLcoeffs) | Calculates the coefficients used in the RLpoint and RL algorithms -[RLmatrix](https://github.com/differint/differint/wiki/RLmatrix) | Determines the matrix used in the RL algorithm -[PCcoeffs](https://github.com/differint/differint/wiki/PCcoeffs) | Determines the coefficients used in the PC algorithm - - -## Credits -Baleanu, D., Diethelm, K., Scalas, E., & Trujillo, J.J. (2012). Fractional Calculus: Models and Numerical Methods. World Scientific. - -Oldham, K.B. & Spanier, J. (1974). The Fractional Calculus: Theory and Applications of Differentiation and Integration to Arbitrary Order. Academic Press Inc. - -Karniadakis, G.E.. (2019). Handbook of Fractional Calculus with Applications Volume 3: Numerical Methods. De Gruyter. - -## License - -MIT © [Matthew Adams](2018) +--- + + + +## 📝 License + +**MIT License** +See [LICENSE](./LICENSE). + +--- + +## 🔗 Related Projects + +* [differint](https://github.com/differint/differint) (original library, now less maintained) +* [differintC](https://github.com/iparsw/differintC) (C/C++ accelerated version by @iparsw) +--- + +*For questions or help, open an [issue](https://github.com/iparsw/differintP/issues) or check the Discussions!* +