Merge branch 'joss-paper'

.gitignore

@@ -1,14 +1,14 @@
-build
-*.so
-__pycache__
-*.pyc
-.eggs
-pyoscode.egg-info/
-.ipynb_checkpoints
-pyoscode/docs/_build
-pyoscode/docs/source/_static
-pyoscode/docs/source/_templates
-examples/*
-!examples/*.cpp
-!examples/*.py
-!examples/*.ipynb
+*
+!/examples/*.py
+!/examples/*.ipynb
+!/examples/*.cpp
+!/examples/images/**
+!/include/**
+!/pyoscode/
+!/tests/
+!Dockerfile
+!/JOSS-paper/*
+!LICENSE
+!README.md
+!setup.py
+!requirements.txt

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+#sphinx:
+#  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+    - requirements: pyoscode/docs/requirements.txt

.travis.yml

@@ -1,8 +1,3 @@
-before_install:
-    - git clone https://github.com/eigenteam/eigen-git-mirror
-    - export CPLUS_INCLUDE_PATH="$PWD/eigen-git-mirror/:$CPLUS_INCLUDE_PATH"
-    - sudo apt-get update
-    - sudo apt-get install libboost-all-dev
 language: python
 python: 
     - "2.7"
@@ -13,7 +8,10 @@ install:
     - pip install -r requirements.txt
     - pip install .
 script:
-    - pytest tests/
+    - coverage run -m pytest tests/
 branches:
     only:
     - master
+    - joss-paper
+after_success:
+    - bash <(curl -s https://codecov.io/bash)

Dockerfile

@@ -0,0 +1,39 @@
+FROM ubuntu:18.04
+
+RUN apt-get update && apt-get install -y \
+    git python3-pip
+RUN pip3 install --no-cache --upgrade pip && \
+    pip3 install --no-cache notebook && \
+    pip3 install scipy numpy matplotlib ipywidgets jupyter_contrib_nbextensions \
+    hide_code cite2c RISE && \
+    jupyter contrib nbextension install --user && \
+    jupyter nbextension enable hide_code --user --py && \
+    python3 -m cite2c.install
+
+#RUN git clone https://github.com/eigenteam/eigen-git-mirror 
+#ENV CPLUS_INCLUDE_PATH=${PWD}/eigen-git-mirror/:${CPLUS_INCLUDE_PATH}
+#RUN echo $CPLUS_INCLUDE_PATH
+RUN mkdir oscode
+RUN git clone --single-branch --branch joss-paper https://github.com/fruzsinaagocs/oscode oscode/
+
+RUN cd oscode && \
+    python3 setup.py install
+
+# create user with a home directory
+ARG NB_USER
+ARG NB_UID
+ENV USER ${NB_USER}
+ENV HOME /home/${NB_USER}
+
+RUN adduser --disabled-password \
+    --gecos "Default user" \
+    --uid ${NB_UID} \
+    ${NB_USER}
+WORKDIR ${HOME}
+USER ${USER}
+
+# Make sure the contents of our repo are in ${HOME}
+COPY . ${HOME}
+USER root
+RUN chown -R ${NB_UID} ${HOME}
+USER ${NB_USER}

JOSS-paper/paper.bib

@@ -0,0 +1,160 @@
+@article{oscode,
+  title = {Efficient method for solving highly oscillatory ordinary differential equations with applications to physical systems},
+  author = {Agocs, F. J. and Handley, W. J. and Lasenby, A. N. and Hobson, M. P.},
+  journal = {Phys. Rev. Research},
+  volume = {2},
+  issue = {1},
+  pages = {013030},
+  numpages = {16},
+  year = {2020},
+  month = {Jan},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevResearch.2.013030},
+  url = {https://link.aps.org/doi/10.1103/PhysRevResearch.2.013030}
+}
+
+@article{beyond-rkwkb,
+  title = {{Beyond the Runge-Kutta-Wentzel-Kramers-Brillouin method}},
+  author = {Bamber, Jamie and Handley, Will},
+  journal = {Phys. Rev. D},
+  volume = {101},
+  issue = {4},
+  pages = {043517},
+  numpages = {13},
+  year = {2020},
+  month = {Feb},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevD.101.043517},
+  url = {https://link.aps.org/doi/10.1103/PhysRevD.101.043517}
+}
+
+@article{pps-curved,
+  title = {Primordial power spectra for curved inflating universes},
+  author = {Handley, Will},
+  journal = {Phys. Rev. D},
+  volume = {100},
+  issue = {12},
+  pages = {123517},
+  numpages = {8},
+  year = {2019},
+  month = {Dec},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevD.100.123517},
+  url = {https://link.aps.org/doi/10.1103/PhysRevD.100.123517}
+}
+
+@article{qic,
+  title = {Quantum initial conditions for inflation and canonical invariance},
+  author = {Agocs, F. J. and Hergt, L. T. and Handley, W. J. and Lasenby, A. N. and Hobson, M. P.},
+  journal = {Phys. Rev. D},
+  volume = {102},
+  issue = {2},
+  pages = {023507},
+  numpages = {20},
+  year = {2020},
+  month = {Jul},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevD.102.023507},
+  url = {https://link.aps.org/doi/10.1103/PhysRevD.102.023507}
+}
+
+@article{petzold,
+author = {Petzold, Linda R.},
+title = {An Efficient Numerical Method for Highly Oscillatory Ordinary Differential Equations},
+journal = {SIAM Journal on Numerical Analysis},
+volume = {18},
+number = {3},
+pages = {455-479},
+year = {1981},
+doi = {10.1137/0718030},
+URL = {https://doi.org/10.1137/0718030},
+eprint = {https://doi.org/10.1137/0718030}
+}
+
+@article{petzold-review,
+title={Numerical solution of highly oscillatory ordinary differential equations}, 
+volume={6}, 
+DOI={10.1017/S0962492900002750}, 
+journal={Acta Numerica}, 
+publisher={Cambridge University Press}, 
+author={Petzold, Linda R. and Jay, Laurent O. and Yen, Jeng}, 
+year={1997}, 
+pages={437–483}
+}
+
+@article{bremer,
+title = "On the numerical solution of second order ordinary differential equations in the high-frequency regime",
+journal = "Applied and Computational Harmonic Analysis",
+volume = "44",
+number = "2",
+pages = "312 - 349",
+year = "2018",
+issn = "1063-5203",
+doi = "https://doi.org/10.1016/j.acha.2016.05.002",
+url = "http://www.sciencedirect.com/science/article/pii/S1063520316300185",
+author = "James Bremer",
+}
+
+@article{hu-et-al-circuits,
+issn = {0332-1649},
+journal = {Compel},
+pages = {1607--1618},
+volume = {28},
+publisher = {Boole Press Limited,},
+number = {6},
+year = {2009},
+title = {On numerical methods for highly oscillatory problems in circuit simulation},
+address = {[Dublin] :},
+author = {Hu Li, Bo and Condon, Marissa and Deaño, Alfredo and Iserles, Arieh and Maczyński, Kornel and Xu, Tao},
+}
+
+@book{deano-integrals,
+author = {Deaño, Alfredo and Huybrechs, Daan and Iserles, Arieh},
+title = {Computing Highly Oscillatory Integrals},
+publisher = {Society for Industrial and Applied Mathematics},
+year = {2017},
+doi = {10.1137/1.9781611975123},
+address = {Philadelphia, PA},
+edition   = {},
+URL = {https://epubs.siam.org/doi/abs/10.1137/1.9781611975123},
+eprint = {https://epubs.siam.org/doi/pdf/10.1137/1.9781611975123}
+}
+
+@article{condon-deano-iserles, 
+title={Asymptotic solvers for oscillatory systems of differential equations}, 
+volume={53}, 
+DOI={10.1007/bf03322583}, 
+number={1}, 
+journal={SeMA Journal}, 
+author={Condon, M. and Deaño, A. and Iserles, A.}, 
+year={2011}, 
+pages={79–101}
+} 
+
+@misc{bremer-code,
+  author = {Bremer},
+  title = {{Phase functions: Fortran 90 code for solving highly oscillatory
+  ordinary differential equations in O(1) time}},
+  year = {2018},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  url = {https://github.com/JamesCBremerJr/Phase-functions}
+}
+
+@misc{dense-output,
+    title={Dense output for highly oscillatory numerical solutions},
+    author={Agocs, F. J. and Hobson, M. P. and Handley, W. J. and Lasenby, A. N.},
+    year={2020},
+    eprint={2007.05013},
+    archivePrefix={arXiv},
+    primaryClass={physics.comp-ph}
+}
+
+@misc{rkwkb-handley,
+    title={The Runge-Kutta-Wentzel-Kramers-Brillouin Method},
+    author={Handley, W. J. and Lasenby, A. N. and Hobson, M. P.},
+    year={2016},
+    eprint={1612.02288},
+    archivePrefix={arXiv},
+    primaryClass={physics.comp-ph}
+}

JOSS-paper/paper.md

@@ -0,0 +1,120 @@
+---
+title: '(py)oscode: fast solutions of oscillatory ODEs'
+tags:
+  - Python
+  - C++
+  - numerical methods
+  - ordinary differential equations
+  - oscillatory 
+  - runge-kutta 
+authors:
+  - name: Fruzsina Julia Agocs^[corresponding author.]
+    orcid: 0000-0002-1763-5884
+    affiliation: "1, 2" # (Multiple affiliations must be quoted)
+affiliations:
+ - name: Astrophysics Group, Cavendish Laboratory, J. J. Thomson Avenue, Cambridge, CB3 0HE, UK
+   index: 1
+ - name: Kavli Institute for Cosmology, Madingley Road, Cambridge, CB3 0HA, UK
+   index: 2
+date: 13 August 2017
+bibliography: paper.bib
+
+---
+
+# Summary
+
+Oscillatory differential equations are ubiquitous in physics, chemistry and beyond. They arise in
+quantum mechanics, electrical circuitry, suspension systems, molecular dynamics,
+and in models of gravitational and electromagnetic waves.
+The numerical solution of such systems however can be a computational bottleneck when tackled with conventional methods
+available from numerical libraries. 
+
+We present `(py)oscode`, a general-purpose numerical routine for solving a class of highly
+oscillatory ordinary differential equations (ODEs) efficiently. The package has
+been designed to solve equations which describe a single harmonic oscillator
+with a time-dependent frequency and damping term, i.e. are of the form
+\begin{equation}\label{eq:eom}
+y'' + 2\gamma(x) y' + \omega^2(x) y = 0.
+\end{equation}
+The frequency $\omega(x)$ and damping $\gamma(x)$ terms do not need
+to be explicit functions of $x$ (they can instead be e.g. the result of another
+numerical solution of an ODE), as they are supplied as sequences $\omega_j,
+\gamma_j$ evaluated at $x_i \leq x_j \leq x_f$, where $(x_i, x_f)$ is the
+integration range.
+
+`(py)oscode` is written in C++, but comes with a Python wrapper.
+Its Python interface was designed to be similar to those included in `scipy`'s numerical ODE solution
+modules. This is demonstrated in the example below whose output is shown in
+\autoref{fig:airy}.
+
+```python
+import numpy as np
+import scipy.special as sp
+import pyoscode
+
+# Set up the Airy equation as an example: y'' + xy = 0
+xs = np.linspace(0,40.0,5000)
+ws = np.sqrt(xs)
+gs = np.zeros_like(xs)
+# Initial conditions
+xi = 1.0
+xf = 40.0
+yi = sp.airy(-xi)[0]
+dyi = -sp.airy(-xi)[1]
+# Get dense output at the following points
+t_eval = np.linspace(15,35,600)
+# Solve the equation
+solution = pyoscode.solve(xs, ws, gs, xi, xf, yi, dyi, t_eval=t_eval)
+```
+
+![Numerical solution of the Airy equation, $y'' + xy = 0$, with `pyoscode`. The
+increase in step-size of `pyoscode`'s internal steps (orange dots) is due to the
+algorithm switching from using the RK method to the WKB approximation in the presence of high-frequency
+oscillations. The orange segment shows dense output, the solution at these
+points was computed at no additional evaluations of terms in the differential
+equation. \label{fig:airy}](examples/airy.png)
+
+# Statement of need 
+
+Even if the terms in \autoref{eq:eom} change slowly, if the frequency of
+oscillations in the solution is high enough, standard numerical methods struggle
+to solve such equations quickly. Traditional methods have to trace every
+oscillation in the solution, taking many steps in $x$ at an enormous
+computational cost. The algorithm underlying `(py)oscode`, published in
+[@oscode] and based on [@rkwkb-handley], can detect when the solution is oscillatory and switch to a method
+based on an analytic approximation (Wentzel--Kramers--Brillouin, WKB) suited for
+oscillatory functions, otherwise using a Runge--Kutta (RK) method. Using the WKB
+approximation allows the algorithm to skip over several wavelengths of
+oscillation in a single step, reducing the number of steps taken drastically. It
+adaptively updates its step-size to keep the local numerical error within a
+user-specified tolerance. `(py)oscode` is capable of producing a solution estimate
+at an arbitrary value of $x$, not just at its internal steps, therefore it can
+be used to generate a "continuous" solution, or dense output [@dense-output]. 
+
+# Related research and software
+
+`(py)oscode`'s development was motivated by the need for a significantly more
+efficient solver for the evolution of early-universe quantum fluctuations. These
+perturbations are thought to have been stretched to macroscopic scales by a
+phase of accelerated expansion, cosmic inflation, to later become the
+large-scale structure we see today. To understand the origins of structure it
+is therfore essential to model the perturbations and understand the physics
+involved in inflation. `(py)oscode` has been used to speed up the numerical evolution of quantum
+fluctuations in the early universe, enabling the exploration of models beyond
+the standard model of cosmology [@pps-curved]. It served as inspiration for
+other numerical methods aiming to extend the range of oscillatory ODEs to solve
+[@beyond-rkwkb]. 
+
+The efficient solution of oscillatory ODEs is a long-standing
+numerical analysis problem with many existing methods to handle certain
+sub-classes of equations. Examples include successful methods by Petzold [@petzold], reviewed in [@petzold-review] with many references therein, 
+Iserles et al. [@condon-deano-iserles] [@deano-integrals] [@hu-et-al-circuits], and Bremer [@bremer] (with code available from [@bremer-code]).
+
+# Acknowledgements
+
+I thank Lukas Hergt for invaluable discussions during the early development of
+`(py)oscode` and his ongoing support. Construction of the algorithm would not have been possible
+without the help and guidance of Will Handley, Mike Hobson, and Anthony Lasenby. 
+I was supported by the Science and Technology Facilities Council (STFC).
+
+# References