Use DocumenterCitations.jl to manage references (#245)

nathanaelbosch · Aug 1, 2023 · 221cd1f · 221cd1f
1 parent 9896a40
commit 221cd1f
Show file tree

Hide file tree

Showing 17 changed files with 312 additions and 60 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,7 +1,9 @@
 [deps]
+Bibliography = "f1be7e48-bf82-45af-a471-ae754a193061"
 DiffEqUncertainty = "ef61062a-5684-51dc-bb67-a0fcdec5c97d"
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Fenrir = "e9b4b195-f5cd-427c-8076-5358c553c37f"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,9 +1,35 @@
 using Documenter
 using ProbNumDiffEq
 
+using DocumenterCitations, Bibliography
+
+# DocumenterCitations.bib_sorting(::Val{:numeric}) = :nyt
+# function DocumenterCitations.format_bibliography_label(
+#     ::Val{:numeric},
+#     entry,
+#     citations::DocumenterCitations.OrderedDict{String,Int64},
+# )
+#     key = entry.id
+#     sorted_bibtex_keys = citations |> keys |> collect |> sort
+#     i = findfirst(x -> x == key, sorted_bibtex_keys)
+#     @info "format_bibliography_label" entry.id citations sorted_bibtex_keys i entry.date
+#     return "[$i]"
+# end
+# Bibliography.sorting_rules[:nyt] = [:authors; :date; :title]
+
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "refs.bib"),
+    style=:numeric,
+    # style=:authoryear,
+)
+sort_bibliography!(bib.entries, :nyt)  # name-year-title
+
 makedocs(
+    bib,
     sitename="ProbNumDiffEq.jl",
-    format=Documenter.HTML(),
+    format=Documenter.HTML(
+        assets=String["assets/citations.css"],
+    ),
     modules=[ProbNumDiffEq],
     pages=[
         "Home" => "index.md",
@@ -30,6 +56,7 @@ makedocs(
             "Filtering and Smoothing" => "filtering.md"
             "Implementation via OrdinaryDiffEq.jl" => "implementation.md"
         ],
+        "References" => "references.md",
     ],
 )
 

diff --git a/docs/src/assets/citations.css b/docs/src/assets/citations.css
@@ -0,0 +1,17 @@
+.citation dl {
+    display: grid;
+    grid-template-columns: max-content auto; }
+.citation dt {
+    grid-column-start: 1; }
+.citation dd {
+    grid-column-start: 2;
+    margin-bottom: 0.75em; }
+.citation ul {
+    padding: 0 0 2.25em 0;
+    margin: 0;
+    list-style: none;}
+.citation ul li {
+    text-indent: -2.25em;
+    margin: 0.33em 0.5em 0.5em 2.25em;}
+.citation ol li {
+    padding-left:0.75em;}
diff --git a/docs/src/diffusions.md b/docs/src/diffusions.md
@@ -44,7 +44,7 @@ Or more compactly:
 | Time-fixed   | [`FixedDiffusion`](@ref)   | [`FixedMVDiffusion`](@ref)            |
 
 
-For more details on diffusions and calibration, check out this paper [[1]](@ref diffusionrefs).
+For more details on diffusions and calibration, check out this paper [bosch20capos](@cite).
 
 
 ## API
@@ -59,4 +59,9 @@ FixedMVDiffusion
 
 ## [References](@id diffusionrefs)
 
-[1] N. Bosch, P. Hennig, F. Tronarp: **Calibrated Adaptive Probabilistic ODE Solvers** (2021) ([link](http://proceedings.mlr.press/v130/bosch21a.html))
+```@bibliography
+Pages = []
+Canonical = false
+
+bosch20capos
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -37,41 +37,6 @@ For a quick introduction check out the "[Solving ODEs with Probabilistic Numeric
 - Compatible with DAEs in mass-matrix ODE form (see [Solving DAEs with Probabilistic Numerics](@ref))
 
 
-## [References](@id references)
-
-The main references _for this package_ include:
-
-- N. Bosch, P. Hennig, F. Tronarp:
-  [**Probabilistic Exponential Integrators**](https://arxiv.org/abs/2305.14978)
-  (2023)
-- N. Bosch, F. Tronarp, P. Hennig:
-  [**Pick-and-Mix Information Operators for Probabilistic ODE Solvers**](https://proceedings.mlr.press/v151/bosch22a.html)
-  (2022)
-- N. Krämer, N. Bosch, J. Schmidt, P. Hennig:
-  [**Probabilistic ODE Solutions in Millions of Dimensions**](https://proceedings.mlr.press/v162/kramer22b.html)
-  (2022)
-- N. Bosch, P. Hennig, F. Tronarp:
-  [**Calibrated Adaptive Probabilistic ODE Solvers**](http://proceedings.mlr.press/v130/bosch21a.html)
-  (2021)
-- F. Tronarp, S. Särkkä, and P. Hennig:
-  [**Bayesian ODE Solvers: The Maximum A Posteriori Estimate**](https://link.springer.com/article/10.1007/s11222-021-09993-7)
-  (2021)
-- N. Krämer, P. Hennig:
-  [**Stable Implementation of Probabilistic ODE Solvers**](https://arxiv.org/abs/2012.10106v1)
-  (2020)
-- H. Kersting, T. J. Sullivan, and P. Hennig:
-  [**Convergence Rates of Gaussian Ode Filters**](https://link.springer.com/article/10.1007/s11222-020-09972-4)
-  (2020)
-- F. Tronarp, H. Kersting, S. Särkkä, and P. Hennig:
-  [**Probabilistic Solutions To Ordinary Differential Equations As Non-Linear Bayesian Filtering: A New Perspective**](https://link.springer.com/article/10.1007/s11222-019-09900-1)
-  (2019)
-- M. Schober, S. Särkkä, and P. Hennig:
-  [**A Probabilistic Model for the Numerical Solution of Initial Value Problems**](https://link.springer.com/article/10.1007/s11222-017-9798-7)
-  (2018)
-
-More references on ODE filters and on probabilistic numerics in general can be found on [probabilistic-numerics.org ](https://www.probabilistic-numerics.org/research/general/).
-
-
 ## Related packages
 
 - [probdiffeq](https://pnkraemer.github.io/probdiffeq/): Fast and feature-rich filtering-based probabilistic ODE solvers in JAX.

diff --git a/docs/src/initialization.md b/docs/src/initialization.md
@@ -65,7 +65,13 @@ TaylorModeInit
 ClassicSolverInit
 ```
 
+
 ## [References](@id initrefs)
 
-[1] N. Krämer, P. Hennig: **Stable Implementation of Probabilistic ODE Solvers** (2020) ([link](https://arxiv.org/abs/2012.10106))
-[2] M. Schober, S. Särkkä, and P. Hennig: **A Probabilistic Model for the Numerical Solution of Initial Value Problems** (2018) ([link](https://link.springer.com/article/10.1007/s11222-017-9798-7))
+```@bibliography
+Pages = []
+Canonical = false
+
+kraemer20stableimplementation
+schober16probivp
+```
diff --git a/docs/src/references.md b/docs/src/references.md
@@ -0,0 +1,5 @@
+# [References](@id references)
+
+```@bibliography
+*
+```
diff --git a/docs/src/refs.bib b/docs/src/refs.bib
@@ -0,0 +1,172 @@
+@misc{bosch23expint,
+  title =        {Probabilistic Exponential Integrators},
+  author =       {Nathanael Bosch and Philipp Hennig and Filip Tronarp},
+  year =         2023,
+  eprint =       {2305.14978},
+  archivePrefix ={arXiv},
+  primaryClass = {math.NA}
+}
+
+@InProceedings{krämer21highdim,
+  title =        {Probabilistic {ODE} Solutions in Millions of Dimensions},
+  author =       {Krämer, Nicholas and Bosch, Nathanael and Schmidt, Jonathan
+                  and Hennig, Philipp},
+  booktitle =    {Proceedings of the 39th International Conference on Machine
+                  Learning},
+  pages =        {11634--11649},
+  year =         2022,
+  editor =       {Chaudhuri, Kamalika and Jegelka, Stefanie and Song, Le and
+                  Szepesvari, Csaba and Niu, Gang and Sabato, Sivan},
+  volume =       162,
+  series =       {Proceedings of Machine Learning Research},
+  month =        {17--23 Jul},
+  publisher =    {PMLR},
+  pdf =          {https://proceedings.mlr.press/v162/kramer22b/kramer22b.pdf},
+  url =          {https://proceedings.mlr.press/v162/kramer22b.html},
+}
+
+@InProceedings{bosch22pickandmix,
+  title =        {Pick-and-Mix Information Operators for Probabilistic {ODE}
+                  Solvers},
+  author =       {Bosch, Nathanael and Tronarp, Filip and Hennig, Philipp},
+  booktitle =    {Proceedings of The 25th International Conference on Artificial
+                  Intelligence and Statistics},
+  pages =        {10015--10027},
+  year =         2022,
+  editor =       {Camps-Valls, Gustau and Ruiz, Francisco J. R. and Valera,
+                  Isabel},
+  volume =       151,
+  series =       {Proceedings of Machine Learning Research},
+  month =        {28--30 Mar},
+  publisher =    {PMLR},
+  pdf =          {https://proceedings.mlr.press/v151/bosch22a/bosch22a.pdf},
+  url =          {https://proceedings.mlr.press/v151/bosch22a.html},
+}
+
+@InProceedings{bosch20capos,
+  title =        {Calibrated Adaptive Probabilistic {ODE} Solvers},
+  author =       {Bosch, Nathanael and Hennig, Philipp and Tronarp, Filip},
+  booktitle =    {Proceedings of The 24th International Conference on Artificial
+                  Intelligence and Statistics},
+  pages =        {3466--3474},
+  year =         2021,
+  editor =       {Banerjee, Arindam and Fukumizu, Kenji},
+  volume =       130,
+  series =       {Proceedings of Machine Learning Research},
+  month =        {13--15 Apr},
+  publisher =    {PMLR},
+  pdf =          {http://proceedings.mlr.press/v130/bosch21a/bosch21a.pdf},
+  url =          {http://proceedings.mlr.press/v130/bosch21a.html},
+}
+
+@article{tronarp20bayes,
+  author =       {Tronarp, Filip and Särkkä, Simo and Hennig, Philipp},
+  title =        {Bayesian {ODE} solvers: the maximum a posteriori estimate},
+  journal =      {Statistics and Computing},
+  year =         2021,
+  month =        {Mar},
+  day =          03,
+  volume =       31,
+  number =       3,
+  pages =        23,
+  issn =         {1573-1375},
+  doi =          {10.1007/s11222-021-09993-7},
+  url =          {https://doi.org/10.1007/s11222-021-09993-7}
+}
+
+@article{tronarp18probsol,
+  author =       {Filip Tronarp and Hans Kersting and Simo Särkkä and Philipp
+                  Hennig},
+  title =        {Probabilistic solutions to ordinary differential equations as
+                  nonlinear {B}ayesian filtering: a new perspective},
+  year =         2019,
+  volume =       29,
+  number =       6,
+  pages =        {1297-1315},
+  doi =          {10.1007/s11222-019-09900-1},
+  url =          {https://doi.org/10.1007/s11222-019-09900-1},
+  journal =      {Statistics and Computing},
+}
+
+@article{kraemer20stableimplementation,
+  author =       {Krämer, Nicholas and Hennig, Philipp},
+  title =        {Stable Implementation of Probabilistic {ODE} Solvers},
+  journal =      {CoRR},
+  year =         2020,
+  url =          {http://arxiv.org/abs/2012.10106v1},
+  archivePrefix ={arXiv},
+  eprint =       {2012.10106},
+  primaryClass = {stat.ML},
+}
+
+@article{kersting18convergencerates,
+  author =       {Kersting, Hans and Sullivan, T. J. and Hennig, Philipp},
+  title =        {Convergence rates of {G}aussian {ODE} filters},
+  journal =      {Statistics and Computing},
+  year =         2020,
+  month =        {Nov},
+  day =          01,
+  volume =       30,
+  number =       6,
+  pages =        {1791-1816},
+  issn =         {1573-1375},
+  doi =          {10.1007/s11222-020-09972-4},
+  url =          {https://doi.org/10.1007/s11222-020-09972-4}
+}
+
+@article{schober16probivp,
+  author =       "Schober, Michael and Särkkä, Simo and Hennig, Philipp",
+  title =        "A probabilistic model for the numerical solution of initial
+                  value problems",
+  journal =      "Statistics and Computing",
+  year =         2019,
+  month =        "Jan",
+  day =          01,
+  volume =       29,
+  number =       1,
+  pages =        "99--122",
+  issn =         "1573-1375",
+  doi =          "10.1007/s11222-017-9798-7",
+  url =          "https://doi.org/10.1007/s11222-017-9798-7"
+}
+
+@InProceedings{tronarp22fenrir,
+  title =        {Fenrir: Physics-Enhanced Regression for Initial Value
+                  Problems},
+  author =       {Tronarp, Filip and Bosch, Nathanael and Hennig, Philipp},
+  booktitle =    {Proceedings of the 39th International Conference on Machine
+                  Learning},
+  pages =        {21776--21794},
+  year =         2022,
+  editor =       {Chaudhuri, Kamalika and Jegelka, Stefanie and Song, Le and
+                  Szepesvari, Csaba and Niu, Gang and Sabato, Sivan},
+  volume =       162,
+  series =       {Proceedings of Machine Learning Research},
+  month =        {17--23 Jul},
+  publisher =    {PMLR},
+  pdf =          {https://proceedings.mlr.press/v162/tronarp22a/tronarp22a.pdf},
+  url =          {https://proceedings.mlr.press/v162/tronarp22a.html},
+}
+
+@inproceedings{kersting16active,
+  author =       {Kersting, Hans and Hennig, Philipp},
+  title =        {Active Uncertainty Calibration in Bayesian ODE Solvers},
+  year =         2016,
+  isbn =         9780996643115,
+  publisher =    {AUAI Press},
+  booktitle =    {Proceedings of the Thirty-Second Conference on Uncertainty in
+                  Artificial Intelligence},
+  pages =        {309–318},
+  numpages =     10,
+  series =       {UAI'16},
+  url =          {http://www.auai.org/uai2016/proceedings/papers/163.pdf},
+}
+
+@book{hennig22probnum,
+  place =        {Cambridge},
+  title =        {Probabilistic Numerics: Computation as Machine Learning},
+  DOI =          {10.1017/9781316681411},
+  publisher =    {Cambridge University Press},
+  author =       {Hennig, Philipp and Osborne, Michael A. and Kersting, Hans P.},
+  year =         2022,
+}
diff --git a/docs/src/solvers.md b/docs/src/solvers.md
@@ -21,4 +21,10 @@ RosenbrockExpEK
 
 ## [References](@id solversrefs)
 
-[1] N. Bosch, F. Tronarp, P. Hennig: **Pick-and-Mix Information Operators for Probabilistic ODE Solvers** (2022) ([link](https://proceedings.mlr.press/v151/bosch22a.html))
+
+```@bibliography
+Pages = []
+Canonical = false
+
+bosch23expint
+```
diff --git a/docs/src/tutorials/dae.md b/docs/src/tutorials/dae.md
@@ -136,4 +136,9 @@ So it seems that, even if the index-3 DAE could also be solved directly, index l
 
 ### References
 
-[1] N. Bosch, F. Tronarp, P. Hennig: **Pick-and-Mix Information Operators for Probabilistic ODE Solvers** (2022) ([link](https://proceedings.mlr.press/v151/bosch22a.html))
+```@bibliography
+Pages = []
+Canonical = false
+
+bosch22pickandmix
+```
diff --git a/docs/src/tutorials/dynamical_odes.md b/docs/src/tutorials/dynamical_odes.md
@@ -85,7 +85,7 @@ plot(sol2, vars=(3, 4))
 Solving second-order ODEs is not just a matter of convenience - in fact, SciMLBase's `SecondOrderODEProblem` is neatly designed in such a way that all the classic solvers from OrdinaryDiffEq.jl can handle it by solving the corresponding first-order ODE.
 But, transforming the ODE to first order increases the dimensionality of the problem, and comes therefore at increased computational cost; this also motivates [classic specialized solvers for second-order ODEs](https://diffeq.sciml.ai/stable/solvers/dynamical_solve/).
 
-The probabilistic numerical solvers from ProbNumDiffEq.jl have the same internal state representation for first and second order ODEs; all that changes is the _measurement model_ [1].
+The probabilistic numerical solvers from ProbNumDiffEq.jl have the same internal state representation for first and second order ODEs; all that changes is the _measurement model_ [bosch22pickandmix](@citep).
 As a result, we can use the `EK1` both for first and second order ODEs, but it automatically specializes on the latter to provide a __2x performance boost__:
 
 ```
@@ -131,7 +131,7 @@ Let's fix this to get a physically more meaningful solution.
 
 ### Energy preservation with the `ManifoldUpdate` callback
 
-In the language of ODE filters, preserving energy over time amounts to just another measurement model [1].
+In the language of ODE filters, preserving energy over time amounts to just another measurement model [bosch22pickandmix](@citep).
 The most convenient way of updating on this additional zero measurement with ProbNumDiffEq.jl is with the `ManifoldUpdate` callback.
 
 !!! note
@@ -155,6 +155,12 @@ plot!(longsol_preserving.t, E.(longsol_preserving.u))
 
 Voilà! With the `ManifoldUpdate` callback we could preserve the energy over time and obtain a more truthful probabilistic numerical long-term simulation of the Hénon-Heiles model.
 
-#### References
 
-[1] N. Bosch, F. Tronarp, P. Hennig: **Pick-and-Mix Information Operators for Probabilistic ODE Solvers** (2022)
+### References
+
+```@bibliography
+Pages = []
+Canonical = false
+
+bosch22pickandmix
+```