diff --git a/doc/index.rst b/doc/index.rst index 7ac7597c3..070f86fea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -189,22 +189,30 @@ 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 `_: .. 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} } +.. 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 `_: @@ -243,7 +251,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. 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/readme.md b/readme.md index 544ad663e..583b54f75 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} } ``` @@ -234,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/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/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/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/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 diff --git a/rkeops/doc/introduction_to_rkeops.rst b/rkeops/doc/introduction_to_rkeops.rst index f51a7d1b0..f91ebd5e5 100644 --- a/rkeops/doc/introduction_to_rkeops.rst +++ b/rkeops/doc/introduction_to_rkeops.rst @@ -1,45 +1,180 @@ +Introduction to RKeOps +====================== + +.. 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 `__. +.. rubric:: Authors + :name: authors -KeOps, PyKeOps, KeOpsLab ------------------------- +Please contact us for any **bug report**, **question** or **feature +request** by filing a report on our `GitHub issue +tracker `__! -- `Benjamin Charlier `__ -- `Jean Feydy `__ +**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 +199,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 +235,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 +263,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 +307,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 +323,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 +350,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 +380,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 +416,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 +443,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 +457,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 +467,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 +503,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..ce3e122a5 100644 --- a/rkeops/doc/using_rkeops.rst +++ b/rkeops/doc/using_rkeops.rst @@ -1,3 +1,48 @@ +Using RKeOps +============ + +.. 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 +50,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 +72,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 +116,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 +158,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 +251,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 +293,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 +380,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 +416,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 +444,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 +504,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 +522,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 +544,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 +584,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 +595,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 +619,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 +630,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 +647,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 +715,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 +745,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 +783,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 +846,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 +890,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 +922,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 +945,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 + +
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 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} diff --git a/rkeops/rkeops.md b/rkeops/rkeops.md index 588980d3c..ff31eb1bd 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://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. + + +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} +} +``` --- diff --git a/rkeops/vignettes/introduction_to_rkeops.Rmd b/rkeops/vignettes/introduction_to_rkeops.Rmd index fc0b4c591..c29ec4243 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://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. + + +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} +} +``` ---