Alice3: add minimal documentation + Magnetic field macro (#13011)

Author: mconcas

Detectors/Upgrades/ALICE3/README.md

@@ -0,0 +1,69 @@
+# ALICE 3 full simulation
+
+## Simulation
+### Simulation software for Run 5
+Current simulation approach for ALICE 3 is a specification of what it is used in the main O2 simulation package.
+It shares the same structure and possibly inherits all the features in place already.
+For all of the features that are not really Run-5 specific please refer to the official [O2 Simulation Documentation](https://aliceo2group.github.io/simulation/docs/).
+
+### Rationale for the "Upgrades" codebase
+Run 5 code for the detectors is stored in the `Detectors/Upgrades/ALICE3` directory and its suboflder strucure mimicks the same we have in `Detectors`.
+For specific data formats the plan is to keep the same approach in `DataFormats/Upgrades`.
+
+### Available modules
+Run 5 executable is called `o2-sim-run5` and accepts the same syntax as `o2-sim`.
+There is also the serial vertsion `o2-sim-serial-run5` that is the serial implementation.
+The specific modules for Run 5 are enabled by passing their their IDs to the `-m` parameter of the `o2-sim`.
+A list of the available DetIDs is reproted in the table below:
+
+| Detector ID | Detector description             |
+|-------------|----------------------------------|
+| `A3IP`      | Beam pipe                        |
+| `TRK`       | Barrel Tracker                   |
+| `TF3`       | Time Of Flight detectors         |
+| `FT3`       | Forward endcaps                  |
+| `RCH`       | Ring Imaging Cherenkov detectors |
+| `ECL`       | Electromagnetic Calorimeter      |
+| `MI3`       | Muon Identification              |
+| `FCT`       | Forward Conversion Tracker       |
+| `A3ABSO`    | Absorber                         |
+| `A3MAG`     | Magnet                           |
+
+Names are arbitrarily chosen and are such as to be orthogonal to any Run 3+ other DetID.
+The detector IDs of sensitive modules are mapped to the corresponding `o2::detector::DetID` class definition for convenience, so to be consistent with output names of the hit files.
+
+### Use the ALICE 3 magnetic field
+By definition the `o2-sim-run5` will use the Run 3 magnetic field configurations.
+Field description can be overridden with a custom macro with a path exported in the `ALICE3_MAGFIELD_MACRO` environment variable.
+The env var `ALICE3_SIM_FIELD` needs also to be set to `ON`.
+Example:
+
+```bash
+export ALICE3_SIM_FIELD=ON
+export ALICE3_MAGFIELD_MACRO=../ALICE3Field.C
+```
+
+An exampling macro for a custom magnetic field is stored in `Detectors/Upgrades/macros/ALICE3Field.C`.
+
+### Run a simple simulation for run 5
+The simplest command to be run to test the simulation is working is:
+
+```bash
+o2-sim-run5 -n 0
+```
+This will not produce any events but will spin the machinery and will produce the `o2sim_geometry.root` file with the whole geometry description.
+To enable a specific set of modules, e.g. the beampipe and the TOFs one can specify which modules to enable, e.g.:
+
+```bash
+o2-sim-run5 -n 10 -m A3IP TF3
+```
+### Output of the simulation
+The simulation will produce a `o2sim_Hits<DetID>.root` file with a tree with the hits related to that detector.
+Currently, hits are produced for: `TRK`, `FT3`, and `TF3`.
+More detectors will be included.
+
+## Reconstruction
+WIP
+
+## Analysis
+WIP

Detectors/Upgrades/ALICE3/macros/ALICE3Field.C

@@ -0,0 +1,66 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+//
+// Author: J. E. Munoz Mendez jesus.munoz@cern.ch
+
+std::function<void(const double*, double*)> field()
+{
+  return [](const double* x, double* b) {
+    double Rc;
+    double R1;
+    double R2;
+    double B1;
+    double B2;
+    double beamStart = 500.;    //[cm]
+    double tokGauss = 1. / 0.1; // conversion from Tesla to kGauss
+
+    bool isMagAbs = true;
+
+    // ***********************
+    // LAYOUT 1
+    // ***********************
+
+    // RADIUS
+    Rc = 185.; //[cm]
+    R1 = 220.; //[cm]
+    R2 = 290.; //[cm]
+
+    // To set the B2
+    B1 = 2.;                                    //[T]
+    B2 = -Rc * Rc / ((R2 * R2 - R1 * R1) * B1); //[T]
+
+    if ((abs(x[2]) <= beamStart) && (sqrt(x[0] * x[0] + x[1] * x[1]) < Rc)) {
+      b[0] = 0.;
+      b[1] = 0.;
+      b[2] = B1 * tokGauss;
+    } else if ((abs(x[2]) <= beamStart) &&
+               (sqrt(x[0] * x[0] + x[1] * x[1]) >= Rc &&
+                sqrt(x[0] * x[0] + x[1] * x[1]) < R1)) {
+      b[0] = 0.;
+      b[1] = 0.;
+      b[2] = 0.;
+    } else if ((abs(x[2]) <= beamStart) &&
+               (sqrt(x[0] * x[0] + x[1] * x[1]) >= R1 &&
+                sqrt(x[0] * x[0] + x[1] * x[1]) < R2)) {
+      b[0] = 0.;
+      b[1] = 0.;
+      if (isMagAbs) {
+        b[2] = B2 * tokGauss;
+      } else {
+        b[2] = 0.;
+      }
+    } else {
+      b[0] = 0.;
+      b[1] = 0.;
+      b[2] = 0.;
+    }
+  };
+}

cmake/O2RootMacroExclusionList.cmake

@@ -60,7 +60,8 @@ list(APPEND O2_ROOT_MACRO_EXCLUSION_LIST
             macro/load_all_libs.C
             macro/putCondition.C
             macro/rootlogon.C
-            Detectors/FIT/FT0/calibration/macros/makeChannelOffsetCalibObjectInCCDB.C)
+            Detectors/FIT/FT0/calibration/macros/makeChannelOffsetCalibObjectInCCDB.C
+            Detectors/Upgrades/ALICE3/macros/ALICE3Field.C)
 
 
 if(NOT BUILD_SIMULATION)