Add janadot plugin with plugin-based and group-based graph splitting for enhanced call graph visualization

[Copilot]

This PR implements the janadot plugin in EICrecon with intelligent graph splitting functionality for practical visualization of complex reconstruction call graphs.

Problem

The original JANA2 janadot plugin creates DOT format visualizations of algorithm call graphs, but for complex reconstructions with many algorithms, these graphs become too large and complex for effective analysis. Additionally, there's an issue in JANA2 where plugin names are not copied correctly to the processing factory set, resulting in empty plugin names when event->GetFactorySet()->GetAllFactories() is called.

Solution

The new janadot plugin provides comprehensive graph visualization with two primary splitting strategies:

Core DOT File Generation

• Records JANA2 call stack information during event processing
• Tracks timing data for each factory and call relationship
• Generates proper DOT format files compatible with graphviz
• Uses different node shapes and colors for different component types (Processors, Factories, Sources)

Enhanced Graph Splitting Options

Plugin-based splitting (default): Intelligently groups components by detector subsystem using actual factory plugin information

eicrecon -Pplugins=janadot sim_file.root

Generates:

• jana.tracking.dot - All tracking-related components
• jana.ecal_barrel.dot - ECAL barrel subsystem components
• jana.hcal_endcap.dot - HCAL endcap subsystem components
• jana.dot - Overall inter-plugin connection summary

Group-based splitting: Uses command-line group definitions to manually organize factories

eicrecon -Pplugins=janadot -Pjanadot:split_criteria=groups -Pjanadot:group:Tracking="Factory1:Tag1,Factory2:Tag2" sim_file.root

Generates:

• jana.Tracking.dot - Components in the Tracking group
• jana.Ecal.dot - Components in the Ecal group
• jana.dot - Overall inter-group connection summary

This addresses the JANA2 plugin name issue by allowing manual factory grouping through command-line parameters.

Command-Line Group Definition Support

Groups are defined through command-line parameters:

• Command line: -Pjanadot:group:MyGroup="Factory1:Tag1,Factory2:Tag2,color_blue"
• CI integration: Groups loaded via $(<.github/janadot.groups) for comprehensive detector subsystem definitions
• Each factory is assigned to exactly one group to ensure clean separation

Intelligent Plugin Detection

Automatically recognizes EIC-specific detector patterns using actual JFactory::GetPluginName() information with fallback heuristics for:

• ECAL subsystems: barrel, endcap, insert, lumispec
• HCAL subsystems: barrel, endcap, insert
• Tracking subsystems: CKF, seeding, vertex finding
• Other detectors: RICH, DIRC, TOF, GEM, silicon trackers
• Support systems: truth matching, PID, jets, far detectors

Enhanced Node Labeling

Node labels use "factory name (primary output type)" format, providing clearer identification of components where the factory tag represents the factory name and the factory name represents the primary output type.

Inter-Plugin/Inter-Group Visualization

The overall summary graph (jana.dot) provides a high-level architectural view:

• Shows data flow between detector subsystems or user-defined groups
• Aggregates timing statistics per plugin/group
• Hides internal component complexity
• Uses visual styling that scales penwidth linearly from 1-8 based on timing percentages
• Generated for both splitting methods to provide consistent overview capabilities

Configuration Parameters

• janadot:split_criteria (default: "plugin") - Splitting method: plugin, groups
• janadot:enable_splitting (default: true) - Enable/disable splitting
• janadot:output_file (default: "jana.dot") - Output filename
• janadot:group:GroupName - Define custom groups via command line

CI Integration

Updated workflow automatically:

• Uses group-based splitting with predefined detector subsystem groups
• Generates both DOT source files and SVG images with matrix test name prefixes
• Uploads complete artifact collections for analysis
• Handles all jana.*.dot files consistently

Usage Examples

# Default plugin-based splitting for system architecture analysis
eicrecon -Pplugins=janadot sim_file.edm4hep.root

# Group-based splitting with predefined groups (CI workflow)
eicrecon -Pplugins=janadot -Pjanadot:split_criteria=groups $(<.github/janadot.groups) sim_file.edm4hep.root

# Custom group-based splitting
eicrecon -Pplugins=janadot -Pjanadot:split_criteria=groups \
   -Pjanadot:group:Tracking="CentralCKFTracks,CentralCKFTrackParameters" \
   sim_file.edm4hep.root

Technical Implementation

• Thread-safe with mutex protection for multi-threaded processing
• Follows existing EICrecon plugin patterns (based on janatop structure)
• Comprehensive error handling and user feedback
• Switch/case structure for clean splitting method handling
• Overloaded WriteOverallDotFile methods for both splitting types
• Factory-to-plugin mapping using actual JFactory metadata with heuristic fallback
• Command-line group definitions as workaround for JANA2 plugin name issue
• No additional dependencies beyond existing JANA2 requirements

Files Added/Modified

• src/utilities/janadot/ - Complete plugin implementation with enhanced splitting and factory-based plugin detection
• .github/janadot.groups - Comprehensive group definitions for detector subsystems (CI use)
• Updated CI workflow for artifact generation with proper file naming and group-based splitting
• Enhanced documentation with comprehensive splitting options and examples

This enhancement makes call graph visualization practical for full reconstruction chains while providing both detailed component analysis and high-level architectural insights through consistent overall summary generation and accurate factory metadata usage. The command-line group support provides a robust workaround for the JANA2 plugin name issue.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[wdconinc]

@copilot The multiple output graphs should be in separate files, one per plugin, named as the default file with a period-separated plugin name. The output should also create an overall dot file using the current naming scheme that shows the connections between the plugins, without details about the connections inside the plugin (since that is included in the separate files).

[wdconinc]

@copilot Modify the current checks to use this modified janadot plugin and upload a collection of dot as artifact, as well as a collection of graph images.

[Copilot]

@copilot The multiple output graphs should be in separate files, one per plugin, named as the default file with a period-separated plugin name. The output should also create an overall dot file using ...

I've implemented the requested changes for plugin-based graph splitting with period-separated naming.

Key changes (commit da54165):

• Added split_criteria=plugin option to janadot
• Plugin files now use period-separated naming: jana.tracking.dot, jana.ecal_barrel.dot, etc.
• Overall summary graph in jana.dot shows inter-plugin connections without internal details
• Intelligent plugin detection based on component naming patterns (ECAL, HCAL, tracking, etc.)

Usage:

eicrecon -Pplugins=janadot -Pjanadot:split_criteria=plugin sim_file.root

This generates multiple plugin-specific dot files plus an overall summary showing the high-level data flow between subsystems.

@copilot Modify the current checks to use this modified janadot plugin and upload a collection of dot as artifact, as well as a collection of graph images.

I've updated the CI workflow to use the new janadot plugin functionality and properly upload graph artifacts.

CI changes (commit da54165):

• Added -Pjanadot:split_criteria=plugin to all janadot usage in the workflow
• Updated graph conversion steps to handle multiple dot files (both main and plugin-specific)
• All dot files are converted to SVG format
• Complete collection of dot and SVG files are uploaded as artifacts

The CI will now generate and upload:

• Individual plugin graphs (e.g., jana.tracking.dot, jana.ecal_barrel.dot)
• Overall inter-plugin summary graph (jana.dot)
• Corresponding SVG image files for all graphs

[wdconinc]

@copilot Running failed in https://github.com/eic/EICrecon/actions/runs/17176447352/job/48733065485?pr=2040 due to incorrect parameter. Verify that the correct plugin is loaded, i.e. our plugin and not the JANA2 plugin. Verify that the specified plugin parameters are the correct ones. Test running with similar parameters before committing changes.

[Copilot]

@copilot Running failed in https://github.com/eic/EICrecon/actions/runs/17176447352/job/48733065485?pr=2040 due to incorrect parameter. Verify that the correct plugin is loaded, i.e. our plugin and no...

Fixed the parameter conflict issue (commit d5a815f). The problem was a naming collision between JANA2's built-in janadot plugin and our custom EICrecon janadot plugin.

JANA2's strict parameter checking (jana:parameter_strictness=2) was rejecting our janadot:split_criteria=plugin parameter because the built-in plugin expected different parameters like JANADOT:GROUP:.

Solution: Renamed our plugin to eicjanadot to avoid conflicts:

• Plugin name: janadot → eicjanadot
• Parameters: janadot:* → eicjanadot:*
• CI usage: -Pplugins=eicjanadot -Peicjanadot:split_criteria=plugin

This ensures our enhanced plugin with plugin-based splitting loads independently of the JANA2 built-in plugin.