prefab 1.3.0__py3-none-any.whl → 1.4.1__py3-none-any.whl

prefab/geometry.py

@@ -1,23 +1,31 @@
-"""Provides functions for manipulating ndarrays of device geometries."""
+"""
+Functions for manipulating and transforming device geometry arrays.
 
-from typing import Optional
+This module provides utilities for common geometric operations on numpy arrays
+representing device geometries, including normalization, binarization, trimming,
+padding, blurring, rotation, morphological operations (erosion/dilation), and
+flattening. All functions operate on npt.NDArray[np.float64] arrays.
+"""
+
+from typing import cast
 
 import cv2
 import numpy as np
+import numpy.typing as npt
 
 
-def normalize(device_array: np.ndarray) -> np.ndarray:
+def normalize(device_array: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
     """
     Normalize the input ndarray to have values between 0 and 1.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be normalized.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The normalized array with values scaled between 0 and 1.
     """
     return (device_array - np.min(device_array)) / (
@@ -26,14 +34,14 @@ def normalize(device_array: np.ndarray) -> np.ndarray:
 
 
 def binarize(
-    device_array: np.ndarray, eta: float = 0.5, beta: float = np.inf
-) -> np.ndarray:
+    device_array: npt.NDArray[np.float64], eta: float = 0.5, beta: float = np.inf
+) -> npt.NDArray[np.float64]:
     """
     Binarize the input ndarray based on a threshold and a scaling factor.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be binarized.
     eta : float
         The threshold value for binarization. Defaults to 0.5.
@@ -43,15 +51,19 @@ def binarize(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The binarized array with elements scaled to 0 or 1.
     """
-    return (np.tanh(beta * eta) + np.tanh(beta * (device_array - eta))) / (
-        np.tanh(beta * eta) + np.tanh(beta * (1 - eta))
+    return cast(
+        npt.NDArray[np.float64],
+        (np.tanh(beta * eta) + np.tanh(beta * (device_array - eta)))
+        / (np.tanh(beta * eta) + np.tanh(beta * (1 - eta))),
     )
 
 
-def binarize_hard(device_array: np.ndarray, eta: float = 0.5) -> np.ndarray:
+def binarize_hard(
+    device_array: npt.NDArray[np.float64], eta: float = 0.5
+) -> npt.NDArray[np.float64]:
     """
     Apply a hard threshold to binarize the input ndarray. The `binarize` function is
     generally preferred for most use cases, but it can create numerical artifacts for
@@ -59,46 +71,24 @@ def binarize_hard(device_array: np.ndarray, eta: float = 0.5) -> np.ndarray:
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be binarized.
     eta : float
         The threshold value for binarization. Defaults to 0.5.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The binarized array with elements set to 0 or 1 based on the threshold.
     """
     return np.where(device_array < eta, 0.0, 1.0)
 
 
-def binarize_sem(sem_array: np.ndarray) -> np.ndarray:
-    """
-    Binarize a grayscale scanning electron microscope (SEM) image.
-
-    This function applies Otsu's method to automatically determine the optimal threshold
-    value for binarization of a grayscale SEM image.
-
-    Parameters
-    ----------
-    sem_array : np.ndarray
-        The input SEM image array to be binarized.
-
-    Returns
-    -------
-    np.ndarray
-        The binarized SEM image array with elements scaled to 0 or 1.
-    """
-    return cv2.threshold(
-        sem_array.astype("uint8"), 0, 1, cv2.THRESH_BINARY + cv2.THRESH_OTSU
-    )[1]
-
-
-def binarize_monte_carlo(
-    device_array: np.ndarray,
+def binarize_with_roughness(
+    device_array: npt.NDArray[np.float64],
     noise_magnitude: float,
     blur_radius: float,
-) -> np.ndarray:
+) -> npt.NDArray[np.float64]:
     """
     Binarize the input ndarray using a dynamic thresholding approach to simulate surface
     roughness.
@@ -116,7 +106,7 @@ def binarize_monte_carlo(
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be binarized.
     noise_magnitude : float
         The standard deviation of the Gaussian distribution used to generate noise for
@@ -127,35 +117,35 @@ def binarize_monte_carlo(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The binarized array with elements set to 0 or 1 based on the dynamically
         generated threshold.
     """
     device_array = np.squeeze(device_array)
-    base_threshold = np.random.normal(loc=0.5, scale=0.1)
-    base_threshold = np.clip(base_threshold, 0.2, 0.8)
+    base_threshold_raw = float(np.random.normal(loc=0.5, scale=0.1))
+    base_threshold = max(0.2, min(base_threshold_raw, 0.8))
     threshold_noise = np.random.normal(
         loc=0, scale=noise_magnitude, size=device_array.shape
     )
-    spatial_threshold = cv2.GaussianBlur(
+    spatial_threshold: npt.NDArray[np.float64] = cv2.GaussianBlur(
         threshold_noise, ksize=(0, 0), sigmaX=blur_radius
-    )
-    dynamic_threshold = base_threshold + spatial_threshold
+    ).astype(np.float64)
+    dynamic_threshold: npt.NDArray[np.float64] = base_threshold + spatial_threshold
     binarized_array = np.where(device_array < dynamic_threshold, 0.0, 1.0)
     binarized_array = np.expand_dims(binarized_array, axis=-1)
     return binarized_array
 
 
 def ternarize(
-    device_array: np.ndarray, eta1: float = 1 / 3, eta2: float = 2 / 3
-) -> np.ndarray:
+    device_array: npt.NDArray[np.float64], eta1: float = 1 / 3, eta2: float = 2 / 3
+) -> npt.NDArray[np.float64]:
     """
     Ternarize the input ndarray based on two thresholds. This function is useful for
     flattened devices with angled sidewalls (i.e., three segments).
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be ternarized.
     eta1 : float
         The first threshold value for ternarization. Defaults to 1/3.
@@ -164,21 +154,22 @@ def ternarize(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The ternarized array with elements set to 0, 0.5, or 1 based on the thresholds.
     """
     return np.where(device_array < eta1, 0.0, np.where(device_array >= eta2, 1.0, 0.5))
 
 
 def trim(
-    device_array: np.ndarray, buffer_thickness: Optional[dict[str, int]] = None
-) -> np.ndarray:
+    device_array: npt.NDArray[np.float64],
+    buffer_thickness: dict[str, int] | None = None,
+) -> npt.NDArray[np.float64]:
     """
     Trim the input ndarray by removing rows and columns that are completely zero.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be trimmed.
     buffer_thickness : Optional[dict[str, int]]
         A dictionary specifying the thickness of the buffer to leave around the non-zero
@@ -187,22 +178,28 @@ def trim(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The trimmed array, potentially with a buffer around the non-zero elements.
     """
     if buffer_thickness is None:
         buffer_thickness = {"top": 0, "bottom": 0, "left": 0, "right": 0}
 
-    nonzero_rows, nonzero_cols = np.nonzero(np.squeeze(device_array))
-    row_min = max(nonzero_rows.min() - buffer_thickness.get("top", 0), 0)
+    nonzero_indices = np.nonzero(np.squeeze(device_array))
+    nonzero_rows = nonzero_indices[0]
+    nonzero_cols = nonzero_indices[1]
+
+    row_min_val = int(nonzero_rows.min())
+    row_max_val = int(nonzero_rows.max())
+    col_min_val = int(nonzero_cols.min())
+    col_max_val = int(nonzero_cols.max())
+
+    row_min = max(row_min_val - buffer_thickness.get("top", 0), 0)
     row_max = min(
-        nonzero_rows.max() + buffer_thickness.get("bottom", 0) + 1,
-        device_array.shape[0],
+        row_max_val + buffer_thickness.get("bottom", 0) + 1, device_array.shape[0]
     )
-    col_min = max(nonzero_cols.min() - buffer_thickness.get("left", 0), 0)
+    col_min = max(col_min_val - buffer_thickness.get("left", 0), 0)
     col_max = min(
-        nonzero_cols.max() + buffer_thickness.get("right", 0) + 1,
-        device_array.shape[1],
+        col_max_val + buffer_thickness.get("right", 0) + 1, device_array.shape[1]
     )
     return device_array[
         row_min:row_max,
@@ -210,20 +207,22 @@ def trim(
     ]
 
 
-def pad(device_array: np.ndarray, pad_width: int) -> np.ndarray:
+def pad(
+    device_array: npt.NDArray[np.float64], pad_width: int
+) -> npt.NDArray[np.float64]:
     """
     Pad the input ndarray uniformly with a specified width on all sides.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be padded.
     pad_width : int
         The number of pixels to pad on each side.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The padded array.
     """
     return np.pad(
@@ -234,13 +233,15 @@ def pad(device_array: np.ndarray, pad_width: int) -> np.ndarray:
     )
 
 
-def blur(device_array: np.ndarray, sigma: float = 1.0) -> np.ndarray:
+def blur(
+    device_array: npt.NDArray[np.float64], sigma: float = 1.0
+) -> npt.NDArray[np.float64]:
     """
     Apply Gaussian blur to the input ndarray and normalize the result.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be blurred.
     sigma : float
         The standard deviation for the Gaussian kernel. This controls the amount of
@@ -248,21 +249,28 @@ def blur(device_array: np.ndarray, sigma: float = 1.0) -> np.ndarray:
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The blurred and normalized array with values scaled between 0 and 1.
     """
     return np.expand_dims(
-        normalize(cv2.GaussianBlur(device_array, ksize=(0, 0), sigmaX=sigma)), axis=-1
+        normalize(
+            cv2.GaussianBlur(device_array, ksize=(0, 0), sigmaX=sigma).astype(
+                np.float64
+            )
+        ),
+        axis=-1,
     )
 
 
-def rotate(device_array: np.ndarray, angle: float) -> np.ndarray:
+def rotate(
+    device_array: npt.NDArray[np.float64], angle: float
+) -> npt.NDArray[np.float64]:
     """
     Rotate the input ndarray by a given angle.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be rotated.
     angle : float
         The angle of rotation in degrees. Positive values mean counter-clockwise
@@ -270,7 +278,7 @@ def rotate(device_array: np.ndarray, angle: float) -> np.ndarray:
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The rotated array.
     """
     center = (device_array.shape[1] / 2, device_array.shape[0] / 2)
@@ -280,116 +288,73 @@ def rotate(device_array: np.ndarray, angle: float) -> np.ndarray:
             device_array,
             M=rotation_matrix,
             dsize=(device_array.shape[1], device_array.shape[0]),
-        ),
+        ).astype(np.float64),
         axis=-1,
     )
 
 
-def erode(device_array: np.ndarray, kernel_size: int) -> np.ndarray:
+def erode(
+    device_array: npt.NDArray[np.float64], kernel_size: int
+) -> npt.NDArray[np.float64]:
     """
     Erode the input ndarray using a specified kernel size and number of iterations.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array representing the device geometry to be eroded.
     kernel_size : int
         The size of the kernel used for erosion.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The eroded array.
     """
     kernel = np.ones((kernel_size, kernel_size), dtype=np.uint8)
-    return np.expand_dims(cv2.erode(device_array, kernel=kernel), axis=-1)
+    return np.expand_dims(
+        cv2.erode(device_array, kernel=kernel).astype(np.float64), axis=-1
+    )
 
 
-def dilate(device_array: np.ndarray, kernel_size: int) -> np.ndarray:
+def dilate(
+    device_array: npt.NDArray[np.float64], kernel_size: int
+) -> npt.NDArray[np.float64]:
     """
     Dilate the input ndarray using a specified kernel size.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array representing the device geometry to be dilated.
     kernel_size : int
         The size of the kernel used for dilation.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The dilated array.
     """
     kernel = np.ones((kernel_size, kernel_size), dtype=np.uint8)
-    return np.expand_dims(cv2.dilate(device_array, kernel=kernel), axis=-1)
+    return np.expand_dims(
+        cv2.dilate(device_array, kernel=kernel).astype(np.float64), axis=-1
+    )
 
 
-def flatten(device_array: np.ndarray) -> np.ndarray:
+def flatten(device_array: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
     """
     Flatten the input ndarray by summing the vertical layers and normalizing the result.
 
     Parameters
     ----------
-    device_array : np.ndarray
+    device_array : npt.NDArray[np.float64]
         The input array to be flattened.
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float64]
         The flattened array with values scaled between 0 and 1.
     """
-    return normalize(np.sum(device_array, axis=-1, keepdims=True))
-
-
-def enforce_feature_size(
-    device_array: np.ndarray, min_feature_size: int, strel: str = "disk"
-) -> np.ndarray:
-    """
-    Enforce a minimum feature size on the device geometry.
-
-    This function applies morphological operations to ensure that all features in the
-    device geometry are at least the specified minimum size. It uses either a disk
-    or square structuring element for the operations.
-
-    Notes
-    -----
-    This function does not guarantee that the minimum feature size is enforced in all
-    cases. A better process is needed.
-
-    Parameters
-    ----------
-    device_array : np.ndarray
-        The input array representing the device geometry.
-    min_feature_size : int
-        The minimum feature size to enforce, in nanometers.
-    strel : str
-        The type of structuring element to use. Can be either "disk" or "square".
-        Defaults to "disk".
-
-    Returns
-    -------
-    np.ndarray
-        The modified device array with enforced feature size.
-
-    Raises
-    ------
-    ValueError
-        If an invalid structuring element type is specified.
-    """
-    if strel == "disk":
-        kernel = cv2.getStructuringElement(
-            cv2.MORPH_ELLIPSE, (min_feature_size, min_feature_size)
-        )
-    elif strel == "square":
-        kernel = cv2.getStructuringElement(
-            cv2.MORPH_RECT, (min_feature_size, min_feature_size)
-        )
-    else:
-        raise ValueError(f"Invalid structuring element: {strel}")
-
-    device_array_2d = (device_array[:, :, 0] * 255).astype(np.uint8)
-    modified_geometry = cv2.morphologyEx(device_array_2d, cv2.MORPH_CLOSE, kernel)
-    modified_geometry = cv2.morphologyEx(modified_geometry, cv2.MORPH_OPEN, kernel)
-
-    return np.expand_dims(modified_geometry.astype(float) / 255, axis=-1)
+    return normalize(
+        cast(npt.NDArray[np.float64], np.sum(device_array, axis=-1, keepdims=True))
+    )

prefab/models/__init__.py

@@ -0,0 +1,57 @@
+"""
+Fabrication process model definitions and configurations.
+
+This module automatically discovers and loads all model definitions from
+Python files in the models/ directory.
+"""
+
+import importlib
+from pathlib import Path
+
+from .base import Fab, Model
+
+models = {}
+
+
+def _load_models_from_module(module):
+    """
+    Load all Model instances from a module into the models dict.
+
+    If the module defines a __models__ dict, use that for registration.
+    Otherwise, auto-register all Model instances using their variable names.
+
+    Parameters
+    ----------
+    module : module
+        Python module containing Model instances to register.
+    """
+    if hasattr(module, "__models__"):
+        models_dict = getattr(module, "__models__")
+        for name, obj in models_dict.items():
+            if isinstance(obj, Model):
+                models[name] = obj
+    else:
+        for name, obj in vars(module).items():
+            if isinstance(obj, Model):
+                models[name] = obj
+
+
+models_dir = Path(__file__).parent
+
+for model_file in models_dir.glob("*.py"):
+    if model_file.stem in ("__init__", "base"):
+        continue
+
+    module_name = f".{model_file.stem}"
+    try:
+        module = importlib.import_module(module_name, package=__package__)
+        _load_models_from_module(module)
+    except Exception:
+        pass
+
+
+__all__ = [
+    "Fab",
+    "Model",
+    "models",
+]

prefab/models/base.py

@@ -0,0 +1,63 @@
+"""
+Base model definitions for fabrication processes.
+
+This module defines the core data structures for representing nanofabrication
+processes and their associated models.
+"""
+
+import json
+from datetime import date
+
+from pydantic import BaseModel
+
+
+class Fab(BaseModel):
+    """
+    Represents a fabrication process in the PreFab model library.
+
+    Attributes
+    ----------
+    foundry : str
+        The name of the foundry where the fabrication process takes place.
+    process : str
+        The specific process used in the fabrication.
+    """
+
+    foundry: str
+    process: str
+
+
+class Model(BaseModel):
+    """
+    Represents a model of a fabrication process including versioning and dataset detail.
+
+    Attributes
+    ----------
+    fab : Fab
+        An instance of the Fab class representing the fabrication details.
+    version : str
+        The version identifier of the model.
+    version_date : date
+        The release date of this version of the model.
+    dataset : str
+        The identifier for the dataset used in this model.
+    dataset_date : date
+        The date when the dataset was last updated or released.
+    tag : str
+        An optional tag for additional categorization or notes.
+
+    Methods
+    -------
+    to_json()
+        Serializes the model instance to a JSON formatted string.
+    """
+
+    fab: Fab
+    version: str
+    version_date: date
+    dataset: str
+    dataset_date: date
+    tag: str
+
+    def to_json(self):
+        return json.dumps(self.model_dump(), default=str)

prefab/models/evaluation.py

@@ -0,0 +1,29 @@
+"""
+Base evaluation models.
+
+Pre-configured model instances for common fabrication processes.
+"""
+
+from datetime import date
+
+from .base import Fab, Model
+
+
+Generic = Fab(
+    foundry="Generic",
+    process="SOI",
+)
+
+Generic_SOI_ANF1_d0 = Model(
+    fab=Generic,
+    version="ANF1",
+    version_date=date(2025, 11, 7),
+    dataset="d0",
+    dataset_date=date(2025, 11, 7),
+    tag="",
+)
+
+# Export models with user-facing names
+__models__ = {
+    "Generic_SOI": Generic_SOI_ANF1_d0,
+}