scatter2d/CustomFormFactor.py: add explanatory comments; clean up

rawEx/scatter2d/CustomFormFactor.py

@@ -11,7 +11,7 @@ import matplotlib.pyplot as plt
 def sinc(x):
     if abs(x) == 0:
         return 1.
-    return cmath.sin(x)/x
+    return cmath.sin(x) / x
 
 
 class CustomFormfactor:
@@ -22,27 +22,35 @@ class CustomFormfactor:
     """
 
     def __init__(self, L, H):
+        """ arguments and initialization for the formfactor """
+
         # parameters describing the form factor
         self.L = L
         self.H = H
 
-    def formfactor(self, q):
-        qzhH = 0.5*q.z()*self.H
-        qxhL = 0.5*q.x()*self.L
-        qyhL = 0.5*q.y()*self.L
-        return 0.5*self.H*self.L**2*cmath.exp(complex(0., 1.)*qzhH)*\
-               sinc(qzhH)*(sinc(0.5*qyhL)*(sinc(qxhL)-0.5*sinc(0.5*qxhL))+\
-               sinc(0.5*qxhL)*sinc(qyhL))
+    def formfactor(self, q:'C3'):
+        """ main scattering function """
+
+        qzhH = 0.5 * q.z() * self.H
+        qxhL = 0.5 * q.x() * self.L
+        qyhL = 0.5 * q.y() * self.L
+        return (0.5 * self.H * self.L**2
+                * cmath.exp(complex(0., 1.) * qzhH) * sinc(qzhH)
+                * (sinc(0.5 * qyhL) * (sinc(qxhL) - 0.5 * sinc(0.5 * qxhL))
+                   + sinc(0.5 * qxhL) * sinc(qyhL)))
 
     def spanZ(self, rotation):
+        """ upper and lower z-positions of a custom shape """
+
         return ba.Span(0, self.H)
 
 
 def get_sample():
     """
-    A sample with particles, having a custom form factor, on a substrate.
+    Sample with particles, having a custom formfactor, on a substrate.
     """
-    # defining materials
+
+    # materials
     vacuum = ba.RefractiveMaterial("Vacuum", 0, 0)
     material_substrate = ba.RefractiveMaterial("Substrate", 6e-6, 2e-8)
     material_particle = ba.RefractiveMaterial("Particle", 6e-4, 2e-8)
@@ -56,6 +64,18 @@ def get_sample():
     vacuum_layer.addLayout(particle_layout)
     substrate_layer = ba.Layer(material_substrate)
 
+    """ NOTE:
+    Slicing of custom formfactor is not possible.
+    all layers must have number of slices equal to 1.
+    It is a default situation; otherwise use
+    ```
+    my_layer.setNumberOfSlices(1)
+    ```
+
+    Furthermore, a custom particle should not cross layer boundaries;
+    that is, the z-span should be within a single layer
+    """
+
     # assemble sample
     sample = ba.Sample()
     sample.addLayer(vacuum_layer)
@@ -68,8 +88,12 @@ def get_simulation(sample):
     n = <%= test_mode ? 11 : 100 %>
     det = ba.SphericalDetector(n, -1*deg, 1*deg, n, 0, 2*deg)
     simulation = ba.ScatteringSimulation(beam, sample, det)
-    simulation.options().setNumberOfThreads(
-        1)  # deactivate multithreading (why?)
+
+    # Deactivate multithreading:
+    # Currently BornAgain cannot access the Python interpreter
+    # from a multi-threaded C++ function
+    simulation.options().setNumberOfThreads(1)
+
     return simulation