AMS-BP 0.0.231__py3-none-any.whl → 0.2.0__py3-none-any.whl

AMS_BP/optics/lasers/laser_profiles.py

@@ -23,17 +23,21 @@ class LaserParameters:
 
     wavelength: float  # Wavelength in nanometers
     power: Union[float, Callable[[float], float]]  # Power in watts
-    beam_width: float  # 1/e² beam width at waist in microns
+    beam_width: Optional[float] = None  # 1/e² beam width at waist in microns
     numerical_aperture: Optional[float] = None  # NA of focusing lens
-    position: Union[Tuple[float, float, float], Callable[[float], np.ndarray]] = (
+    position: Union[
+        Tuple[float, float, float], Callable[[float], Tuple[float, float, float]]
+    ] = (
         0.0,
         0.0,
         0.0,
     )
-    refractive_index: float = 1.0  # Refractive index of medium
+    refractive_index: Optional[float] = 1.0  # Refractive index of medium
 
     def __post_init__(self):
         """Validate parameters after initialization."""
+        if not self.beam_width:
+            self.beam_width = self.diffraction_limited_width
         self._validate_parameters()
         self._compute_derived_parameters()
         self.max_power = self.power
@@ -96,7 +100,10 @@ class LaserParameters:
             Power in watts
         """
         if callable(self.power):
-            return self.power(t)
+            power = self.power(t)
+            if power < 0:
+                raise ValueError("Laser Power Cannot be Negative")
+            return power
         return self.power
 
     def get_position(self, t: float) -> Tuple[float, float, float]:
@@ -228,7 +235,7 @@ class LaserProfile(ABC):
 class GaussianBeam(LaserProfile):
     """3D Gaussian laser beam profile with time dependence."""
 
-    def calculate_intensity(
+    def calculate_intensity_(
         self,
         x: np.ndarray | float,
         y: np.ndarray | float,
@@ -267,7 +274,7 @@ class GaussianBeam(LaserProfile):
             # * np.cos(phase_terms)
         )
 
-    def calculate_intensity_(
+    def calculate_intensity(
         self,
         x: np.ndarray | float,
         y: np.ndarray | float,
@@ -305,7 +312,7 @@ class GaussianBeam(LaserProfile):
         w_z = self.get_beam_width(z_shifted)
 
         # Calculate peak intensity (z-dependent)
-        I0 = 2 * power / (np.pi * (self.params.beam_width / 2.0) ** 2)
+        I0 = 2 * power / (np.pi * (self.params.beam_width) ** 2)
         I0_z = I0 * (self.params.beam_width / w_z) ** 2
 
         # Calculate phase terms if needed
@@ -368,15 +375,16 @@ class WidefieldBeam(LaserProfile):
         Returns:
             Intensity scaling factor between 0 and 1
         """
-        # Use error function for smooth transition at DoF boundaries
-        # Scale factor determines how sharp the transition is
-        scale_factor = 2.0  # Adjust this to change transition sharpness
-
-        # Normalize z by DoF and create smooth falloff
-        normalized_z = scale_factor * (np.abs(z) - self.dof / 2) / self.dof
-
-        # Use sigmoid function for smooth transition
-        return 1 / (1 + np.exp(normalized_z))
+        # # Use error function for smooth transition at DoF boundaries
+        # # Scale factor determines how sharp the transition is
+        # scale_factor = 2.0  # Adjust this to change transition sharpness
+        #
+        # # Normalize z by DoF and create smooth falloff
+        # normalized_z = scale_factor * (np.abs(z)) / self.dof
+        #
+        # # Use sigmoid function for smooth transition
+        # return 1 / (1 + np.exp(normalized_z))
+        return 1.0
 
     def calculate_intensity(
         self,
@@ -413,7 +421,7 @@ class WidefieldBeam(LaserProfile):
         base_intensity = power / (np.pi * self.max_radius**2)
 
         # Apply radial intensity profile with smooth falloff at edges
-        edge_width = self.max_radius * 0.1  # 10% of max radius
+        edge_width = self.max_radius * 0.00001
         radial_profile = 0.5 * (1 - np.tanh((r - self.max_radius) / edge_width))
         # Apply DoF-based axial intensity profile
         axial_profile = self._calculate_dof_profile(z_shifted)
@@ -422,32 +430,6 @@ class WidefieldBeam(LaserProfile):
         return base_intensity * radial_profile * axial_profile
 
 
-# Example usage
-if __name__ == "__main__":
-    # Create parameters for a typical microscope objective
-    params = LaserParameters(
-        wavelength=488,  # 488 nm
-        power=0.001,  # 1 mW
-        beam_width=0.25,  # 250 nm
-        numerical_aperture=1.4,
-        refractive_index=1.518,  # Oil immersion
-    )
-
-    # Create beam object
-    beam = GaussianBeam(params)
-
-    # Get intensity map
-    result = beam.get_intensity_map(
-        volume_size=(5, 5, 10),  # 5x5x10 microns
-        voxel_size=0.1,  # 100 nm voxels
-        t=0,  # t=0 seconds
-    )
-
-    # print(f"Beam waist: {params.beam_width:.3f} µm")
-    # print(f"Rayleigh range: {params.rayleigh_range:.3f} µm")
-    # print(f"Diffraction limit: {params.diffraction_limited_width:.3f} µm")
-
-
 class HiLoBeam(LaserProfile):
     """
     Highly Inclined Laminated Optical (HiLo) illumination profile.
@@ -522,7 +504,7 @@ class HiLoBeam(LaserProfile):
         z_shifted = z - pos[2]
 
         # Calculate radial distance from optical axis
-        r = np.sqrt(x_shifted**2 + y_shifted**2)
+        r_squared = x_shifted**2 + y_shifted**2
 
         # Base beam parameters
         w0 = self.params.beam_width  # Beam waist
@@ -542,150 +524,10 @@ class HiLoBeam(LaserProfile):
         intensity = (
             I0
             * (w0 / w_z) ** 2  # Beam width scaling
-            * np.exp(-2 * r**2 / w_z**2)  # Gaussian radial profile
+            * np.exp(-2 * r_squared / w_z**2)  # Gaussian radial profile
         )
 
         # Lamination effect: attenuate out-of-focus regions
         lamination_factor = np.exp(-np.abs(z_shifted) / (2 * self.axial_resolution))
 
         return intensity * lamination_factor
-
-
-class ConfocalBeam(LaserProfile):
-    """
-    Confocal microscopy beam profile with point scanning and pinhole characteristics.
-
-    Implements key optical principles of confocal microscopy:
-    - Point scanning illumination
-    - Pinhole-based rejection of out-of-focus light
-    - Depth-resolved imaging capabilities
-    """
-
-    def __init__(
-        self,
-        params: LaserParameters,
-        pinhole_diameter: float,  # Pinhole diameter in microns
-        scanning_mode: str = "point",  # 'point' or 'line'
-        line_orientation: str = "horizontal",  # 'horizontal' or 'vertical'
-    ):
-        """
-        Initialize Confocal beam profile.
-
-        Args:
-            params: LaserParameters for the beam
-            pinhole_diameter: Diameter of the detection pinhole in microns
-            scanning_mode: Scanning method ('point' or 'line')
-            line_orientation: Orientation for line scanning
-        """
-        super().__init__(params)
-
-        # Validate numerical aperture
-        if params.numerical_aperture is None:
-            raise ValueError(
-                "Numerical aperture must be specified for confocal microscopy"
-            )
-
-        # Pinhole and optical characteristics
-        self.pinhole_diameter = pinhole_diameter
-        self.scanning_mode = scanning_mode
-        self.line_orientation = line_orientation
-
-        # Calculate optical parameters
-        wavelength_microns = params.wavelength / 1000.0
-        na = params.numerical_aperture
-
-        # Theoretical resolution calculations
-        self.lateral_resolution = 0.61 * wavelength_microns / na
-        self.axial_resolution = 0.5 * wavelength_microns / (na**2)
-
-        # Pinhole transmission calculation
-        # Airy disk radius calculation
-        self.airy_radius = 1.22 * wavelength_microns / (2 * na)
-
-        # Transmission through pinhole
-        def pinhole_transmission(z):
-            """
-            Calculate pinhole transmission as a function of z-position.
-            Uses an error function to model smooth transition.
-            """
-            # Normalized z-position relative to focal plane
-            z_norm = z / self.axial_resolution
-
-            # Smooth transition function
-            return 0.5 * (1 + np.tanh(-z_norm))
-
-        self.pinhole_transmission = pinhole_transmission
-
-        # print("Confocal Microscopy Configuration:")
-        # print(f"  Scanning Mode: {scanning_mode}")
-        # print(f"  Pinhole Diameter: {pinhole_diameter:.2f} µm")
-        # print(f"  Lateral Resolution: {self.lateral_resolution:.3f} µm")
-        # print(f"  Axial Resolution: {self.axial_resolution:.3f} µm")
-        # print(f"  Airy Disk Radius: {self.airy_radius:.3f} µm")
-
-    def calculate_intensity(
-        self,
-        x: np.ndarray | float,
-        y: np.ndarray | float,
-        z: np.ndarray | float,
-        t: float,
-    ) -> np.ndarray:
-        """
-        Calculate the confocal illumination intensity distribution.
-
-        Args:
-            x: X coordinates in microns (3D array)
-            y: Y coordinates in microns (3D array)
-            z: Z coordinates in microns (3D array)
-            t: Time in seconds
-
-        Returns:
-            3D array of intensities in W/µm²
-        """
-        # Get time-dependent parameters
-        power = self.params.get_power(t)
-        pos = self.params.get_position(t)
-
-        # Shift coordinates based on current beam position
-        x_shifted = x - pos[0]
-        y_shifted = y - pos[1]
-        z_shifted = z - pos[2]
-
-        # Base beam parameters
-        w0 = self.params.beam_width  # Beam waist
-        zR = self.params.rayleigh_range  # Rayleigh range
-
-        # Calculate beam width at z
-        w_z = w0 * np.sqrt(1 + (z_shifted / zR) ** 2)
-
-        # Peak intensity calculation
-        I0 = 2 * power / (np.pi * w0**2)
-
-        # Scanning mode intensity modification
-        if self.scanning_mode == "point":
-            # Point scanning: standard Gaussian beam
-            radial_intensity = (
-                I0
-                * (w0 / w_z) ** 2
-                * np.exp(-2 * (x_shifted**2 + y_shifted**2) / w_z**2)
-            )
-        elif self.scanning_mode == "line":
-            # Line scanning: different intensity distribution
-            if self.line_orientation == "horizontal":
-                line_intensity = (
-                    I0 * (w0 / w_z) ** 2 * np.exp(-2 * y_shifted**2 / w_z**2)
-                )
-                radial_intensity = line_intensity
-            else:  # vertical line scanning
-                line_intensity = (
-                    I0 * (w0 / w_z) ** 2 * np.exp(-2 * x_shifted**2 / w_z**2)
-                )
-                radial_intensity = line_intensity
-        else:
-            raise ValueError(f"Unknown scanning mode: {self.scanning_mode}")
-
-        # Pinhole transmission effect
-        pinhole_effect = self.pinhole_transmission(z_shifted)
-
-        # Final intensity calculation
-        return radial_intensity * pinhole_effect

AMS_BP/optics/lasers/scanning_patterns.py

@@ -0,0 +1,102 @@
+import math
+from functools import partial
+from typing import Callable, List, Tuple
+
+import numpy as np
+
+"""Currently unused module"""
+
+
+def plane_point_scan(
+    x_lims: List[float],
+    y_lims: List[float],
+    step_xy: float,
+) -> np.ndarray:
+    """
+    Generate a point scanning pattern for a confocal microscope plane scan.
+
+    Args:
+        x_lims (List[float]): [min_x, max_x] scanning limits in x direction
+        y_lims (List[float]): [min_y, max_y] scanning limits in y direction
+        step_xy (float): Step size between points in both x and y directions
+
+    Returns:
+        np.ndarray: Array of shape (n_points, 2) containing [x, y] coordinates for the scan
+    """
+    # Calculate number of points in each dimension
+    nx = math.ceil((x_lims[1] - x_lims[0]) / step_xy) + 1
+    ny = math.ceil((y_lims[1] - y_lims[0]) / step_xy) + 1
+
+    # Generate coordinate arrays
+    x = np.linspace(x_lims[0], x_lims[1], nx)
+    y = np.linspace(y_lims[0], y_lims[1], ny)
+
+    # Create meshgrid for all coordinates
+    xx, yy = np.meshgrid(x, y)
+
+    # Convert to scan pattern array
+    # For even rows, reverse x direction for serpentine scan
+    scan_points = []
+    for i in range(ny):
+        row_x = xx[i]
+        row_y = yy[i]
+
+        if i % 2 == 1:  # Reverse even rows for serpentine pattern
+            row_x = row_x[::-1]
+
+        points = np.column_stack((row_x, row_y))
+        scan_points.append(points)
+
+    # Combine all points into final array
+    scan_pattern = np.vstack(scan_points)
+
+    return scan_pattern
+
+
+def confocal_pointscan_time_z(
+    x_lims: List[float],
+    y_lims: List[float],
+    step_xy: float,  # can be defined as the beam width at the focus plane
+    frame_exposure_time: float,  # s
+) -> Tuple[Callable[[float, float], Tuple[float, float, float]], float]:
+    scan_pattern = plane_point_scan(x_lims=x_lims, y_lims=y_lims, step_xy=step_xy)
+    scan_pattern_len = len(scan_pattern)
+
+    dwell_time = frame_exposure_time / scan_pattern_len
+
+    def return_laser_position(
+        z_position: float, time: float
+    ) -> Tuple[float, float, float]:
+        index_frame = time % frame_exposure_time
+        ind = int(index_frame / dwell_time)
+        # print(index_frame, ind)
+        return (*scan_pattern[ind], z_position)
+
+    return return_laser_position, dwell_time
+
+
+def confocal_pointscan_time_z0(
+    x_lims: List[float],
+    y_lims: List[float],
+    step_xy: float,  # can be defined as the beam width at the focus plane
+    frame_exposure_time: float,  # s
+    z_val: float,  # um
+) -> Tuple[Callable[[float], Tuple[float, float, float]], float]:
+    """
+    Create a generator for a point scanning pattern for a confocal microscope plane scan which takes in a time and returns the postion of the laser.
+
+    Args:
+        x_lims (List[float]): [min_x, max_x] scanning limits in x direction
+        y_lims (List[float]): [min_y, max_y] scanning limits in y direction
+        step_xy (float): Step size between points in both x and y directions
+        frame_exposure_time (float): exposure time of the frame
+        z_val (float): z value of the sample plane
+
+    Returns:
+        Callable[time]: (x,y,z) position of the laser
+        dwell_time (float): the dwell time per position
+    """
+    func, dwell_time = confocal_pointscan_time_z(
+        x_lims, y_lims, step_xy, frame_exposure_time
+    )
+    return partial(func, z_val), dwell_time

AMS_BP/optics/psf/psf_engine.py

@@ -85,15 +85,19 @@ class PSFEngine:
         self._grid_xy = _generate_grid(self._psf_size, self.params.pixel_size)
 
         # Pre-calculate normalized sigma values
-        self._norm_sigma_xy = self._sigma_xy / 2.355
-        self._norm_sigma_z = self._sigma_z / 2.355
+        self._norm_sigma_xy = self._sigma_xy / 2.0
+        self._norm_sigma_z = self._sigma_z / 2.0
 
         # Generate pinhole mask if specified
         if self.params.pinhole_radius is not None:
             if self.params.pinhole_radius < AIRYFACTOR * self._sigma_xy:
-                raise ValueError(
+                RuntimeWarning(
                     f"Pinhole size ({self.params.pinhole_radius} um) is smaller than {AIRYFACTOR} times the Airy lobe. This will diffract the emission light in the pinhole; an ideal pinhole size for this setup is {self._sigma_xy} um."
                 )
+                #
+                # raise ValueError(
+                #     f"Pinhole size ({self.params.pinhole_radius} um) is smaller than {AIRYFACTOR} times the Airy lobe. This will diffract the emission light in the pinhole; an ideal pinhole size for this setup is {self._sigma_xy} um."
+                # )
             self._pinhole_mask = self._generate_pinhole_mask()
         else:
             self._pinhole_mask = None
@@ -116,7 +120,9 @@ class PSFEngine:
         return (r <= self.params.pinhole_radius).astype(np.float64)
 
     @lru_cache(maxsize=128)
-    def psf_z(self, z_val: float) -> NDArray[np.float64]:
+    def psf_z(
+        self, x_val: float, y_val: float, z_val: float, norm_scale: bool = True
+    ) -> NDArray[np.float64]:
         """Calculate the PSF at the detector for a point source at z_val.
 
         This represents how light from a point source at position z_val
@@ -124,17 +130,28 @@ class PSFEngine:
         detector. If a pinhole is present, it spatially filters this pattern.
 
         Args:
+            x_val: x-position of the point source in micrometers
+            y_val: y-position of the point source in micrometers
             z_val: Z-position of the point source in micrometers
 
         Returns:
             2D array containing the light intensity pattern at the detector
         """
         x, y = self._grid_xy
+        sigma_xy_z_squared = (self._norm_sigma_xy**2) * (
+            1 + (z_val / self._norm_sigma_z) ** 2
+        )
 
         # Calculate how light from the point source diffracts through collection optics
-        r_squared = (x / self._norm_sigma_xy) ** 2 + (y / self._norm_sigma_xy) ** 2
-        z_term = (z_val / self._norm_sigma_z) ** 2
-        psf_at_detector = np.exp(-0.5 * (r_squared + z_term))
+        r_squared = (x - x_val % self.params.pixel_size) ** 2 + (
+            y - y_val % self.params.pixel_size
+        ) ** 2
+        psf_at_detector = np.exp(-0.5 * (r_squared / sigma_xy_z_squared))
+
+        if norm_scale:
+            psf_at_detector = self.normalize_psf(
+                psf_at_detector, mode="sum"
+            ) * self.psf_z_xy0(z_val)
 
         if self._pinhole_mask is not None:
             # Apply pinhole's spatial filtering
@@ -252,7 +269,7 @@ def calculate_psf_size(
         Tuple of dimensions (z,y,x) or (y,x) for the PSF calculation
     """
     # Calculate radius to capture important features (2x Airy radius)
-    r_psf = 2 * sigma_xy
+    r_psf = 3 * sigma_xy
 
     # Convert to pixels and ensure odd number
     pixels_xy = int(np.ceil(r_psf / pixel_size))

AMS_BP/photophysics/photon_physics.py

@@ -168,11 +168,11 @@ class incident_photons:
                 photons_n = self.transmission_photon_rate.values[i] * dt
                 photons += photons_n
                 psf_gen = (
-                    self.generator[i].normalize_psf(
-                        self.generator[i].psf_z(z_val=self.position[2]),
-                        mode="sum",
+                    self.generator[i].psf_z(
+                        x_val=self.position[0],
+                        y_val=self.position[1],
+                        z_val=self.position[2],
                     )
-                    * self.generator[i].psf_z_xy0(z_val=self.position[2])
                     * photons_n
                 )
 

AMS_BP/photophysics/state_kinetics.py

@@ -27,6 +27,7 @@ class StateTransitionCalculator:
         self.current_global_time = current_global_time  # ms (oversample motion time)
         self.laser_intensity_generator = laser_intensity_generator
         self.fluorescent_state_history = {}  # {fluorescent.state.name : [delta time (seconds), laser_intensites], ...}
+        self.current_global_time_s = self.current_global_time * 1e-3
 
     def __call__(
         self,
@@ -44,13 +45,33 @@ class StateTransitionCalculator:
                 self.fluorescent_state_history[i.name] = [0, laser_intensities]
         return laser_intensities
 
+    def _get_intensities(self, time_pos: int, time_laser: float) -> dict:
+        laser_intensities = self.laser_intensity_generator(
+            florPos=self.flurophoreobj.position_history[time_pos],
+            time=time_laser,
+        )
+        return laser_intensities
+
     def MCMC(self) -> Tuple[State, ErnoMsg]:
         time = 0
         transitions = self.flurophoreobj.state_history[self.current_global_time][2]
+        if not transitions:
+            self.fluorescent_state_history[
+                self.flurophoreobj.fluorophore.states[
+                    self.flurophoreobj.state_history[self.current_global_time][0].name
+                ]
+            ][0] += self.time_duration
+            return self.flurophoreobj.fluorophore.states[
+                self.flurophoreobj.state_history[self.current_global_time][0].name
+            ], ErnoMsg(success=True)
         final_state_name = transitions[0].from_state
-        laser_intensities = self._initialize_state_hist(self.current_global_time, time)
-
+        laser_intensities = self._initialize_state_hist(
+            self.current_global_time, time + self.current_global_time_s
+        )
         while time < self.time_duration:
+            laser_intensities = self._get_intensities(
+                self.current_global_time, self.current_global_time_s + time
+            )
             stateTransitionMatrixR = [
                 sum(
                     state_transitions.rate()(laser["wavelength"], laser["intensity"])
@@ -59,8 +80,22 @@ class StateTransitionCalculator:
                 for state_transitions in transitions
             ]  # 1/s
             if not stateTransitionMatrixR:
+                if (
+                    self.flurophoreobj.fluorophore.states[final_state_name].state_type
+                    == StateType.FLUORESCENT
+                ):
+                    self.fluorescent_state_history[
+                        self.flurophoreobj.fluorophore.states[final_state_name].name
+                    ][0] += self.time_duration
                 break
             if sum(stateTransitionMatrixR) == 0:
+                if (
+                    self.flurophoreobj.fluorophore.states[final_state_name].state_type
+                    == StateType.FLUORESCENT
+                ):
+                    self.fluorescent_state_history[
+                        self.flurophoreobj.fluorophore.states[final_state_name].name
+                    ][0] += self.time_duration
                 break
 
             # print(final_state_name)