build based on 702bbed

previews/PR436/create_kernel/index.html

@@ -23,4 +23,4 @@
         return MyKernel(x.n, xs.a)
     end
     return (a = x.a,), reconstruct_mykernel
-end</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../metrics/">« Metrics</a><a class="docs-footer-nextpage" href="../api/">API »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Sunday 10 March 2024 08:21">Sunday 10 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../metrics/">« Metrics</a><a class="docs-footer-nextpage" href="../api/">API »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Monday 11 March 2024 08:07">Monday 11 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

previews/PR436/design/index.html

@@ -4,4 +4,4 @@
         kernelmatrix(k.kernels[2], x; obsdim=obsdim)
 end</code></pre><p>While this prevents this package from having to pre-specify a convention, it doesn&#39;t resolve the <code>length</code> issue, or the issue of representing collections of inputs which aren&#39;t immediately represented as vectors. Moreover, it complicates the internals; in contrast, consider what this function looks like with an <code>AbstractVector</code>:</p><pre><code class="language-julia hljs">function kernelmatrix(k::KernelSum, x::AbstractVector)
     return kernelmatrix(k.kernels[1], x) + kernelmatrix(k.kernels[2], x)
-end</code></pre><p>This code is clearer (less visual noise), and has removed a possible bug – if the implementer of <code>kernelmatrix</code> forgets to pass the <code>obsdim</code> kwarg into each subsequent <code>kernelmatrix</code> call, it&#39;s possible to get the wrong answer.</p><p>This being said, we do support matrix-valued inputs – see <a href="#Why-We-Have-Support-for-Both">Why We Have Support for Both</a>.</p><h3 id="AbstractVectors"><a class="docs-heading-anchor" href="#AbstractVectors">AbstractVectors</a><a id="AbstractVectors-1"></a><a class="docs-heading-anchor-permalink" href="#AbstractVectors" title="Permalink"></a></h3><p>Requiring all collections of inputs to be <code>AbstractVector</code>s resolves all of these problems, and ensures that the data is self-describing to the extent that KernelFunctions.jl requires.</p><p>Firstly, the question of how to interpret the columns and rows of a matrix of inputs is resolved. Users <em>must</em> wrap matrices which represent collections of inputs in either a <code>ColVecs</code> or <code>RowVecs</code>, both of which have clearly defined semantics which are hard to confuse.</p><p>By design, there is also no discrepancy between the number of inputs in the collection, and the <code>length</code> function – the <code>length</code> of a <code>ColVecs</code>, <code>RowVecs</code>, or <code>Vector{&lt;:Real}</code> is equal to the number of inputs.</p><p>There is no loss of performance.</p><p>A collection of <code>N</code> <code>Real</code>-valued inputs can be represented by an <code>AbstractVector{&lt;:Real}</code> of <code>length</code> <code>N</code>, rather than needing to use an <code>AbstractMatrix{&lt;:Real}</code> of size either <code>N x 1</code> or <code>1 x N</code>. The same can be said for any other input type <code>T</code>, and new subtypes of <code>AbstractVector</code> can be added if particularly efficient ways exist to store collections of inputs of type <code>T</code>. A good example of this in practice is using <code>Tuple{S, Int}</code>, for some input type <code>S</code>, as the <a href="../api/#Inputs-for-Multiple-Outputs">Inputs for Multiple Outputs</a>.</p><p>This approach can also lead to clearer user code. A user need only wrap their inputs in a <code>ColVecs</code> or <code>RowVecs</code> once in their code, and this specification is automatically re-used <em>everywhere</em> in their code. In this sense, it is straightforward to write code in such a way that there is one unique source of &quot;truth&quot; about the way in which a particular data set should be interpreted. Conversely, the <code>obsdim</code> resolution requires that the <code>obsdim</code> keyword argument is passed around with the data <em>every</em> <em>single</em> <em>time</em> that you use it.</p><p>The benefits of the <code>AbstractVector</code> approach are likely most strongly felt when writing a substantial amount of code on top of KernelFunctions.jl – in the same way that using <code>AbstractVector</code>s inside KernelFunctions.jl removes the need for large amounts of keyword argument propagation, the same will be true of other code.</p><h3 id="Why-We-Have-Support-for-Both"><a class="docs-heading-anchor" href="#Why-We-Have-Support-for-Both">Why We Have Support for Both</a><a id="Why-We-Have-Support-for-Both-1"></a><a class="docs-heading-anchor-permalink" href="#Why-We-Have-Support-for-Both" title="Permalink"></a></h3><p>In short: many people like matrices, and are familiar with <code>obsdim</code>-style keyword arguments.</p><p>All internals are implemented using <code>AbstractVector</code>s though, and the <code>obsdim</code> interface is just a thin layer of utility functionality which sits on top of this. To avoid confusion and silent errors, we do not favour a specific convention (rows or columns) but instead it is necessary to specify the <code>obsdim</code> keyword argument explicitly.</p><h2 id="inputs_for_multiple_outputs"><a class="docs-heading-anchor" href="#inputs_for_multiple_outputs">Kernels for Multiple-Outputs</a><a id="inputs_for_multiple_outputs-1"></a><a class="docs-heading-anchor-permalink" href="#inputs_for_multiple_outputs" title="Permalink"></a></h2><p>There are two equally-valid perspectives on multi-output kernels: they can either be treated as matrix-valued kernels, or standard kernels on an extended input domain. Each of these perspectives are convenient in different circumstances, but the latter greatly simplifies the incorporation of multi-output kernels in KernelFunctions.</p><p>More concretely, let <code>k_mat</code> be a matrix-valued kernel, mapping pairs of inputs of type <code>T</code> to matrices of size <code>P x P</code> to describe the covariance between <code>P</code> outputs. Given inputs <code>x</code> and <code>y</code> of type <code>T</code>, and integers <code>p</code> and <code>q</code>, we can always find an equivalent standard kernel <code>k</code> mapping from pairs of inputs of type <code>Tuple{T, Int}</code> to the <code>Real</code>s as follows:</p><pre><code class="language-julia hljs">k((x, p), (y, q)) = k_mat(x, y)[p, q]</code></pre><p>This ability to treat multi-output kernels as single-output kernels is very helpful, as it means that there is no need to introduce additional concepts into the API of KernelFunctions.jl, just additional kernels! This in turn simplifies downstream code as they don&#39;t need to &quot;know&quot; about the existence of multi-output kernels in addition to standard kernels. For example, GP libraries built on top of KernelFunctions.jl just need to know about <code>Kernel</code>s, and they get multi-output kernels, and hence multi-output GPs, for free.</p><p>Where there is the need to specialise <em>implementations</em> for multi-output kernels, this is done in an encapsulated manner – parts of KernelFunctions that have nothing to do with multi-output kernels know <em>nothing</em> about the existence of multi-output kernels.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../api/">« API</a><a class="docs-footer-nextpage" href="../examples/gaussian-process-priors/">Gaussian process prior samples »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Sunday 10 March 2024 08:21">Sunday 10 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre><p>This code is clearer (less visual noise), and has removed a possible bug – if the implementer of <code>kernelmatrix</code> forgets to pass the <code>obsdim</code> kwarg into each subsequent <code>kernelmatrix</code> call, it&#39;s possible to get the wrong answer.</p><p>This being said, we do support matrix-valued inputs – see <a href="#Why-We-Have-Support-for-Both">Why We Have Support for Both</a>.</p><h3 id="AbstractVectors"><a class="docs-heading-anchor" href="#AbstractVectors">AbstractVectors</a><a id="AbstractVectors-1"></a><a class="docs-heading-anchor-permalink" href="#AbstractVectors" title="Permalink"></a></h3><p>Requiring all collections of inputs to be <code>AbstractVector</code>s resolves all of these problems, and ensures that the data is self-describing to the extent that KernelFunctions.jl requires.</p><p>Firstly, the question of how to interpret the columns and rows of a matrix of inputs is resolved. Users <em>must</em> wrap matrices which represent collections of inputs in either a <code>ColVecs</code> or <code>RowVecs</code>, both of which have clearly defined semantics which are hard to confuse.</p><p>By design, there is also no discrepancy between the number of inputs in the collection, and the <code>length</code> function – the <code>length</code> of a <code>ColVecs</code>, <code>RowVecs</code>, or <code>Vector{&lt;:Real}</code> is equal to the number of inputs.</p><p>There is no loss of performance.</p><p>A collection of <code>N</code> <code>Real</code>-valued inputs can be represented by an <code>AbstractVector{&lt;:Real}</code> of <code>length</code> <code>N</code>, rather than needing to use an <code>AbstractMatrix{&lt;:Real}</code> of size either <code>N x 1</code> or <code>1 x N</code>. The same can be said for any other input type <code>T</code>, and new subtypes of <code>AbstractVector</code> can be added if particularly efficient ways exist to store collections of inputs of type <code>T</code>. A good example of this in practice is using <code>Tuple{S, Int}</code>, for some input type <code>S</code>, as the <a href="../api/#Inputs-for-Multiple-Outputs">Inputs for Multiple Outputs</a>.</p><p>This approach can also lead to clearer user code. A user need only wrap their inputs in a <code>ColVecs</code> or <code>RowVecs</code> once in their code, and this specification is automatically re-used <em>everywhere</em> in their code. In this sense, it is straightforward to write code in such a way that there is one unique source of &quot;truth&quot; about the way in which a particular data set should be interpreted. Conversely, the <code>obsdim</code> resolution requires that the <code>obsdim</code> keyword argument is passed around with the data <em>every</em> <em>single</em> <em>time</em> that you use it.</p><p>The benefits of the <code>AbstractVector</code> approach are likely most strongly felt when writing a substantial amount of code on top of KernelFunctions.jl – in the same way that using <code>AbstractVector</code>s inside KernelFunctions.jl removes the need for large amounts of keyword argument propagation, the same will be true of other code.</p><h3 id="Why-We-Have-Support-for-Both"><a class="docs-heading-anchor" href="#Why-We-Have-Support-for-Both">Why We Have Support for Both</a><a id="Why-We-Have-Support-for-Both-1"></a><a class="docs-heading-anchor-permalink" href="#Why-We-Have-Support-for-Both" title="Permalink"></a></h3><p>In short: many people like matrices, and are familiar with <code>obsdim</code>-style keyword arguments.</p><p>All internals are implemented using <code>AbstractVector</code>s though, and the <code>obsdim</code> interface is just a thin layer of utility functionality which sits on top of this. To avoid confusion and silent errors, we do not favour a specific convention (rows or columns) but instead it is necessary to specify the <code>obsdim</code> keyword argument explicitly.</p><h2 id="inputs_for_multiple_outputs"><a class="docs-heading-anchor" href="#inputs_for_multiple_outputs">Kernels for Multiple-Outputs</a><a id="inputs_for_multiple_outputs-1"></a><a class="docs-heading-anchor-permalink" href="#inputs_for_multiple_outputs" title="Permalink"></a></h2><p>There are two equally-valid perspectives on multi-output kernels: they can either be treated as matrix-valued kernels, or standard kernels on an extended input domain. Each of these perspectives are convenient in different circumstances, but the latter greatly simplifies the incorporation of multi-output kernels in KernelFunctions.</p><p>More concretely, let <code>k_mat</code> be a matrix-valued kernel, mapping pairs of inputs of type <code>T</code> to matrices of size <code>P x P</code> to describe the covariance between <code>P</code> outputs. Given inputs <code>x</code> and <code>y</code> of type <code>T</code>, and integers <code>p</code> and <code>q</code>, we can always find an equivalent standard kernel <code>k</code> mapping from pairs of inputs of type <code>Tuple{T, Int}</code> to the <code>Real</code>s as follows:</p><pre><code class="language-julia hljs">k((x, p), (y, q)) = k_mat(x, y)[p, q]</code></pre><p>This ability to treat multi-output kernels as single-output kernels is very helpful, as it means that there is no need to introduce additional concepts into the API of KernelFunctions.jl, just additional kernels! This in turn simplifies downstream code as they don&#39;t need to &quot;know&quot; about the existence of multi-output kernels in addition to standard kernels. For example, GP libraries built on top of KernelFunctions.jl just need to know about <code>Kernel</code>s, and they get multi-output kernels, and hence multi-output GPs, for free.</p><p>Where there is the need to specialise <em>implementations</em> for multi-output kernels, this is done in an encapsulated manner – parts of KernelFunctions that have nothing to do with multi-output kernels know <em>nothing</em> about the existence of multi-output kernels.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../api/">« API</a><a class="docs-footer-nextpage" href="../examples/gaussian-process-priors/">Gaussian process prior samples »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Monday 11 March 2024 08:07">Monday 11 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

previews/PR436/examples/gaussian-process-priors/Manifest.toml

@@ -26,10 +26,10 @@ uuid = "6e34b625-4abd-537c-b88f-471c36dfa7a0"
 version = "1.0.8+1"
 
 [[deps.Cairo_jll]]
-deps = ["Artifacts", "Bzip2_jll", "CompilerSupportLibraries_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "JLLWrappers", "LZO_jll", "Libdl", "Pixman_jll", "Pkg", "Xorg_libXext_jll", "Xorg_libXrender_jll", "Zlib_jll", "libpng_jll"]
-git-tree-sha1 = "4b859a208b2397a7a623a03449e4636bdb17bcf2"
+deps = ["Artifacts", "Bzip2_jll", "CompilerSupportLibraries_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "JLLWrappers", "LZO_jll", "Libdl", "Pixman_jll", "Xorg_libXext_jll", "Xorg_libXrender_jll", "Zlib_jll", "libpng_jll"]
+git-tree-sha1 = "a4c43f59baa34011e303e76f5c8c91bf58415aaf"
 uuid = "83423d85-b0ee-5818-9007-b63ccbeb887a"
-version = "1.16.1+1"
+version = "1.18.0+1"
 
 [[deps.Calculus]]
 deps = ["LinearAlgebra"]
@@ -289,9 +289,9 @@ version = "0.21.0+0"
 
 [[deps.Glib_jll]]
 deps = ["Artifacts", "Gettext_jll", "JLLWrappers", "Libdl", "Libffi_jll", "Libiconv_jll", "Libmount_jll", "PCRE2_jll", "Zlib_jll"]
-git-tree-sha1 = "e94c92c7bf4819685eb80186d51c43e71d4afa17"
+git-tree-sha1 = "3ec2a90c4b4d8e452bfd16ad9f6cb09b78256bce"
 uuid = "7746bdde-850d-59dc-9ae8-88ece973131d"
-version = "2.76.5+0"
+version = "2.78.3+0"
 
 [[deps.Graphite2_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
@@ -363,8 +363,8 @@ version = "3.0.2+0"
 
 [[deps.KernelFunctions]]
 deps = ["ChainRulesCore", "Compat", "CompositionsBase", "Distances", "FillArrays", "Functors", "IrrationalConstants", "LinearAlgebra", "LogExpFunctions", "Random", "Requires", "SpecialFunctions", "Statistics", "StatsBase", "TensorCore", "Test", "ZygoteRules"]
-git-tree-sha1 = "f741039ce2690cf16fb6e2635d08860f2d5da7dc"
-repo-rev = "48215e5301b7b98de0bbc8431c032c5eda35f234"
+git-tree-sha1 = "a70fe1064019bda8eda7358932cc42f58da22bf1"
+repo-rev = "702bbed91607238e7f3e3d18d8fa9599e70f9abc"
 repo-url = "/home/runner/work/KernelFunctions.jl/KernelFunctions.jl"
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
 version = "0.10.63"
@@ -950,9 +950,9 @@ version = "1.1.34+0"
 
 [[deps.XZ_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl"]
-git-tree-sha1 = "37195dcb94a5970397ad425b95a9a26d0befce3a"
+git-tree-sha1 = "31c421e5516a6248dfb22c194519e37effbf1f30"
 uuid = "ffd25f8a-64ca-5728-b0f7-c24cf3aae800"
-version = "5.6.0+0"
+version = "5.6.1+0"
 
 [[deps.Xorg_libICE_jll]]
 deps = ["Libdl", "Pkg"]