From da83f7055f7b97eb7a5bc68273661eb5c540413b Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 08:57:39 +0200 Subject: [PATCH 01/12] add reference to JMLR paper --- readme.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/readme.md b/readme.md index 544ad663e..1ec5d654a 100644 --- a/readme.md +++ b/readme.md @@ -184,18 +184,26 @@ KeOps provides core routines for the following projects and libraries: [Shapes toolbox](https://plmlab.math.cnrs.fr/jeanfeydy/shapes_toolbox), two research-oriented [LDDMM](https://en.wikipedia.org/wiki/Large_deformation_diffeomorphic_metric_mapping) toolkits. -# Licensing, academic use +# Licensing, citation, academic use This library is licensed under the permissive [MIT license](https://en.wikipedia.org/wiki/MIT_License), which is fully compatible with both **academic** and **commercial** applications. -If you use this code in a research paper, **please cite**: + +If you use this code in a research paper, **please cite** our +[original publication](https://jmlr.org/papers/v22/20-275.html): + +> Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). ```tex -@article{charlier2020kernel, - title={Kernel operations on the {GPU}, with autodiff, without memory overflows}, - author={Charlier, Benjamin and Feydy, Jean and Glaun{\`e}s, Joan Alexis and Collin, Fran{\c{c}}ois-David and Durif, Ghislain}, - journal={arXiv preprint arXiv:2004.11127}, - year={2020} +@article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} } ``` From 6e0ade57a8e5529679e3fdfc9460e8a128ae2c82 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 09:04:12 +0200 Subject: [PATCH 02/12] update authorship and citation information --- rkeops/rkeops.md | 68 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 58 insertions(+), 10 deletions(-) diff --git a/rkeops/rkeops.md b/rkeops/rkeops.md index 588980d3c..75de6c376 100644 --- a/rkeops/rkeops.md +++ b/rkeops/rkeops.md @@ -12,22 +12,70 @@ For a full documentation you may read: # Authors -Feel free to contact us for any bug report or feature request, you can also fill -an issue report on [GitHub](https://github.com/getkeops/keops/issues). +Please contact us for any **bug report**, **question** or **feature request** by filing +a report on our [GitHub issue tracker](https://github.com/getkeops/keops/issues)! -## KeOps, PyKeOps, KeOpsLab +**Core library - KeOps, PyKeOps, KeOpsLab:** -- [Benjamin Charlier](https://imag.umontpellier.fr/~charlier/) -- [Jean Feydy](https://www.jeanfeydy.com) -- [Joan Alexis Glaunès](http://helios.mi.parisdescartes.fr/~glaunes/) +- [Benjamin Charlier](https://imag.umontpellier.fr/~charlier/), from the University of Montpellier. +- [Jean Feydy](https://www.jeanfeydy.com), from Imperial College London. +- [Joan Alexis Glaunès](http://helios.mi.parisdescartes.fr/~glaunes/), from the University of Paris. -## RKeOps +**R bindings - RKeOps:** -- [Ghislain Durif](https://gdurif.perso.math.cnrs.fr/) +- [Ghislain Durif](https://gdurif.perso.math.cnrs.fr/), from the University of Montpellier. -## Contributors +**Contributors:** -- François-David Collin +- [François-David Collin](https://github.com/fradav), from the University of Montpellier: Tensordot operation, CI setup. +- [Tanguy Lefort](https://github.com/tanglef), from the University of Montpellier: conjugate gradient solver. +- [Mauricio Diaz](https://github.com/mdiazmel), from the University of Montpellier: CI setup. +- [Benoît Martin](https://github.com/benoitmartin88), from the Aramis Inria team: multi-GPU support. +- [Francis Williams](https://www.fwilliams.info), from New York University: maths operations. +- [Kshiteej Kalambarkar](https://www.linkedin.com/in/kshiteejkalambarkar/), from Quansight: maths operations. +- [D. J. Sutherland](https://djsutherland.ml), from the TTI-Chicago: bug fix in the Python package. +- [David Völgyes](https://scholar.google.no/citations?user=ngT2GvMAAAAJ&hl=en), from the Norwegian Institute of Science and Technology: bug fix in the formula parser. + + +Beyond explicit code contributions, KeOps has grown out of numerous discussions with applied mathematicians and machine learning experts. We would especially like to thank +[Alain Trouvé](https://atrouve.perso.math.cnrs.fr/), +[Stanley Durrleman](https://who.rocq.inria.fr/Stanley.Durrleman/), +[Gabriel Peyré](http://www.gpeyre.com/) and +[Michael Bronstein](https://people.lu.usi.ch/bronstem/) +for their valuable suggestions and financial support. + +# Citation + +If you use this code in a research paper, **please cite** our +[original publication](https://jmlr.org/papers/v22/20-275.html): + +> Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). + +```tex +@article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} +} +``` + +For applications to **geometric (deep) learning**, +you may also consider our [NeurIPS 2020 paper](https://www.jeanfeydy.com/Papers/KeOps_NeurIPS_2020.pdf): + +```tex +@article{feydy2020fast, + title={Fast geometric learning with symbolic matrices}, + author={Feydy, Jean and Glaun{\`e}s, Joan and Charlier, Benjamin and Bronstein, Michael}, + journal={Advances in Neural Information Processing Systems}, + volume={33}, + year={2020} +} +``` --- From a7566c0707d47cbb5b3a3376033a1c043460cb65 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 09:39:08 +0200 Subject: [PATCH 03/12] add reference to papers and update authors list in vignette --- rkeops/vignettes/introduction_to_rkeops.Rmd | 70 ++++++++++++++++++--- 1 file changed, 60 insertions(+), 10 deletions(-) diff --git a/rkeops/vignettes/introduction_to_rkeops.Rmd b/rkeops/vignettes/introduction_to_rkeops.Rmd index fc0b4c591..f35b8003d 100644 --- a/rkeops/vignettes/introduction_to_rkeops.Rmd +++ b/rkeops/vignettes/introduction_to_rkeops.Rmd @@ -28,22 +28,72 @@ knitr::opts_chunk$set( # Authors -Feel free to contact us for any bug report or feature request, you can also fill -an issue report on [GitHub](https://github.com/getkeops/keops/issues). +Please contact us for any **bug report**, **question** or **feature request** by filing +a report on our [GitHub issue tracker](https://github.com/getkeops/keops/issues)! -## KeOps, PyKeOps, KeOpsLab +**Core library - KeOps, PyKeOps, KeOpsLab:** -* [Benjamin Charlier](https://imag.umontpellier.fr/~charlier/) -* [Jean Feydy](https://www.jeanfeydy.com) -* [Joan Alexis Glaunès](http://helios.mi.parisdescartes.fr/~glaunes/) +- [Benjamin Charlier](https://imag.umontpellier.fr/~charlier/), from the University of Montpellier. +- [Jean Feydy](https://www.jeanfeydy.com), from Imperial College London. +- [Joan Alexis Glaunès](http://helios.mi.parisdescartes.fr/~glaunes/), from the University of Paris. -## RKeOps +**R bindings - RKeOps:** + +- [Ghislain Durif](https://gdurif.perso.math.cnrs.fr/), from the University of Montpellier. + +**Contributors:** + +- [François-David Collin](https://github.com/fradav), from the University of Montpellier: Tensordot operation, CI setup. +- [Tanguy Lefort](https://github.com/tanglef), from the University of Montpellier: conjugate gradient solver. +- [Mauricio Diaz](https://github.com/mdiazmel), from the University of Montpellier: CI setup. +- [Benoît Martin](https://github.com/benoitmartin88), from the Aramis Inria team: multi-GPU support. +- [Francis Williams](https://www.fwilliams.info), from New York University: maths operations. +- [Kshiteej Kalambarkar](https://www.linkedin.com/in/kshiteejkalambarkar/), from Quansight: maths operations. +- [D. J. Sutherland](https://djsutherland.ml), from the TTI-Chicago: bug fix in the Python package. +- [David Völgyes](https://scholar.google.no/citations?user=ngT2GvMAAAAJ&hl=en), from the Norwegian Institute of Science and Technology: bug fix in the formula parser. + + +Beyond explicit code contributions, KeOps has grown out of numerous discussions with applied mathematicians and machine learning experts. We would especially like to thank +[Alain Trouvé](https://atrouve.perso.math.cnrs.fr/), +[Stanley Durrleman](https://who.rocq.inria.fr/Stanley.Durrleman/), +[Gabriel Peyré](http://www.gpeyre.com/) and +[Michael Bronstein](https://people.lu.usi.ch/bronstem/) +for their valuable suggestions and financial support. -* [Ghislain Durif](https://gdurif.perso.math.cnrs.fr/) +--- + +# Citation + +If you use this code in a research paper, **please cite** our +[original publication](https://jmlr.org/papers/v22/20-275.html): -## Contributors +> Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). -* François-David Collin +```tex +@article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} +} +``` + +For applications to **geometric (deep) learning**, +you may also consider our [NeurIPS 2020 paper](https://www.jeanfeydy.com/Papers/KeOps_NeurIPS_2020.pdf): + +```tex +@article{feydy2020fast, + title={Fast geometric learning with symbolic matrices}, + author={Feydy, Jean and Glaun{\`e}s, Joan and Charlier, Benjamin and Bronstein, Michael}, + journal={Advances in Neural Information Processing Systems}, + volume={33}, + year={2020} +} +``` --- From c023734224b402e2fa83b0e1bf3a62665c7e9bf7 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 09:39:59 +0200 Subject: [PATCH 04/12] add reference to JMLR paper in man page using Rdpack package --- rkeops/DESCRIPTION | 4 +++- rkeops/NAMESPACE | 1 + rkeops/R/rkeops-package.R | 4 ++++ rkeops/inst/REFERENCES.bib | 10 ++++++++++ rkeops/man/rkeops-package.Rd | 3 +++ 5 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 rkeops/inst/REFERENCES.bib diff --git a/rkeops/DESCRIPTION b/rkeops/DESCRIPTION index 61a2ad370..bedafe197 100644 --- a/rkeops/DESCRIPTION +++ b/rkeops/DESCRIPTION @@ -38,7 +38,8 @@ Imports: Rcpp (>= 1.0.1), RhpcBLASctl, openssl (>= 1.3), - stringr (>= 1.4.0) + stringr (>= 1.4.0), + Rdpack Suggests: testthat (>= 2.1.0), knitr, @@ -53,3 +54,4 @@ LazyData: true Roxygen: list(markdown = TRUE) RoxygenNote: 7.1.1 VignetteBuilder: knitr +RdMacros: Rdpack diff --git a/rkeops/NAMESPACE b/rkeops/NAMESPACE index 19596ee15..7736fdce0 100644 --- a/rkeops/NAMESPACE +++ b/rkeops/NAMESPACE @@ -38,6 +38,7 @@ export(use_cpu) export(use_gpu) import(Rcpp) importFrom(Rcpp,sourceCpp) +importFrom(Rdpack,reprompt) importFrom(RhpcBLASctl,omp_set_num_threads) importFrom(openssl,sha256) importFrom(parallel,detectCores) diff --git a/rkeops/R/rkeops-package.R b/rkeops/R/rkeops-package.R index 8abf8fafe..9f7df37a8 100644 --- a/rkeops/R/rkeops-package.R +++ b/rkeops/R/rkeops-package.R @@ -32,9 +32,13 @@ #' (`browseVignettes("rkeops")`) and visit #' https://www.kernel-operations.io/. #' +#' @references +#' \insertRef{JMLR:v22:20-275}{rkeops} +#' #' @import Rcpp #' @importFrom Rcpp sourceCpp #' @importFrom utils head packageVersion +#' @importFrom Rdpack reprompt #' @useDynLib rkeops, .registration = TRUE #' NULL diff --git a/rkeops/inst/REFERENCES.bib b/rkeops/inst/REFERENCES.bib new file mode 100644 index 000000000..6d688acf0 --- /dev/null +++ b/rkeops/inst/REFERENCES.bib @@ -0,0 +1,10 @@ +@article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} +} \ No newline at end of file diff --git a/rkeops/man/rkeops-package.Rd b/rkeops/man/rkeops-package.Rd index 0e696da6d..ab2fa5645 100644 --- a/rkeops/man/rkeops-package.Rd +++ b/rkeops/man/rkeops-package.Rd @@ -27,6 +27,9 @@ For more information, please read the vignettes (\code{browseVignettes("rkeops")}) and visit https://www.kernel-operations.io/. } +\references{ +\insertRef{JMLR:v22:20-275}{rkeops} +} \author{ \itemize{ \item \href{http://imag.umontpellier.fr/~charlier/}{Benjamin Charlier} From b340eff0a5787cf54b039d28900fd51a144853b0 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 09:45:26 +0200 Subject: [PATCH 05/12] fix url to personal page of a contributor (previous url did not pass R build check) --- readme.md | 2 +- rkeops/rkeops.md | 2 +- rkeops/vignettes/introduction_to_rkeops.Rmd | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index 1ec5d654a..583b54f75 100644 --- a/readme.md +++ b/readme.md @@ -242,7 +242,7 @@ a report on our [GitHub issue tracker](https://github.com/getkeops/keops/issues) - [Mauricio Diaz](https://github.com/mdiazmel), from the University of Montpellier: CI setup. - [Benoît Martin](https://github.com/benoitmartin88), from the Aramis Inria team: multi-GPU support. - [Francis Williams](https://www.fwilliams.info), from New York University: maths operations. -- [Kshiteej Kalambarkar](https://www.linkedin.com/in/kshiteejkalambarkar/), from Quansight: maths operations. +- [Kshiteej Kalambarkar](https://github.com/kshitij12345), from Quansight: maths operations. - [D. J. Sutherland](https://djsutherland.ml), from the TTI-Chicago: bug fix in the Python package. - [David Völgyes](https://scholar.google.no/citations?user=ngT2GvMAAAAJ&hl=en), from the Norwegian Institute of Science and Technology: bug fix in the formula parser. diff --git a/rkeops/rkeops.md b/rkeops/rkeops.md index 75de6c376..ff31eb1bd 100644 --- a/rkeops/rkeops.md +++ b/rkeops/rkeops.md @@ -32,7 +32,7 @@ a report on our [GitHub issue tracker](https://github.com/getkeops/keops/issues) - [Mauricio Diaz](https://github.com/mdiazmel), from the University of Montpellier: CI setup. - [Benoît Martin](https://github.com/benoitmartin88), from the Aramis Inria team: multi-GPU support. - [Francis Williams](https://www.fwilliams.info), from New York University: maths operations. -- [Kshiteej Kalambarkar](https://www.linkedin.com/in/kshiteejkalambarkar/), from Quansight: maths operations. +- [Kshiteej Kalambarkar](https://github.com/kshitij12345), from Quansight: maths operations. - [D. J. Sutherland](https://djsutherland.ml), from the TTI-Chicago: bug fix in the Python package. - [David Völgyes](https://scholar.google.no/citations?user=ngT2GvMAAAAJ&hl=en), from the Norwegian Institute of Science and Technology: bug fix in the formula parser. diff --git a/rkeops/vignettes/introduction_to_rkeops.Rmd b/rkeops/vignettes/introduction_to_rkeops.Rmd index f35b8003d..c29ec4243 100644 --- a/rkeops/vignettes/introduction_to_rkeops.Rmd +++ b/rkeops/vignettes/introduction_to_rkeops.Rmd @@ -48,7 +48,7 @@ a report on our [GitHub issue tracker](https://github.com/getkeops/keops/issues) - [Mauricio Diaz](https://github.com/mdiazmel), from the University of Montpellier: CI setup. - [Benoît Martin](https://github.com/benoitmartin88), from the Aramis Inria team: multi-GPU support. - [Francis Williams](https://www.fwilliams.info), from New York University: maths operations. -- [Kshiteej Kalambarkar](https://www.linkedin.com/in/kshiteejkalambarkar/), from Quansight: maths operations. +- [Kshiteej Kalambarkar](https://github.com/kshitij12345), from Quansight: maths operations. - [D. J. Sutherland](https://djsutherland.ml), from the TTI-Chicago: bug fix in the Python package. - [David Völgyes](https://scholar.google.no/citations?user=ngT2GvMAAAAJ&hl=en), from the Norwegian Institute of Science and Technology: bug fix in the formula parser. From 122b3cac87c4d9787168c89bb425f7a700872ad3 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 09:57:01 +0200 Subject: [PATCH 06/12] update LICENSING and COPYRIGHT information (add details and update dates) --- licence.txt | 6 +++++- rkeops/LICENSE | 9 +++++++-- rkeops/inst/COPYRIGHTS | 2 +- 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/licence.txt b/licence.txt index 6459abf7a..c9f9737b0 100644 --- a/licence.txt +++ b/licence.txt @@ -1,4 +1,8 @@ -Copyright (c) 2018-2020 B. Charlier, J. Feydy, J. Glaunès, G. Durif, F.-D. Collin +The MIT License (MIT) + +Copyright (c) 2015-2019 Daniel Frey (included C++ library 'sequences') + +Copyright (c) 2018-2021 B. Charlier, J. Feydy, J. Glaunès, G. Durif, F.-D. Collin (KeOps/PyKeOps/KeOpslab/RKeOps) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/rkeops/LICENSE b/rkeops/LICENSE index c8f95b4ef..6594afec5 100644 --- a/rkeops/LICENSE +++ b/rkeops/LICENSE @@ -1,2 +1,7 @@ -YEAR: 2015-2020 -COPYRIGHT HOLDER: Benjamin Charlier, Jean Feydy, Joan A. Glaunès, Ghislain Durif, François-David Collin (KeOps/RKeOps), Daniel Frey (included C++ library 'sequences'), see included file COPYRIGHTS for details. \ No newline at end of file +YEAR: 2015-2019 +COPYRIGHT HOLDER: Daniel Frey (included C++ library 'sequences') + +YEAR: 2018-2021 +COPYRIGHT HOLDER: Benjamin Charlier, Jean Feydy, Joan A. Glaunès, Ghislain Durif, François-David Collin (KeOps/RKeOps) + +See included file COPYRIGHTS for details. diff --git a/rkeops/inst/COPYRIGHTS b/rkeops/inst/COPYRIGHTS index 81c2621c9..35192da5e 100644 --- a/rkeops/inst/COPYRIGHTS +++ b/rkeops/inst/COPYRIGHTS @@ -3,5 +3,5 @@ Copyright: 2015 - 2019 Daniel Frey License: MIT Files: * -Copyright: 2018 - 2020 Benjamin Charlier, Jean Feydy, Joan A. Glaunès, Ghislain Durif, François-David Collin +Copyright: 2018 - 2021 Benjamin Charlier, Jean Feydy, Joan A. Glaunès, Ghislain Durif, François-David Collin License: MIT \ No newline at end of file From 9cbba6ebc1c1ea55b3bf1e1037b2727c3224a76c Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 10:02:41 +0200 Subject: [PATCH 07/12] update RKeOps documentation for the website --- rkeops/doc/introduction_to_rkeops.rst | 341 +++++++++++++--- rkeops/doc/using_rkeops.rst | 550 ++++++++++++++++++++++---- 2 files changed, 760 insertions(+), 131 deletions(-) diff --git a/rkeops/doc/introduction_to_rkeops.rst b/rkeops/doc/introduction_to_rkeops.rst index f51a7d1b0..4bc807b65 100644 --- a/rkeops/doc/introduction_to_rkeops.rst +++ b/rkeops/doc/introduction_to_rkeops.rst @@ -1,45 +1,183 @@ +Introduction to RKeOps +====================== + +2021-04-08 +^^^^^^^^^^ + +.. raw:: html + +
+ +- `Authors <#authors>`__ +- `Citation <#citation>`__ +- `What is RKeOps? <#what-is-rkeops>`__ + + - `KeOps <#keops>`__ + - `RKeOps <#rkeops>`__ + - `Why using RKeOps? <#why-using-rkeops>`__ + +- `Matrix reduction and kernel + operator <#matrix-reduction-and-kernel-operator>`__ + + - `What you need to do <#what-you-need-to-do>`__ + - `Example in R <#example-in-r>`__ + - `Generic kernel function <#generic-kernel-function>`__ + - `CPU and GPU computing <#cpu-and-gpu-computing>`__ + +- `Installing and using RKeOps <#installing-and-using-rkeops>`__ + +.. raw:: html + +
+ - URL: https://www.kernel-operations.io/ - Source: https://github.com/getkeops/keops - Licence and Copyright: see https://github.com/getkeops/keops/blob/master/licence.txt -Authors -======= +.. raw:: html -Feel free to contact us for any bug report or feature request, you can -also fill an issue report on -`GitHub `__. +
-KeOps, PyKeOps, KeOpsLab ------------------------- +.. rubric:: Authors + :name: authors -- `Benjamin Charlier `__ -- `Jean Feydy `__ +Please contact us for any **bug report**, **question** or **feature +request** by filing a report on our `GitHub issue +tracker `__! + +**Core library - KeOps, PyKeOps, KeOpsLab:** + +- `Benjamin Charlier `__, from + the University of Montpellier. +- `Jean Feydy `__, from Imperial College + London. - `Joan Alexis - Glaunès `__ + Glaunès `__, from the + University of Paris. + +**R bindings - RKeOps:** + +- `Ghislain Durif `__, from the + University of Montpellier. + +**Contributors:** + +- `François-David Collin `__, from the + University of Montpellier: Tensordot operation, CI setup. +- `Tanguy Lefort `__, from the University + of Montpellier: conjugate gradient solver. +- `Mauricio Diaz `__, from the University + of Montpellier: CI setup. +- `Benoît Martin `__, from the + Aramis Inria team: multi-GPU support. +- `Francis Williams `__, from New York + University: maths operations. +- `Kshiteej Kalambarkar `__, from + Quansight: maths operations. +- `D. J. Sutherland `__, from the TTI-Chicago: + bug fix in the Python package. +- `David + Völgyes `__, + from the Norwegian Institute of Science and Technology: bug fix in + the formula parser. + +Beyond explicit code contributions, KeOps has grown out of numerous +discussions with applied mathematicians and machine learning experts. We +would especially like to thank `Alain +Trouvé `__, `Stanley +Durrleman `__, `Gabriel +Peyré `__ and `Michael +Bronstein `__ for their valuable +suggestions and financial support. + +-------------- + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Citation + :name: citation + +If you use this code in a research paper, **please cite** our `original +publication `__: + + Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. + Kernel Operations on the GPU, with Autodiff, without Memory + Overflows. Journal of Machine Learning Research 22, 1–6 (2021). -RKeOps ------- +.. raw:: html -- `Ghislain Durif `__ +
-Contributors ------------- +.. code:: tex -- François-David Collin + @article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} + } + +.. raw:: html + +
+ +For applications to **geometric (deep) learning**, you may also consider +our `NeurIPS 2020 +paper `__: + +.. raw:: html + +
+ +.. code:: tex + + @article{feydy2020fast, + title={Fast geometric learning with symbolic matrices}, + author={Feydy, Jean and Glaun{\`e}s, Joan and Charlier, Benjamin and Bronstein, Michael}, + journal={Advances in Neural Information Processing Systems}, + volume={33}, + year={2020} + } + +.. raw:: html + +
-------------- -What is RKeOps? -=============== +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: What is RKeOps? + :name: what-is-rkeops RKeOps is the R package interfacing the KeOps library. `Here `__ you can find a few slides explaining functionalities of the KeOps library. -KeOps ------ +.. raw:: html + +
+ +.. rubric:: KeOps + :name: keops Seamless Kernel Operations on GPU (or CPU), with auto-differentiation and without memory overflows @@ -64,8 +202,16 @@ CUDA implementation of your custom mathematical operators. To ensure its versatility, KeOps can be used through Matlab, Python (NumPy or PyTorch) and R back-ends. -RKeOps ------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: RKeOps + :name: rkeops | RKeOps is a library that can @@ -92,8 +238,16 @@ RKeOps clustering, Gaussian-kernel-based problems (e.g. linear system with Ridge regularization), etc. -Why using RKeOps? ------------------ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Why using RKeOps? + :name: why-using-rkeops | RKeOps provides @@ -112,14 +266,27 @@ Why using RKeOps? -------------- -Matrix reduction and kernel operator -==================================== +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Matrix reduction and kernel operator + :name: matrix-reduction-and-kernel-operator | The general framework of RKeOps (and KeOps) is to provide fast and scalable matrix operations on GPU, in particular kernel-based - computations of the form \\[\\underset{i=1,…,M}{\\text{reduction}}\\ + computations of the form \\[\\underset{i=1,...,M}{\\text{reduction}}\\ G(\\boldsymbol{\\sigma}, \\mathbf x\_i, \\mathbf y\_j) \\ \\ \\ \\ - \\text{or}\\ \\ \\ \\ \\underset{j=1,…,N}{\\text{reduction}}\\ + \\text{or}\\ \\ \\ \\ \\underset{j=1,...,N}{\\text{reduction}}\\ G(\\boldsymbol{\\sigma}, \\mathbf x\_i, \\mathbf y\_j)\\] where - | \\(\\boldsymbol{\\sigma}\\in\\mathbb R^L\\) is a vector of @@ -143,8 +310,12 @@ Matrix reduction and kernel operator ***Note:*** You can use a wide range of reduction such as ``sum``, ``min``, ``argmin``, ``max``, ``argmax``, etc. -What you need to do -------------------- +.. raw:: html + +
+ +.. rubric:: What you need to do + :name: what-you-need-to-do | To use RKeOps you only need to express your computations as a formula with the previous form. @@ -155,17 +326,25 @@ What you need to do | You can use two type of input matrices with RKeOps: -- | ones whose rows (or columns) are indexed by \\(i=1,…,M\\) such as +- | ones whose rows (or columns) are indexed by \\(i=1,...,M\\) such as \\(\\mathbf X = [x\_{ik}]\_{M \\times D}\\) -- | others whose rows (or columns) are indexed by \\(j=1,…,N\\) such as - \\(\\mathbf Y = [y\_{ik'}]\_{N \\times D'}\\) +- | others whose rows (or columns) are indexed by \\(j=1,...,N\\) such + as \\(\\mathbf Y = [y\_{ik'}]\_{N \\times D'}\\) More details about input matrices (size, storage order) are given in the vignette 'Using RKeOps'. -Example in R ------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Example in R + :name: example-in-r We want to implement with RKeOps the following mathematical formula \\[\\sum\_{j=1}^{N} \\exp\\Big(-\\sigma \|\| \\mathbf x\_i - \\mathbf @@ -174,19 +353,27 @@ y\_j \|\|\_2^{\\,2}\\Big)\\,\\mathbf b\_j\\] with - | parameter: \\(\\sigma\\in\\mathbb R\\) - | \\(i\\)-indexed variables \\(\\mathbf X = [\\mathbf - x\_i]\_{i=1,…,M} \\in\\mathbb R^{M\\times 3}\\) + x\_i]\_{i=1,...,M} \\in\\mathbb R^{M\\times 3}\\) - | \\(j\\)-indexed variables \\(\\mathbf Y = [\\mathbf - y\_j]\_{j=1,…,N} \\in\\mathbb R^{N\\times 3}\\) and \\(\\mathbf B = - [\\mathbf b\_j]\_{j=1,…,N} \\in\\mathbb R^{N\\times 6}\\) + y\_j]\_{j=1,...,N} \\in\\mathbb R^{N\\times 3}\\) and \\(\\mathbf B + = [\\mathbf b\_j]\_{j=1,...,N} \\in\\mathbb R^{N\\times 6}\\) In R, we can define the corresponding KeOps formula as a **simple text string**: -:: +.. raw:: html + +
+ +.. code:: r formula = "Sum_Reduction(Exp(-s * SqNorm2(x - y)) * b, 0)" +.. raw:: html + +
+ - ``SqNorm2`` = squared \\(\\ell\_2\\) norm - ``Exp`` = exponential - ``Sum_reduction(..., 0)`` = sum reduction over the dimension 0 i.e. @@ -196,17 +383,29 @@ and the corresponding arguments of the formula, i.e. parameters or variables indexed by \\(i\\) or \\(j\\) with their corresponding inner dimensions: -:: +.. raw:: html + +
+ +.. code:: r args = c("x = Vi(3)", # vector indexed by i (of dim 3) "y = Vj(3)", # vector indexed by j (of dim 3) "b = Vj(6)", # vector indexed by j (of dim 6) "s = Pm(1)") # parameter (scalar) +.. raw:: html + +
+ Then we just compile the corresponding operator and apply it to some data -:: +.. raw:: html + +
+ +.. code:: r # compilation op <- keops_kernel(formula, args) @@ -220,8 +419,20 @@ data # computation (order of the input arguments should be similar to `args`) res <- op(list(X, Y, B, s)) -Generic kernel function ------------------------ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Generic kernel function + :name: generic-kernel-function | With RKeOps, you can define kernel functions \\(K: \\mathbb R^D \\times \\mathbb R^D \\to \\mathbb R\\) such as, for some vectors @@ -235,7 +446,7 @@ Generic kernel function \\exp\\left(-\\frac{1}{2\\sigma^2} \|\| \\mathbf x\_i - \\mathbf y\_j \|\|\_2^{\\,2}\\right)\\) with \\(\\sigma>0\\) -- | and more… +- | and more... | Then you can compute reductions based on such functions, especially when the \\(M \\times N\\) matrix \\(\\mathbf K = [K(\\mathbf x\_i, @@ -249,7 +460,7 @@ Generic kernel function \\mathbf y\_j)\\boldsymbol\\beta\_j\\ \\ \\ \\ \\text{or}\\ \\ \\ \\ \\sum\_{j=1}^N K(\\mathbf x\_i, \\mathbf y\_j)\\boldsymbol\\beta\_j\\] for some vectors - \\((\\boldsymbol\\beta\_j)\_{j=1,…,N} \\in \\mathbb R^{N\\times + \\((\\boldsymbol\\beta\_j)\_{j=1,...,N} \\in \\mathbb R^{N\\times D}\\) - More complex operations: \\[\\sum\_{i=1}^{M}\\, K\_1(\\mathbf x\_i, @@ -259,13 +470,21 @@ Generic kernel function \\mathbf y\_j)\\, K\_2(\\mathbf u\_i, \\mathbf v\_j)\\,\\langle \\boldsymbol\\alpha\_i\\, ,\\,\\boldsymbol\\beta\_j\\rangle\\] for some kernel \\(K\_1\\) and \\(K\_2\\), and some \\(D\\)-vectors - \\((\\mathbf x\_i)\_{i=1,…,M}, (\\mathbf u\_i)\_{i=1,…,M}, - (\\boldsymbol\\alpha\_i)\_{i=1,…,M} \\in \\mathbb R^{M\\times D}\\) - and \\((\\mathbf y\_j)\_{j=1,…,N}, (\\mathbf v\_j)\_{j=1,…,N}, - (\\boldsymbol\\beta\_j)\_{j=1,…,N} \\in \\mathbb R^{N\\times D}\\) + \\((\\mathbf x\_i)\_{i=1,...,M}, (\\mathbf u\_i)\_{i=1,...,M}, + (\\boldsymbol\\alpha\_i)\_{i=1,...,M} \\in \\mathbb R^{M\\times D}\\) + and \\((\\mathbf y\_j)\_{j=1,...,N}, (\\mathbf v\_j)\_{j=1,...,N}, + (\\boldsymbol\\beta\_j)\_{j=1,...,N} \\in \\mathbb R^{N\\times D}\\) + +.. raw:: html + +
-CPU and GPU computing ---------------------- +.. raw:: html + +
+ +.. rubric:: CPU and GPU computing + :name: cpu-and-gpu-computing Based on your formulae, RKeOps compile on the fly operators that can be used to run the corresponding computations on CPU or GPU, it uses a @@ -287,7 +506,23 @@ argument ``device`` to choose a specific GPU id to run computations). -------------- -Installing and using RKeOps -=========================== +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Installing and using RKeOps + :name: installing-and-using-rkeops See the specific vignette **Using RKeOps**. + +.. raw:: html + +
diff --git a/rkeops/doc/using_rkeops.rst b/rkeops/doc/using_rkeops.rst index 84188591f..739a0d274 100644 --- a/rkeops/doc/using_rkeops.rst +++ b/rkeops/doc/using_rkeops.rst @@ -1,3 +1,51 @@ +Using RKeOps +============ + +2021-04-08 +^^^^^^^^^^ + +.. raw:: html + +
+ +- `Installing RKeOps <#installing-rkeops>`__ + + - `Requirements <#requirements>`__ + - `Install from CRAN <#install-from-cran>`__ + - `Install from Github sources <#install-from-github-sources>`__ + - `Get sources and install from local + repository <#get-sources-and-install-from-local-repository>`__ + +- `How to use RKeOps <#how-to-use-rkeops>`__ + + - `Example <#example>`__ + - `Formula <#formula>`__ + - `Arguments <#arguments>`__ + + - `Input matrix <#input-matrix>`__ + - `Notations <#notations>`__ + + - `Creating a new operator <#creating-a-new-operator>`__ + - `Run computations <#run-computations>`__ + - `Computing gradients <#computing-gradients>`__ + - `RKeOps options <#rkeops-options>`__ + + - `Compile options <#compile-options>`__ + - `Choosing CPU or GPU computing at + runtime <#choosing-cpu-or-gpu-computing-at-runtime>`__ + - `Other runtime options <#other-runtime-options>`__ + + - `Advanced use <#advanced-use>`__ + + - `Precision <#precision>`__ + - `Data storage orientation <#data-storage-orientation>`__ + - `Compilation files and + cleaning <#compilation-files-and-cleaning>`__ + +.. raw:: html + +
+ | RKeOps is a R front-end for the KeOps C++/Cuda library. It provides standard functions that can be used in any R code. @@ -5,11 +53,19 @@ Thanks to RKeOps, you can use **GPU computing directly inside R** without the cost of developing a specific CUDA implementation of your custom mathematical operators. -Installing RKeOps -================= +.. raw:: html + +
+ +.. rubric:: Installing RKeOps + :name: installing-rkeops + +.. raw:: html -Requirements ------------- +
+ +.. rubric:: Requirements + :name: requirements - R (tested with R >= 3.5) - Cmake (>=3.10) @@ -19,18 +75,42 @@ Requirements **Disclaimer:** KeOps (including RKeOps) is not functional on Windows, it was only tested on Linux and MacOS. -Install from CRAN ------------------ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Install from CRAN + :name: install-from-cran **Note:** RKeOps is avaible on CRAN but only for UNIX environment (GNU/Linux and MacOS) and not for Windows. -:: +.. raw:: html + +
+ +.. code:: r install.packages("rkeops") -Install from Github sources ---------------------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Install from Github sources + :name: install-from-github-sources !! In most recent version of devtools, the ``args`` argument is not available anymore and it is not possible to use @@ -39,19 +119,40 @@ Install from Github sources - Install directly from Github (requires ``git``) -:: +.. raw:: html + +
+ +.. code:: r devtools::install_git("https://github.com/getkeops/keops", subdir = "rkeops", args="--recursive") # not possible to use `devtools::intall_github()` because of the required submodule -Get sources and install from local repository ---------------------------------------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Get sources and install from local repository + :name: get-sources-and-install-from-local-repository - Get KeOps sources (bash command) - :: + .. raw:: html + +
+ + .. code:: bash git clone --recurse-submodules="keops/lib/sequences" https://github.com/getkeops/keops # or @@ -60,33 +161,73 @@ Get sources and install from local repository git submodule update --init -- keops/lib/sequences # other submodules are not necessary for RKeOps + .. raw:: html + +
+ - Install from local source in R (assuming you are in the ``keops`` directory) -:: +.. raw:: html + +
+ +.. code:: r devtools::install("rkeops") +.. raw:: html + +
+ -------------- -How to use RKeOps -================= +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: How to use RKeOps + :name: how-to-use-rkeops Load RKeOps in R: -:: +.. raw:: html + +
+ +.. code:: r library(rkeops) ## ## You are using rkeops version 1.4.2 +.. raw:: html + +
+ RKeOps allows to define and compile new operators that run computations on GPU. -Example -------- +.. raw:: html + +
+ +.. rubric:: Example + :name: example -:: +.. raw:: html + +
+ +.. code:: r # implementation of a convolution with a Gaussian kernel formula = "Sum_Reduction(Exp(-s * SqNorm2(x - y)) * b, 0)" @@ -113,23 +254,35 @@ Example # computation (order of the input arguments should be similar to `args`) res <- op(list(X, Y, B, s)) +.. raw:: html + +
+ The different elements (formula, arguments, compilation, computation) in the previous example will be detailled in the next sections. -Formula -------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Formula + :name: formula To use RKeOps and define new operators, you need to write the corresponding *formula* which is a text string defining a composition of mathematical operations. It should be characterized by two elements: -#. a composition of generic functions applied to some input matrices, - whose one of their dimensions is either indexed by \\(i=1,…,M\\) or - \\(j=1,…,N\\) +1. a composition of generic functions applied to some input matrices, + whose one of their dimensions is either indexed by \\(i=1,...,M\\) or + \\(j=1,...,N\\) -#. a reduction over indexes \\(i=1,…,M\\) (row-wise) or \\(j=1,…,N\\) - (column-wise) of the \\(M \\times N\\) matrix whose entries are - defined by 1. +2. a reduction over indexes \\(i=1,...,M\\) (row-wise) or + \\(j=1,...,N\\) (column-wise) of the \\(M \\times N\\) matrix whose + entries are defined by 1. | RKeOps implements a wide range of mathematical operators and reduction: please refers to @@ -143,43 +296,63 @@ mathematical operations. It should be characterized by two elements: - | parameter: \\(\\sigma\\in\\mathbb R\\) -- | \\(i\\)-indexed variables \\([\\mathbf x\_i]\_{i=1,…,M} +- | \\(i\\)-indexed variables \\([\\mathbf x\_i]\_{i=1,...,M} \\in\\mathbb R^{M\\times 3}\\) -- | \\(j\\)-indexed variables \\([\\mathbf y\_j]\_{j=1,…,N} - \\in\\mathbb R^{N\\times 3}\\) and \\([\\mathbf b\_j]\_{j=1,…,N} +- | \\(j\\)-indexed variables \\([\\mathbf y\_j]\_{j=1,...,N} + \\in\\mathbb R^{N\\times 3}\\) and \\([\\mathbf b\_j]\_{j=1,...,N} \\in\\mathbb R^{N\\times 6}\\) In R, we can define the corresponding KeOps formula as a simple **text string**: -:: +.. raw:: html + +
+ +.. code:: r formula = "Sum_Reduction(Exp(-s * SqNorm2(x - y)) * b, 0)" +.. raw:: html + +
+ - ``SqNorm2`` = squared \\(\\ell\_2\\) norm - ``Exp`` = exponential - ``Sum_reduction(..., 0)`` = sum reduction over the dimension 0 i.e. sum on the \\(j\\)'s (1 to sum over the \\(i\\)'s) -Arguments ---------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Arguments + :name: arguments The formula describing your computation can take several input arguments: variables and parameters. The input variables will generally corresponds to rows or columns of your data matrices, you need to be cautious with their dimensions. -Input matrix -~~~~~~~~~~~~ +.. raw:: html + +
+ +.. rubric:: Input matrix + :name: input-matrix | You can use two type of input matrices with RKeOps: -- | ones whose rows (or columns) are indexed by \\(i=1,…,M\\) such as +- | ones whose rows (or columns) are indexed by \\(i=1,...,M\\) such as \\(\\mathbf X = [x\_{ik}]\_{M \\times D}\\) -- | others whose rows (or columns) are indexed by \\(j=1,…,N\\) such as - \\(\\mathbf Y = [y\_{ik'}]\_{N \\times D'}\\) +- | others whose rows (or columns) are indexed by \\(j=1,...,N\\) such + as \\(\\mathbf Y = [y\_{ik'}]\_{N \\times D'}\\) | The dimensions over indexes \\(i\\) or \\(j\\) are called the **outer dimensions** (i.e. \\(M\\) or \\(N\\)). The other dimensions (i.e. @@ -210,8 +383,16 @@ Input matrix \\(M\\) and \\(N\\) are set at runtime (and can change from one run to another). -Notations -~~~~~~~~~ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Notations + :name: notations Input arguments of the formula are defined by using keywords, they can be of different types: @@ -238,17 +419,25 @@ type of all arguments in your formula. The vector of arguments should be -:: +.. raw:: html + +
+ +.. code:: r args = c("=(dim1)", "=(dim2)", "=(dimX)") +.. raw:: html + +
+ where - ```` is the name - ```` is the type (among ``Vi``, ``Vj`` or ``Pm``) - ```` is the **inner dimension** -| of the ``X``\\(^\\text{th}\\) variable in the formula. +| of the ``X``\ \\(^\\text{th}\\) variable in the formula. ***Important:*** The names should correspond to the ones used in the formula. The input parameter order will be the one used when calling @@ -258,25 +447,53 @@ where `formula <#formula>`__, i.e. parameters or variables indexed by \\(i\\) or \\(j\\) with their corresponding inner dimensions: -:: +.. raw:: html + +
+ +.. code:: r args = c("x = Vi(3)", # vector indexed by i (of dim 3) "y = Vj(3)", # vector indexed by j (of dim 3) "b = Vj(6)", # vector indexed by j (of dim 6) "s = Pm(1)") # parameter (scalar) -Creating a new operator ------------------------ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Creating a new operator + :name: creating-a-new-operator By using the function ``keops_kernel``, based on the formula and its arguments that we previously defined, we can compile and load into R the corresponding operator: -:: +.. raw:: html + +
+ +.. code:: r # compilation op <- keops_kernel(formula, args) +.. raw:: html + +
+ | Calling ``keops_kernel(formula, args)`` returns a function that can be later used to run computations on your data with your value of parameters. You should only be cautious with the similarity of each @@ -290,8 +507,16 @@ and will be reused when calling again the function ``keops_kernel`` on the same formula with the same arguments and the same conditions (e.g. precision), to avoid useless recompilation. -Run computations ----------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Run computations + :name: run-computations We generate data with inner dimensions (number of columns) corresponding to each arguments expected by the operator ``op``. The function ``op`` @@ -300,7 +525,11 @@ checks the association between the supplied names and the names of the formula arguments. In this case only, it can also correct the order of the input list to match the expected order of arguments. -:: +.. raw:: html + +
+ +.. code:: r # data and parameter values nx <- 100 @@ -318,12 +547,28 @@ the input list to match the expected order of arguments. # computation (order of the input arguments should be similar to `args`) res <- op(list(x, y, beta, s)) -Computing gradients -------------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Computing gradients + :name: computing-gradients You can define gradients directly in the formula, e.g. -:: +.. raw:: html + +
+ +.. code:: r # defining a formula with a Gradient formula <- "Grad(Sum_Reduction(SqNorm2(x-y), 0), x, eta)" @@ -342,6 +587,10 @@ You can define gradients directly in the formula, e.g. input <- list(x, y, eta) res <- op(input) +.. raw:: html + +
+ where ``eta`` is the new variable at which the gradient is computed, its dimension should correspond to the output dimension of the operation inside the gradient (here ``SqNorm2(x-y)`` is of dimension 1). @@ -349,7 +598,11 @@ inside the gradient (here ``SqNorm2(x-y)`` is of dimension 1). You can also use the function ``keops_grad`` to derive existing KeOps operators. -:: +.. raw:: html + +
+ +.. code:: r # defining an operator (reduction on squared distance) formula <- "Sum_Reduction(SqNorm2(x-y), 0)" @@ -369,6 +622,10 @@ operators. input <- list(x, y, eta) res <- grad_op(input) +.. raw:: html + +
+ **Note:** when defining a gradient, the operator created by ``keops_grad``\ requires an additional variable whose inner dimension corresponds to the output dimension of the derived formula (here @@ -376,8 +633,16 @@ corresponds to the output dimension of the derived formula (here dimension corresponds to the outer dimension of the variable regarding which the gradient is taken (here ``x``). -RKeOps options --------------- +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: RKeOps options + :name: rkeops-options RKeOps behavior is driven by specific options in ``R`` global options scope. Such options are set up when loading RKeOps (i.e. by calling @@ -385,34 +650,66 @@ scope. Such options are set up when loading RKeOps (i.e. by calling You can get the current values of RKeOps options with -:: +.. raw:: html + +
+ +.. code:: r get_rkeops_options() +.. raw:: html + +
+ To (re)set RKeOps options to default values, run: -:: +.. raw:: html + +
+ +.. code:: r set_rkeops_options() +.. raw:: html + +
+ To set a specific option with a given value, you can do: -:: +.. raw:: html + +
+ +.. code:: r set_rkeops_option(option, value) # `option` = text string, name of the option to set up # `value` = whatever value to assign to the chosen option +.. raw:: html + +
+ Check ``?set_rkeops_option`` for more details. -Compile options -~~~~~~~~~~~~~~~ +.. raw:: html + +
+ +.. rubric:: Compile options + :name: compile-options - ``use_cuda_if_possible``: by default, user-defined operators are compiled for GPU if CUDA is available (and compiled for CPU otherwise). -:: +.. raw:: html + +
+ +.. code:: r # enable compiling for GPU if available (not necessary if using default options) compile4gpu() @@ -421,16 +718,28 @@ Compile options # disable compiling for GPU set_rkeops_option("use_cuda_if_possible", 0) +.. raw:: html + +
+ - ``precision``: by default, user-defined operators are compiled to use float 32bits for computations (faster than float 64bits or double, compensated sum is available to reduce errors inherent to float 32bits operations) -:: +.. raw:: html + +
+ +.. code:: r set_rkeops_option("precision", "float") # float 32bits (default) set_rkeops_option("precision", "double") # float 64bits +.. raw:: html + +
+ You can directly change the precision used in compiled operators with the functions ``compile4float32`` and ``compile4float64`` which respectively enable float 32bits precision (default) and float 64bits @@ -439,18 +748,35 @@ respectively enable float 32bits precision (default) and float 64bits - other compile options (including boolean value to enable verbosity or to add debugging flag), see ``?compile_options`` -Choosing CPU or GPU computing at runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Choosing CPU or GPU computing at runtime + :name: choosing-cpu-or-gpu-computing-at-runtime By default, RKeOps runs computations on CPU (even for GPU-compiled operators). To enable GPU computing, you can run (before calling your operator): -:: +.. raw:: html + +
+ +.. code:: r use_gpu() # see `?runtime_options` for a more advanced use of GPU inside RKeOps +.. raw:: html + +
+ You can also specify the GPU id that you want to use, e.g. ``use_gpu(device=0)`` to use GPU 0 (default) for instance. @@ -460,27 +786,59 @@ To deactivate GPU computations, you can run ``use_cpu()``. for computations, e.g. with ``use_cpu(ncore = 2)`` to run on 2 cores. -Other runtime options -~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Other runtime options + :name: other-runtime-options - ``device_id``: choose on which GPU the computations will be done, default is 0. -:: +.. raw:: html + +
+ +.. code:: r set_rkeops_option("device_id", 0) +.. raw:: html + +
+ ***Note***: We recommend to handle GPU assignation outside RKeOps, for instance by setting the environment variable ``CUDA_VISIBLE_DEVICES``. Thus, you can keep the default GPU device id = 0 in RKeOps. - Other runtime options, see ``?runtime_options`` -Advanced use ------------- +.. raw:: html + +
+ +.. raw:: html + +
-Precision -~~~~~~~~~ +.. raw:: html + +
+ +.. rubric:: Advanced use + :name: advanced-use + +.. raw:: html + +
+ +.. rubric:: Precision + :name: precision By default, RKeOps uses float 32bits precision for computations. Since R only considers 64bits floating point numbers, if you want to use float @@ -491,8 +849,16 @@ will suffer a performance loss (potentially not an issue on high-end GPUs). In any case, compensated summation reduction is available in KeOps to correct for 32bits floating point arithmetic errors. -Data storage orientation -~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Data storage orientation + :name: data-storage-orientation | In R, matrices are stored using a column-major order, meaning that a \\(M \\times D\\) matrix is stored in memory as a succession of @@ -527,7 +893,11 @@ columns, and inner dimensions the rows, e.g. transpose matrices Example: -:: +.. raw:: html + +
+ +.. code:: r # standard column reduction of a matrix product op <- keops_kernel(formula = "Sum_Reduction((x|y), 1)", @@ -555,8 +925,20 @@ Example: # corresponds to the inner dimension) res <- op(list(X,Y), inner_dim=0) -Compilation files and cleaning -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
+ +.. rubric:: Compilation files and cleaning + :name: compilation-files-and-cleaning The compilation of new operators produces shared library (or share object ``.so``) files stored in a ``build`` sub-directory of the package @@ -566,3 +948,15 @@ defined operators. You can check where your compiled operators are stored by running ``get_build_dir()``. To clean RKeOps install and remove all shared library files, you can run ``clean_rkeops()``. + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + +
From ed03e473a705d68a8c6ef7bf94451d86189f13f6 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 11:06:28 +0200 Subject: [PATCH 08/12] modify url to contributor profile --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 7ac7597c3..0867f33c9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -243,7 +243,7 @@ a report on our `GitHub issue tracker - `Mauricio Diaz `_, from the University of Montpellier: CI setup. - `Benoît Martin `_, from the Aramis Inria team: multi-GPU support. - `Francis Williams `_, from New York University: maths operations. -- `Kshiteej Kalambarkar `_, from Quansight: maths operations. +- `Kshiteej Kalambarkar `_, from Quansight: maths operations. - `D. J. Sutherland `_, from the TTI-Chicago: bug fix in the Python package. - `David Völgyes `_, from the Norwegian Institute of Science and Technology: bug fix in the formula parser. From a7a7d0d2a4018e78b2d57a33efd2ce390a49e0a5 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 11:15:20 +0200 Subject: [PATCH 09/12] add reference to JMLR paper in doc --- doc/index.rst | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 0867f33c9..80d5898d5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -189,20 +189,28 @@ KeOps provides core routines for the following packages: -Licensing, academic use +Licensing, citation, academic use ----------------------- This library is licensed under the permissive `MIT license `_, which is fully compatible with both **academic** and **commercial** applications. -If you use this code in a research paper, **please cite**: + +If you use this code in a research paper, **please cite** our +`original publication `_: + +> Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). .. code-block:: bibtex - @article{charlier2020kernel, - title={Kernel operations on the {GPU}, with autodiff, without memory overflows}, - author={Charlier, Benjamin and Feydy, Jean and Glaun{\`e}s, Joan Alexis and Collin, Fran{\c{c}}ois-David and Durif, Ghislain}, - journal={arXiv preprint arXiv:2004.11127}, - year={2020} + @article{JMLR:v22:20-275, + author = {Benjamin Charlier and Jean Feydy and Joan Alexis Glaunès and François-David Collin and Ghislain Durif}, + title = {Kernel Operations on the GPU, with Autodiff, without Memory Overflows}, + journal = {Journal of Machine Learning Research}, + year = {2021}, + volume = {22}, + number = {74}, + pages = {1-6}, + url = {http://jmlr.org/papers/v22/20-275.html} } From 5564ae91b547bade29b96a9a983a7a1b67b84474 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 11:24:01 +0200 Subject: [PATCH 10/12] fix missing package for CI (Rdpack for citation) --- rkeops/ci/prepare_ci.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rkeops/ci/prepare_ci.R b/rkeops/ci/prepare_ci.R index 64ee01183..062c2b81c 100644 --- a/rkeops/ci/prepare_ci.R +++ b/rkeops/ci/prepare_ci.R @@ -1,4 +1,4 @@ pkg_list <- c("devtools", "openssl", "knitr", "Rcpp", "RcppEigen", "RhpcBLASctl", "rmarkdown", - "roxygen2", "stringr", "testthat") + "roxygen2", "stringr", "testthat", "Rdpack") install_pkg(pkg_list) # function defined in local .Rprofile From 67434b1cdddf68a36c694b61437f983daa21fc37 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 15:25:45 +0200 Subject: [PATCH 11/12] fix broken link + reformat biblio citation --- doc/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 80d5898d5..070f86fea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -196,9 +196,7 @@ This library is licensed under the permissive `MIT license `_: - -> Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). +`original publication `_: .. code-block:: bibtex @@ -213,6 +211,8 @@ If you use this code in a research paper, **please cite** our url = {http://jmlr.org/papers/v22/20-275.html} } +.. note:: Charlier, B., Feydy, J., Glaunès, J. A., Collin, F.-D. & Durif, G. Kernel Operations on the GPU, with Autodiff, without Memory Overflows. Journal of Machine Learning Research 22, 1–6 (2021). + For applications to **geometric (deep) learning**, you may also consider our `NeurIPS 2020 paper `_: From c0ad86b4a7d1a0f0119b8e88792e0ccbc1505687 Mon Sep 17 00:00:00 2001 From: GD Date: Thu, 8 Apr 2021 15:33:07 +0200 Subject: [PATCH 12/12] remove useless date --- rkeops/doc/introduction_to_rkeops.rst | 3 --- rkeops/doc/using_rkeops.rst | 3 --- 2 files changed, 6 deletions(-) diff --git a/rkeops/doc/introduction_to_rkeops.rst b/rkeops/doc/introduction_to_rkeops.rst index 4bc807b65..f91ebd5e5 100644 --- a/rkeops/doc/introduction_to_rkeops.rst +++ b/rkeops/doc/introduction_to_rkeops.rst @@ -1,9 +1,6 @@ Introduction to RKeOps ====================== -2021-04-08 -^^^^^^^^^^ - .. raw:: html
diff --git a/rkeops/doc/using_rkeops.rst b/rkeops/doc/using_rkeops.rst index 739a0d274..ce3e122a5 100644 --- a/rkeops/doc/using_rkeops.rst +++ b/rkeops/doc/using_rkeops.rst @@ -1,9 +1,6 @@ Using RKeOps ============ -2021-04-08 -^^^^^^^^^^ - .. raw:: html