Add KSIntSurfaceScattering to simulate scatterings on a surface by richeldichel · Pull Request #147 · KATRIN-Experiment/Kassiopeia

richeldichel · 2026-06-03T13:43:28Z

This class adds the possibility to simulate scattering of an electron on a surface with a given probability for backscattering of the electron and a given probability for production of a secondary electron from the surface.

Code originally by V. Hannen

This class adds the possibility to simulate scattering of an electron on a surface with a given probability for backscattering of the electron and a given probability for production of a secondary electron from the surface. Code originally by V. Hannen

Copilot

Pull request overview

This PR introduces a new surface interaction (KSIntSurfaceScattering) to model electron interactions with surfaces, including probabilistic backscattering and probabilistic secondary-electron emission, and wires it into the build system and XML bindings.

Changes:

Added KSIntSurfaceScattering interaction implementation and interface.
Added XML binding builder to configure the interaction via ksint_surface_scattering with relevant attributes.
Registered new sources/headers in the Interactions and Bindings CMakeLists.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
Kassiopeia/Interactions/Source/KSIntSurfaceScattering.cxx	Implements the scattering interaction, including backscattering, absorption, and secondary creation logic.
Kassiopeia/Interactions/Include/KSIntSurfaceScattering.h	Declares the interaction API and configuration fields (probabilities, energies, side selection).
Kassiopeia/Interactions/CMakeLists.txt	Adds the new interaction source/header to the Interactions library build.
Kassiopeia/Bindings/Interactions/Source/KSIntSurfaceScatteringBuilder.cxx	Registers the new XML element and its attributes.
Kassiopeia/Bindings/Interactions/Include/KSIntSurfaceScatteringBuilder.h	Implements attribute-to-setter wiring for XML configuration.
Kassiopeia/Bindings/CMakeLists.txt	Adds the new builder source/header to the Bindings build.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…eview Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Ran Scripts/gen-bindings-docs.sh to regenerate the documentation. The diff includes some other previous PRs.

richeldichel · 2026-06-08T08:11:59Z

I have added the suggestions by Copilot as they were all well-justified. Additionally, I enclosed the debug statements about the particle state in a #ifdef Kassiopeia_ENABLE_DEBUG as it does not make any sense otherwise.

The largest diff now comes from the update of the bindings documentation as I re-ran gen-bindings-docs.sh.

2xB

Thank you very much for the work! That looks like an interesting feature. I have some remarks, the most significant of which is my impression that there seems to be an error in KSIntSurfaceScattering::CreateSecondaryElectron.

2xB · 2026-06-12T15:13:38Z

+    void SetSide(std::string side_name)
+    {
+        //default is both sides of the surface execute the interaction
+        fSideName = std::string("both");


This should really just be an enum. Also, information is duplicated between this, fPerformSideCheck and fSideSignIsNegative. Which is hard to track when it somehow gets de-synced. I would keep it as a single enum and then maybe when it is actually used do something like const performSideCheck = fSideName != SideName::Both.

2xB · 2026-06-12T15:20:35Z

+#include "KSIntSurfaceScattering.h"
+
+#include "KRandom.h"
+#include "KSInteractionsMessage.h"
+using katrin::KRandom;
+
+#include "KConst.h"
+
+#include <cmath>
+
+using katrin::KThreeVector;


Suggested change

#include "KSIntSurfaceScattering.h"

#include "KRandom.h"

#include "KSInteractionsMessage.h"

using katrin::KRandom;

#include "KConst.h"

#include <cmath>

using katrin::KThreeVector;

#include "KSIntSurfaceScattering.h"

#include "KConst.h"

#include "KRandom.h"

#include "KSInteractionsMessage.h"

#include "KThreeVector.hh"

#include <cmath>

#include <limits>

using katrin::KRandom;

using katrin::KThreeVector;

Cleaning up the includes here. Also adding #include <limits> for the NaNs suggested below.

2xB · 2026-06-12T15:24:29Z

+    fScatProbability(0.3),
+    fScatLossFraction(0.0),
+    fSecElectronProbability(0.25),
+    fSecElectronMeanEnergy(4.0),


Suggested change

fScatProbability(0.3),

fScatLossFraction(0.0),

fSecElectronProbability(0.25),

fSecElectronMeanEnergy(4.0),

fScatProbability(std::numeric_limits<double>::quiet_NaN()),

fScatLossFraction(std::numeric_limits<double>::quiet_NaN()),

fSecElectronProbability(std::numeric_limits<double>::quiet_NaN()),

fSecElectronMeanEnergy(std::numeric_limits<double>::quiet_NaN()),

There is no point in hidden defaults. Either a user sets it or it should fail. There should also be an error thrown if any of these is NaN during calculation so one knows what one missed.

2xB · 2026-06-12T15:27:07Z

+#endif
+
+  // figure out the basis directions for the particle ejection
+  // eject it with a diffuse 'Lambertian' distribution


Suggested change

// eject it with a diffuse 'Lambertian' distribution

This comment has nothing to do with this code.

2xB · 2026-06-12T15:31:05Z

+
+  const KThreeVector tInitialMomentum = anInitialParticle.GetMomentum();
+  const double dot_prod = tInitialMomentum.Dot(tNormal);
+  bool execute_interaction = true;


if at the end of a function usually feels ugly to me since it adds some avoidable nesting. Like here: I would start with if (!execute_interaction) and early return; from there, that way the interaction code does not have to be in an if block but can just happen if no return happened.
That debug output is not useful in this case anyways since the particle was not really changed.

2xB · 2026-06-12T16:00:52Z

+  tInitialNormalMomentum = -1.0 * tInitialNormalMomentum;  //reverse direction for reflection
+  KThreeVector tInitialTangentMomentum = tInitialMomentum - tInitialNormalMomentum;


I get the impression at first glance that the next function has essentially the same code but programmed significantly more cleanly - most of my comments here don't apply there. Could it live in a common helper function GetReflectionMomentum(anInitialParticle, tSinTheta, tCosTheta) so it only exists once, preferably in the more clean way?

Other than that, I think there seems to be a bug here since this seems double-negating: tInitialNormalMomentum before the negation to my understanding should be the momentum in direction of the surface. Meaning tInitialMomentum - tInitialNormalMomentum before the negation should be the momentum orthogonal to tInitialNormalMomentum. That tInitialNormalMomentum = -1.0 * tInitialNormalMomentum; in combination with the minus sign in the next line does not make sense to me.

Also in general I think re-defining an existing variable is bad style. That also goes for the next two lines.

2xB · 2026-06-12T16:04:34Z

+  tInitialNormalMomentum = tInitialNormalMomentum.Unit();
+  tInitialTangentMomentum = tInitialTangentMomentum.Unit();


It's really inconsistent when .Unit() is applied and when one tracks variables, one sees that sometimes that is applied twice.

2xB · 2026-06-12T16:11:51Z

+  if (tDirection.Dot(momDirection) > 0) {
+  tDirection = -1.0 * tDirection;
+  }
+


Isn't this a case that should never happen if the calculation was programmed correctly? Then it should better error in that case.

2xB · 2026-06-12T16:13:33Z

+    if (tKineticEnergy < 0.0) {
+        intmsg(eError) << "surface diffuse interaction named <" << GetName()
+                       << "> tried to give a particle a negative kinetic energy." << eom;
+        return;
+    }
+


How would that happen? Isn't it better to ensure fScatLossFraction is between 0 and 1?

2xB · 2026-06-12T16:18:37Z

+        1.));  // only KRandom::GetInstance().Uniform( 0., 1. ); is wrong: see http://www.sciencedirect.com/science/article/pii/S0042207X02001732
+    double tCosTheta = std::sqrt((1.0 - tSinTheta) * (1.0 + tSinTheta));
+
+    KThreeVector tNormal;


I believe this following code I have essentially already reviewed above - Could it live in a function GetReflectionMomentum(anInitialParticle, tSinTheta, tCosTheta) so it only exists once?

richeldichel requested a review from Copilot June 3, 2026 13:43

Copilot started reviewing on behalf of richeldichel June 3, 2026 13:43 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

richeldichel and others added 3 commits June 8, 2026 09:55

KSIntSurfaceScattering: Apply minor fixes and suggestions from code r…

57d40c0

…eview Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Wrap debug statements with #ifdef Kassiopeia_ENABLE_DEBUG

56ddce2

Update bindings documentation

62d986b

Ran Scripts/gen-bindings-docs.sh to regenerate the documentation. The diff includes some other previous PRs.

richeldichel marked this pull request as ready for review June 8, 2026 08:14

richeldichel requested a review from 2xB June 8, 2026 08:14

2xB requested changes Jun 12, 2026

View reviewed changes

		tInitialNormalMomentum = -1.0 * tInitialNormalMomentum; //reverse direction for reflection
		KThreeVector tInitialTangentMomentum = tInitialMomentum - tInitialNormalMomentum;

		tInitialNormalMomentum = tInitialNormalMomentum.Unit();
		tInitialTangentMomentum = tInitialTangentMomentum.Unit();

Uh oh!

Conversation

richeldichel commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

richeldichel commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

2xB left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

2xB Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

richeldichel commented Jun 8, 2026 •

edited

Loading

2xB left a comment •

edited

Loading

2xB Jun 12, 2026 •

edited

Loading