Home

This page is generated from docs/index.md. Do not edit it directly; change the repository source and let automation publish the Wiki.

CLAS12 sample tools Wiki

This code prepares simulation samples for the e4ν collaboration using the CLAS12 spectrometer¹ simulation chain. It provides separate workflows for preparing truth-level particles and submitting detector simulation and reconstruction.

The first workflow writes particles before detector simulation, called truth-level particles, to LUND text files. The uniform LUND creator randomly chooses momenta and angles within your configured ranges, producing deliberately unphysical events for detector-acceptance studies. The physical LUND converter copies supported particles from existing event-generator output. Its current input reader uses GENIE production output in the GST format stored in ROOT files; it does not run GENIE. After creation succeeds, it writes a LUND creation log: a JSON file listing the sample settings, files, and event counts.

The second workflow submits those LUND files to Slurm on Jefferson Lab's ifarm. Each task runs GEMC detector simulation², followed by CLAS12 reconstruction with COATJAVA³. After Slurm accepts the jobs, submission writes a Slurm submission log, a JSON file describing the accepted submission. The jobs later produce reconstructed HIPO data, which can be analyzed with CLAS12ROOT.

The diagram summarizes the path from event preparation to reconstructed output. Creation and submission are separate user actions:

flowchart LR
    subgraph CREATION["LUND file creation"]
        U["Uniform acceptance sampling"] ==> L["LUND files"]
        P["Existing physical event-generator truth"] ==> L
    end
    subgraph SUBMISSION["Slurm job submission"]
        L ==> G["GEMC detector simulation"]
        G ==> R["COATJAVA reconstruction"]
        R ==> H["Reconstructed HIPO files"]
    end

    classDef creation fill:#DEEBF7,color:#2E75B6,stroke:#2E75B6,stroke-width:2px;
    class CREATION creation;
    classDef submission fill:#E2F0D9,color:#548235,stroke:#548235,stroke-width:2px;
    class SUBMISSION submission;
    classDef stage fill:#e8f1ef,color:#183247,stroke:#0f8492,stroke-width:2px;
    class U,P,L,G,R,H stage;

Loading

Use main for the published application and dev for development. The generated Wiki footer identifies the source checkout commit, its date, and the branch used by source links. Both branches can publish this same Wiki; check that identity before comparing the manual with your checkout. The repository README is a short introduction; this page is the manual entry point.

Reading order

If you want to run the software: follow the getting-started reading path: dependencies, quickstart, run directories and outputs, the selected LUND-creation guide, then simulation submission and output verification. Read the output layout immediately after the quickstart so you know which directory to pass to submission.

If you want to modify or extend the software: follow the developer reading path. It starts with architecture and the source map, explains the scientific and data contracts, then covers contribution, builds, validation, and specific extensions. First read the user guide for the workflow you intend to change.

Use the workflow command examples as a copyable option inventory, not as a substitute for understanding the selected profile and output path.

Scope

The repository currently creates LUND files and submits ifarm simulation jobs. The submission command returns when Slurm accepts the jobs; users must then follow their progress and check the output. It does not calculate acceptance, select events from reconstructed HIPO files (skimming), create analysis NTuples, or perform physics analysis. If these tasks are added later, each needs a separate workflow directory with documented inputs, outputs, and settings.

References

1. V. D. Burkert et al., “The CLAS12 Spectrometer at Jefferson Laboratory,” Nucl. Instrum. Meth. A 959, 163419 (2020). doi:10.1016/j.nima.2020.163419 ↩

2. M. Ungaro et al., “The CLAS12 Geant4 simulation,” Nucl. Instrum. Meth. A 959, 163422 (2020). doi:10.1016/j.nima.2020.163422 ↩

3. V. Ziegler et al., “The CLAS12 software framework and event reconstruction,” Nucl. Instrum. Meth. A 959, 163472 (2020). doi:10.1016/j.nima.2020.163472 ↩