========================================================================
oscode: Oscillatory ordinary differential equation solver
========================================================================
.. image:: https://codecov.io/gh/fruzsinaagocs/oscode/branch/joss-paper/graph/badge.svg
:target: https://codecov.io/gh/fruzsinaagocs/oscode
:alt: codecov status
.. image:: https://github.com/fruzsinaagocs/oscode/actions/workflows/python-package.yml/badge.svg
:target: https://github.com/fruzsinaagocs/oscode/actions
:alt: GH workflow status
.. image:: https://readthedocs.org/projects/oscode/badge/?version=latest
:target: https://oscode.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://badges.gitter.im/oscode-help/community.svg
:target: https://gitter.im/oscode-help/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
:alt: Chat on gitter
.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
:target: https://opensource.org/licenses/BSD-3-Clause
:alt: BSD 3-clause license
.. image:: https://img.shields.io/pypi/dm/pyoscode?color=indigo
:target: https://pypi.org/project/pyoscode/
:alt: PyPI downloads
.. image:: https://joss.theoj.org/papers/d4c9396ef9b2b595e2f3881a4f8a7cda/status.svg
:target: https://joss.theoj.org/papers/d4c9396ef9b2b595e2f3881a4f8a7cda
:alt: JOSS status
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4322958.svg
:target: https://doi.org/10.5281/zenodo.4322958
:alt: Zenodo doi
|
|
.. contents::
:local:
|
About
-----
Oscode is a C++ tool with a Python interface that solves **osc**\illatory
**o**\rdinary **d**\ifferential **e**\quations efficiently. It is designed to
deal with equations of the form
.. image::
https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/oscillator.png
where |gamma| (friction term) and |omega| (frequency) can be given as arrays.
.. |gamma| image:: https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/gamma.png
.. |omega| image:: https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/omega.png
Oscode makes use of an analytic approximation of x(t) embedded in a
stepping procedure to skip over long regions of oscillations, giving a reduction
in computing time. The approximation is valid when the frequency changes slowly
relative to the timescales of integration, it is therefore worth applying when
this condition holds for at least some part of the integration range.
For the details of the numerical method used by oscode, see Citation_.
Installation
------------
Dependencies
~~~~~~~~~~~~
Basic requirements for using the C++ interface:
- C++11 or later
- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`__ (a header-only library included in this source)
The strictly necessary Python dependencies are automatically installed when you use `pip` or the `setup.py`. They are:
- `numpy <https://pypi.org/project/numpy/>`__
The *optional* dependencies are:
- for tests
- `scipy <https://pypi.org/project/scipy/>`__
- `pytest <https://docs.pytest.org/en/stable/getting-started.html>`__
- for examples/plotting
- `matplotlib <https://pypi.org/project/matplotlib/>`__
- `scipy <https://pypi.org/project/scipy/>`__
- for generating offline documentation
- `sphinx <https://pypi.org/project/Sphinx/>`__
- `doxygen <https://www.doxygen.nl/index.html>`__
- `breathe <https://pypi.org/project/breathe/>`__
- `exhale <https://pypi.org/project/exhale/>`__
Python
~~~~~~
``pyoscode`` can be installed via pip
.. code:: bash
pip install pyoscode
or via the setup.py
.. code:: bash
git clone https://github.com/fruzsinaagocs/oscode
cd oscode
python setup.py install --user
or
.. code:: bash
git clone https://github.com/fruzsinaagocs/oscode
cd oscode
pip install .
You can then import ``pyoscode`` from anywhere. Omit the ``--user`` option if
you wish to install globally or in a virtual environment. If you have any
difficulties, check out the `FAQs - Installation
<https://github.com/fruzsinaagocs/oscode#installation-1>`__ section below.
You can check that things are working by running `tests/` (also ran by Travis continuous integration):
.. code:: bash
pytest tests/
C++
~~~
``oscode`` is a header-only C++ package, it requires no installation.
.. code:: bash
git clone https://github.com/fruzsinaagocs/oscode
and then include the relevant header files in your C++ code:
.. code:: c
#include "solver.hpp"
#include "system.hpp"
Quick start
-----------
Try the following quick examples. They are available in the `examples
<https://github.com/fruzsinaagocs/oscode/tree/master/examples/>`__.
Python
~~~~~~
:Introduction to pyoscode: |intro_binder|
:Cosmology examples: |cosmology_binder|
:Scipy 2020 lecture notebook: |scipy_binder|
.. |intro_binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/introduction_to_pyoscode.ipynb
.. |cosmology_binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/cosmology.ipynb
.. |scipy_binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/pyoscode_scipy.ipynb
.. image::
https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/spectra.gif
:width: 800
C++
~~~
:Introduction to oscode: `examples/burst.cpp`
:To plot results from `burst.cpp`: `examples/plot_burst.py`
To compile and run:
.. code:: bash
cd examples/
g++ -I../include/ -g -Wall -std=c++11 -c -o burst.o burst.cpp
g++ -I../include/ -g -Wall -std=c++11 -o burst burst.o
./burst
Documentation
-------------
Documentation is hosted at `readthedocs <https://oscode.readthedocs.io>`__.
To build your own local copy of the documentation you can run:
.. code:: bash
cd pyoscode/docs
make html
Citation
--------
If you use ``oscode`` to solve equations for a publication, please cite:
- `Efficient method for solving highly oscillatory ordinary differential equations with applications to physical systems <https://doi.org/10.1103/PhysRevResearch.2.013030>`__,
- `Dense output for highly oscillatory numerical solutions <https://arxiv.org/abs/2007.05013>`__
Contributing
------------
Any comments and improvements to this project are welcome. You can contribute
by:
- Opening and `issue <https://www.github.com/fruzsinaagocs/oscode/issues/>`__ to report bugs and propose new features.
- Making a pull request.
Further help
------------
You can get help by submitting an issue or posting a message on `Gitter <https://gitter.im/oscode-help/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge>`__.
FAQs
----
Installation
~~~~~~~~~~~~
1. Eigen import errors:
.. code:: bash
pyoscode/_pyoscode.hpp:6:10: fatal error: Eigen/Dense: No such file or directory
#include <Eigen/Dense>
^~~~~~~~~~~~~
Try explicitly including the location of your Eigen library via the
``CPLUS_INCLUDE_PATH`` environment variable, for example:
.. code:: bash
CPLUS_INCLUDE_PATH=/usr/include/eigen3 python setup.py install --user
# or
CPLUS_INCLUDE_PATH=/usr/include/eigen3 pip install pyoscode
where ``/usr/include/eigen3`` should be replaced with your system-specific
eigen location.
Thanks
------
Many thanks to **Will Handley**, **Lukas Hergt**, **Anthony Lasenby**, and **Mike Hobson** for
their support and advice regarding the algorithm behind `oscode`.
There are many packages without which some part of `oscode` (e.g. testing and
examples) wouldn't run as nicely and smoothly, thank you all developers for
making and maintaining these open-source projects. A special thanks goes to the
devs of `exhale <https://pypi.org/project/exhale/>`__ for making the beautiful C++ documentation possible.
Changelog
---------
- 1.1.2:
- Dense output bug fix at the C++ interface
- 1.1.1:
- Support for mac and Windows OS at CI.
- 1.1.0:
- Users can now define w, g as functions in Python (pyoscode) and call the solver via pyoscode.solve_fn(...)
- 1.0.6:
- Fix issues related to dense output not being correctly generated, e.g. when timepoints at which dense output was asked for are in descending order, etc.
- 1.0.5:
- Fixes related to dense output generation
- Support for w, g to be given as class member functions in C++
- Switched to GH actions for continuous integration, and fixed code such that unit tests would run again
- Minor tweaks
- 1.0.4:
- set minimally required numpy version: numpy>=1.20.0
- drop Python 2.7 support, instead support 3.8 and 3.9 in addition to 3.7
- 1.0.3:
- paper accepted to JOSS
- 1.0.2:
- Fixed getting correct numpy include directories
- 1.0.1:
- Added `pyproject.toml` to handle build dependencies (numpy)
- 1.0.0:
- Dense output
- Arrays for frequency and damping term need not be evenly spaced
- Automatic C++ documentation on readthedocs
- Eigen included in source for pip installability
- First pip release :)
- 0.1.2:
- Bug that occurred when beginning and end of integration coincided
corrected
- 0.1.1:
- Automatic detection of direction of integration
- 0.1.0:
- Memory leaks at python interface fixed
- C++ documentation added
Raw data
{
"_id": null,
"home_page": "https://github.com/fruzsinaagocs/oscode",
"name": "pyoscode",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "PPS,cosmic inflation,cosmology,oscillatory,ODE",
"author": "Fruzsina Agocs",
"author_email": "fa325@cam.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/e2/42/f6332be9032e13f9a58af52b56300d6eeb98a6d1a16fb8ba8afba22cacb3/pyoscode-1.1.2.tar.gz",
"platform": null,
"description": "========================================================================\noscode: Oscillatory ordinary differential equation solver\n========================================================================\n\n.. image:: https://codecov.io/gh/fruzsinaagocs/oscode/branch/joss-paper/graph/badge.svg\n :target: https://codecov.io/gh/fruzsinaagocs/oscode\n :alt: codecov status\n.. image:: https://github.com/fruzsinaagocs/oscode/actions/workflows/python-package.yml/badge.svg\n :target: https://github.com/fruzsinaagocs/oscode/actions\n :alt: GH workflow status\n.. image:: https://readthedocs.org/projects/oscode/badge/?version=latest\n :target: https://oscode.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. image:: https://badges.gitter.im/oscode-help/community.svg\n :target: https://gitter.im/oscode-help/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge\n :alt: Chat on gitter\n.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg\n :target: https://opensource.org/licenses/BSD-3-Clause\n :alt: BSD 3-clause license\n.. image:: https://img.shields.io/pypi/dm/pyoscode?color=indigo \n :target: https://pypi.org/project/pyoscode/\n :alt: PyPI downloads\n.. image:: https://joss.theoj.org/papers/d4c9396ef9b2b595e2f3881a4f8a7cda/status.svg\n :target: https://joss.theoj.org/papers/d4c9396ef9b2b595e2f3881a4f8a7cda\n :alt: JOSS status\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4322958.svg\n :target: https://doi.org/10.5281/zenodo.4322958\n :alt: Zenodo doi\n\n|\n|\n\n.. contents::\n :local:\n\n|\n\nAbout\n-----\n\nOscode is a C++ tool with a Python interface that solves **osc**\\illatory\n**o**\\rdinary **d**\\ifferential **e**\\quations efficiently. It is designed to\ndeal with equations of the form\n\n.. image:: \n https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/oscillator.png\n\nwhere |gamma| (friction term) and |omega| (frequency) can be given as arrays.\n\n.. |gamma| image:: https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/gamma.png\n\n.. |omega| image:: https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/omega.png\n\nOscode makes use of an analytic approximation of x(t) embedded in a\nstepping procedure to skip over long regions of oscillations, giving a reduction\nin computing time. The approximation is valid when the frequency changes slowly\nrelative to the timescales of integration, it is therefore worth applying when\nthis condition holds for at least some part of the integration range. \n\nFor the details of the numerical method used by oscode, see Citation_.\n\n\nInstallation\n------------\n\nDependencies\n~~~~~~~~~~~~\n\nBasic requirements for using the C++ interface:\n\n- C++11 or later\n- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`__ (a header-only library included in this source)\n\nThe strictly necessary Python dependencies are automatically installed when you use `pip` or the `setup.py`. They are:\n\n- `numpy <https://pypi.org/project/numpy/>`__\n\nThe *optional* dependencies are: \n\n- for tests\n - `scipy <https://pypi.org/project/scipy/>`__ \n - `pytest <https://docs.pytest.org/en/stable/getting-started.html>`__ \n- for examples/plotting\n - `matplotlib <https://pypi.org/project/matplotlib/>`__\n - `scipy <https://pypi.org/project/scipy/>`__ \n- for generating offline documentation\n - `sphinx <https://pypi.org/project/Sphinx/>`__ \n - `doxygen <https://www.doxygen.nl/index.html>`__\n - `breathe <https://pypi.org/project/breathe/>`__\n - `exhale <https://pypi.org/project/exhale/>`__\n\n\nPython\n~~~~~~\n\n``pyoscode`` can be installed via pip \n\n.. code:: bash\n \n pip install pyoscode\n\nor via the setup.py\n\n.. code:: bash\n\n git clone https://github.com/fruzsinaagocs/oscode\n cd oscode\n python setup.py install --user\n\nor\n\n.. code:: bash\n\n git clone https://github.com/fruzsinaagocs/oscode\n cd oscode\n pip install .\n\nYou can then import ``pyoscode`` from anywhere. Omit the ``--user`` option if\nyou wish to install globally or in a virtual environment. If you have any\ndifficulties, check out the `FAQs - Installation\n<https://github.com/fruzsinaagocs/oscode#installation-1>`__ section below. \n\nYou can check that things are working by running `tests/` (also ran by Travis continuous integration):\n\n.. code:: bash\n\n pytest tests/\n\nC++\n~~~\n\n``oscode`` is a header-only C++ package, it requires no installation.\n\n.. code:: bash\n\n git clone https://github.com/fruzsinaagocs/oscode\n\nand then include the relevant header files in your C++ code:\n\n.. code:: c\n\n #include \"solver.hpp\"\n #include \"system.hpp\"\n\n\nQuick start\n-----------\n\nTry the following quick examples. They are available in the `examples\n<https://github.com/fruzsinaagocs/oscode/tree/master/examples/>`__.\n\nPython\n~~~~~~\n\n:Introduction to pyoscode: |intro_binder|\n:Cosmology examples: |cosmology_binder|\n:Scipy 2020 lecture notebook: |scipy_binder|\n\n.. |intro_binder| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/introduction_to_pyoscode.ipynb\n\n.. |cosmology_binder| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/cosmology.ipynb\n\n.. |scipy_binder| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/fruzsinaagocs/oscode/master?filepath=examples/pyoscode_scipy.ipynb\n\n\n.. image::\n https://github.com/fruzsinaagocs/oscode/raw/master/pyoscode/images/spectra.gif\n :width: 800\n\nC++\n~~~\n\n:Introduction to oscode: `examples/burst.cpp`\n:To plot results from `burst.cpp`: `examples/plot_burst.py`\n\nTo compile and run:\n\n.. code:: bash\n \n cd examples/\n g++ -I../include/ -g -Wall -std=c++11 -c -o burst.o burst.cpp\n g++ -I../include/ -g -Wall -std=c++11 -o burst burst.o\n ./burst\n\n\nDocumentation\n-------------\n\nDocumentation is hosted at `readthedocs <https://oscode.readthedocs.io>`__.\n\nTo build your own local copy of the documentation you can run:\n\n.. code:: bash\n\n cd pyoscode/docs\n make html\n\nCitation\n--------\n\nIf you use ``oscode`` to solve equations for a publication, please cite:\n\n- `Efficient method for solving highly oscillatory ordinary differential equations with applications to physical systems <https://doi.org/10.1103/PhysRevResearch.2.013030>`__,\n- `Dense output for highly oscillatory numerical solutions <https://arxiv.org/abs/2007.05013>`__\n\nContributing\n------------\n\nAny comments and improvements to this project are welcome. You can contribute\nby:\n\n- Opening and `issue <https://www.github.com/fruzsinaagocs/oscode/issues/>`__ to report bugs and propose new features.\n- Making a pull request.\n\nFurther help\n------------\n\nYou can get help by submitting an issue or posting a message on `Gitter <https://gitter.im/oscode-help/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge>`__.\n\nFAQs\n----\n\nInstallation\n~~~~~~~~~~~~\n\n1. Eigen import errors:\n .. code:: bash\n\n pyoscode/_pyoscode.hpp:6:10: fatal error: Eigen/Dense: No such file or directory\n #include <Eigen/Dense>\n ^~~~~~~~~~~~~\n\n Try explicitly including the location of your Eigen library via the\n ``CPLUS_INCLUDE_PATH`` environment variable, for example:\n\n .. code:: bash\n\n CPLUS_INCLUDE_PATH=/usr/include/eigen3 python setup.py install --user\n # or \n CPLUS_INCLUDE_PATH=/usr/include/eigen3 pip install pyoscode\n\n where ``/usr/include/eigen3`` should be replaced with your system-specific\n eigen location.\n\nThanks\n------\n\nMany thanks to **Will Handley**, **Lukas Hergt**, **Anthony Lasenby**, and **Mike Hobson** for\ntheir support and advice regarding the algorithm behind `oscode`.\nThere are many packages without which some part of `oscode` (e.g. testing and\nexamples) wouldn't run as nicely and smoothly, thank you all developers for\nmaking and maintaining these open-source projects. A special thanks goes to the\ndevs of `exhale <https://pypi.org/project/exhale/>`__ for making the beautiful C++ documentation possible. \n\n\nChangelog\n---------\n\n- 1.1.2:\n - Dense output bug fix at the C++ interface \n- 1.1.1: \n - Support for mac and Windows OS at CI.\n- 1.1.0:\n - Users can now define w, g as functions in Python (pyoscode) and call the solver via pyoscode.solve_fn(...)\n- 1.0.6:\n - Fix issues related to dense output not being correctly generated, e.g. when timepoints at which dense output was asked for are in descending order, etc. \n- 1.0.5:\n - Fixes related to dense output generation\n - Support for w, g to be given as class member functions in C++\n - Switched to GH actions for continuous integration, and fixed code such that unit tests would run again\n - Minor tweaks\n- 1.0.4:\n - set minimally required numpy version: numpy>=1.20.0\n - drop Python 2.7 support, instead support 3.8 and 3.9 in addition to 3.7\n- 1.0.3: \n - paper accepted to JOSS\n- 1.0.2:\n - Fixed getting correct numpy include directories\n- 1.0.1:\n - Added `pyproject.toml` to handle build dependencies (numpy)\n- 1.0.0:\n - Dense output\n - Arrays for frequency and damping term need not be evenly spaced\n - Automatic C++ documentation on readthedocs\n - Eigen included in source for pip installability\n - First pip release :)\n- 0.1.2:\n - Bug that occurred when beginning and end of integration coincided\n corrected\n- 0.1.1:\n - Automatic detection of direction of integration\n- 0.1.0:\n - Memory leaks at python interface fixed\n - C++ documentation added \n",
"bugtrack_url": null,
"license": "oscode",
"summary": "oscode: Oscillatory ordinary differential equation solver",
"version": "1.1.2",
"project_urls": {
"Documentation": "https://oscode.readthedocs.io",
"Homepage": "https://github.com/fruzsinaagocs/oscode"
},
"split_keywords": [
"pps",
"cosmic inflation",
"cosmology",
"oscillatory",
"ode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e242f6332be9032e13f9a58af52b56300d6eeb98a6d1a16fb8ba8afba22cacb3",
"md5": "b2955ca26f148ccc22af65581903b71e",
"sha256": "262daec396ead91fcff04a7af3afb7fe087583a0fbd3d57ffc5b2516f0a73b09"
},
"downloads": -1,
"filename": "pyoscode-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "b2955ca26f148ccc22af65581903b71e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8191349,
"upload_time": "2023-06-01T22:07:43",
"upload_time_iso_8601": "2023-06-01T22:07:43.221569Z",
"url": "https://files.pythonhosted.org/packages/e2/42/f6332be9032e13f9a58af52b56300d6eeb98a6d1a16fb8ba8afba22cacb3/pyoscode-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-01 22:07:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fruzsinaagocs",
"github_project": "oscode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyoscode"
}
JSON
