feat: addFatras preselectParticles config for ParticleSelector (#1350)

Allow preselection of particles before Fatras using `ParticleSelectorConfig()`, eg.
```
s = addFatras(
    s, trackingGeometry, field,
    ParticleSelectorConfig(
        eta=(-4.0, 4.0),
        pt=(1 * u.GeV, 10 * u.GeV),
        removeNeutral=True,
    ))
```
This is usually required to use Pythia8 with Fatras.

To this end, an example of using Pythia8 to generate ttbar + mu=200 pile-up is included (commented-out) in `full_chain_itk.py`.

Examples/Python/python/acts/examples/__init__.py

@@ -140,7 +140,11 @@ def NamedTypeArgsWrapper(*args, **kwargs):
 
             for k, v in kwargs.items():
                 cls = namedTypeArgs.get(k)
-                if cls is not None and v.__class__.__module__ == int.__module__:
+                if (
+                    cls is not None
+                    and v is not None
+                    and type(v).__module__ == int.__module__  # is v a 'builtins'?
+                ):
                     if issubclass(cls, Iterable):
                         kwargs[k] = cls(*v)
                     else:

Examples/Python/python/acts/examples/simulation.py

@@ -31,6 +31,21 @@
     ["num", "pdg", "randomizeCharge"],
     defaults=[None, None, None],
 )
+ParticleSelectorConfig = namedtuple(
+    "ParticleSelectorConfig",
+    [
+        "rho",  # (min,max)
+        "absZ",  # (min,max)
+        "time",  # (min,max)
+        "phi",  # (min,max)
+        "eta",  # (min,max)
+        "absEta",  # (min,max)
+        "pt",  # (min,max)
+        "removeCharged",  # bool
+        "removeNeutral",  # bool
+    ],
+    defaults=[(None, None)] * 7 + [None] * 2,
+)
 
 
 @acts.examples.NamedTypeArgs(
@@ -293,14 +308,17 @@ def addPythia8(
     return evGen if returnEvGen else s
 
 
+@acts.examples.NamedTypeArgs(
+    preselectParticles=ParticleSelectorConfig,
+)
 def addFatras(
     s: acts.examples.Sequencer,
     trackingGeometry: acts.TrackingGeometry,
     field: acts.MagneticFieldProvider,
     outputDirCsv: Optional[Union[Path, str]] = None,
     outputDirRoot: Optional[Union[Path, str]] = None,
     rnd: Optional[acts.examples.RandomNumbers] = None,
-    preselectParticles: bool = True,
+    preselectParticles: Optional[ParticleSelectorConfig] = ParticleSelectorConfig(),
 ) -> acts.examples.Sequencer:
     """This function steers the detector simulation using Fatras
 
@@ -316,6 +334,10 @@ def addFatras(
         the output folder for the Root output, None triggers no output
     rnd : RandomNumbers, None
         random number generator
+    preselectParticles : ParticleSelectorConfig(rho, absZ, time, phi, eta, absEta, pt, removeCharged, removeNeutral), None
+        ParticleSelector configuration to select particles as input to Fatras. Each range is specified as a tuple of (min,max).
+        Default of no selections specified in Examples/Algorithms/TruthTracking/ActsExamples/TruthTracking/ParticleSelector.hpp
+        Specify preselectParticles=None to inhibit ParticleSelector altogether.
     """
 
     if int(s.config.logLevel) <= int(acts.logging.DEBUG):
@@ -325,10 +347,28 @@ def addFatras(
     rnd = rnd or acts.examples.RandomNumbers()
 
     # Selector
-    if preselectParticles:
+    if preselectParticles is not None:
         particles_selected = "particles_selected"
         s.addAlgorithm(
             acts.examples.ParticleSelector(
+                **acts.examples.defaultKWArgs(
+                    rhoMin=preselectParticles.rho[0],
+                    rhoMax=preselectParticles.rho[1],
+                    absZMin=preselectParticles.absZ[0],
+                    absZMax=preselectParticles.absZ[1],
+                    timeMin=preselectParticles.time[0],
+                    timeMax=preselectParticles.time[1],
+                    phiMin=preselectParticles.phi[0],
+                    phiMax=preselectParticles.phi[1],
+                    etaMin=preselectParticles.eta[0],
+                    etaMax=preselectParticles.eta[1],
+                    absEtaMin=preselectParticles.absEta[0],
+                    absEtaMax=preselectParticles.absEta[1],
+                    ptMin=preselectParticles.pt[0],
+                    ptMax=preselectParticles.pt[1],
+                    removeCharged=preselectParticles.removeCharged,
+                    removeNeutral=preselectParticles.removeNeutral,
+                ),
                 level=s.config.logLevel,
                 inputParticles="particles_input",
                 outputParticles=particles_selected,

Examples/Scripts/Python/full_chain_itk.py

@@ -6,7 +6,7 @@
 geo_dir = pathlib.Path("acts-itk")
 outputDir = pathlib.Path.cwd()
 
-# acts.examples.dump_args_calls(locals())
+# acts.examples.dump_args_calls(locals())  # show acts.examples python binding calls
 detector, trackingGeometry, decorators = buildITkGeometry(geo_dir)
 field = acts.examples.MagneticFieldMapXyz(str(geo_dir / "bfield/ATLAS-BField-xyz.root"))
 rnd = acts.examples.RandomNumbers(seed=42)
@@ -16,12 +16,16 @@
     MomentumConfig,
     EtaConfig,
     ParticleConfig,
+    addPythia8,
     addFatras,
+    ParticleSelectorConfig,
     addDigitization,
 )
 from acts.examples.reconstruction import (
     addSeeding,
     TruthSeedRanges,
+    SeedingAlgorithm,
+    ParticleSmearingSigmas,
     addCKFTracks,
     CKFPerformanceConfig,
 )
@@ -34,10 +38,22 @@
     ParticleConfig(1, acts.PdgParticle.eMuon, True),
     rnd=rnd,
 )
+# # Uncomment addPythia8 and ParticleSelectorConfig, instead of addParticleGun, to generate ttbar with mu=200 pile-up.
+# s = addPythia8(
+#     s,
+#     hardProcess=["Top:qqbar2ttbar=on"],
+#     vtxGen=acts.examples.GaussianVertexGenerator(
+#         stddev=acts.Vector4(0.0125 * u.mm, 0.0125 * u.mm, 55.5 * u.mm, 5.0 * u.ns),
+#         mean=acts.Vector4(0, 0, 0, 0),
+#     ),
+#     rnd=rnd,
+#     outputDirRoot=outputDir,
+# )
 s = addFatras(
     s,
     trackingGeometry,
     field,
+    # ParticleSelectorConfig(eta=(-4.0, 4.0), pt=(1.0 * u.GeV, 10.0 * u.GeV), removeNeutral=True),
     outputDirRoot=outputDir,
     rnd=rnd,
 )
@@ -49,7 +65,6 @@
     outputDirRoot=outputDir,
     rnd=rnd,
 )
-# from acts.examples.reconstruction import SeedingAlgorithm, ParticleSmearingSigmas
 s = addSeeding(
     s,
     trackingGeometry,

Examples/Scripts/Python/seeding.py

@@ -84,7 +84,7 @@ def runSeeding(
         outputDirCsv=outputDir / "csv",
         outputDirRoot=outputDir,
         rnd=rnd,
-        preselectParticles=False,
+        preselectParticles=None,
     )
 
     srcdir = Path(__file__).resolve().parent.parent.parent.parent