Python library for ODE integration via Taylor's method and LLVM

Last update: Dec 21, 2022

Overview

heyoka.py

Modern Taylor's method via just-in-time compilation
Explore the docs »

Report bug · Request feature · Discuss

The heyókȟa [...] is a kind of sacred clown in the culture of the Sioux (Lakota and Dakota people) of the Great Plains of North America. The heyoka is a contrarian, jester, and satirist, who speaks, moves and reacts in an opposite fashion to the people around them.

heyoka.py is a Python library for the integration of ordinary differential equations (ODEs) via Taylor's method. Notable features include:

support for both double-precision and extended-precision floating-point types (80-bit and 128-bit),
the ability to maintain machine precision accuracy over tens of billions of timesteps,
high-precision zero-cost dense output,
accurate and reliable event detection,
batch mode integration to harness the power of modern SIMD instruction sets,
interoperability with SymPy,
a high-performance implementation of Taylor's method based on automatic differentiation techniques and aggressive just-in-time compilation via LLVM.

heyoka.py is based on the heyoka C++ library.

If you are using heyoka.py as part of your research, teaching, or other activities, we would be grateful if you could star the repository and/or cite our work. For citation purposes, you can use the following BibTex entry, which refers to the heyoka.py paper (arXiv preprint):

@article{10.1093/mnras/stab1032,
    author = {Biscani, Francesco and Izzo, Dario},
    title = "{Revisiting high-order Taylor methods for astrodynamics and celestial mechanics}",
    journal = {Monthly Notices of the Royal Astronomical Society},
    volume = {504},
    number = {2},
    pages = {2614-2628},
    year = {2021},
    month = {04},
    issn = {0035-8711},
    doi = {10.1093/mnras/stab1032},
    url = {https://doi.org/10.1093/mnras/stab1032},
    eprint = {https://academic.oup.com/mnras/article-pdf/504/2/2614/37750349/stab1032.pdf}
}

Documentation

The full documentation can be found here.

Authors

Francesco Biscani (Max Planck Institute for Astronomy)
Dario Izzo (European Space Agency)

License

heyoka.py is released under the MPL-2.0 license.

Comments

[BUG] Failed import after conda install

Describe the bug I can install heyoka.py through conda, but after that I am unable to import it: ModuleNotFoundError: No module named 'heyoka'.

To Reproduce Steps to reproduce the behavior:

Create a new environment. Install numpy and cloudpicke.
conda install heyoka or conda install heyoka -c conda-forge or exactly the method you describe to force the conda-forge to be used with strict.
Try to import heyoka. The following ensues (example where I did conda install heyoka -c conda-forge, but all install methods end up the same):

(envtest3) C:\>conda install heyoka -c conda-forge
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: C:\Users\MYUSERNAME\Miniconda3\envs\envtest3

  added / updated specs:
    - heyoka


The following packages will be downloaded:

    package                    |            build
    ---------------------------|-----------------
    boost-cpp-1.78.0           |       h9f4b32c_1        17.1 MB  conda-forge
    ca-certificates-2022.9.24  |       h5b45459_0         189 KB  conda-forge
    certifi-2022.9.24          |     pyhd8ed1ab_0         155 KB  conda-forge
    fmt-8.1.1                  |       h5362a0b_0         179 KB  conda-forge
    heyoka-0.19.0              |       hb4083ac_0        57.6 MB  conda-forge
    libzlib-1.2.12             |       hcfcfb64_3          71 KB  conda-forge
    openssl-1.1.1q             |       h8ffe710_0         5.8 MB  conda-forge
    sleef-3.5.1                |       hcc89e0a_2        1008 KB  conda-forge
    spdlog-1.10.0              |       h2d74725_0         318 KB  conda-forge
    tbb-2021.6.0               |       h91493d7_0         174 KB  conda-forge
    ucrt-10.0.20348.0          |       h57928b3_0         1.2 MB  conda-forge
    vs2015_runtime-14.29.30139 |       h890b9b1_7         1.3 MB  conda-forge
    zstd-1.5.2                 |       h7755175_4         401 KB  conda-forge
    ------------------------------------------------------------
                                           Total:        85.4 MB

The following NEW packages will be INSTALLED:

  boost-cpp          conda-forge/win-64::boost-cpp-1.78.0-h9f4b32c_1 None
  fmt                conda-forge/win-64::fmt-8.1.1-h5362a0b_0 None
  heyoka             conda-forge/win-64::heyoka-0.19.0-hb4083ac_0 None
  libzlib            conda-forge/win-64::libzlib-1.2.12-hcfcfb64_3 None
  sleef              conda-forge/win-64::sleef-3.5.1-hcc89e0a_2 None
  spdlog             conda-forge/win-64::spdlog-1.10.0-h2d74725_0 None
  tbb                conda-forge/win-64::tbb-2021.6.0-h91493d7_0 None
  ucrt               conda-forge/win-64::ucrt-10.0.20348.0-h57928b3_0 None
  zstd               conda-forge/win-64::zstd-1.5.2-h7755175_4 None

The following packages will be UPDATED:

  ca-certificates    pkgs/main::ca-certificates-2022.07.19~ --> conda-forge::ca-certificates-2022.9.24-h5b45459_0 None
  certifi            pkgs/main/win-64::certifi-2022.9.14-p~ --> conda-forge/noarch::certifi-2022.9.24-pyhd8ed1ab_0 None
  vs2015_runtime     pkgs/main::vs2015_runtime-14.27.29016~ --> conda-forge::vs2015_runtime-14.29.30139-h890b9b1_7 None

The following packages will be SUPERSEDED by a higher-priority channel:

  openssl              pkgs/main::openssl-1.1.1q-h2bbff1b_0 --> conda-forge::openssl-1.1.1q-h8ffe710_0 None


Proceed ([y]/n)? y


Downloading and Extracting Packages
libzlib-1.2.12       | 71 KB     | ############################################################################ | 100%
ucrt-10.0.20348.0    | 1.2 MB    | ############################################################################ | 100%
ca-certificates-2022 | 189 KB    | ############################################################################ | 100%
heyoka-0.19.0        | 57.6 MB   | ############################################################################ | 100%
sleef-3.5.1          | 1008 KB   | ############################################################################ | 100%
tbb-2021.6.0         | 174 KB    | ############################################################################ | 100%
fmt-8.1.1            | 179 KB    | ############################################################################ | 100%
zstd-1.5.2           | 401 KB    | ############################################################################ | 100%
spdlog-1.10.0        | 318 KB    | ############################################################################ | 100%
boost-cpp-1.78.0     | 17.1 MB   | ############################################################################ | 100%
openssl-1.1.1q       | 5.8 MB    | ############################################################################ | 100%
certifi-2022.9.24    | 155 KB    | ############################################################################ | 100%
vs2015_runtime-14.29 | 1.3 MB    | ############################################################################ | 100%
Preparing transaction: done
Verifying transaction: done
Executing transaction: done
Retrieving notices: ...working... done

(envtest3) C:\>python
Python 3.10.4 | packaged by conda-forge | (main, Mar 30 2022, 08:38:02) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import heyoka
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'heyoka'

Expected behavior It should import the package without failing.

Environment:

OS: Windows 10
Installation method: conda
Version: 0.19.0

Additional context

I wanted to benchmark heyoka against the older packages taylor by Jorba and Zou (which got updated to v2.0 very recently), and TIDES from Abad et al, which both work for me.
I am not sure if I understood correctly, but I have not installed the C++ libraries separately, since I believe everything is taken care of by conda, and we can see that it indeed pulls boost-cpp, tbb, fmt. But was it a correct assumption, that I do not have to have anything preinstalled prior to doing conda install ?
I tried deleted and recreating the environment, deactivating it and reactivating it, updating conda, nothing worked. I tried many other random packages in this environment, before and after installing heyoka, and they got installed and imported fine, so this is the only package that does this for me, and the first time I encounter this behavior for a package too.
One thing I noticed is that in C:\Users\MYUSERNAME\Miniconda3\envs\envtest3\Lib\site-packages there are no packages related to the supposed install of heyoka: no heyoka, boost, tbb, fmt, that supposedly got downloaded and installed from the logs as seen above. Whereas when I install random other packages they always end up there. I find instances of heyoka in C:\Users\MYUSERNAME\Miniconda3\pkgs though: the folder heyoka-0.19.0-hb4083ac_0 is there. tbb, fmt, and boost-cpp have the same 'problem' (boost-cpp does show up as boost-cpp-1.78.0-h9f4b32c_1.json in C:\Users\MYUSERNAME\Miniconda3\envs\envtest3\conda-meta if that helps). I tried importing heyoka it in the base environment just in case, but it doesn't work either (conda list doesn't show heyoka in base anyway as expected, whereas it appears in my envtest3 even though I cannot import it). So maybe it is an install path problem ?

bug

opened by viivgit 5

[BUG]
Describe the bug No Taylor coefficients with ensemble_propagate_until

Hi there, awesome program! I just stumbled upon an issue. Below is a somewhat minimal example:

To Reproduce

import heyoka as hy qp = hy.make_vars(*[f"coord_q0", f"coord_p0"]) q, p = qp hameqs = [(q, p), (p, 2.3 * q**2)] integrator = hy.taylor_adaptive(hameqs, [0]*2) q0, p0 = 0.03, -0.05 qp0 = np.array([[q0], [p0]]) def gen(tacp, i): tacp.state[:] = qp0[:, i] return tacp results = hy.ensemble_propagate_for(integrator, delta_t=1, n_iter=1, gen=gen, write_tc=True)

Then I try (in various orders, e.g.):

integrator.update_d_output(t=0.4) integrator.tc

Expected behavior I was expecting that integrator.tc has some non-zero Taylor coefficients for the map around zero, transporting the initial coordinates from t=0 to t=0.4. However, I only see zeros. Perhaps I did something wrong? Same problem with ensemble_propagate_until.

Environment

Linux

Heyoka version: 0.18.0

bug
opened by mtitze 3
[DOCUMENTATION FEATURE] Requesting information from "logger messages" on heyoka.py
I suggest the inclusion of some sort of explanation for the logging message output when heyoka.py is imported

[heyoka] [info] heyoka logger initialised

Nothing is mentioned in the documentation. If it is a debug message, it should be interesting to provide an flag option for switching out those.
opened by hfsf 3
Trappist notebook finalized

The notebook with the long term simulation of the Trappist system (in the form of an advanced example).

Note that execution time is too long thus it may need to be addressed.

opened by darioizzo 1
Issue on page /install.html

The installation from source procedure doesn't play well with pip: Heyoka cannot be named as a dependency for another python project as pip isn't aware that it is installed.

opened by AlexandreFoley 1

Releases(v0.20.0)

v0.20.0(Dec 18, 2022)
This new heyoka.py release comes with a big new feature and several small fixes and additions.

Arbitrary-precision computations :heavy_division_sign:

Taylor integrators shine in high-accuracy applications, and now, with heyoka.py, you can get as accurate as you want!

In addition to double and extended-precision computations, heyoka.py now also supports computations in arbitrary precision. In other words, you can perform numerical integrations with an arbitrarily high accuracy, limited in principle only by the available memory.

Arbitrary-precision computations require the heyoka C++ library to be built with support for the mp++ multiprecision library (see the heyoka installation instructions for more details). A tutorial illustrating how to set up numerical integrations in arbitrary precision is available in the documentation.

Fixes :lady_beetle:

fix build issue with Python 3.11;

fix several small issues in the real128 API.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.19.0(Sep 19, 2022)
This new version of heyoka.py comes with two big new features and a few fixes.

Extended-precision computations :heavy_division_sign:

Extended-precision computations are now fully supported with an API identical to double-precision computations. A tutorial explaining this new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/ext_precision.html

Note that, as a consequence of this new feature, heyoka.py is now more strict than it used to be with respect to type conversions, and this could result in TypeError exceptions being raised in user code after upgrading. Please see the "Breaking Changes" section in the documentation for more details and solutions:

https://bluescarni.github.io/heyoka.py/breaking_changes.html#bchanges-0-19-0

Compiled functions :rocket:

It is now possible to compile just-in-time functions defined via the heyoka.py expression system. Compiled functions provide fast function evaluation capabilities for scalar and vector arguments. A tutorial describing this new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/compiled_functions.html

Fixes :bug:

heyoka.py now compiles without deprecation warnings against the latest versions of the fmt library

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.18.0(May 11, 2022)
This new version of heyoka.py comes with a big new feature and several fixes.

Automatic parallelisation :rocket:

heyoka.py is now capable of automatically performing multithreaded fine-grained parallelisation within an individual integration step. Parallel mode is easily enabled, and it can lead to substantial speed-ups, especially for large ODE systems and/or extended precision computations.

A tutorial exploring this new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/parallel_mode.html

Astrodynamics :ringed_planet:

It is now possible to construct (N+1)-body problems - that is, N-body problems expressed in the reference frame of one of the bodies (rather than in an inertial reference frame).

A fast Kepler solver (supporting both scalar values and NumPy arrays) is now available.

Fixes & clean-ups :lady_beetle:

Several small issues in the implementation of propagate_grid() were identified and fixed.

heyoka.py now depends on the Intel TBB library.

heyoka.py does not depend any more on the spdlog library.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.17.0(Jan 25, 2022)
This new version of heyoka.py comes with a big new feature, several quality-of-life improvements and a few fixes.

Ensemble propagations :rocket:

The big new feature is support for ensemble propagations. In ensemble mode, multiple distinct instances of the same ODE system are integrated in parallel, typically using different sets of initial conditions and/or runtime parameters. Monte Carlo simulations and parameter searches are two typical examples of tasks in which ensemble mode is particularly useful.

The combination of ensemble mode with batch integrators can lead to substantial speedups (e.g., a floating-point throughput increase of 23x was observed on a modern desktop computer using 8 threads of execution, see here).

Quality of life improvements

Several functions in the batch integration API now also accept scalar time values in input, instead of just vectors. This change improves the usability of batch mode by reducing the amount of typing necessary to interact with batch integrators;

a function to compute the suggested SIMD size for the CPU in use was added;

it is now possible to access the internal representation of the integrator's time variable as a double-length float.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.16.0(Nov 20, 2021)
This is another big release for heyoka.py, featuring 2 major new features and substantial performance improvements.

Event detection support in batch mode :fast_forward:

Event detection is now available in the batch mode Taylor integrator. As a result, the batch mode integrator has now feature parity with the scalar mode integrator.

The batch mode event detection API is very similar to scalar mode. A tutorial describing the new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/Batch%20mode%20overview.html#event-detection

Continuous output :chart_with_upwards_trend:

Debuting in this release is support for continuous output for the propagate_for/until() methods of the scalar and batch integrators.

Continuous output allows to compute the value of the solution of the ODE system at any time within the integration time interval covered by propagate_for/until(). Tutorials are available here:

https://bluescarni.github.io/heyoka.py/notebooks/Dense%20output.html#continuous-output

https://bluescarni.github.io/heyoka.py/notebooks/Batch%20mode%20overview.html#continuous-output

This feature has been inspired by a similar feature available in the DifferentialEquations.jl package.

Performance improvements :rocket:

As a result of various micro-optimisations, performance for large ODE systems in compact mode has improved by up to 15%.

Additionally, fast event exclusion checking is now implemented as a JIT-compiled function, which leads to a ~30% reduction in the event detection overhead.

Miscellanea :ballot_box_with_check:

Fix potential issue with data aliasing in corner cases.

Fix wrong counting of integration steps in case of interruption by a terminal event.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.15.1(Oct 10, 2021)

This is a quick bugfix :bug: release that fixes an issue in the conversion of SymPy rationals to the heyoka.py expression system.

The full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.15.0(Sep 28, 2021)
This is one of the biggest releases of heyoka.py to date, featuring various new capabilities, a major change in the expression system and several fixes.

Reference semantics for funcs

A fundamental change debuting in heyoka.py 0.15.0 is that function nodes in the expression system now use reference semantics, instead of value semantics. This change is motivated by various use cases involving large symbolic expressions with a high degree of internal repetition (including, e.g., artificial neural networks), which can now be handled by the expression system orders of magnitude more efficiently (from the point of view of both CPU and memory utilisation).

New features in the expression system :fountain_pen:

It is now possible to compute the symbolic derivative of an expression with respect to a parameter.

Numerical constants can now be defined in a symbolic way. The symbolic π constant is now available in the expression system, using this new framework.

The two-argument inverse tangent function atan2() has been added to the expression system.

The VSOP2013 solution :ringed_planet:

An implementation of the VSOP2013 analytical solution for the motion of the planets of the Solar System has been added to the expression system. This means that it is now possible to formulate differential equations containing the positions/velocities of the planets of the Solar System as functions of time.

A tutorial introducing this new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/vsop2013.html

Improved support for PPC64 :computer:

Thanks to the generosity of OSU's Open Source Lab, who provided remote access to a PowerPC workstation, heyoka.py now features much better support for 64-bit PowerPC processors. In particular, heyoka.py is now able to take advantage of the hardware-accelerated quadruple-precision arithmetic capabilities of recent PowerPC processors.

Other changes :ballot_box_with_check:

Performance improvements to event detection.

Various fixes and improvements to the build system.

Fix a corner-case issue in the implementation of the kepE() function.

Full changelog

As usual, the full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.14.0(Aug 3, 2021)

This new release of heyoka.py implements an important improvement in the automatic deduction of the cooldown value for terminal events, which should now be more reliable than before.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.12.0(Jul 23, 2021)
The 0.12.0 release of heyoka.py features two important additions:

serialisation support,

support for 64-bit ARM CPUs.

Serialisation

Serialisation allows to save/load heyoka.py objects via Python's pickle module. A tutorial showcasing this new feature is available here:

https://bluescarni.github.io/heyoka.py/notebooks/pickling.html

Please pay attention to the very important CAVEATS highlighted at the beginning of the tutorial!

Support for non-x86 CPUs

This is the first version of heyoka.py officially supporting 64-bit ARM processors. ARM builds have been added to the continuous integration pipeline, courtesy of CircleCI.
Source code(tar.gz)
Source code(zip)
v0.11.0(Jul 6, 2021)

This is a minor release to keep the release number of heyoka.py in sync with the release number of the heyoka C++ library. Apart from a new tutorial notebook and a few doc fixes, there are no functional changes with respect to version 0.10.0.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.10.0(Jun 9, 2021)

The latest version of heyoka.py comes with an important new feature, the ability to convert heyoka.py expressions to/from SymPy expressions. A tutorial showcasing this new feature is available here.

Additionally, this release introduces a change in the API of the callbacks that can (optionally) be passed to the propagate_*() methods. Also, this release features a new pairwise product primitive and various improvements to the automatic simplification capabilities of the expression system.

As usual, the detailed changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.9.0(May 25, 2021)

This release includes two new functions in the expression system: the inverse of Kepler's elliptic equation and time polynomials.

Additionally, this release features also performance improvements and various internal cleanups.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.8.0(Apr 28, 2021)

This new release of heyoka.py features a couple of breaking changes in the event detection API. The changes are explained in detail here:

https://bluescarni.github.io/heyoka.py/breaking_changes.html#bchanges-0-8-0

The release contains also a couple of new features for the propagate_*() functions. As usual, the full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.7.0(Apr 22, 2021)

This new release of heyoka.py comes with several feature additions and a couple of fixes.

One important improvement is that the time coordinate in the adaptive integrators is now represented internally in double-length format, which greatly increases time accuracy.

As usual, the full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.6.1(Apr 8, 2021)

This is a small incremental release that bumps up the minimum required version of the heyoka C++ library to 0.6.1.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.6.0(Apr 6, 2021)

This new version of heyoka.py comes with a big new feature, event detection. Various tutorials exploring this new feature are available:

https://bluescarni.github.io/heyoka.py/advanced_tutorials.html#event-detection

Another important new feature is that propagate_grid() can now be used with the batch integrator.

The full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.5.0(Feb 25, 2021)

This is a minor release that features additions and improvements to the expression system. In particular, the symbolic differentiation capabilities of heyoka's expression system are now available also in Python.

The full changelog, as usual, is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.4.0(Feb 20, 2021)
This new release of heyoka.py comes with several new features:

support for outputting the Taylor coefficients that were used to perform a single time step,

support for dense (continuous) output,

efficient propagation over a time grid via dense output,

new automatic simplifications in the expression system,

a new function powi() for exponentiation with natural exponents.

There is also an important bugfix regarding a division by zero in certain corner cases when using pow() with small natural exponents.

As usual, the full changelog is available here:

https://bluescarni.github.io/heyoka.py/changelog.html
Source code(tar.gz)
Source code(zip)
v0.3.0(Feb 13, 2021)

This is the initial release of heyoka.py.
Source code(tar.gz)
Source code(zip)