build based on 38eb996

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-30T08:39:38","documenter_version":"1.7.0"}}
+{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-10-01T13:26:50","documenter_version":"1.7.0"}}

dev/examples/autodiff/index.html

@@ -76,4 +76,4 @@
     Enzyme.Duplicated(obs_seq, ∇obs_enzyme),
     Enzyme.Duplicated(control_seq, ∇control_enzyme),
     Enzyme.Const(seq_ends),
-)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">((nothing, nothing, nothing, nothing),)</code></pre><p>Once again we can check the results.</p><pre><code class="language-julia hljs">∇parameters_enzyme ≈ ∇parameters_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><pre><code class="language-julia hljs">∇obs_enzyme ≈ ∇obs_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><pre><code class="language-julia hljs">∇control_enzyme ≈ ∇control_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><p>For increased efficiency, we could provide temporary storage to Enzyme.jl in order to avoid allocations. This requires going one level deeper and leveraging the in-place <a href="../../api/#HiddenMarkovModels.forward!"><code>HiddenMarkovModels.forward!</code></a> function.</p><h2 id="Gradient-methods"><a class="docs-heading-anchor" href="#Gradient-methods">Gradient methods</a><a id="Gradient-methods-1"></a><a class="docs-heading-anchor-permalink" href="#Gradient-methods" title="Permalink"></a></h2><p>Once we have gradients of the loglikelihood, it is a natural idea to perform gradient descent in order to fit the parameters of a custom HMM. However, there are two caveats we must keep in mind.</p><p>First, computing a gradient essentially requires running the forward-backward algorithm, which means it is expensive. Given the output of forward-backward, if there is a way to perform a more accurate parameter update (like going straight to the maximum likelihood value), it is probably worth it. That is what we show in the other tutorials with the reimplementation of the <code>fit!</code> method.</p><p>Second, HMM parameters live in a constrained space, which calls for a projected gradient descent. Most notably, the transition matrix must be stochastic, and the orthogonal projection onto this set (the Birkhoff polytope) is not easy to obtain.</p><p>Still, first order optimization can be relevant when we lack explicit formulas for maximum likelihood.</p><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../controlled/">« Control dependency</a><a class="docs-footer-nextpage" href="../../api/">API reference »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Monday 30 September 2024 08:39">Monday 30 September 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">((nothing, nothing, nothing, nothing),)</code></pre><p>Once again we can check the results.</p><pre><code class="language-julia hljs">∇parameters_enzyme ≈ ∇parameters_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><pre><code class="language-julia hljs">∇obs_enzyme ≈ ∇obs_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><pre><code class="language-julia hljs">∇control_enzyme ≈ ∇control_forwarddiff</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><p>For increased efficiency, we could provide temporary storage to Enzyme.jl in order to avoid allocations. This requires going one level deeper and leveraging the in-place <a href="../../api/#HiddenMarkovModels.forward!"><code>HiddenMarkovModels.forward!</code></a> function.</p><h2 id="Gradient-methods"><a class="docs-heading-anchor" href="#Gradient-methods">Gradient methods</a><a id="Gradient-methods-1"></a><a class="docs-heading-anchor-permalink" href="#Gradient-methods" title="Permalink"></a></h2><p>Once we have gradients of the loglikelihood, it is a natural idea to perform gradient descent in order to fit the parameters of a custom HMM. However, there are two caveats we must keep in mind.</p><p>First, computing a gradient essentially requires running the forward-backward algorithm, which means it is expensive. Given the output of forward-backward, if there is a way to perform a more accurate parameter update (like going straight to the maximum likelihood value), it is probably worth it. That is what we show in the other tutorials with the reimplementation of the <code>fit!</code> method.</p><p>Second, HMM parameters live in a constrained space, which calls for a projected gradient descent. Most notably, the transition matrix must be stochastic, and the orthogonal projection onto this set (the Birkhoff polytope) is not easy to obtain.</p><p>Still, first order optimization can be relevant when we lack explicit formulas for maximum likelihood.</p><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../controlled/">« Control dependency</a><a class="docs-footer-nextpage" href="../../api/">API reference »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Tuesday 1 October 2024 13:26">Tuesday 1 October 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/examples/basics/index.html

@@ -65,4 +65,4 @@
  [-0.502073, -0.800874]  [-0.5, -0.8]
  [0.504019, 0.801399]    [0.5, 0.8]</code></pre><pre><code class="language-julia hljs">hcat(initialization(hmm_est_concat), initialization(hmm))</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">2×2 Matrix{Float64}:
  0.605645  0.6
- 0.394355  0.4</code></pre><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../">« Home</a><a class="docs-footer-nextpage" href="../types/">Types »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Monday 30 September 2024 08:39">Monday 30 September 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+ 0.394355  0.4</code></pre><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../">« Home</a><a class="docs-footer-nextpage" href="../types/">Types »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Tuesday 1 October 2024 13:26">Tuesday 1 October 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/examples/controlled/index.html

@@ -28,7 +28,7 @@
 
 obs_seq = reduce(vcat, obs_seqs)
 control_seq = reduce(vcat, control_seqs)
-seq_ends = cumsum(length.(obs_seqs));</code></pre><h2 id="Inference"><a class="docs-heading-anchor" href="#Inference">Inference</a><a id="Inference-1"></a><a class="docs-heading-anchor-permalink" href="#Inference" title="Permalink"></a></h2><p>Not much changes from the case with simple time dependency.</p><pre><code class="language-julia hljs">best_state_seq, _ = viterbi(hmm, obs_seq, control_seq; seq_ends)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">([1, 2, 1, 1, 2, 2, 2, 2, 2, 2  …  1, 1, 1, 1, 1, 1, 2, 2, 2, 2], [-272.53877097871964, -292.8465796075759, -332.367537500091, -322.46405498947547, -316.8647069870306, -268.6179339039716, -271.85248398856527, -356.6707367317983, -214.78662752211517, -274.0076333485443  …  -291.7558661484622, -265.21737412674656, -223.91830597317357, -297.14183643079633, -171.075347794121, -320.1569803046106, -194.07083905613257, -301.23391750929693, -325.73252453427676, -196.82633619090439])</code></pre><h2 id="Learning"><a class="docs-heading-anchor" href="#Learning">Learning</a><a id="Learning-1"></a><a class="docs-heading-anchor-permalink" href="#Learning" title="Permalink"></a></h2><p>Once more, we override the <code>fit!</code> function. The state-related parameters are estimated in the standard way. Meanwhile, the observation coefficients are given by the formula for <a href="https://en.wikipedia.org/wiki/Weighted_least_squares">weighted least squares</a>.</p><pre><code class="language-julia hljs">function StatsAPI.fit!(
+seq_ends = cumsum(length.(obs_seqs));</code></pre><h2 id="Inference"><a class="docs-heading-anchor" href="#Inference">Inference</a><a id="Inference-1"></a><a class="docs-heading-anchor-permalink" href="#Inference" title="Permalink"></a></h2><p>Not much changes from the case with simple time dependency.</p><pre><code class="language-julia hljs">best_state_seq, _ = viterbi(hmm, obs_seq, control_seq; seq_ends)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">([2, 2, 2, 2, 1, 1, 1, 2, 2, 2  …  2, 2, 2, 1, 1, 1, 1, 1, 1, 1], [-282.9758167143853, -276.00671751411386, -371.24181781000067, -307.61823249622614, -367.83170808085697, -202.3308642947108, -329.55893436574945, -262.873633152325, -193.4782294384391, -324.22142538789774  …  -237.18347666459772, -196.9444524847919, -376.0529887946711, -321.37826172211396, -345.20244256849907, -324.6386344081525, -367.2170181263724, -298.71453741912063, -229.71806938636718, -230.7122097211064])</code></pre><h2 id="Learning"><a class="docs-heading-anchor" href="#Learning">Learning</a><a id="Learning-1"></a><a class="docs-heading-anchor-permalink" href="#Learning" title="Permalink"></a></h2><p>Once more, we override the <code>fit!</code> function. The state-related parameters are estimated in the standard way. Meanwhile, the observation coefficients are given by the formula for <a href="https://en.wikipedia.org/wiki/Weighted_least_squares">weighted least squares</a>.</p><pre><code class="language-julia hljs">function StatsAPI.fit!(
     hmm::ControlledGaussianHMM{T},
     fb_storage::HMMs.ForwardBackwardStorage,
     obs_seq::AbstractVector,
@@ -60,17 +60,17 @@
 trans_guess = [0.6 0.4; 0.3 0.7]
 dist_coeffs_guess = [-1.1 * ones(d), 1.1 * ones(d)]
 hmm_guess = ControlledGaussianHMM(init_guess, trans_guess, dist_coeffs_guess);</code></pre><pre><code class="language-julia hljs">hmm_est, loglikelihood_evolution = baum_welch(hmm_guess, obs_seq, control_seq; seq_ends)
-first(loglikelihood_evolution), last(loglikelihood_evolution)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">(-267324.84961230913, -263780.73057643685)</code></pre><p>How did we perform?</p><pre><code class="language-julia hljs">cat(hmm_est.trans, hmm.trans; dims=3)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">2×2×2 Array{Float64, 3}:
+first(loglikelihood_evolution), last(loglikelihood_evolution)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">(-264727.24942514714, -261198.93867245756)</code></pre><p>How did we perform?</p><pre><code class="language-julia hljs">cat(hmm_est.trans, hmm.trans; dims=3)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">2×2×2 Array{Float64, 3}:
 [:, :, 1] =
- 0.695396  0.304604
- 0.203493  0.796507
+ 0.70373   0.29627
+ 0.201148  0.798852
 
 [:, :, 2] =
  0.7  0.3
  0.2  0.8</code></pre><pre><code class="language-julia hljs">hcat(hmm_est.dist_coeffs[1], hmm.dist_coeffs[1])</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">3×2 Matrix{Float64}:
- -1.00171  -1.0
- -1.00098  -1.0
- -0.99532  -1.0</code></pre><pre><code class="language-julia hljs">hcat(hmm_est.dist_coeffs[2], hmm.dist_coeffs[2])</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">3×2 Matrix{Float64}:
- 0.995554  1.0
- 1.00376   1.0
- 0.995381  1.0</code></pre><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../temporal/">« Time dependency</a><a class="docs-footer-nextpage" href="../autodiff/">Autodiff »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Monday 30 September 2024 08:39">Monday 30 September 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+ -0.998469  -1.0
+ -1.00476   -1.0
+ -1.00124   -1.0</code></pre><pre><code class="language-julia hljs">hcat(hmm_est.dist_coeffs[2], hmm.dist_coeffs[2])</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">3×2 Matrix{Float64}:
+ 1.00392   1.0
+ 0.993359  1.0
+ 1.00449   1.0</code></pre><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../temporal/">« Time dependency</a><a class="docs-footer-nextpage" href="../autodiff/">Autodiff »</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="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Tuesday 1 October 2024 13:26">Tuesday 1 October 2024</span>. Using Julia version 1.10.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>