Metadata-Version: 2.4
Name: CyRK
Version: 0.17.1
Summary: Runge-Kutta ODE Integrator Implemented in Cython and Numba.
Author-email: "Joe P. Renaud" <joe.p.renaud@gmail.com>
License-Expression: CC-BY-NC-SA-4.0
Project-URL: Homepage, https://github.com/jrenaud90/CyRK
Project-URL: Bug Tracker, https://github.com/jrenaud90/CyRK/issues
Project-URL: Documentation, https://cyrk.readthedocs.io/en/latest/
Keywords: Scientific Computing,Runge-Kutta,Numerical Integration,ODEs,Ordinary Differential Equations,cython,numba,Integration
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numba>=0.54.1
Requires-Dist: numpy<2.5,>=1.22
Requires-Dist: scipy>=1.9.3
Provides-Extra: dev
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: timeit; extra == "dev"
Requires-Dist: line_profiler==3.5.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: linkify-it-py; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: toml; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: nbconvert; extra == "docs"
Requires-Dist: jupyter; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: breathe; extra == "docs"
Requires-Dist: jupyter; extra == "docs"
Requires-Dist: pytest; extra == "docs"
Requires-Dist: matplotlib>=3.4.2; extra == "docs"
Dynamic: license-file

# CyRK
<div style="text-align: center;">
<a href="https://doi.org/10.5281/zenodo.7093266"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.7093266.svg" alt="DOI"></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.9|3.10|3.11|3.12|3.13-blue" alt="Python Version 3.9-3.14" /></a>
<!-- <a href="https://codecov.io/gh/jrenaud90/CyRK" ><img src="https://codecov.io/gh/jrenaud90/CyRK/branch/main/graph/badge.svg?token=MK2PqcNGET" alt="Code Coverage"/></a> -->
<br />
<a href="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_win.yml"><img src="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_win.yml/badge.svg?branch=main" alt="Windows Tests" /></a>
<a href="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_mac.yml"><img src="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_mac.yml/badge.svg?branch=main" alt="MacOS Tests" /></a>
<a href="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_ubun.yml"><img src="https://github.com/jrenaud90/CyRK/actions/workflows/push_tests_ubun.yml/badge.svg?branch=main" alt="Ubuntu Tests" /></a>
<a href="https://app.readthedocs.org/projects/cyrk/builds/?version__slug=latest"><img src="https://app.readthedocs.org/projects/cyrk/badge/?version=latest&style=flat" alt="Ubuntu Tests" /></a>


<br />
<a href="https://pypi.org/project/CyRK/"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/CyRK?label=PyPI%20Downloads" /></a>
<a href="https://anaconda.org/conda-forge/cyrk"> <img alt="Conda Downloads" src="https://img.shields.io/conda/d/conda-forge/cyrk" /> </a>
</div>

---
[Documentation](https://cyrk.readthedocs.io/en/latest/) | [GitHub](https://github.com/jrenaud90/cyrk)

<a href="https://github.com/jrenaud90/CyRK/releases"><img src="https://img.shields.io/badge/CyRK-0.17.0 Alpha-orange" alt="CyRK Version 0.17.0 Alpha" /></a>

**Runge-Kutta ODE Integrator Implemented in Cython and Numba**

<img style="text-align: center" src="https://github.com/jrenaud90/CyRK/blob/main/Benchmarks/CyRK_SciPy_Compare_predprey_v0-17-0.png" alt="CyRK Performance Graphic" />

CyRK provides fast integration tools to solve systems of ODEs using an adaptive time stepping scheme. CyRK can accept differential equations that are written in pure Python, njited numba, or cython-based cdef. Implementing these types of functions is generally easier than doing so in pure C. Calling CyRK's functions and utilizing its results is also much easier to integrate into existing Python or Cython software. Using CyRK can speed up development time while avoiding the slow performance that comes with using pure Python-based solvers like SciPy's `solve_ivp`.

The purpose of this package is to provide some 
functionality of [scipy's solve_ivp](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html) with greatly improved performance.

Currently, CyRK's [numba-based](https://numba.discourse.group/) (njit-safe) implementation is **8--60x faster** than scipy's solve_ivp function.
The [cython-based](https://cython.org/) `pysolve_ivp` function that works with python (or njit'd) functions is **10-40x faster** than scipy.
The [cython-based](https://cython.org/) `cysolver_ivp` function that works with cython-based cdef functions is **100-500x faster** than scipy.

Details about CyRK's performance including more benchmarks can be found [here](https://cyrk.readthedocs.io/en/latest/Performance.html).

CyRK's solvers can also be [parallelized](https://cyrk.readthedocs.io/en/latest/Parallelization.html) for even larger gains.

An additional benefit of the two cython implementations is that they are pre-compiled. This avoids most of the start-up performance hit experienced by just-in-time compilers like numba.

# Overview

## Supported Features
CyRK's `pysolve_ivp` (which works with pure python functions) and `cysolve_ivp` (which works with cython compiled functions) shares many of the same features as SciPy's `solve_ivp`:
* Triggerable [events](https://cyrk.readthedocs.io/en/latest/Events.html) to track certain events or cause a early termination.
* Adaptive step size solver that uses relative and absolute error of the ODE to increase or decrease the step size as needed.
* [Dense](https://cyrk.readthedocs.io/en/latest/Dense_Output_and_t_eval.html) output to create callable functions to interpolate an ODE's solution between solution steps. Allowing user to take advantage of the much more efficient adaptive step size solver. 
* A user-provided [time domain](https://cyrk.readthedocs.io/en/latest/Dense_Output_and_t_eval.html) or `t_eval` can be given to the solver to find solutions at specific time steps.

_Note: `nbsolve_ivp` has a much more limited feature set than `cysolve_ivp` and `pysolve_ivp`. The latter methods are recommended where possible._

### Supported Integrators
Currently, CyRK supports the following integration methods:
* "RK23" - Explicit Runge-Kutta method of order 3(2).
* "RK45" - Explicit Runge-Kutta method of order 5(4)
* "DOP853" - Explicit Runge-Kutta method of order 8. Error is controlled using a combination of 5th and 3rd order interpolators.

More methods will be added as the need arises. We are always looking for contributors if you'd like to see your favorite method added to CyRK!

### Additional Features
In additional to improved performance, CyRK offers a few additional features that SciPy does not:
* Ability to capture [extra outputs](https://cyrk.readthedocs.io/en/latest/Extra_Output.html) during integration so a user can record other parameters instead of just the dependent variables without having to make repeat calls to the differential equations.
* Ability to [reuse](https://cyrk.readthedocs.io/en/latest/CySolverResult_Reuses.html) solvers when the previous result is no longer needed or has been recorded (improving performance, particularly for problems with small integration domain sizes).
* CyRK provides a robust integration diagnostic feedback system to identify and help remedy issues with an ODE solution.
* CyRK offers much more control over the memory management and other aspects of the solver.

### Limitations
There are some features that SciPy has that CyRK currently does not. A non-exhaustive list is:
* A number of integrator methods are missing, particularly implicit approaches.
* `cysolve_ivp` and `pysolve_ivp` can only work with ODEs of double-precision floating point numbers. So complex numbers are not directly supported but systems of ODEs of complex numbers can be converted to systems of doubles for use with CyRK.

## Installation

*CyRK has been tested on Python 3.9--3.14; Windows, Ubuntu, and MacOS.*

Install via pip:

`pip install CyRK`

conda:

`conda install -c conda-forge CyRK`

mamba:

`mamba install cyrk`

If not installing from a wheel, CyRK will attempt to install `Cython` and `Numpy` in order to compile the source code. A "C++ 20" compatible compiler is required.
Compiling CyRK has been tested on the latest versions of Windows, Ubuntu, and MacOS. Your milage may vary if you are using an older or different operating system.
If on MacOS you will likely need a non-default compiler in order to compile the required [OpenMP](https://www.openmp.org/) package. See the "Installation Troubleshooting" section below. 
After everything has been compiled, cython will be uninstalled and CyRK's runtime dependencies (see the pyproject.toml file for the latest list) will be installed instead.

A new installation of CyRK can be tested quickly by running the following from a python console.
```python
from CyRK import test_pysolver, test_cysolver, test_nbrk
test_pysolver()
# Should see "CyRK's PySolver was tested successfully."
test_cysolver()
# Should see "CyRK's CySolver was tested successfully."
test_nbrk()
# Should see "CyRK's nbrk_ode was tested successfully."
```

### Installation Troubleshooting

*Please [report](https://github.com/jrenaud90/CyRK/issues) installation issues. We will work on a fix and/or add workaround information here.*

- If you see a "Can not load module: CyRK.cy" or similar error then the cython extensions likely did not compile during installation. Try running `pip install CyRK --no-binary="CyRK"` 
to force python to recompile the cython extensions locally (rather than via a prebuilt wheel).

- On MacOS: If you run into problems installing CyRK then reinstall using the verbose flag (`pip install -v .`) to look at the installation log. If you see an error that looks like "clang: error: unsupported option '-fopenmp'" then you are likely using the default compiler or other compiler that does not support OpenMP. Read more about this issue [here](https://github.com/facebookresearch/xformers/issues/157) and the steps taken [here](https://github.com/jrenaud90/CyRK/blob/main/.github/workflows/push_tests_mac.yml). A fix for this issue is to use `llvm`'s clang compiler. This can be done by doing the following in your terminal before installing CyRK.
```
brew install llvm
brew install libomp

# If on a newer computer that uses ARM64 (Apple Silicon) then:
export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"
export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
export CC=/opt/homebrew/opt/llvm/bin/clang
export CXX=/opt/homebrew/opt/llvm/bin/clang++

# Otherwise change these directories to:
export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"
export LDFLAGS="-L/usr/local/opt/libomp/lib"
export CPPFLAGS="-I/usr/local/opt/libomp/include"
export CC=/usr/local/opt/llvm/bin/clang
export CXX=/usr/local/opt/llvm/bin/clang++

pip install CyRK --no-binary="CyRK"
```

- CyRK has a number of runtime status codes which can be used to help determine what failed during integration. Learn more about these codes [https://cyrk.readthedocs.io/en/latest/Status_and_Error_Codes.html](here).

### Development and Testing Dependencies

If you intend to work on CyRK's code base you will want to install the following dependencies in order to run CyRK's test suite and experimental notebooks.

`conda install pytest scipy matplotlib jupyter`

`conda install` can be replaced with `pip install` if you prefer.

## Using CyRK
To learn how to use CyRK, please reference our detailed documentation on Read the Docs!

[Read the Docs: CyRK Documentation](https://cyrk.readthedocs.io/en/latest/)

## Citing CyRK

It is great to see CyRK used in other software or in scientific studies. We ask that you reference CyRK's [GitHub](https://github.com/jrenaud90/CyRK) website so interested parties can learn about this package. And please cite the following paper in any formal publication of your work.

```bibtex
@software{renaud_2022_cyrk,
  author       = {Renaud, Joe P.},
  title        = {CyRK - ODE Integrator Implemented in Cython and Numba},
  year         = {2022},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.7093266},
  url          = {[https://doi.org/10.5281/zenodo.7093266](https://doi.org/10.5281/zenodo.7093266)}
}
```

It would also be great to hear about the work being done with CyRK and add your project to the list below, so get in touch!

In addition to citing CyRK, please strongly consider citing SciPy and its references for the specific Runge-Kutta model that was used in your work. CyRK is largely an adaptation of SciPy's functionality. Find more details [here](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html).

```bibtex
@article{virtanen2020scipy,
  author  = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and van der Walt, St{\'e}fan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, CJ and Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and VanderPlas, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E.A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and van Mulbregt, Paul and {SciPy 1.0 Contributors}},
  title   = {{SciPy 1.0: Fundamental Algorithms for Scientific Computing in Python}},
  journal = {Nature Methods},
  year    = {2020},
  volume  = {17},
  number  = {3},
  pages   = {261--272}
}
```

## Projects using CyRK
_Don't see your project here? Create a GitHub issue or otherwise get in touch!_
- [TidalPy](https://github.com/jrenaud90/TidalPy)
- [Rydiqule](https://github.com/QTC-UMD/rydiqule)
- [KG-simulation](https://github.com/w-smialek/KG-simulation)
- [twpaSolver](https://github.com/twpalab/twpasolver)
- [NOrbit](https://github.com/curritod/norbit)
- [APPS-ODE](https://github.com/jiangnanhugo/APPS-ODE)

## Contribute to CyRK
_Please look [here](https://github.com/jrenaud90/CyRK/graphs/contributors) for an up-to-date list of contributors to the CyRK package._

CyRK is open-source and is distributed under the Apache 2.0 license. You are welcome to fork this repository and make any edits with attribution back to this project (please see the `Citing CyRK` section).
- We encourage users to report bugs or feature requests using [GitHub Issues](https://github.com/jrenaud90/CyRK/issues).
- If you would like to contribute but don't know where to start, check out the [good first issue](https://github.com/jrenaud90/CyRK/labels/good%20first%20issue) tag on GitHub.
- Users are welcome to submit pull requests and should feel free to create them before the final code is completed so that feedback and suggestions can be given early on.
