Skip to content

Commit

Permalink
build based on a6115c4
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Oct 10, 2023
1 parent db50687 commit 8a4139c
Show file tree
Hide file tree
Showing 17 changed files with 1,516 additions and 0 deletions.
1 change: 1 addition & 0 deletions previews/PR275/.documenter-siteinfo.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-10T12:28:33","documenter_version":"1.1.0"}}
30 changes: 30 additions & 0 deletions previews/PR275/advanced/custom_branch/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Parse Custom Branch · UnROOT.jl</title><meta name="title" content="Parse Custom Branch · UnROOT.jl"/><meta property="og:title" content="Parse Custom Branch · UnROOT.jl"/><meta property="twitter:title" content="Parse Custom Branch · UnROOT.jl"/><meta name="description" content="Documentation for UnROOT.jl."/><meta property="og:description" content="Documentation for UnROOT.jl."/><meta property="twitter:description" content="Documentation for UnROOT.jl."/><script data-outdated-warner src="../../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="../.."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../../assets/documenter.js"></script><script src="../../search_index.js"></script><script src="../../siteinfo.js"></script><script src="../../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../../">UnROOT.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../../">Introduction</a></li><li><a class="tocitem" href="../../exampleusage/">Example Usage</a></li><li><a class="tocitem" href="../../performancetips/">Performance Tips</a></li><li><span class="tocitem">Advanced Usage</span><ul><li class="is-active"><a class="tocitem" href>Parse Custom Branch</a><ul class="internal"><li><a class="tocitem" href="#Reading-Raw-Data-from-Branch"><span>Reading Raw Data from Branch</span></a></li></ul></li><li><a class="tocitem" href="../reduce_latency/">Reduce startup latency</a></li></ul></li><li><a class="tocitem" href="../../devdocs/">For Contributors</a></li><li><a class="tocitem" href="../../internalapis/">APIs</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Advanced Usage</a></li><li class="is-active"><a href>Parse Custom Branch</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Parse Custom Branch</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/JuliaHEP/UnROOT.jl/blob/main/docs/src/advanced/custom_branch.md#L" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Parse-Custom-Branch"><a class="docs-heading-anchor" href="#Parse-Custom-Branch">Parse Custom Branch</a><a id="Parse-Custom-Branch-1"></a><a class="docs-heading-anchor-permalink" href="#Parse-Custom-Branch" title="Permalink"></a></h1><p>It is possible to parse Branches with custom structure as long as you know how the bytes should be interpreted. As an example, the <code>TLorentzVector</code> is added using this mechanism and we will walk through the steps needed:</p><h3 id=".-Provide-a-map-between-fClassName-of-your-struct-(as-seen-in-.root)-to-a-Julia-type."><a class="docs-heading-anchor" href="#.-Provide-a-map-between-fClassName-of-your-struct-(as-seen-in-.root)-to-a-Julia-type.">1. Provide a map between <code>fClassName</code> of your struct (as seen in .root) to a Julia type.</a><a id=".-Provide-a-map-between-fClassName-of-your-struct-(as-seen-in-.root)-to-a-Julia-type.-1"></a><a class="docs-heading-anchor-permalink" href="#.-Provide-a-map-between-fClassName-of-your-struct-(as-seen-in-.root)-to-a-Julia-type." title="Permalink"></a></h3><p>Pass a <code>Dict{String, Type}</code> to <code>ROOTFile(filepath; customstructs)</code>. The <code>TLorentzVector</code> is shipped <a href="https://github.com/JuliaHEP/UnROOT.jl/blob/06b692523bbff3f467f6b7fe3544e411a719bc9e/src/root.jl#L21">by default</a>:</p><pre><code class="language-julia hljs">ROOTFile(filepath; customstructs = Dict(&quot;TLorentzVector&quot; =&gt; LorentzVector{Float64}))</code></pre><p>This <code>Dict</code> will subsequently be used by the <code>auto_T_JaggT</code> function <a href="https://github.com/JuliaHEP/UnROOT.jl/blob/06b692523bbff3f467f6b7fe3544e411a719bc9e/src/root.jl#L213-L222">at here</a> such that when we encounter a branch with this <code>fClassName</code>, we will return your <code>Type</code> as the detected element type of this branch.</p><h3 id=".-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data"><a class="docs-heading-anchor" href="#.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data">2. Extend the raw bytes interpreting function <code>UnROOT.interped_data</code></a><a id=".-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data-1"></a><a class="docs-heading-anchor-permalink" href="#.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data" title="Permalink"></a></h3><p>By default, given a branch element type and a &quot;jaggness&quot; type, a general function <a href="https://github.com/JuliaHEP/UnROOT.jl/blob/06b692523bbff3f467f6b7fe3544e411a719bc9e/src/root.jl#L149">is defined</a> which will try to parse the raw bytes into Julia data structure. The <code>::Type{T}</code> will match what you have provided in the <code>Dict</code> in the previous step.</p><p>Thus, to &quot;teach&quot; UnROOT how to interpret bytes for your type <code>T</code>, you would want to defined a more specific <code>UnROOT.interped_data</code> than the default one. Taking the <code>TLorentzVector</code> <a href="https://github.com/JuliaHEP/UnROOT.jl/blob/06b692523bbff3f467f6b7fe3544e411a719bc9e/src/custom.jl#L23">as example</a> again, we define a function:</p><pre><code class="language-julia hljs">using LorentzVector
const LVF64 = LorentzVector{Float64}
function UnROOT.interped_data(rawdata, rawoffsets, ::Type{LVF64}, ::Type{J}) where {T, J &lt;: JaggType}
# `rawoffsets` is actually redundant, since we know each TLV is always 64 bytes (withe 32 bytes header)
[
reinterpret(LVF64, x) for x in Base.Iterators.partition(rawdata, 64)
]
end

# VorView is defined in the `src/custom.jl`
function Base.reinterpret(::Type{LVF64}, v::VorView) where T
# x,y,z,t in ROOT
v4 = ntoh.(reinterpret(Float64, v[1+32:end]))
# t,x,y,z in LorentzVectors.jl
LVF64(v4[4], v4[1], v4[2], v4[3])
end</code></pre><p>The <code>Base.reinterpret</code> function is just a helper function, you could instead write everything inside <code>UnROOT.interped_data</code>. We then builds on these, to interpret Jagged TLV branch: https://github.com/JuliaHEP/UnROOT.jl/blob/4747f6f5fd97ed1a872765485b4eb9e99ec5a650/src/custom.jl#L47</p><h3 id="More-details"><a class="docs-heading-anchor" href="#More-details">More details</a><a id="More-details-1"></a><a class="docs-heading-anchor-permalink" href="#More-details" title="Permalink"></a></h3><p>To expand a bit what we&#39;re doing here, the <code>rawdata</code> for a single <code>TLV</code> is always <code>64 bytes</code> long and the first <code>32 bytes</code> are TObject header which we don&#39;t care (which is why we don&#39;t care about <code>rawoffsets</code> here). The last <code>32 bytes</code> make up 4 <code>Float64</code> and we simply parse them and return a collection of (julia) <code>LorentzVector{Float64}</code>.</p><p>In general, if <code>auto_T_JaggT</code> returned <code>MyType</code> as promised branch element type, then</p><pre><code class="language-julia hljs">UnROOT.interped_data(rawdata, rawoffsets, ::Type{MyType},</code></pre><p>should return <code>Vector{MyType}</code> because <code>UnROOT.interped_data</code> receives raw bytes of a basket at a time.</p><p>And that&#39;s it! Afterwards both <code>LazyBranch</code> and <code>LazyTree</code> will be able to constructed with correct type and also knows how to interpret bytes when you indexing or iterating through them</p><h2 id="Reading-Raw-Data-from-Branch"><a class="docs-heading-anchor" href="#Reading-Raw-Data-from-Branch">Reading Raw Data from Branch</a><a id="Reading-Raw-Data-from-Branch-1"></a><a class="docs-heading-anchor-permalink" href="#Reading-Raw-Data-from-Branch" title="Permalink"></a></h2><p>Alternatively, reading raw data is also possible using the <code>UnROOT.array(f::ROOTFile, path; raw=true)</code> method. The output can be then reinterpreted using a custom type with the method <code>UnROOT.splitup(data, offsets, T::Type; skipbytes=0, jagged=true)</code>. This provides more fine grain control in case your branch is highly irregular. You can then define suitable Julia <code>type</code> and <code>readtype</code> method for parsing these data. Alternatively, you can of course parse the <code>data</code> and <code>offsets</code> entirely manually. Here is it in action, with the help of the <code>type</code>s from <code>custom.jl</code>, and some data from the KM3NeT experiment:</p><pre><code class="language-julia hljs">julia&gt; using UnROOT

julia&gt; f = ROOTFile(&quot;test/samples/km3net_online.root&quot;)
ROOTFile(&quot;test/samples/km3net_online.root&quot;) with 10 entries and 41 streamers.

julia&gt; data, offsets = array(f, &quot;KM3NET_EVENT/KM3NET_EVENT/snapshotHits&quot;; raw=true)
2058-element Array{UInt8,1}:
0x00
0x03
⋮

julia&gt; UnROOT.splitup(data, offsets, UnROOT._KM3NETDAQHit)
4-element Vector{Vector{UnROOT._KM3NETDAQHit}}:
[UnROOT._KM3NETDAQHit(1073742790, 0x00, 9, 0x60)......</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../performancetips/">« Performance Tips</a><a class="docs-footer-nextpage" href="../reduce_latency/">Reduce startup latency »</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><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.1.0 on <span class="colophon-date" title="Tuesday 10 October 2023 12:28">Tuesday 10 October 2023</span>. Using Julia version 1.9.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
26 changes: 26 additions & 0 deletions previews/PR275/advanced/reduce_latency/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Reduce startup latency · UnROOT.jl</title><meta name="title" content="Reduce startup latency · UnROOT.jl"/><meta property="og:title" content="Reduce startup latency · UnROOT.jl"/><meta property="twitter:title" content="Reduce startup latency · UnROOT.jl"/><meta name="description" content="Documentation for UnROOT.jl."/><meta property="og:description" content="Documentation for UnROOT.jl."/><meta property="twitter:description" content="Documentation for UnROOT.jl."/><script data-outdated-warner src="../../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="../.."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../../assets/documenter.js"></script><script src="../../search_index.js"></script><script src="../../siteinfo.js"></script><script src="../../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../../">UnROOT.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../../">Introduction</a></li><li><a class="tocitem" href="../../exampleusage/">Example Usage</a></li><li><a class="tocitem" href="../../performancetips/">Performance Tips</a></li><li><span class="tocitem">Advanced Usage</span><ul><li><a class="tocitem" href="../custom_branch/">Parse Custom Branch</a></li><li class="is-active"><a class="tocitem" href>Reduce startup latency</a></li></ul></li><li><a class="tocitem" href="../../devdocs/">For Contributors</a></li><li><a class="tocitem" href="../../internalapis/">APIs</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Advanced Usage</a></li><li class="is-active"><a href>Reduce startup latency</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Reduce startup latency</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/JuliaHEP/UnROOT.jl/blob/main/docs/src/advanced/reduce_latency.md#L" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Bake-sysimage-with-PackageCompiler.jl"><a class="docs-heading-anchor" href="#Bake-sysimage-with-PackageCompiler.jl">Bake <code>sysimage</code> with <code>PackageCompiler.jl</code></a><a id="Bake-sysimage-with-PackageCompiler.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Bake-sysimage-with-PackageCompiler.jl" title="Permalink"></a></h1><p>You can bake a sysimage tailored for your analysis to reduce latency.</p><pre><code class="language-julia hljs">&gt; cat readtree.jl
using UnROOT

const r = ROOTFile(&quot;/home/akako/.julia/dev/UnROOT/test/samples/NanoAODv5_sample.root&quot;)

const t = LazyTree(r, &quot;Events&quot;, [&quot;nMuon&quot;, &quot;Electron_dxy&quot;])


@show t[1, :Electron_dxy]

&gt; time julia --startup-file=no readtree.jl
t[1, :Electron_dxy] = Float32[0.00037050247]

________________________________________________________
Executed in 10.82 secs fish external
usr time 11.09 secs 580.00 micros 11.09 secs
sys time 0.65 secs 189.00 micros 0.65 secs</code></pre><p>In Julia, `]add PackageCompiler&#39;:</p><pre><code class="language-julia hljs">julia&gt; using PackageCompiler

julia&gt; PackageCompiler.create_sysimage(:UnROOT; precompile_statements_file=&quot;./readtree.jl&quot;, sysimage_path=&quot;./unroot.so&quot;, replace_default=false)&#39;</code></pre><p>profit:</p><pre><code class="language-fish hljs">&gt; time julia -J ./unroot.so readtree.jl
t[1, :Electron_dxy] = Float32[0.00037050247]

________________________________________________________
Executed in 619.20 millis fish external
usr time 902.29 millis 0.00 millis 902.29 millis
sys time 658.59 millis 1.05 millis 657.54 millis</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../custom_branch/">« Parse Custom Branch</a><a class="docs-footer-nextpage" href="../../devdocs/">For Contributors »</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><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.1.0 on <span class="colophon-date" title="Tuesday 10 October 2023 12:28">Tuesday 10 October 2023</span>. Using Julia version 1.9.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit 8a4139c

Please sign in to comment.