Skip to content

add doxygen action #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dglazier merged 2 commits into from
Sep 19, 2025
Merged

add doxygen action #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bf076b
add doxygen action
dglazier Sep 19, 2025
b4ef1a0
Merge branch 'master' into quasifree
dglazier Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .github/workflows/doxygen-deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,12 @@ jobs:

- name: Prepare site for deployment
run: |
mkdir -p _site/reference
#cp docs/index.html _site/
mv doxygen-html/* _site/reference/
# Create the final deployment directory
mkdir -p _site
# Copy your new custom landing page to be the site's root index.html
cp docs/index.html _site/index.html
# Move the generated doxygen files into the 'reference' subdirectory


- name: Upload artifact
uses: actions/upload-pages-artifact@v3
Expand Down
174 changes: 174 additions & 0 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>RAD | Reaction Aware Dataframes</title>
<script src="https://cdn.tailwindcss.com"></script>
<link href="https://fonts.googleapis.com/css?family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
<style>
body { font-family: 'Inter', sans-serif; background: #f5f7fa; }
.rad-card { background: #fff; border: 1px solid #b5c3d7; border-radius: 1rem; box-shadow: 0 2px 10px #0a25400d; }
.diagram-box { border: 2px solid #24406e; border-radius: 0.75rem; padding: 1rem; background: #f7fafc; margin-bottom: 1.5rem; }
.diagram-title { font-weight: 600; color: #24406e; }
.diagram-arrow { font-size: 1.5rem; color: #24406e; text-align: center; }
.diagram-accent { color: #ffd166; font-weight: bold; }
code, pre { font-family: 'Fira Mono', 'Menlo', 'Monaco', 'Consolas', monospace; }
.class-label { font-weight: 700; color: #0a2540; background: #ffd16622; border-radius: 0.5rem; padding: 0.25rem 0.75rem; display: inline-block; margin-bottom: 0.25rem; }
.subclass-label { font-weight: 600; color: #24406e; background: #b5c3d755; border-radius: 0.5rem; padding: 0.2rem 0.5rem; display: inline-block; margin-bottom: 0.15rem; }
.note { background: #ffd16633; border-left: 4px solid #ffd166; padding: 0.75rem 1rem; border-radius: 0.5rem; margin: 1rem 0; }
.section-title { font-size: 2rem; font-weight: bold; color: #0a2540; margin-bottom: 1rem; }
</style>
</head>
<body class="text-slate-700">
<div class="max-w-6xl mx-auto p-4 sm:p-8">
<!-- Header -->
<header class="text-center mb-12">
<h1 class="text-4xl font-bold text-slate-900 tracking-tight">RAD: Reaction Aware Dataframes</h1>
<p class="mt-2 text-lg text-slate-600">Modern Particle &amp; Nuclear Physics Data Analysis with ROOT RDataFrame</p>
<a href="./reference/" target="_blank" class="inline-block mt-8 bg-[#ffd166] text-[#0a2540] font-semibold py-2 px-5 rounded-lg shadow hover:bg-[#ffb700] transition">View Full Class Reference (Doxygen)</a>
</header>

<!-- Core Concepts -->
<section class="mb-16">
<h2 class="section-title text-center">Core Concepts</h2>
<div class="grid grid-cols-1 md:grid-cols-2 gap-8">
<div class="rad-card p-6">
<h3 class="text-xl font-semibold mb-2 text-[#24406e]">Reaction Configuration</h3>
<p>RAD is built around the idea of configuring a physics reaction as a <span class="class-label">ConfigReaction</span> object, which manages the full analysis process.</p>
<ul class="list-disc pl-5 mt-2 text-slate-600">
<li>Simplifies code for different final states and data formats (HepMC, ePIC, etc.)</li>
<li>Designed for ROOT RDataFrame, with header-only, runtime parsing</li>
<li>Automates MC matching, truth variable calculation, and combinatorial analysis</li>
<li>User code focuses on defining particles and analysis logic, not boilerplate</li>
</ul>
</div>
<div class="rad-card p-6">
<h3 class="text-xl font-semibold mb-2 text-[#24406e]">Modular Utilities</h3>
<p>RAD provides a suite of utility classes and functions for:</p>
<ul class="list-disc pl-5 mt-2 text-slate-600">
<li>Particle creation (<span class="subclass-label">ParticleCreator</span>)</li>
<li>Kinematic calculations (<span class="subclass-label">BasicKinematics</span>, <span class="subclass-label">ReactionKinematicsRDF</span>)</li>
<li>Histogram management (<span class="subclass-label">Histogrammer</span>)</li>
<li>Random number generation (<span class="subclass-label">Random</span>)</li>
</ul>
<p class="mt-2">These are composed with your <span class="class-label">ConfigReaction</span> object for flexible analysis workflows.</p>
</div>
</div>
</section>

<!-- Class Structure & Workflow Diagram -->
<section class="mb-16">
<h2 class="section-title text-center">Code Structure & Workflow</h2>
<div class="diagram-box">
<div class="diagram-title mb-2">Class Hierarchy & Usage Flow</div>
<div class="flex flex-col items-center">
<span class="class-label">ConfigReaction <span class="text-slate-500 text-sm">(abstract base)</span></span>
<span class="diagram-arrow">&#8595;</span>
<div class="flex flex-row flex-wrap gap-4 justify-center mb-2">
<div>
<span class="class-label">ElectroIonReaction</span>
<div class="diagram-arrow">&#8595;</div>
<div>
<span class="subclass-label">HepMCElectro</span>
<span class="text-xs text-slate-500 block">For MC generator analysis (HepMC3 data)</span>
</div>
<div>
<span class="subclass-label">ePICReaction</span>
<span class="text-xs text-slate-500 block">User-defined: for real experiments (ePIC, etc.)</span>
</div>
</div>
<div>
<span class="class-label">PhotoIonReaction</span>
<div class="diagram-arrow">&#8595;</div>
<div>
<span class="subclass-label">HepMCPhoto</span>
<span class="text-xs text-slate-500 block">MC generator analysis (photoproduction)</span>
</div>
<div>
<span class="subclass-label">[YourExperimentPhoto]</span>
<span class="text-xs text-slate-500 block">User-defined: for real experiments</span>
</div>
</div>
</div>
<span class="diagram-arrow">&#8595;</span>
<span class="subclass-label">ParticleCreator, Histogrammer, Utilities</span>
<span class="text-xs text-slate-500 text-center">Composition: instantiated and used with your reaction object</span>
</div>
<div class="note mt-4">
<strong>Note:</strong> For new analyses, subclass <span class="class-label">ElectroIonReaction</span> or <span class="class-label">PhotoIonReaction</span> to match your experiment and data format. Use <span class="subclass-label">ParticleCreator</span> to define particles, and <span class="subclass-label">Histogrammer</span> to manage histograms.
</div>
</div>
<div class="diagram-box">
<div class="diagram-title mb-2">Typical Analysis Workflow</div>
<ul class="list-decimal pl-6 text-slate-700">
<li><b>Choose reaction type</b>: Subclass <span class="class-label">ElectroIonReaction</span> or <span class="class-label">PhotoIonReaction</span> (e.g. <span class="subclass-label">HepMCElectro</span> for MC, or your experiment's class)</li>
<li><b>Configure particles</b>: Use <span class="subclass-label">ParticleCreator</span> to assign indices and build composite particles</li>
<li><b>Define analysis steps</b>: Kinematics, selection, truth-matching, etc. (using utilities)</li>
<li><b>Histogram management</b>: Instantiate <span class="subclass-label">Histogrammer</span> with your reaction object, configure histograms and splits</li>
<li><b>Run analysis</b>: Execute interactively through ROOT (typically <code>root example.C</code>)</li>
</ul>
</div>
</section>

<!-- Example Usage Section -->
<section class="mb-16">
<h2 class="section-title text-center">Example Usage: ProcessHepMCY.C</h2>
<div class="rad-card p-6">
<pre><code>// Setup for MC generator data (HepMC3)
#include "HepMCElectro.h"
#include "ParticleCreator.h"
#include "Indicing.h"
#include "Histogrammer.h"
#include "BasicKinematicsRDF.h"
#include "ReactionKinematicsRDF.h"
#include "ElectronScatterKinematicsRDF.h"
#include <TBenchmark.h>
#include <TCanvas.h>

void ProcessHepMCY() {
using namespace rad::names::data_type; // For MC(), Rec(), Truth() types
ROOT::EnableImplicitMT(4);

// 1. Create reaction object for HepMC3 MC data
rad::config::HepMCElectro hepmc{"hepmc3_tree", "data_file.root"};
hepmc.AliasMomentumComponents();

// 2. Define particles (using ParticleCreator)
rad::config::ParticleCreator particles{hepmc};
// Assign indices, build composite particles...

// 3. Create and draw histograms (using Histogrammer)
rad::histo::Histogrammer histo{hepmc};
// Configure histograms, draw with histo.DrawSame("Q2",gPad);

// 4. Process and analyze event data...
}
// Run with: root examples/ProcessHepMCY.C
</code></pre>
<p class="mt-4 text-slate-600">This workflow is typical for both MC generator and real experimental data (just swap the reaction class for your experiment).</p>
</div>
</section>

<!-- Build & Usage Section -->
<section class="mb-16">
<h2 class="section-title text-center">Build & Usage</h2>
<div class="rad-card p-6">
<h3 class="text-lg font-semibold text-[#24406e] mb-2">Quick Install</h3>
<pre class="bg-slate-800 text-white p-4 rounded text-sm overflow-x-auto"><code>git clone https://github.com/dglazier/rad
export ROOT_INCLUDE_PATH=/path/to/rad/include:$ROOT_INCLUDE_PATH</code></pre>

<h3 class="text-lg font-semibold text-[#24406e] mt-6 mb-2">Interactive Analysis</h3>
<pre class="bg-slate-800 text-white p-4 rounded text-sm overflow-x-auto"><code>root examples/ProcessHepMCY.C</code></pre>
<p class="mt-2 text-slate-600">No build required (header-only). Analysis is performed interactively in ROOT using C++ scripts.</p>
</div>
</section>

<!-- Footer -->
<footer class="text-center p-8 border-t border-slate-200 mt-12">
<p class="text-slate-500">RAD: Reaction Aware Dataframes &mdash; Modern Particle &amp; Nuclear Physics Analysis</p>
<p class="text-slate-400 text-sm mt-2">Project by <a href="https://github.com/dglazier/rad" class="underline">dglazier</a> &amp; collaborators</p>
</footer>
</div>
</body>
</html>