Porting: multi-plane, Steiner, traj. fitting

.aiexclude

@@ -0,0 +1,2 @@
+**/docs/
+**/test/

.clang-format

@@ -1,90 +1,36 @@
 ---
 Language:        Cpp
-# BasedOnStyle:  sphenix
 AccessModifierOffset: -1
 AlignAfterOpenBracket: Align
-AlignConsecutiveAssignments: false
-AlignConsecutiveDeclarations: false
-AlignEscapedNewlinesLeft: true
 AlignOperands:   true
 AlignTrailingComments: true
 AllowAllParametersOfDeclarationOnNextLine: true
-AllowShortBlocksOnASingleLine: false
-AllowShortCaseLabelsOnASingleLine: false
 AllowShortFunctionsOnASingleLine: All
 AllowShortIfStatementsOnASingleLine: true
 AllowShortLoopsOnASingleLine: true
-AlwaysBreakAfterDefinitionReturnType: None
-AlwaysBreakAfterReturnType: None
 AlwaysBreakBeforeMultilineStrings: true
 AlwaysBreakTemplateDeclarations: true
 BinPackArguments: true
 BinPackParameters: true
 BraceWrapping:   
   AfterClass:      true
   AfterControlStatement: true
-  AfterEnum:       false
   AfterFunction:   true
-  AfterNamespace:  false
-  AfterObjCDeclaration: false
-  AfterStruct:     false
-  AfterUnion:      false
-  BeforeCatch:     false
-  BeforeElse:      false
-  IndentBraces:    false
 BreakBeforeBinaryOperators: None
 BreakBeforeBraces: Stroustrup
 BreakBeforeTernaryOperators: true
-BreakConstructorInitializersBeforeComma: true
 ColumnLimit:     120
-CommentPragmas:  '^ IWYU pragma:'
-ConstructorInitializerAllOnOneLineOrOnePerLine: false
 ConstructorInitializerIndentWidth: 2
 ContinuationIndentWidth: 4
 Cpp11BracedListStyle: true
-DerivePointerAlignment: true
-DisableFormat:   true
-ExperimentalAutoDetectBinPacking: false
-ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
-IncludeCategories: 
-  - Regex:           '^<.*\.h>'
-    Priority:        1
-  - Regex:           '^<.*'
-    Priority:        2
-  - Regex:           '.*'
-    Priority:        3
-IndentCaseLabels: false
 IndentWidth:     4
-IndentWrappedFunctionNames: false
-KeepEmptyLinesAtTheStartOfBlocks: false
-MacroBlockBegin: ''
-MacroBlockEnd:   ''
-MaxEmptyLinesToKeep: 1
 NamespaceIndentation: All
-ObjCBlockIndentWidth: 2
-ObjCSpaceAfterProperty: false
-ObjCSpaceBeforeProtocolList: false
-PenaltyBreakBeforeFirstCallParameter: 1
-PenaltyBreakComment: 300
-PenaltyBreakFirstLessLess: 120
-PenaltyBreakString: 1000
-PenaltyExcessCharacter: 1000000
-PenaltyReturnTypeOnItsOwnLine: 200
 PointerAlignment: Right
 ReflowComments:  true
-SortIncludes:    false
-SpaceAfterCStyleCast: true
-SpaceBeforeAssignmentOperators: true
-SpaceBeforeParens: ControlStatements
-SpaceInEmptyParentheses: false
 SpacesBeforeTrailingComments: 2
-SpacesInAngles:  false
-SpacesInContainerLiterals: true
-SpacesInCStyleCastParentheses: false
-SpacesInParentheses: false
-SpacesInSquareBrackets: false
 Standard:        Auto
 TabWidth:        8
 UseTab:          Never
+DisableFormat: true
 ...
 

.gitignore

@@ -87,3 +87,11 @@ spng
 .cache
 .clangd
 junk*
+downloads
+tmp*
+
+doxy
+*.bak
+doxy_quick
+html
+latex

Doxyfile

@@ -177,9 +177,11 @@ SHORT_NAMES            = NO
 # description. If set to NO, the Javadoc-style will behave just like regular Qt-
 # style comments (thus requiring an explicit @brief command for a brief
 # description.)
+### this is comments like /** ... */
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
+CSharp_comments = YES
 
 # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
 # line (until the first dot) of a Qt-style comment as the brief description. If
@@ -280,7 +282,7 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # Note that for custom extensions you also need to set FILE_PATTERNS otherwise
 # the files are not read by doxygen.
 
-EXTENSION_MAPPING      = 
+EXTENSION_MAPPING      = org=md
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -753,7 +755,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = README.org apps util iface gen sigproc sio sst tbb
+INPUT = README.org apps aux cfg clus docs gen hio iface img pgraph pytorch root sigproc sio tbb test util zio
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -773,7 +775,8 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.c \
+FILE_PATTERNS          = *.org \
+                         *.c \
                          *.cc \
                          *.cxx \
                          *.cpp \
@@ -845,7 +848,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */test/*
+EXCLUDE_PATTERNS       = */test/* **/talks/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -908,7 +911,9 @@ INPUT_FILTER           =
 # filters are used. If the FILTER_PATTERNS tag is empty or if none of the
 # patterns match the file name, INPUT_FILTER is applied.
 
-FILTER_PATTERNS        = 
+## Run "./run-doxygen" instead of bare "doxygen" to make this line work
+## Note, the filter takes the source file as first arg and prints result to stdout
+FILTER_PATTERNS        = "*.org=run-doxygen org2md"
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER ) will also be used to filter the input files that are used for
@@ -930,7 +935,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = docs/README.org
+USE_MDFILE_AS_MAINPAGE = README.org
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

README.org

@@ -1,7 +1,12 @@
+#+BEGIN_COMMENT
+\mainpage
+#+END_COMMENT
+
 #+TITLE: Wire-Cell Toolkit 
 #+SETUPFILE: docs/setup-readme.org
 
 
+
 Welcome to the Wire-Cell Toolkit (WCT) source repository at https://github.com/wirecell/wire-cell-toolkit.
 
 * Overview

apps/src/ConfigDumper.cxx

@@ -63,4 +63,5 @@ void ConfigDumper::execute()
     }
 
     Persist::dump(get<string>(m_cfg, "filename"), cm.all());
+    (void)nfailed; // unused, but useful for debugging
 }

aux/inc/WireCellAux/LinterpFunction.h

@@ -0,0 +1,46 @@
+#include "WireCellIface/IScalarFunction.h"
+#include "WireCellIface/IConfigurable.h"
+#include "WireCellUtil/Interpolate.h"
+
+namespace WireCell::Aux {
+
+    /** A scalar function implemented as linear interpolation on regularly or
+     * irregularly spaced points.
+     *
+     * Extrapolation returns end point values.
+     */
+    class LinterpFunction : public WireCell::IScalarFunction, WireCell::IConfigurable {
+    public:
+        virtual ~LinterpFunction();
+
+        virtual void configure(const WireCell::Configuration& config);
+        virtual WireCell::Configuration default_configuration() const {
+            return Configuration{}; // user must supply all
+        }
+
+        virtual double scalar_function(double x);
+    private:
+
+        /// Config: values
+        ///
+        /// Array of function samples.
+        ///
+        /// Config: coords
+        ///
+        /// Array of the coordinates at which values are sampled.
+        /// 
+        /// Config: start
+        ///
+        /// The first abscissa value.
+        ///
+        /// Config: step
+        ///
+        /// Distance between regular samples
+        ///
+        /// Note: coords and (start,step) are mutually exclusive.  The former
+        /// implies irregular sample interpolation and the latter regular.
+
+        std::function<double(const double&)> m_terp;
+    };
+
+}

aux/inc/WireCellAux/ParticleInfo.h

@@ -0,0 +1,128 @@
+#ifndef WIRECELLAUX_PARTICLEINFO
+#define WIRECELLAUX_PARTICLEINFO
+
+#include "WireCellUtil/Point.h"
+#include "WireCellUtil/Units.h"
+#include "WireCellUtil/D4Vector.h"
+#include <string>
+#include <map>
+
+namespace WireCell::Aux {
+
+    /**
+     * @brief A comprehensive particle information storage class
+     * 
+     * This class stores all relevant particle physics information including
+     * PDG codes, 4-momentum, mass, name, and kinetic energy. It follows
+     * Wire-Cell toolkit conventions and integrates well with existing
+     * deposition and clustering infrastructure.
+     */
+    class ParticleInfo {
+    public:
+        // Default constructor - creates an invalid/empty particle
+        ParticleInfo();
+
+        // Comprehensive constructor
+        ParticleInfo(int pdg_code, 
+                    double mass,
+                    const std::string& name,
+                    double kinetic_energy,
+                    const WireCell::Point& momentum_3vec,
+                    int id = 0,
+                    double charge = 0.0);
+
+        // Constructor from 4-momentum
+        ParticleInfo(int pdg_code,
+                    double mass, 
+                    const std::string& name,
+                    const WireCell::D4Vector<double>& four_momentum,
+                    int id = 0,
+                    double charge = 0.0);
+
+        virtual ~ParticleInfo() = default;
+
+        // Core particle properties
+        int pdg() const { return m_pdg_code; }
+        double mass() const { return m_mass; }
+        const std::string& name() const { return m_name; }
+        double kinetic_energy() const { return m_kinetic_energy; }
+        int id() const { return m_id; }
+        double charge() const { return m_charge; }
+
+        // 4-momentum access
+        double energy() const { return m_four_momentum.e(); }
+        WireCell::Point momentum() const { return WireCell::Point(m_four_momentum.px(), m_four_momentum.py(), m_four_momentum.pz()); }
+        const WireCell::D4Vector<double>& four_momentum() const { return m_four_momentum; }
+
+        // Derived quantities
+        double momentum_magnitude() const { return m_four_momentum.p(); }
+        double beta() const { return m_four_momentum.beta(); }           // v/c
+        double gamma() const { return m_four_momentum.gamma(); }          // Lorentz factor
+        double rapidity() const { return m_four_momentum.rapidity(); }       // 0.5 * ln((E+pz)/(E-pz))
+
+        // Utility methods
+        bool is_valid() const { return m_pdg_code != 0; }
+        bool is_charged() const { return std::abs(m_charge) > 1e-6; }
+        bool is_stable() const;        // Based on PDG code
+
+        // Setters (for cases where you need to modify after construction)
+        void set_pdg(int pdg) { m_pdg_code = pdg; }
+        void set_mass(double mass) { m_mass = mass; update_kinematics(); }
+        void set_name(const std::string& name) { m_name = name; }
+        void set_momentum(const WireCell::Point& momentum_3vec);
+        void set_four_momentum(const WireCell::D4Vector<double>& four_momentum);
+        void set_kinetic_energy(double ke);
+        void set_id(int id) { m_id = id; }
+        void set_charge(double charge) { m_charge = charge; }
+
+        // Static utility methods for PDG lookups
+        static std::string pdg_to_name(int pdg_code);
+        static double pdg_to_mass(int pdg_code);
+        static double pdg_to_charge(int pdg_code);
+
+        // Factory method to create from PDG code
+        static ParticleInfo from_pdg(int pdg_code, 
+                                   const WireCell::Point& momentum_3vec,
+                                   int id = 0);
+
+        double particle_score() const { return m_particle_score; }
+        void set_particle_score(double score) { m_particle_score = score; }
+
+    private:
+        // Core data members
+        int m_pdg_code;
+        double m_mass;
+        std::string m_name;
+        double m_kinetic_energy;
+        WireCell::D4Vector<double> m_four_momentum;  // (E, px, py, pz)
+        int m_id;
+        double m_charge;
+        double m_particle_score{-1.0}; // Optional score for particle ID confidence
+
+        // Internal helper methods
+        void update_kinematics();     // Recalculate energy/momentum relationships
+        void validate_inputs();       // Check for physical consistency
+
+        // Static data for PDG lookups
+        static const std::map<int, std::string>& get_pdg_name_map();
+        static const std::map<int, double>& get_pdg_mass_map();
+        static const std::map<int, double>& get_pdg_charge_map();
+    };
+
+    // Convenience typedefs
+    using ParticleInfoPtr = std::shared_ptr<ParticleInfo>;
+    using ParticleInfoVector = std::vector<ParticleInfo>;
+    using ParticleInfoSelection = std::vector<ParticleInfo*>;
+
+    // Helper functions for common particle types
+    namespace ParticleHelpers {
+        ParticleInfo electron(const WireCell::Point& momentum, int id = 0);
+        ParticleInfo muon(const WireCell::Point& momentum, int charge_sign = 1, int id = 0);
+        ParticleInfo pion_charged(const WireCell::Point& momentum, int charge_sign = 1, int id = 0);
+        ParticleInfo proton(const WireCell::Point& momentum, int id = 0);
+        ParticleInfo photon(const WireCell::Point& momentum, int id = 0);
+    }
+
+} // namespace WireCell::Aux
+
+#endif // WIRECELLAUX_PARTICLEINFO