add max_displacement_ratio parameter for custom scaling of displacement_ratios

Author: sam-ti

src/ti_plm/__init__.py

@@ -1,6 +1,7 @@
 """
 This is the main module defining the PLM class. The PLM class leverages the 'param' library to parameterize a PLM device, such as its resolution, pixel pitch, phase state levels, etc. Each parameter is defined at the class level and includes default values and detailed documentation about what that parameter is. The `param` library enforces type checking and makes it easy to define a dependency graph through function decorators.
 """
+
 from importlib.metadata import version
 import param
 import numpy as np
@@ -34,6 +35,13 @@ class PLM(param.Parameterized):
         default=np.array([])
     )
 
+    max_displacement_ratio = param.Number(
+        label='Max Displacement Ratio',
+        doc='Optional max displacement ratio override. If set, this value will be used to scale the `displacement_ratios` array. Otherwise, the values will be scaled to the number of states minus one, e.g. 15/16 for 4-bit devices.',
+        allow_None=True,
+        default=None
+    )
+    
     memory_lut = param.Array(
         label='Memory LUT',
         doc='Lookup table for values that are written to the PLM electrodes under each mirror corresponding to each displacement level. These values are typically not in monotonically increasing order.',
@@ -75,7 +83,7 @@ def size(self):
     def area(self):
         return np.prod(self.size())
 
-    @param.depends('displacement_ratios', 'phase_range', watch=True, on_init=True)
+    @param.depends('displacement_ratios', 'max_displacement_ratio', 'phase_range', watch=True, on_init=True)
     def _update_phase_buckets(self):
         """Cache the phase bucket array for use in the quantize operation.
         
@@ -88,8 +96,12 @@ def _update_phase_buckets(self):
         # save number of bits for later use by other class methods
         self._n_bits = len(self.displacement_ratios)
 
+        # if max_displacement_ratio is set, use it to scale displacement ratios
+        # otherwise, scale to the number of states minus one (e.g. 15/16 for 4-bit devices)
+        ratio_scale = self.max_displacement_ratio if self.max_displacement_ratio is not None else (self._n_bits - 1) / self._n_bits
+        
         # scale displacements between phase_range min and max such that the full displacement range represents one less bit than the available bit depth
-        phase_disp = self.phase_range[0] + (self.displacement_ratios * (self._n_bits - 1) / self._n_bits) * (self.phase_range[-1] - self.phase_range[0])
+        phase_disp = self.phase_range[0] + self.displacement_ratios * ratio_scale * (self.phase_range[-1] - self.phase_range[0])
         phase_disp = np.hstack([phase_disp, self.phase_range[-1]])
 
         # use average value of each phase level and the level above it to create buckets

tests/test_plm_devices.py

@@ -116,6 +116,7 @@ def test_p67():
     assert np.array_equal(plm.size(), [8640e-6, 13824e-6])
     assert approx(plm.area()) == 1.1943935e-4
 
+
 def test_p67_minus_pi_to_pi():
     from ti_plm import PLM
 
@@ -210,3 +211,66 @@ def test_p67_3d():
     # test full algorithm
     out = plm.process_phase_map(phase, replicate_bits=False, enforce_shape=False)
     assert np.array_equal(out, bits_expected)
+
+
+def test_p67_custom():
+    from ti_plm import PLM
+    
+    plm = PLM.from_db(
+        'p67',
+        name='Custom p67',
+        displacement_ratios=np.array([0.0, 0.0126, 0.0259, 0.0495, 0.0710, 0.0878, 0.1382, 0.2153, 0.3274, 0.3610, 0.4204, 0.5046, 0.5916, 0.6730, 0.8254, 1.0]),
+        max_displacement_ratio=0.8
+    )
+    
+    # create test phase map of phase values associated with each displacement level of a p67 SHV device
+    phase = np.array([[0.0, 0.0126, 0.0259, 0.0495, 0.0710, 0.0878, 0.1382, 0.2153, 0.3274, 0.3610, 0.4204, 0.5046, 0.5916, 0.6730, 0.8254, 1.0]]) * 0.8 * 2 * np.pi
+
+    # define expect phase state index corresponding to each phase value above
+    phase_idx_expected = np.array([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]])
+    
+    # define expected memory values for each displacement level
+    memory_expected = np.array([[3, 2, 1, 7, 0, 6, 5, 4, 11, 10, 9, 8, 15, 14, 13, 12]])
+    
+    # define expected bits we should get for the given phase map, which accounts for memory mapping and bit layout on electrodes under PLM mirrors
+    bits_expected_unflipped = np.array([
+    #   Phase state index
+    #    0       1       2       3       4       5       6       7       8       9       10      11      12      13      14      15
+    #   Memory value
+    #    3       2       1       7       0       6       5       4       11      10      9       8       15      14      13      12
+    #   Electrode cell values
+        [1, 0,   1, 0,   0, 0,   1, 0,   0, 0,   1, 0,   0, 0,   0, 0,   1, 1,   1, 1,   0, 1,   0, 1,   1, 1,   1, 1,   0, 1,   0, 1],
+        [1, 0,   0, 0,   1, 0,   1, 1,   0, 0,   0, 1,   1, 1,   0, 1,   1, 0,   0, 0,   1, 0,   0, 0,   1, 1,   0, 1,   1, 1,   0, 1]
+    ], dtype=np.uint8)
+    bits_expected = np.flip(bits_expected_unflipped, -1)  # flip along column axis (horizontal) for p67 plm
+    
+    # test individual functions related to calculating bits from phase map
+    phase_idx = plm.quantize(phase)
+    assert np.array_equal(phase_idx, phase_idx_expected)
+    memory = plm.memory_lut[phase_idx]
+    assert np.array_equal(memory, memory_expected)
+    bits = plm.electrode_map(phase_idx)
+    assert np.array_equal(bits, bits_expected)
+    
+    # test full algorithm
+    out = plm.process_phase_map(phase, replicate_bits=False, enforce_shape=False)
+    assert np.array_equal(out, bits_expected)
+    
+    # test phase wrapping (2pi --> 0)
+    assert np.array_equal(
+        plm.process_phase_map(np.array([[[2 * np.pi]]]), replicate_bits=False, enforce_shape=False),
+        np.array([[  # note this is a flipped 0 index phase state
+            [0, 1],
+            [0, 1]
+        ]])
+    )
+
+    # make sure shape enforcement is working
+    # calling process_phase_map without enforce_shape=False will throw an exception if the input phase map shape doesn't match plm.shape
+    from ti_plm import TIPLMException
+    with raises(TIPLMException):
+        plm.process_phase_map(phase)
+    
+    # make sure size and area are calculated correctly
+    assert np.array_equal(plm.size(), [8640e-6, 13824e-6])
+    assert approx(plm.area()) == 1.1943935e-4