-
Notifications
You must be signed in to change notification settings - Fork 14
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
Showing
2 changed files
with
113 additions
and
64 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,101 @@ | ||
| # How to Contribute to ATTPCROOT | ||
|
|
||
| > [!NOTE] | ||
| > These guidelines should be applicable to most contributions. At the same time, these are not 'one-size-fits-all' rules, | ||
| > and there might be cases where diverging from these guidelines is warranted. If you want to do something that doesn't fit in these guidelines, just ask! | ||
| ## Bug reports, questions, feature requests, etc. | ||
| Create a [new issue](https://github.com/ATTPC/ATTPCROOTv2/issues/new/choose) on our GitHub. | ||
|
|
||
|
|
||
| ## Your Code Contribution | ||
|
|
||
| The source code for ATTPCROOT is kept in [GitHub](https://github.com/ATTPC/ATTPCROOTv2). | ||
| Changes go through pull requests ("PRs"). | ||
| The primary branch for development is `develop`. | ||
|
|
||
| > [!IMPORTANT] | ||
| > We require PRs to cleanly apply to develop without a merge commit, i.e. through "fast-forward". | ||
| > Please follow the [coding conventions](https://github.com/ATTPC/ATTPCROOTv2/wiki/Coding-conventions), as this is a simple item for | ||
| > reviewers to otherwise get stuck on. | ||
| > To make your (and our own) life easier, we provide a | ||
| > [`clang-format` configuration file](https://github.com/ATTPC/ATTPCROOTv2/blob/develop/.clang-format). | ||
|
|
||
| ## Your Commit | ||
|
|
||
| Each commit is a self-contained, _atomic_ change. This means that: | ||
| 1. **Each commit should be able to successfully build ATTPCROOT.** | ||
| Doing so makes traveling through the git history, for example during a `git bisect` much easier. | ||
| 2. **Each commit does not contain more than one independent change.** | ||
| We define "one change" to mean a single shift in behavior or added feature. That could be many lines of code or entirely new classes. Once again, this makes review much easier as we can revert individual changes that cannot be merged yet (for whatever reason) more easily. If many changes are made in a single commit it gets messy to tease things out if something is broken. | ||
|
|
||
| > [!TIP] | ||
| > During a code review, it may be useful to make smaller commits to track intermediate changes, and rebase after the PR | ||
| > is approved to ensure the above points are met and to reduce clutter. | ||
| ### Your Commit Message | ||
|
|
||
| The commit summary should not exceed 72 characters, be meaningful (i.e., it | ||
| describes the change) and should be written in the | ||
| [present imperative mood](https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD#n239) | ||
| (e.g. `Add this awesome feature` instead of `Adds this awesome feature` or `Added this awesome feature`). | ||
|
|
||
| The commit message that follow the summary can be used to provide more context to the change. | ||
| It should describe the **why**, rather than the **what** and **how** (we can gather this from the commit summary and the | ||
| change diff, respectively). | ||
| The commit message should be wrapped at 72 characters. | ||
|
|
||
|
|
||
| ## Your Pull Request | ||
|
|
||
| > [!NOTE] | ||
| > For the mechanics on how to create pull requests, please visit | ||
| > [this page](https://root.cern/for_developers/creating_pr). | ||
| The title of your PR follows the same principle as the commit summary. If your PR only involves one commit, you can | ||
| reuse this summary. | ||
|
|
||
| The PR description describes (and in case of multiple commits, summarizes) the change in more detail. | ||
| Again, try to describe the **why** (and in this case, to a lesser extent the **what**), rather than the **how**. | ||
|
|
||
| If your PR is related to an open [issue](https://github.com/ATTPC/ATTPCROOTv2/issues), make sure to link it. | ||
| This will be done automatically if you add | ||
| [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) | ||
| to the PR description. | ||
|
|
||
| Once a PR is created, one of the maintainers will review it (hopefully quickly). Please ping people :wave: should you not get timely feedback, for instance with `@ATTPC/attpcroot-managers ping!` | ||
|
|
||
| ## Tests | ||
|
|
||
| As you contribute code, this code will likely fix an issue or add a feature. | ||
| Whatever it is: this requires you to add a new test, or to extend an existing test. Depending on the size and complexity | ||
| of this test, it exists either in the `test/` subdirectory of each part of ATTPCROOT (see for instance | ||
| [`AtData/test`](https://github.com/ATTPC/ATTPCROOTv2/tree/develop/AtData/test)), or in | ||
| [`macro/tests`](https://github.com/ATTPC/ATTPCROOTv2/tree/develop/macro/tests). | ||
| We are just expanding out our coverage of tests, so you may need to add the `test/` subdirectory to whatever part of the code you are working in. | ||
|
|
||
| Tests in `test/` subdirectories are unit tests, mostly based on | ||
| [Google Test](https://github.com/google/googletest) and easily extended. These unit tests should define the expected behavior of your code. They should not depend on any external resource (access to a file on the HD or network, etc.) Unit tests are only helpful if they are *fast*. | ||
|
|
||
| Tests in | ||
| [macro/tests](https://github.com/ATTPC/ATTPCROOTv2/tree/develop/macro/tests) are more involved (e.g., tests with | ||
| data files) and are run as interpreted macros rather than compiled unit tests. | ||
|
|
||
| ## Continuous Integration | ||
|
|
||
| To prevent bad surprises and make a better first impression, we | ||
| strongly encourage new developers to [run the tests](https://github.com/ATTPC/ATTPCROOTv2/wiki/Running-tests) | ||
| _before_ submitting a pull request. | ||
|
|
||
| We have some automated (and not automated :cry:) CI tests that are used for pull requests: | ||
| - *Formatting check*: `clang-format` automatically checks that a PR | ||
| [follows](https://github.com/ATTPC/ATTPCROOTv2/blob/develop/.clang-format) ATTPCROOT's | ||
| [coding conventions](https://github.com/ATTPC/ATTPCROOTv2/wiki/Coding-conventions). | ||
| If coding violations are found, it provides you with a `patch` output that you likely want to apply to your PR. | ||
| - *Simple Static Analysis*: PRs are analyzed using [`clang-tidy`](https://clang.llvm.org/extra/clang-tidy/) and [`iwyu`](https://include-what-you-use.org/). | ||
| - *Build and test*: Ensures all unit tests pass and the code builds. | ||
|
|
||
| Typically, PRs must pass all these tests; we will ask you to fix any issues that may arise. | ||
| Some tests are run only outside the PR testing system: | ||
| we might come back to you with additional reports after your contribution was merged. |
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 |
|---|---|---|
| @@ -1,74 +1,22 @@ | ||
| [](https://zenodo.org/doi/10.5281/zenodo.10027878) | ||
| # About | ||
|
|
||
| ATTPCROOT is a ROOT-based (root.cern.ch) framework to analyze data of active target detectors including the ATTPC (Active Target Time Projection Chamber) detector and the p-ATTPC (Prototype). For reference http://ribf.riken.jp/ARIS2014/slide/files/Jun2/Par2B06Bazin-final.pdf. The detector is based at the NSCL but experiments are performed at other facilities as well (Notre Dame, TRIUMF, Argonne...). | ||
| ATTPCROOT is a ROOT-based (root.cern.ch) framework to analyze data of active target detectors including the ATTPC (Active Target Time Projection Chamber) detector and the p-ATTPC (Prototype). For reference http://ribf.riken.jp/ARIS2014/slide/files/Jun2/Par2B06Bazin-final.pdf. The detector is based at the FRIB but experiments are performed at other facilities as well (Notre Dame, TRIUMF, Argonne...). | ||
|
|
||
| The framework allows the end user to unpack and analyze the data, as well as perform realistic simulations based on a Virtual Monte Carlo (VMC) package. The framework needs external libraries (FairSoft and FairRoot https://fairroot.gsi.de/) to be compiled and executed, which are developed by other groups and not directly supported by the AT-TPC group. Please refer to their forums for installation issues of these packages. | ||
|
|
||
| # Installation and Use | ||
|
|
||
| For installation directions see the wiki: https://github.com/ATTPC/ATTPCROOTv2/wiki/Installation | ||
|
|
||
| For documentation on the use of the code see the wiki: https://github.com/ATTPC/ATTPCROOTv2/wiki/Accessing-documentation | ||
|
|
||
| # Old documentation to be ported to wiki and updated | ||
|
|
||
| ## Running Analysis | ||
|
|
||
| When running analysis in a macro, an instance of FairRunAna is created and tasks added to it. Each task will take in an event, process it, and then pass the event to the next task. Each task can save the intermediary step if desired by setting the boolean flag kIsPersistant. | ||
|
|
||
| ### Unpacking Tasks | ||
| These tasks are responsible for taking raw data in and saving it in an ATRawEvent class. | ||
|
|
||
| ### Pulse Shape Analysis | ||
| These tasks are responsible for taking an ATRawEvent and saving it as an ATEvent. That is, it takes the waveforms from the pads and process it into an array of ATHits which are the location of charge deposition in the TPC in space. | ||
|
|
||
| All the different PSA methods are handled by the same task, ATPSAtask. This task can also handle gain and jitter calibration through the class ATCalibration. When constructing the task, a pointer must be passed to a class that derives from the virtual class ATPSA. This derived class handles the logic of the task and the managment of whatever parameters are necessary. Below contains documentation on the various implemented PSA methods, including discriptions of their parameters. | ||
|
|
||
|
|
||
| # Notes on design | ||
| ATTPCROOT is task based and there are two main input streams of data. One is from simulations, the other experimental data. The two streams come together at the level of waveforms on the pads, either simulated or real. From then on the analysis is identiacal. | ||
| # Contributing | ||
| For the most part, we try to follow ROOT's guidelines. | ||
| * [How to contribute](https://github.com/ATTPC/ATTPCROOT/blob/develop/CONTRIBUTING.md) | ||
| * [Coding conventions](https://github.com/ATTPC/ATTPCROOTv2/wiki/Coding-conventions) | ||
|
|
||
| ## Simulation Tasks | ||
|
|
||
| ### FairRunSim | ||
| Physics (Primary Generators/physics lists) -> MC Tracks | ||
|
|
||
| ### FairRunAna | ||
|
|
||
| #### ATClusterize task | ||
| MC Tracks -> e- locations along track (TClonesArray of ATSimulationPoints) | ||
|
|
||
| #### ATPulseTask | ||
| e- locations along track (TClonesArray of ATSimulationPoints) -> waveform on pads (TClonesArray of ATRawEvent) | ||
|
|
||
| ## Data Tasks | ||
|
|
||
| ### FairRunAna | ||
|
|
||
| #### HDFParserTask | ||
| HDF5 file -> waveform on pads (TClonesArray of ATRawEvent) | ||
| Output is named: "ATRawEvent" | ||
| ## Analysis Tasks | ||
|
|
||
| ### FairRunAna | ||
|
|
||
| #### ATPSATask | ||
| There are many diffrent options for this task depending on how you want to treat the wavefrom (the standard ATTPC version is ATPSASimple2), but in general: | ||
|
|
||
| Waveform on pads (TClonesArray of ATRawEvent) -> record of hits, 3D position and charge in tpc, (ATHit) on pad (TClonesArray of ATEvent) | ||
| Output is named: "ATEventH" | ||
| # Cite | ||
| [](https://zenodo.org/doi/10.5281/zenodo.10027878) | ||
|
|
||
| This task uses the parameters in the ATTPC .par files. In particular this loads (bolded are used by PSASimple): | ||
| * **NumTbs (Number of time buckets)** | ||
| * **TBTTime (Sampling rate in ns)** | ||
| * **DriftVelocity (cm/us)** | ||
| * BField | ||
| * EField | ||
| * EntTB (position in time buckets for detector entrance) | ||
| When citing ATTPCROOT use the DOI specific to the version of ATTPCROOT you are using, [availible on Zenodo](https://zenodo.org/records/10113377). | ||
|
|
||
| # Installation and Use | ||
|
|
||
| #### ATPRATask | ||
| Has options for RANSAC, Hierarchical Clustering, and Houghs algorithms for track finding. | ||
| For installation directions see the wiki: https://github.com/ATTPC/ATTPCROOTv2/wiki/Installation | ||
|
|
||
| record of hits (TClonesArray of AtEvent) -> record of reconstructed tracks (ATTrack) (TClonesArray of ATPatternEvent) | ||
| For documentation on the use of the code see the wiki: https://github.com/ATTPC/ATTPCROOTv2/wiki/Accessing-documentation | ||
|
|