-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Documenter.jl
committed
Feb 7, 2024
1 parent
5dac890
commit 38a4059
Showing
17 changed files
with
1,539 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| {"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-02-07T15:14:49","documenter_version":"1.2.1"}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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="1.-Provide-a-map-between-fClassName-of-your-struct-(as-seen-in-.root)-to-a-Julia-type."><a class="docs-heading-anchor" href="#1.-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="1.-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="#1.-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("TLorentzVector" => 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="2.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data"><a class="docs-heading-anchor" href="#2.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data">2. Extend the raw bytes interpreting function <code>UnROOT.interped_data</code></a><a id="2.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data-1"></a><a class="docs-heading-anchor-permalink" href="#2.-Extend-the-raw-bytes-interpreting-function-UnROOT.interped_data" title="Permalink"></a></h3><p>By default, given a branch element type and a "jaggness" 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 "teach" 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 <: 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'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't care (which is why we don'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'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> using UnROOT | ||
|
|
||
| julia> f = ROOTFile("test/samples/km3net_online.root") | ||
| ROOTFile("test/samples/km3net_online.root") with 10 entries and 41 streamers. | ||
|
|
||
| julia> data, offsets = array(f, "KM3NET_EVENT/KM3NET_EVENT/snapshotHits"; raw=true) | ||
| 2058-element Array{UInt8,1}: | ||
| 0x00 | ||
| 0x03 | ||
| ⋮ | ||
|
|
||
| julia> 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.2.1 on <span class="colophon-date" title="Wednesday 7 February 2024 15:14">Wednesday 7 February 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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">> cat readtree.jl | ||
| using UnROOT | ||
|
|
||
| const r = ROOTFile("/home/akako/.julia/dev/UnROOT/test/samples/NanoAODv5_sample.root") | ||
|
|
||
| const t = LazyTree(r, "Events", ["nMuon", "Electron_dxy"]) | ||
|
|
||
|
|
||
| @show t[1, :Electron_dxy] | ||
|
|
||
| > 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':</p><pre><code class="language-julia hljs">julia> using PackageCompiler | ||
|
|
||
| julia> PackageCompiler.create_sysimage(:UnROOT; precompile_statements_file="./readtree.jl", sysimage_path="./unroot.so", replace_default=false)'</code></pre><p>profit:</p><pre><code class="language-fish hljs">> 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.2.1 on <span class="colophon-date" title="Wednesday 7 February 2024 15:14">Wednesday 7 February 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html> |
Oops, something went wrong.