diff --git a/docs/acts_project.md b/docs/acts_project.md index 2753f1cd8da..a5bbd9055e3 100644 --- a/docs/acts_project.md +++ b/docs/acts_project.md @@ -1,11 +1,11 @@ # The ACTS project -The *A Common Tracking Software (Acts)* project is an attempt to preserve and evolve the track reconstruction software of the LHC era towards HL-LHC and beyond. It has been initiated in 2016 starting from the [ATLAS Common Tracking Software](https://gitlab.cern.ch/atlas/athena/-/tree/master/Tracking). Given the changing computing landscape, dedicated care of parallel code execution is taken, and is written in `C++17`. +The *A Common Tracking Software (ACTS)* project is an attempt to preserve and evolve the track reconstruction software of the LHC era towards HL-LHC and beyond. It has been initiated in 2016 starting from the [ATLAS Common Tracking Software](https://gitlab.cern.ch/atlas/athena/-/tree/master/Tracking). Given the changing computing landscape, dedicated care of parallel code execution is taken, and is written in `C++17`. A [coherent write-up of the project](https://link.springer.com/article/10.1007/s41781-021-00078-8) has been published in 2022 in Springer's CSBS. ```{note} -Acts is designed as a library that *contains components* for assembling a track reconstruction suite for High Energy Physics and Nuclear Physics. Acts does not strive to provide a complete experiment framework, but rather modules and connections to be used within an experiment context. These connections contain e.g. binding mechanisms to different geometry libraries, a cost-free yet flexible mechanism to use experiment specific contextual data (calibrations, detector alignment, experiment conditions), or simply the possibility to integrate an external screen logging facility. +ACTS is designed as a library that *contains components* for assembling a track reconstruction suite for High Energy Physics and Nuclear Physics. ACTS does not strive to provide a complete experiment framework, but rather modules and connections to be used within an experiment context. These connections contain e.g. binding mechanisms to different geometry libraries, a cost-free yet flexible mechanism to use experiment specific contextual data (calibrations, detector alignment, experiment conditions), or simply the possibility to integrate an external screen logging facility. ``` The library is structured as follows: @@ -17,20 +17,20 @@ The library is structured as follows: ```{tip} -Developers and R&D meetings can be found in the [Acts indico category](https://indico.cern.ch/category/7968/). +Developers and R&D meetings can be found in the [ACTS indico category](https://indico.cern.ch/category/7968/). ``` ## Philosophy - In order to minimize virtual function calls and complex inheritance schemes, Acts does - in general - not define module interfaces, but rather relies on a data-centric pattern. Wherever possible, composition is favoured over inheritance/code extension. + In order to minimize virtual function calls and complex inheritance schemes, ACTS does - in general - not define module interfaces, but rather relies on a data-centric pattern. Wherever possible, composition is favoured over inheritance/code extension. - Code execution performance is a big focus in Acts in order to serve the needs of the HL-LHC experiments; however, this is attempted to be reached mainly by technical means rather than compromising the physics performance. + Code execution performance is a big focus in ACTS in order to serve the needs of the HL-LHC experiments; however, this is attempted to be reached mainly by technical means rather than compromising the physics performance. ## R&D Testbed - Acts should also provide a testbed for fruitful algorithm R&D, and hence is closely coupled to the development of the [Open Data Detector](https://gitlab.cern.ch/acts/OpenDataDetector) which can be built as a `thirdparty` dependency as part of the Acts project, and builds the backbone of the chain demonstrators. +ACTS should also provide a testbed for fruitful algorithm R&D, and hence is closely coupled to the development of the [Open Data Detector](https://gitlab.cern.ch/acts/OpenDataDetector) which can be built as a `thirdparty` dependency as part of the ACTS project, and builds the backbone of the chain demonstrators. In addition, two dedicated R&D lines are part of the `acts-project`, one for machine learning based/inspired modules [acts-machine-learning](mailto:acts-machine-learning@cern.ch), and one for massively parallel code execution [acts-parallelization](mailto:acts-parallelization@cern.ch), which mainly focuses on GPU accelerators and portability. -Code spill-over from the R&D lines into the main Acts repository are performed on demand and depending on the maturity of the R&D projects. +Code spill-over from the R&D lines into the main ACTS repository are performed on demand and depending on the maturity of the R&D projects. diff --git a/docs/authors.rst b/docs/authors.rst index b60483a02d4..0bbf777fb07 100644 --- a/docs/authors.rst +++ b/docs/authors.rst @@ -8,7 +8,7 @@ Detailed contributor information can also be found on the projects `Github contr Contributors to the ATLAS tracking software ------------------------------------------- -The Acts project was initially based on the ATLAS tracking software. +The ACTS project was initially based on the ATLAS tracking software. The development team is grateful for the work done by the following people on the ATLAS tracking software. Alejandro Alonso Diaz, Adam Edward Barton, Andy Buckley, Anthony Morley, Aaron James Armbruster, Olivier Arnaez, John Baines, Sebastien Binet, Bruno Lenzi, Veronique Boisvert, Guennadi Borissov, Eva Bouhova-Thacker, Antonio Boveia, Christian Gumpert, Christian Schmitt, Camilla Maiani, Andrea Coccaro, Christian Ohm, Christoph Rauchegger, Christoph Wasicki, Daniel Ryan Blackburn, Dave Casper, David Divalentino, Dmitry Emeliyanov, Daniel Hay Guest, Daniel Kollar, David Lopez Mateos, Daniel Mori, David Quarrie, David Rousseau, David Richard Shope, Till Eifert, Esben Lund, Edward Moyse, Frederic Brochu, Sebastian Fleischmann, Fred Luehring, Felix Socher, Igor Gavrilenko, Gerhard Immanue Brandt, Graham John Cree, Peter Van Gemmeren, Giacinto Piacquadio, Goetz Gaycken, Steven Goldfarb, Grant Gorfine, Carl Bryan Gwilliam, Heberth Jesus Torres Davila, Loek Hooft Van Huysduynen, Haichen Wang, Ioannis Nomidis, Ilija Vukotic, Jahred Adelman, Javier Jimenez Pena, Johanna Bronner, James Catmore, John Derek Chapman, Jason Lee, Jeremy Robert Love, John Alison, Jochen Meyer, Juergen Thomas, Jochem Snuverink, Jeffrey Tseng, Jike Wang, Konstantinos Karakostas, Kathryn Grimm, Peter Kluit, Thomas Koffas, Nikolaos Konstantinidis, Attila Krasznahorkay, Vicente Lacuesta Miquel, Remi Lafaye, Antonio Limosani, Markus Elsing, Salvador Marti I Garcia, Jiri Masik, Massimiliano Bellomo, Matthias Danninger, Miriam Deborah Diamond, Joerg Mechnich, Maria Jose Costa Mezquita, Maaike Limper, Manuel Neumann, Marcin Nowak, Matthew Scott Rudolph, Maximiliano Sioli, Michael Ughetto, Noemi Calace, Nectarios Benekos, Niels Van Eldik, Nir Amram, Nathan Rogers Bernard, Nicholas Styles, Konstantinos Ntekas, Emil Obreshkov, Susumu Oda, Gustavo Ordonez Sanz, Ourania Sidiropoulou, Petr Balek, Pawel Bruckman De Renstrom, Pierfrancesco Butti, Troels Petersen, Kirill Prokofiev, Alan Poppleton, Rachel Reisner Hinman, Elmar Ritsch, Roland Jansky, Markus Jungst, Robert Johannes Langenberg, Robert Harrington, Ruslan Mashinistov, Andreas Salzburger, Sebastian Boeser, R D Schaffer, Shih-Chieh Hsu, Sabine Elles, Rolf Seuster, Silvia Miglioranzi, Stewart Martin-Haugh, Song-Ming Wang, Simone Pagan Griso, Shaun Roe, Savanna Marie Shaw, Scott Snyder, Stefania Spagnolo, Thijs Cornelissen, Tommaso Lari, Tatjana Lenz, Sarka Todorova, Vakhtang Tsulaia, Vato Kartvelishvili, Veerle Heijne, Vadim Kostyukhin, Weimin Song, Andreas Wildauer, Walter Lampl, William Axel Leight, Wolfgang Liebig, Wolfgang Lukas, Marcin Wolter diff --git a/docs/codeguide.md b/docs/codeguide.md index 5afdd1aba02..c9c310b459d 100644 --- a/docs/codeguide.md +++ b/docs/codeguide.md @@ -6,7 +6,7 @@ All guidelines have a short identifier label, e.g. N.1, for easier reference in For cases and constructs not explicitly mentioned here, code should fall back to the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). -## Acts-specific +## ACTS-specific ### A.indices: Always use enum values to access vector/matrix components diff --git a/docs/contribution/documentation_cheatsheet.md b/docs/contribution/documentation_cheatsheet.md index 7e95c026837..f7826741664 100644 --- a/docs/contribution/documentation_cheatsheet.md +++ b/docs/contribution/documentation_cheatsheet.md @@ -65,12 +65,12 @@ members: center ::: (cheatsheetlabels)= -## Cross referencing and labels +## Cross-referencing and labels * Setting a label (should be in front of a heading or something like that): ```text -## Cross referencing and labels +## Cross-referencing and labels (cheatsheetlabels)= ``` diff --git a/docs/contribution/physmon.md b/docs/contribution/physmon.md index 2b5b9f21741..fa62ad9ccc0 100644 --- a/docs/contribution/physmon.md +++ b/docs/contribution/physmon.md @@ -4,7 +4,7 @@ The ACTS CI runs a suite of physics performance monitoring jobs dubbed *physmon*. The purpose is to monitor and detect changes in the physics performance, both intentional and accidental. -The associated job will run a number of workflow combinations. Currently this +The associated job will run a number of workflow combinations. Currently, this includes the truth tracking and OpenDataDetector *full chain* workflows. The latter is further split into configurations with full seeding, truth smeared or truth estimated seeds. These jobs produce performance output files. diff --git a/docs/contribution/profiling.md b/docs/contribution/profiling.md index 9e7c442d37f..aa29d6e0fa5 100644 --- a/docs/contribution/profiling.md +++ b/docs/contribution/profiling.md @@ -53,7 +53,7 @@ $ go install github.com/google/pprof@latest ## Link gperftools Libraries When Compiling -The library needed to run the CPU profilier should be linked into the ACTS project using the following build option: +The library needed to run the CPU profiler should be linked into the ACTS project using the following build option: ``` -DACTS_ENABLE_CPU_PROFILING=ON @@ -67,7 +67,7 @@ Similarly, to enable the memory profiler the following build option should be us ## Alternative to Recompiling -Alternatively, you can avoid rebuiding the project by pointing the `LD_PRELOAD` environment variable to the profiler library for CPU profiling: +Alternatively, you can avoid rebuilding the project by pointing the `LD_PRELOAD` environment variable to the profiler library for CPU profiling: ``` LD_PRELOAD="" diff --git a/docs/core/core.rst b/docs/core/core.rst index 089a9657972..7c0ed49db85 100644 --- a/docs/core/core.rst +++ b/docs/core/core.rst @@ -1,7 +1,7 @@ Core library ============ -The Acts core functionality is grouped into modules, where each module contains +The ACTS core functionality is grouped into modules, where each module contains tools related to one particular subject, i.e. experiment geometry or vertexing. .. toctree:: diff --git a/docs/core/geometry/geometry_id.md b/docs/core/geometry/geometry_id.md index 2d7bf03d8d7..3d75686bec9 100644 --- a/docs/core/geometry/geometry_id.md +++ b/docs/core/geometry/geometry_id.md @@ -7,7 +7,7 @@ building, e.g. for the uploading/assigning of material to the surface after creation. The {class}`Acts::GeometryIdentifier` uses a simple masking procedure for applying an identification schema. -While it is used in Acts-internal applications such as material mapping, it is not employed for +While it is used in ACTS-internal applications such as material mapping, it is not employed for `EventData` and `Geometry` identification in an experiment setup. Instead, one should define and use the `Identifier` class in the latter case. diff --git a/docs/core/geometry/layerless/layerless.md b/docs/core/geometry/layerless/layerless.md index 68f243a0eeb..50ea307ce83 100644 --- a/docs/core/geometry/layerless/layerless.md +++ b/docs/core/geometry/layerless/layerless.md @@ -37,7 +37,7 @@ While objects may be stored as `std::shared_ptr` internally, their access dur ### Navigation state and delegates -A struct {struct}`Acts::Experimental::NavigationState` holds the current navigation information through the geometry, which comprises of +A struct {struct}`Acts::Experimental::NavigationState` holds the current navigation information through the geometry, which comprises - the current {class}`Acts::Experimental::DetectorVolume` in associated with the position within the detector, called `currentVolume` - a list of portal candidates to leave the `currentVolume` @@ -70,7 +70,7 @@ Illustration of a shared direct portal between two volumes, the arrows indicate Illustration of a shared extended portal between several volumes, the arrows indicate the direction of attachment. ::: -The implementation of a unique, binned or any other volume link can be adapted to the detector geometry by providing a suitablen `Acts::Experimental::DetectorVolumeUpdator` delegate. +The implementation of a unique, binned or any other volume link can be adapted to the detector geometry by providing a suitable `Acts::Experimental::DetectorVolumeUpdator` delegate. ### The Detector volume object @@ -95,7 +95,7 @@ In case the volume contains surfaces and/or volumes, an adequate navigation stat :::{figure} ../figures/EndcapGrid.png :width: 600px :align: center -Illustration of a planar module andcap detector with a grid holding the indices to the candidate surfaces. +Illustration of a planar module endcap detector with a grid holding the indices to the candidate surfaces. ::: :::{note} @@ -108,7 +108,7 @@ The detector object is the holder class of all geometry objects, it has to conta - at least one detector volume - a name string -- a volume finder delegate (as `Acts::Experimental::DetecorVolumeFinder`) that allows to uniquely associate a point in space with a contained volume of the detector. +- a volume finder delegate (as `Acts::Experimental::DetectorVolumeFinder`) that allows to uniquely associate a point in space with a contained volume of the detector. :::{note} When the detector is constructed, name duplicates are checked for and if found a `std::exception` is thrown. Similarly, when sensitive surfaces are provided and duplicate `Acts::GeometryIdentifier` objects are found during detector construction a `std::exception` is thrown. The latter can be avoided by using an appropriate (set of) `Acts::GeometyIdGenerator` tool(s) which will guarantee some level of uniqueness. diff --git a/docs/core/geometry/legacy/building.md b/docs/core/geometry/legacy/building.md index 2eef564a0ee..5d24bd61626 100644 --- a/docs/core/geometry/legacy/building.md +++ b/docs/core/geometry/legacy/building.md @@ -35,9 +35,9 @@ binding for the ATLAS experiment. ```{note} While `DD4hep` offers a descriptive language with a dedicated extension mechanism -that can be used by Acts to interpret the underlying geometry hierarchy and and structure, +that can be used by ACTS to interpret the underlying geometry hierarchy and and structure, there is no such guarantee when having the already as built `TGeo` geometry in hand. -Therefore a dedicated Acts configuration file based on `json` can be provided that allows +Therefore a dedicated ACTS configuration file based on `json` can be provided that allows to specify parsing restrictions for sub detectors. ``` diff --git a/docs/core/geometry/surfaces.md b/docs/core/geometry/surfaces.md index 3908300a097..55a0d41039c 100644 --- a/docs/core/geometry/surfaces.md +++ b/docs/core/geometry/surfaces.md @@ -17,14 +17,14 @@ Each {class}`Acts::Surface` instance reports its type from {func}`Acts::Surface: ::: -| Surface Type | Local Coordinates | Bound Types available | -|:----------------------|-------------------|:--------------------------------------------------------------------------------------------| -| {class}`Acts::ConeSurface` | $[r\phi, z]$ | {class}`Acts::ConeBounds` | -| {class}`Acts::CylinderSurface` | $[r, \phi]$ | {class}`Acts::CylinderBounds` | -| {class}`Acts::DiscSurface` | $[r, \phi]$ | {class}`Acts::RadialBounds`, {class}`Acts::DiscTrapezoidBounds` | -| {class}`Acts::PlaneSurface` | $[x, y]$ | {class}`Acts::RectangleBounds`, {class}`Acts::TrapezoidBounds`,
{class}`Acts::InfiniteBounds`, {class}`Acts::EllipseBounds` | -| {class}`Acts::PerigeeSurface`,
{class}`Acts::StrawSurface` | $[d, z]$ | {class}`Acts::CylinderBounds` | -| {class}`Acts::LineSurface` | $[d_0, z_0]$ | {class}`Acts::LineBounds` | +| Surface Type | Local Coordinates | Bound Types available | +|:---------------------------------------------------------------|-------------------|:--------------------------------------------------------------------------------------------------------------------------------| +| {class}`Acts::ConeSurface` | $[r\phi, z]$ | {class}`Acts::ConeBounds` | +| {class}`Acts::CylinderSurface` | $[r, \phi]$ | {class}`Acts::CylinderBounds` | +| {class}`Acts::DiscSurface` | $[r, \phi]$ | {class}`Acts::RadialBounds`, {class}`Acts::DiscTrapezoidBounds` | +| {class}`Acts::PlaneSurface` | $[x, y]$ | {class}`Acts::RectangleBounds`, {class}`Acts::TrapezoidBounds`,
{class}`Acts::InfiniteBounds`, {class}`Acts::EllipseBounds` | +| {class}`Acts::PerigeeSurface`,
{class}`Acts::StrawSurface` | $[d, z]$ | {class}`Acts::CylinderBounds` | +| {class}`Acts::LineSurface` | $[d_0, z_0]$ | {class}`Acts::LineBounds` | ```{tip} In an ideal setup, the coordinate systems also define the readout diff --git a/docs/core/magnetic_field.md b/docs/core/magnetic_field.md index 1dc4e515cba..067144b3d29 100644 --- a/docs/core/magnetic_field.md +++ b/docs/core/magnetic_field.md @@ -100,7 +100,7 @@ which is returned unmodified to every call to For more complex magnetic field implementations {class}`Acts::InterpolatedMagneticField` can be used. The idea here is to calculate an interpolated value of the magnetic field from a grid of known field values. -In 3D, this means the interpolation is done from the 8 cornerpoints of a *field +In 3D, this means the interpolation is done from the 8 corner points of a *field cell*. The field cell can be retrieved for any given position. Since during typical access patterns, e.g. the propagation, subsequent steps are relatively likely to not cross the field cell boundary, the field cell can be cached. diff --git a/docs/core/misc/grid_axis.md b/docs/core/misc/grid_axis.md index 035c20ee4a0..2f8d0988bba 100644 --- a/docs/core/misc/grid_axis.md +++ b/docs/core/misc/grid_axis.md @@ -42,7 +42,8 @@ There are three options: ## Grid creation -The types of the axes have to be known at compile-time, since they are provided to the `Grid` as template parameters. Thus the number of dimensions $N$ of the `Grid` is also fixed at compile-time. +The types of the axes have to be known at compile-time, since they are provided to the `Grid` as template parameters. +Thus, the number of dimensions $N$ of the `Grid` is also fixed at compile-time. The axes can be any combination of the aforementioned variations. ```cpp @@ -71,18 +72,18 @@ The local bin indices are always defined from 1 to $N_\text{bins}$ for the respe The `Grid` can determine the number of neighbors around a given bin. This done by first converting the global bin index to local bin indices, and then varying the local bin indices in each dimension. At this stage, each Axis gets to decide, which indices are considered neighbors, which differs depending on `AxisBinningType`. `Open` considers the underflow and overflow bins, while `Bound` does not. `Closed` considers bins on the other side of the axis. The resulting neighbor combination around bin *B* might look like -b x b | 1 | 2 | 3 | -------|------|------|------| -1 | x | 0,+1 | x | -2 | -1,0 | B | +1,0 | -3 | x | 0,-1 | x | +| b x b | 1 | 2 | 3 | +|-------|-------|------|-------| +| 1 | x | 0,+1 | x | +| 2 | -1, 0 | B | +1, 0 | +| 3 | x | 0,-1 | x | Here, the corner combinations are still missing (also true for $N>2$). This is then turned into a hypercube which in $N=2$ results in: -b x b | 1 | 2 | 3 | -------|-------|------|-------| -1 | -1,+1 | 0,+1 | +1,+1 | -2 | -1,0 | B | +1,0  | -3 | -1,-1 | 0,-1 | +1,-1 | +| b x b | 1 | 2 | 3 | +|-------|-------|------|-------| +| 1 | -1,+1 | 0,+1 | +1,+1 | +| 2 | -1, 0 | B | +1, 0 | +| 3 | -1,-1 | 0,-1 | +1,-1 | These local bin indices are then converted into global bin indices before being returned. diff --git a/docs/core/misc/logging.md b/docs/core/misc/logging.md index 8aa6abbe3c0..019f6487969 100644 --- a/docs/core/misc/logging.md +++ b/docs/core/misc/logging.md @@ -1,6 +1,6 @@ # Logging -The Acts logging facility supports several severity levels which allow you to +The ACTS logging facility supports several severity levels which allow you to control the amount of information displayed at run-time. Logger objects can easily be created using the {func}`Acts::getDefaultLogger` function which should be sufficient to get you started. In case you need more customized debug @@ -53,10 +53,10 @@ Code example illustrating the usage: void myFunction() { // open the logfile std::ofstream logfile("log.txt"); - // setup a logger instance for >= INFO messages, streaming into the log file + // set up a logger instance for >= INFO messages, streaming into the log file std::unique_ptr logger = Acts::getDefaultLogger("MyLogger", Acts::Logging::INFO, &logfile); - // make sure the Acts debug macros can work with your logger + // make sure the ACTS debug macros can work with your logger ACTS_VERBOSE("This message will not appear in the logfile."); ACTS_INFO("But this one will: Hello World!"); // do not forget to close the logfile @@ -66,8 +66,8 @@ void myFunction() { ## Logger integration -In case you are using Acts in another framework which comes with its own -logging facility (e.g. Gaudi) you can pipe the logging output from Acts +In case you are using ACTS in another framework which comes with its own +logging facility (e.g. Gaudi) you can pipe the logging output from ACTS tools and algorithms to your framework's logging system by supplying different implementations of: @@ -106,11 +106,11 @@ Using this mechanism is now **discouraged** for integration with an experiment framework. ::: -Since Acts makes extensive use of {func}`Acts::getDefaultLogger` to provide +Since ACTS makes extensive use of {func}`Acts::getDefaultLogger` to provide sufficient information for debugging, you might want to provide a modified implementation of this function (using your output filter and printing policies) to also pipe this output to your framework. You can use the following -approach using the possibility to inject custom code by pre-loading shared +approach using the possibility to inject custom code by preloading shared libraries with `LD_PRELOAD`. You need to provide an appropriate implementation for a function of the following signature into a separate source file and compile it in a shared library @@ -124,7 +124,7 @@ std::unique_ptr getDefaultLogger(const std::string&, } ``` -Then you can run your executable, which uses Acts tools and algorithms, in +Then you can run your executable, which uses ACTS tools and algorithms, in the following way (tested under Unix) ```console diff --git a/docs/core/propagation.md b/docs/core/propagation.md index 63213ca2f6d..93562aacc13 100644 --- a/docs/core/propagation.md +++ b/docs/core/propagation.md @@ -1,7 +1,7 @@ (propagation_impl)= # Propagation and extrapolation -The track propagation is an essential part of track reconstruction. This section describes the high-level classes and concepts used for this task in Acts. +The track propagation is an essential part of track reconstruction. This section describes the high-level classes and concepts used for this task in ACTS. ## Overview: Steppers, Navigators and Actors @@ -10,7 +10,7 @@ The propagation through a geometry is based on the interaction of two different * The **Stepper** provides the implementation of the solution of the equation of motion (either by analytical means or through numerical integration). * The **Navigator** keeps track of the current position in the geometry and adjusts the step size so that the stepper does not step through a surface. -Following the general Acts design, these classes do not manage their internal state via member variables, but provide an internal `State` struct which contains all relevant data and is managed by the propagator. +Following the general ACTS design, these classes do not manage their internal state via member variables, but provide an internal `State` struct which contains all relevant data and is managed by the propagator. The interaction of these two components is handled by the {class}`Acts::Propagator` class template that takes the stepper and the navigator as template parameters: @@ -83,12 +83,12 @@ Acts comes with two navigators: The standard navigator {class}`Acts::Navigator` The navigators provide information about the current position inside the geometry in their state variable ({struct}`Acts::Navigator::State` and {struct}`Acts::DirectNavigator::State`), e.g. pointers to the `currentSurface` and the `currentVolume`. :::{tip} -The {class}`Acts::Navigator` by default does a straight-line extrapolation to resolve layer candidates. In certain geometries (e.g., telescope) this can lead to the effect that bent tracks miss some layers. This can be mitigated by disabling the bound-check for layer resolval with the `boundaryCheckLayerResolving` option in {struct}`Acts::Navigator::Config`. +The {class}`Acts::Navigator` by default does a straight-line extrapolation to resolve layer candidates. In certain geometries (e.g., telescope) this can lead to the effect that bent tracks miss some layers. This can be mitigated by disabling the bound-check for layer resolution with the `boundaryCheckLayerResolving` option in {struct}`Acts::Navigator::Config`. ::: ## Steppers -Acts also provides a variety of stepper implementations. Since these in general can work very differently internally, the state itself is not the main interface to the steppers. Instead all steppers provide a common API, to that we can pass instances of the stepper state. This allows a generic and template-based design even for very different steppers: +ACTS also provides a variety of stepper implementations. Since these in general can work very differently internally, the state itself is not the main interface to the steppers. Instead, all steppers provide a common API, to that we can pass instances of the stepper state. This allows a generic and template-based design even for very different steppers: ```c++ template diff --git a/docs/core/reconstruction/pattern_recognition/seeding.md b/docs/core/reconstruction/pattern_recognition/seeding.md index 4eab14b03cc..2f3f499a1bf 100644 --- a/docs/core/reconstruction/pattern_recognition/seeding.md +++ b/docs/core/reconstruction/pattern_recognition/seeding.md @@ -15,12 +15,12 @@ tracking. A good seeding algorithm, therefore, has the following properties: * It finds at least one seed for each particle that should be found -* It doesn’t find many seeds which do NOT correspond to particles -* It doesn’t find many seeds per particle +* It doesn't find many seeds which do NOT correspond to particles +* It doesn't find many seeds per particle The most typical way to create seeds is to combine measurements. In a homogeneous magnetic field, 3 measurements perfectly describe the helical path of a charged particle. One such triplet of measurements would then constitute a seed and defines, in close bounds, where the tracking needs to look for additional measurements to create a track spanning the whole detector. The difficulty is in choosing the correct measurements, as a helix can be fitted through any 3 measurements in a collision event with potentially tens of thousands of measurements. Therefore, many constraints or “cuts” are defined to reduce the number of candidates. Cuts may define where particles originate or the range of energy of particles to be found or otherwise restrict the combination of measurements for seed creation. -## Acts Implementation +## ACTS Implementation The seeding implementation in `Core/include/Acts/Seeding/` was written with a focus on parallelism and maintainability and as detector agnostic as possible, only assuming a (near) homogeneous magnetic field with particles originating from the central detector region. Cuts are configurable and can be plugged in as an algorithm which is called by the seeding. The seeding works on measurements or “SpacePoints” (SP), which need to provide $(x,y,z)$ coordinates with the $z$ axis being along the magnetic field, and $x$ and $y$. For the seeding algorithm to function the particle point of origin has to have a radius smaller than the radius of the detector layer closest to the interaction region. In other words, this seeding algorithm is not suitable for secondary particles originating far from the interaction region. diff --git a/docs/core/reconstruction/track_fitting.md b/docs/core/reconstruction/track_fitting.md index 4044f98762c..9520d20297a 100644 --- a/docs/core/reconstruction/track_fitting.md +++ b/docs/core/reconstruction/track_fitting.md @@ -5,7 +5,7 @@ It is part of the pattern recognition/track reconstruction/tracking. We can run the track fitting algorithms, after we allocated all hits to single tracks with the help of a track finding algorithm. It is not necessary, that all points of a track are present. -Currently we have implementations for three different fitters: +Currently, we have implementations for three different fitters: * Kalman Filter * GSF * Global Chi-Square Fitter (GX2F) [wip] @@ -93,7 +93,7 @@ To simplify integration, the GSF returns an {struct}`Acts::KalmanFitterResult` o If the GSF finds the column with the string identifier *"gsf-final-multi-component-state"* (defined in `Acts::GsfConstants::kFinalMultiComponentStateColumn`) in the track container, it adds the final multi-component state to the track as a `std::optional>` object. -A GSF example can be found in the Acts Examples Framework [here](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/truth_tracking_gsf.py). +A GSF example can be found in the ACTS Examples Framework [here](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/truth_tracking_gsf.py). ### Customising the Bethe-Heitler approximation @@ -117,7 +117,7 @@ The {class}`Acts::AtlasBetheHeitlerApprox` is constructed with two parameterizat ## Global Chi-Square Fitter (GX2F) [wip] :::{todo} -Write GX2F documeneation +Write GX2F documentation ::: [^billoir]: https://twiki.cern.ch/twiki/pub/LHCb/ParametrizedKalman/paramKalmanV01.pdf diff --git a/docs/core/visualization/3d.md b/docs/core/visualization/3d.md index 50b302c7f23..81d40a2d1c1 100644 --- a/docs/core/visualization/3d.md +++ b/docs/core/visualization/3d.md @@ -1,7 +1,7 @@ # 3D Visualization -A very lightweight layer for visualizing Acts geometry objects and event data model is provided within the Core component. -Acts does not provide a viewer per se, but instead it was chosen to plug a visitor that can then be used for visualizing the given objects. +A very lightweight layer for visualizing ACTS geometry objects and event data model is provided within the Core component. +ACTS does not provide a viewer per se, but instead it was chosen to plug a visitor that can then be used for visualizing the given objects. The visitor has to implement the `IVisualization3D` interface and can then straight forwardly used with the visualization helper structs. Two visualization helpers that implement industry standard 3D formats can be used from this component, but evidently any other visitor can be plugged in as long as it satisfies the `IVisualization` interface. diff --git a/docs/examples/full_chain_odd.md b/docs/examples/full_chain_odd.md index 9f229abcbd6..75bab1badd2 100644 --- a/docs/examples/full_chain_odd.md +++ b/docs/examples/full_chain_odd.md @@ -1,6 +1,6 @@ # Walkthrough of the OpenDataDetector full chain example -The OpenDataDatector (ODD) is fictitious silicon detector which resides in its own repository on [GitLab](https://gitlab.cern.ch/acts/OpenDataDetector). It is used for testing and as a performance baseline in Acts. +The OpenDataDetector (ODD) is fictitious silicon detector which resides in its own repository on [GitLab](https://gitlab.cern.ch/acts/OpenDataDetector). It is used for testing and as a performance baseline in ACTS. Our full chain ODD example is written in Python and can be found [here](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/full_chain_odd.py). @@ -30,13 +30,14 @@ The simulation step involves random processes and in order to get the same resul rnd = acts.examples.RandomNumbers(seed=42) ``` -All simulation and reconstruction pipelines in Acts begin with a `Sequencer`. It controls the execution of the different algorithms in the chain. We provide the number of events, the number of threads to use (`-1` to use all the machine's cores) and the desired log level. +All simulation and reconstruction pipelines in ACTS begin with a `Sequencer`. It controls the execution of the different algorithms in the chain. We provide the number of events, the number of threads to use (`-1` to use all the machine's cores) and the desired log level. ```python s = acts.examples.Sequencer(events=100, numThreads=-1, logLevel=acts.logging.INFO) ``` -Our first simulation step is the particle gun. It spawns particles and their initial parameters, like position and momentum, inside our detecor. +Our first simulation step is the particle gun. +It spawns particles and their initial parameters, like position and momentum, inside our detector. In our simple example we generate a single muon with random charge (i.e. muon or anti-muon) with 1-10 GeV with uniform pseudorapidity from -3 to 3. @@ -99,7 +100,8 @@ addSeeding( ) ``` -The Combinatorial Kalman Filter (CKF) will use the seeds to propagate the trajectory forward and backward in time with the idea to find more measurements along the way. It combines (i.e. smoothes) these measurements and outputs reconstructed tracks which include smoothed track parameters for each measurement. +The Combinatorial Kalman Filter (CKF) will use the seeds to propagate the trajectory forward and backward in time with the idea to find more measurements along the way. +It combines (i.e. smooths) these measurements and outputs reconstructed tracks which include smoothed track parameters for each measurement. ```python addCKFTracks( diff --git a/docs/examples/howto/add_new_algorithm.md b/docs/examples/howto/add_new_algorithm.md index 33d594ca03e..c97b5c852e1 100644 --- a/docs/examples/howto/add_new_algorithm.md +++ b/docs/examples/howto/add_new_algorithm.md @@ -61,7 +61,7 @@ The `execute` method will be called once for each event. Other methods can also be added to your class. It is good to remember that the algorithmic code in ACTS is typically stateless, and if the state needs to be passed between the calls it should be done explicitly. -An algorithm is stateless if does not modify its own attributes while executing. +An algorithm is stateless if it does not modify its own attributes while executing. This way it becomes reentrant and in consequence thread safe. For instance if the event processing is best organized with such methods: @@ -143,7 +143,7 @@ destruction of this object at the end of event processing is taken care of. It is customary that an algorithm requires configuration parameters. For example, in a seeding algorithm these parameters could include which detector layers should be used. The configuration can be provided to an algorithm through an additional class/structure. -For algorithm it is typically an inner class named `Config`. +For algorithm, it is typically an inner class named `Config`. That is how the configuration object could look like for `MySeedingAlgorithm`: diff --git a/docs/examples/howto/digitization_config.md b/docs/examples/howto/digitization_config.md index bffee0c93f6..6fa05550b98 100644 --- a/docs/examples/howto/digitization_config.md +++ b/docs/examples/howto/digitization_config.md @@ -25,7 +25,7 @@ The following snippet will print a JSON string containing the configuration for two different volumes. The first volume applies gaussian smearing to the first two spatial dimensions and uniform smearing to the time dimension. Correspondingly, the parameter list -for this volume has five entries: two for the simple gaussians and +for this volume has five entries: two for the simple Gaussians and three for the uniform smearer. After this, another volume gets only one spatial dimension smeared by a simple gaussian. diff --git a/docs/examples/howto/material_mapping.rst b/docs/examples/howto/material_mapping.rst index 790f078f644..f9205fcf865 100644 --- a/docs/examples/howto/material_mapping.rst +++ b/docs/examples/howto/material_mapping.rst @@ -125,7 +125,7 @@ The picture ``volumes_and_layers.png`` show you the volumes and all layers const .. image:: figures/materialMapping/volumes_and_layers.png -For each volume containing layers, another picture is produced to show the representative layers (without ``approach`` index) and highlight the ones with ``approach`` index. The picture below show layers for one of the ODD volumes. Knowledge of the approach layers is needed to select the lyers you want the material to be mapped onto. +For each volume containing layers, another picture is produced to show the representative layers (without ``approach`` index) and highlight the ones with ``approach`` index. The picture below show layers for one of the ODD volumes. Knowledge of the approach layers is needed to select the layers you want the material to be mapped onto. .. image:: figures/materialMapping/layers_for_volume_17.png diff --git a/docs/examples/howto/run_ckf_auto_tuning.rst b/docs/examples/howto/run_ckf_auto_tuning.rst index 0e01e11c370..ac0109f1719 100644 --- a/docs/examples/howto/run_ckf_auto_tuning.rst +++ b/docs/examples/howto/run_ckf_auto_tuning.rst @@ -17,7 +17,7 @@ Since Optuna and Orion are independent frameworks, these need to be installed se $ pip install pytest --upgrade $ pip install cmake dataclasses sphinxcontrib-applehelp sphinxcontrib-jsmath sphinxcontrib-serializinghtml argparse sphinxcontrib-devhelp sphinxcontrib-htmlhelp sphinxcontrib-qthelp AppDirs filelock joblib pandas plotly psutil pyYAML requests scipy tabulate cloudpickle scikit-learn orion==0.2.2 cloudpickle==1.6.0 optuna matplotlib -Once all the dependencies are installed, Build Acts with python bindings and Pythia8 support. +Once all the dependencies are installed, Build ACTS with python bindings and Pythia8 support. .. code-block:: console @@ -68,7 +68,7 @@ This creates a new optuna study for a given number of trials defined within the direction='maximize', load_if_exists=True) -The objective function defines the list of parameters to tune along with their range. It suggests a parameter configuration using ``trial.suggest_float`` or ``trial.suggest_int`` function of optuna and runs CKF for this parameter configuration. The output of CKF is read from the performance file named ``performanc_ckf.root`` and a score function is constructed within the objective function. +The objective function defines the list of parameters to tune along with their range. It suggests a parameter configuration using ``trial.suggest_float`` or ``trial.suggest_int`` function of optuna and runs CKF for this parameter configuration. The output of CKF is read from the performance file named ``performance_ckf.root`` and a score function is constructed within the objective function. The objective function and the number of trials are passed to optuna optimize function: ``study.optimize(objective, n_trials=100)``. The best parameter configuration after all the trials is read from ``study.best_trial.params.items()``. diff --git a/docs/formats/formats.rst b/docs/formats/formats.rst index 51fde505086..64d46c69815 100644 --- a/docs/formats/formats.rst +++ b/docs/formats/formats.rst @@ -1,7 +1,7 @@ File formats ============ -Acts supports various file formats to handle configuration and event data. +ACTS supports various file formats to handle configuration and event data. .. toctree:: :maxdepth: 1 diff --git a/docs/getting_started.md b/docs/getting_started.md index 0c6431ce9d2..aca3288c7ab 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -2,7 +2,7 @@ ## Quick start -Acts is developed in C++ and is built using [CMake](https://cmake.org). Building +ACTS is developed in C++ and is built using [CMake](https://cmake.org). Building the core library requires a C++17 compatible compiler, [Boost](http://boost.org), and [Eigen](http://eigen.tuxfamily.org). The following commands will clone the repository, configure, and build the core @@ -21,7 +21,7 @@ section. ## Prerequisites -The following dependencies are required to build the Acts core library: +The following dependencies are required to build the ACTS core library: - A C++17 compatible compiler (recent versions of either gcc and clang should work) - [CMake](https://cmake.org) >= 3.14 @@ -50,7 +50,7 @@ There are some additional dependencies that are automatically provided as part o the build system. These are usually not available through the system package manager and can be found in the ``thirdparty`` directory. -All external dependencies must be provided prior to building Acts. Compatible +All external dependencies must be provided prior to building ACTS. Compatible versions of all dependencies are provided e.g. by the [LCG releases](https://lcginfo.cern.ch/) starting from [LCG 102b](https://lcginfo.cern.ch/release/102b/). For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see [Build options](#build-options). @@ -59,9 +59,9 @@ available and are discussed in the [Building Acts](#building-acts) section. [Profiling](contribution/profiling.md) details the prerequisites for profiling the ACTS project with gperftools. -## Building Acts +## Building ACTS -Acts uses [CMake](https://cmake.org) to configure, build, and install the +ACTS uses [CMake](https://cmake.org) to configure, build, and install the software. After checking out the repository code into a `` directory, CMake is called first to configure the build into a separate `` directory. A typical setup is to create a `/build` directory within the @@ -108,8 +108,8 @@ $ cd $ source CI/setup_cvmfs_lcg.sh ``` -After sourcing the setup script, you can build Acts as described above. The -following commands will build Acts in the `/build` directory with the +After sourcing the setup script, you can build ACTS as described above. The +following commands will build ACTS in the `/build` directory with the Fatras component. ```console @@ -121,7 +121,7 @@ $ cmake --build build ### In a container -A set of container images is available through the [Acts container +A set of container images is available through the [ACTS container registry][acts_containers]. The following containers are used as part of the continuous integration setup and come with all dependencies pre-installed. @@ -170,7 +170,7 @@ where `` is the image id that was previously mentioned. If you are using container $ source /opt/lcg_view/setup.sh ``` -Building Acts follows the instructions above with `/acts` as the source directory, e.g. +Building ACTS follows the instructions above with `/acts` as the source directory, e.g. ```console container $ cmake -B build -S /acts -DACTS_BUILD_FATRAS=on @@ -181,10 +181,10 @@ container $ cmake --build build ### On your local machine -Building and running Acts on your local machine is not officially supported. +Building and running ACTS on your local machine is not officially supported. However, if you have the necessary prerequisites installed it is possible to use -it locally. Acts developers regularly use different Linux distributions -and macOS to build and develop Acts. +it locally. ACTS developers regularly use different Linux distributions +and macOS to build and develop ACTS. (build_docs)= ## Building the documentation @@ -317,14 +317,14 @@ components. -All Acts-specific options are disabled or empty by default and must be +All ACTS-specific options are disabled or empty by default and must be specifically requested. Some of the options have interdependencies that are automatically handled, e.g. enabling any of the specific `ACTS_BUILD_EXAMPLES_...` options will also enable the overall `ACTS_BUILD_EXAMPLES` option. You only need to tell the build system what you want and it will figure out the rest. -In addition to the Acts-specific options, many generic options are available +In addition to the ACTS-specific options, many generic options are available that modify various aspects of the build. The following options are some of the most common ones. For more details, have a look at the annotated list of [useful CMake variables](https://cmake.org/Wiki/CMake_Useful_Variables) or at the [CMake @@ -334,7 +334,7 @@ documentation](https://cmake.org/documentation/). | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | CMAKE_BUILD_TYPE | Build type, e.g. Debug or Release; affects compiler flags
(if not specified **`RelWithDebInfo`** will be used as a default) | | CMAKE_CXX_COMPILER | Which C++ compiler to use, e.g. g++ or clang++ | -| CMAKE_INSTALL_PREFIX | Where to install Acts to | +| CMAKE_INSTALL_PREFIX | Where to install ACTS to | | CMAKE_PREFIX_PATH | Search path for external packages | The build is also affected by some environment variables. They can be set by prepending them to the configuration call: @@ -353,7 +353,7 @@ The following environment variables might be useful. ## The OpenDataDetector -Acts comes packaged with a detector modeled using DD4hep that can be used to test your algorithms. It comes equipped with a magnetic field file as well as an already built material map. +ACTS comes packaged with a detector modeled using DD4hep that can be used to test your algorithms. It comes equipped with a magnetic field file as well as an already built material map. It is available via the git submodule feature by performing the following steps ([`git lfs`](https://git-lfs.github.com/) need to be installed on your machine): ```console @@ -361,7 +361,7 @@ $ git submodule init $ git submodule update ``` -To use it, you will then need to build acts with the `ACTS_BUILD_ODD` option and then point either `LD_LIBRARY_PATH` on Linux or +To use it, you will then need to build ACTS with the `ACTS_BUILD_ODD` option and then point either `LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` and `DD4HEP_LIBRARY_PATH` on MacOs to the install path of the ODD factory (for example: `build/thirdparty/OpenDataDetector/factory`). You can now use the ODD in the python binding by using: @@ -372,14 +372,14 @@ detector, trackingGeometry, decorators = getOpenDataDetector(odd_dir, oddMateria ``` -## Using Acts +## Using ACTS -When using Acts in your own CMake-based project, you need to include the +When using ACTS in your own CMake-based project, you need to include the following lines in your `CMakeLists.txt` file: ```cmake find_package (Acts COMPONENTS comp1 comp2 ...) ``` -where `compX` are the required components from the Acts project. See the +where `compX` are the required components from the ACTS project. See the `cmake` output for more information about which components are available. diff --git a/docs/index.rst b/docs/index.rst index 9df04ab6fd9..0d416d38362 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,10 @@ -Acts Common Tracking Software +ACTS Common Tracking Software ============================= -Acts is an experiment-independent toolkit for (charged) particle track +ACTS is an experiment-independent toolkit for (charged) particle track reconstruction in (high energy) physics experiments implemented in modern C++. -The Acts project provides high-level track reconstruction modules that can be +The ACTS project provides high-level track reconstruction modules that can be used for any tracking detector. The tracking detector geometry description is optimized for efficient navigation and fast extrapolation of tracks. Converters for several common geometry description packages are available. In addition to diff --git a/docs/license.rst b/docs/license.rst index 3d00851a8ca..dd058963b4b 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -1,7 +1,7 @@ License ======= -Acts is licensed under the `Mozilla Public License Version 2.0 +ACTS is licensed under the `Mozilla Public License Version 2.0 `_. The full text of the license can be found below. diff --git a/docs/plugins/MLAlgorithms.md b/docs/plugins/MLAlgorithms.md index 52df957d27e..2534bcb4cfe 100644 --- a/docs/plugins/MLAlgorithms.md +++ b/docs/plugins/MLAlgorithms.md @@ -1,15 +1,15 @@ # Machine leaning algorithms -Acts allows you to replace some of the components of the tracking chain by machine learning solutions. For now a replacement to the ambiguity solver is available, but when others are implemented they will be explained here. - +ACTS allows you to replace some components of the tracking chain by machine learning solutions. +For now a replacement to the ambiguity solver is available, but when others are implemented they will be explained here. ## Onnx plugin -To be able to perform neural network models' inferences in C++ Acts uses [onnxruntime](https://onnxruntime.ai/). An interface to use it has been implemented as an Acts plugin, to use it you will need to compile Acts with the `ACTS_PLUGIN_ONNX` option. For more detail on how to export your model to onnx please see the documentation on their [website](https://onnxruntime.ai/docs/) +To be able to perform neural network models' inferences in C++ ACTS uses [onnxruntime](https://onnxruntime.ai/). An interface to use it has been implemented as an ACTS plugin, to use it you will need to compile ACTS with the `ACTS_PLUGIN_ONNX` option. For more detail on how to export your model to onnx please see the documentation on their [website](https://onnxruntime.ai/docs/) ### OnnxRuntimeBase -The `OnnxRuntimeBase` class implement the inference of a standard MLP via Onnx and just require a link to the `.onnx` file containing the model one wants to use. Please note that right now the implementation of the inference in Acts only work with a single input node and a single output node. The inference can be both perform in single entry mode and in batch mode. In single entry mode, the `runONNXInference` method takes a single vector as entry, each element of the vector corresponding to one of the input features of your network. In batch mode, the input is an `Eigen::Array` with the columns corresponding to the input features and rows to the different batch inputs. +The `OnnxRuntimeBase` class implement the inference of a standard MLP via Onnx and just require a link to the `.onnx` file containing the model one wants to use. Please note that right now the implementation of the inference in ACTS only work with a single input node and a single output node. The inference can be both perform in single entry mode and in batch mode. In single entry mode, the `runONNXInference` method takes a single vector as entry, each element of the vector corresponding to one of the input features of your network. In batch mode, the input is an `Eigen::Array` with the columns corresponding to the input features and rows to the different batch inputs. ## AmbiguityResolutionMLAlgorithm diff --git a/docs/plugins/dd4hep.md b/docs/plugins/dd4hep.md index 0dd9a656a7a..aca27ced72f 100644 --- a/docs/plugins/dd4hep.md +++ b/docs/plugins/dd4hep.md @@ -1,7 +1,7 @@ # DD4hep plugin :::{todo} -Describe new markup and construction for dd4hep plugin and building layerless geometry. +Describe new markup and construction for DD4hep plugin and building layerless geometry. ::: The DD4hepPlugin allows building of a {class}`Acts::TrackingGeometry` from @@ -86,24 +86,24 @@ ACTS uses this parameter to resolve the layer detector elements. ## `DD4hepDetectorElement` -In Acts the surfaces describing the sensitive modules of a detector are directly +In ACTS the surfaces describing the sensitive modules of a detector are directly linked to these of the initial geometry input. In the case of DD4hep the {class}`Acts::DD4hepDetectorElement` was introduced which is the direct link of -Acts to DD4hep. In the case for tracking relevant parameters in the DD4hep +ACTS to DD4hep. In the case for tracking relevant parameters in the DD4hep geometry description are changed (e.g. alignment) it will be automatically -changed in Acts. +changed in ACTS. ## Build The DD4hepPlugin is only build on demand. The DD4hepPlugin depends on the TGeoPlugin therefore both plugins need to be installed. During the cmake configuration the flags `ACTS_BUILD_PLUGIN_DD4HEP=on` and -`ACTS_BUILD_PLUGIN_TGEO=on` need to be set. In addition ROOT and DD4hep +`ACTS_BUILD_PLUGIN_TGEO=on` need to be set. In addition, ROOT and DD4hep installations need to be available to cmake. ## Prerequisites -To guarantee a working translation from DD4hep input to Acts geometry the +To guarantee a working translation from DD4hep input to ACTS geometry the following conditions need to be met: - The detector needs to have a barrel-endcap structure: Every hierarchy of @@ -111,8 +111,8 @@ following conditions need to be met: into 1. {barrel} - 1. {barrel + 2 endcaps} - 1. {2 endcaps} - in case there is no barrel at this stage (e.g. forward end caps) + 2. {barrel + 2 endcaps} + 3. {2 endcaps} - in case there is no barrel at this stage (e.g. forward end caps) These subdetectors need to be flagged using the correct `DetType`. @@ -162,7 +162,7 @@ following conditions need to be met: ``` - The tracking geometry needs to be built from bottom to top to ensure - navigation. Therefore the different hierarchies need to be sorted ascending. + navigation. Therefore, the different hierarchies need to be sorted ascending. Per default the sub detectors are sorted by the id of their `DetElement`. In case another sorting needs to be applied, the users can provide their own function. @@ -171,7 +171,7 @@ There are two modes building the layers around the sensitive detector modules: - The `DetElement` containing the sensitive modules have a geometrical shape. - The boundaries of the layers in Acts are taken directly from the given shape. + The boundaries of the layers in ACTS are taken directly from the given shape. - The `DetElement` containing the sensitive modules have no specific shape (assembly). @@ -193,7 +193,7 @@ extension of the contained layers. The tolerance parameters `layerEnvelopeR` and `layerEnvelopeZ` need to be set in the {func}`Acts::convertDD4hepDetector` function. -Furthermore parameters can be handed over for material mapping or the axes +Furthermore, parameters can be handed over for material mapping or the axes orientation of modules. Summing up the `DetElement` tree in DD4hep should have the following @@ -203,7 +203,7 @@ structure: It is also possible to translate a very simple detector geometry, which just consists of cylindrical (for a barrel) or disc (for endcaps) layers which either -have material, or, are declared sensitive in dd4hep themselves without +have material, or, are declared sensitive in DD4hep themselves without containing any detector modules. (acts-params)= diff --git a/docs/plugins/geant4.md b/docs/plugins/geant4.md index de2c41fecc4..9850e7961b3 100644 --- a/docs/plugins/geant4.md +++ b/docs/plugins/geant4.md @@ -1,6 +1,6 @@ # Geant4 plugin -The Geant4 plugin allows to build {class}`Acts::TrackingGeometry` amnd {class}`Acts::Experimental::Detector` directly from Geant4 geometry input. +The Geant4 plugin allows to build {class}`Acts::TrackingGeometry` and {class}`Acts::Experimental::Detector` directly from Geant4 geometry input. Both rely on the conversion of `G4VPhysicalVolume` into corresponding `Acts` objects. ## Object conversion @@ -8,7 +8,7 @@ Both rely on the conversion of `G4VPhysicalVolume` into corresponding `Acts` obj ### Surface conversion Converting physical volumes into {class}`Acts::Surface` objects that represent sensitive detector elements, is done via the {class}`Acts::Geant4DetectorSurfaceFactory`. -This helper class allows to select volumes from the Geant4 geometry and convert them either into pairs of {class}`Acts::Geant4DetectorElement` and {class}`Acts::Surface` objects in case of sensitive elements, or simnply surfaces objects into case of passive surfaces. +This helper class allows to select volumes from the Geant4 geometry and convert them either into pairs of {class}`Acts::Geant4DetectorElement` and {class}`Acts::Surface` objects in case of sensitive elements, or simply surfaces objects in the case of passive surfaces. The selection is hereby done by providing one or more {class}`Acts::IGeant4PhysicalVolumeSelector` objects to the surface factory. @@ -36,7 +36,7 @@ Possible implementations of this type of conversions can be seen in the correspo #### Inspecting surface conversion within python -The `ActsExamples` python bindings allow to conveniently test the conversion of `Geant4` volumes into sensitive and passive surfaces, assuming you have a GDML file called `detector.gdml` where `Geant4PhysVolume` objects can be identified by a certain string, e.g. names containing the flag `Sensitive`, or `Passive`. Also multiple match strings are allowed. The converted surfaces can then be displayed with `.obj` (part of the Core functionality) or as `.svg` files (if `ACTS_BUILD_PLUGIN_ACTSVG` is switched on) +The `ActsExamples` python bindings allow to conveniently test the conversion of `Geant4` volumes into sensitive and passive surfaces, assuming you have a GDML file called `detector.gdml` where `Geant4PhysVolume` objects can be identified by a certain string, e.g. names containing the flag `Sensitive`, or `Passive`. Also, multiple match strings are allowed. The converted surfaces can then be displayed with `.obj` (part of the Core functionality) or as `.svg` files (if `ACTS_BUILD_PLUGIN_ACTSVG` is switched on) ```python # import the necessary modules diff --git a/docs/plugins/tgeo.rst b/docs/plugins/tgeo.rst index 65153264958..40392d1525c 100644 --- a/docs/plugins/tgeo.rst +++ b/docs/plugins/tgeo.rst @@ -5,7 +5,7 @@ General ------- The ``TGeo`` plugin connects a geometry described with the ``ROOT::Geom`` module with Acts. This is done by parsing the ROOT geometry and selecting ``TGeoNode`` objects that represent chosen geometrical objects. -Acts detector elements are represented by surfaces with dedicated shapes, hence a conversion of the volume based ``TGeoNode`` description into ``Acts::Surface`` objects needs to take place. +ACTS detector elements are represented by surfaces with dedicated shapes, hence a conversion of the volume based ``TGeoNode`` description into ``Acts::Surface`` objects needs to take place. An example use of the ``TGeo`` plugin can be found in the ``TGeoDetector`` example. @@ -20,13 +20,13 @@ Conversion of TGeoShapes to Acts::Surfaces ------------------------------------------ An automatic translation of ``TGeoShape`` objects into corresponding ``Acts::Surface`` objects with appropriate bound descriptions is done by the ``Acts::TGeoSurfaceConverter`` class. -There is some limited freedom in re-defining the orientation of the coordinate system between ROOT and Acts which can be used to adapt local coordinate definitions on the converted objects. +There is some limited freedom in re-defining the orientation of the coordinate system between ROOT and ACTS which can be used to adapt local coordinate definitions on the converted objects. This is indicated by the ``const std::string& axes`` argument of the converter. The nomenclature/convention is the following: * the resulting local cartesian coordinate system must by right-handed: this is guaranteed by the fact that the third local axis is constructed as a cross product of the first two local axis * defining the new local axes with respect to the ``TGeo`` definition is done by naming the new axes in order, e.g. an unchanged coordinate system has the tag ``XYZ``, or ``XY*``, as the third axis is defined by the first two ones - * flipping the direction of a axis is done by lower capital, e.g. ``yZ*`` redefines the negative y-axis of the ``TGeoMatrix`` as the (obvisouly) positive x-axis of the ``Acts::Transform3`` and redefines the positive z-axis of the ``TGeoMatrix`` as corresponding y-axis of the ``Acts::Transform3`` + * flipping the direction of a axis is done by lower capital, e.g. ``yZ*`` redefines the negative y-axis of the ``TGeoMatrix`` as the (obviously) positive x-axis of the ``Acts::Transform3`` and redefines the positive z-axis of the ``TGeoMatrix`` as corresponding y-axis of the ``Acts::Transform3`` In case a translation request is malformed, a ``std::exception`` is thrown, indicating the problem. diff --git a/docs/versioning.rst b/docs/versioning.rst index c1382fe2559..fb8b6820287 100644 --- a/docs/versioning.rst +++ b/docs/versioning.rst @@ -1,14 +1,14 @@ Versioning and public API ========================= -Acts uses `Semantic Versioning `_ to +ACTS uses `Semantic Versioning `_ to indicate breaking changes in its public API. A breaking change will result in a new major version. The `Conventional Commits `_ convention is used for pull requests to track the type of changes that have been merged and ensure that the version number is increased correctly. -Since Acts is still under active development not all visible symbols are +Since ACTS is still under active development not all visible symbols are automatically considered part of the public API and as such fall under the Semantic Versioning rules. The subset of symbols that are currently part of the public API is outlined below. diff --git a/docs/white_papers.toml b/docs/white_papers.toml index bc9c5e7118d..a340ffc6867 100644 --- a/docs/white_papers.toml +++ b/docs/white_papers.toml @@ -15,4 +15,4 @@ pdf_url = "https://github.com/felix-russo/gaussian-track-densities/releases/down [white_papers.metadata] authors = [ "Felix Russo",] title = "Gaussian Track Densities" -description = "Given the impact parameters $(d_0, z_0, t_0)$ of a track in Perigee parametrization, one can model the probability of the particle passing exactly through a point $(d, z, t)$ using a multivariate Gaussian distribution. In this white paper, we derive the maximum and the width of such a distribution for $d = 0$. This is useful in vertex seed finding, where we only consider the track density along the beam axis. We use the analytical results from this white paper in the unit test of the Acts module AdaptiveGridTrackDensity." +description = "Given the impact parameters $(d_0, z_0, t_0)$ of a track in Perigee parametrization, one can model the probability of the particle passing exactly through a point $(d, z, t)$ using a multivariate Gaussian distribution. In this white paper, we derive the maximum and the width of such a distribution for $d = 0$. This is useful in vertex seed finding, where we only consider the track density along the beam axis. We use the analytical results from this white paper in the unit test of the ACTS module AdaptiveGridTrackDensity."