prefab 0.5.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

prefab/geometry.py

@@ -0,0 +1,302 @@
+"""Provides functions for manipulating ndarrays of device geometries."""
+
+import cv2
+import numpy as np
+
+
+def normalize(device_array: np.ndarray) -> np.ndarray:
+    """
+    Normalize the input ndarray to have values between 0 and 1.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be normalized.
+
+    Returns
+    -------
+    np.ndarray
+        The normalized array with values scaled between 0 and 1.
+    """
+    return (device_array - np.min(device_array)) / (
+        np.max(device_array) - np.min(device_array)
+    )
+
+
+def binarize(
+    device_array: np.ndarray, eta: float = 0.5, beta: float = np.inf
+) -> np.ndarray:
+    """
+    Binarize the input ndarray based on a threshold and a scaling factor.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be binarized.
+    eta : float, optional
+        The threshold value for binarization. Defaults to 0.5.
+    beta : float, optional
+        The scaling factor for the binarization process. A higher value makes the
+        transition sharper. Defaults to np.inf, which results in a hard threshold.
+
+    Returns
+    -------
+    np.ndarray
+        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))
+    )
+
+
+def binarize_hard(device_array: np.ndarray, eta: float = 0.5) -> np.ndarray:
+    """
+    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
+    large beta values.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be binarized.
+    eta : float, optional
+        The threshold value for binarization. Defaults to 0.5.
+
+    Returns
+    -------
+    np.ndarray
+        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,
+    threshold_noise_std: float,
+    threshold_blur_std: float,
+) -> np.ndarray:
+    """
+    Binarize the input ndarray using a Monte Carlo approach with Gaussian blurring.
+
+    This function applies a dynamic thresholding technique where the threshold value is
+    determined by a base value perturbed by Gaussian-distributed random noise. The
+    threshold is then spatially varied across the array using Gaussian blurring,
+    simulating a potentially more realistic scenario where the threshold is not uniform
+    across the device.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be binarized.
+    threshold_noise_std : float
+        The standard deviation of the Gaussian distribution used to generate noise for
+        the threshold values. This controls the amount of randomness in the threshold.
+    threshold_blur_std : float
+        The standard deviation for the Gaussian kernel used in blurring the threshold
+        map. This controls the spatial variation of the threshold across the array.
+
+    Returns
+    -------
+    np.ndarray
+        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.clip(np.random.normal(loc=0.5, scale=0.5 / 2), 0.4, 0.6)
+    threshold_noise = np.random.normal(
+        loc=0, scale=threshold_noise_std, size=device_array.shape
+    )
+    spatial_threshold = cv2.GaussianBlur(
+        threshold_noise, ksize=(0, 0), sigmaX=threshold_blur_std
+    )
+    dynamic_threshold = 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:
+    """
+    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
+        The input array to be ternarized.
+    eta1 : float, optional
+        The first threshold value for ternarization. Defaults to 1/3.
+    eta2 : float, optional
+        The second threshold value for ternarization. Defaults to 2/3.
+
+    Returns
+    -------
+    np.ndarray
+        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: int = 0) -> np.ndarray:
+    """
+    Trim the input ndarray by removing rows and columns that are completely zero.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be trimmed.
+    buffer_thickness : int, optional
+        The thickness of the buffer to leave around the non-zero elements of the array.
+        Defaults to 0, which means no buffer is added.
+
+    Returns
+    -------
+    np.ndarray
+        The trimmed array, potentially with a buffer around the non-zero elements.
+    """
+    flattened_device_array = np.squeeze(flatten(device_array))
+    nonzero_rows, nonzero_cols = np.nonzero(flattened_device_array)
+    row_min = max(nonzero_rows.min() - buffer_thickness, 0)
+    row_max = min(
+        nonzero_rows.max() + buffer_thickness + 1,
+        device_array.shape[0],
+    )
+    col_min = max(nonzero_cols.min() - buffer_thickness, 0)
+    col_max = min(
+        nonzero_cols.max() + buffer_thickness + 1,
+        device_array.shape[1],
+    )
+    return device_array[
+        row_min:row_max,
+        col_min:col_max,
+    ]
+
+
+def blur(device_array: np.ndarray, sigma: float = 1.0) -> np.ndarray:
+    """
+    Apply Gaussian blur to the input ndarray and normalize the result.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be blurred.
+    sigma : float, optional
+        The standard deviation for the Gaussian kernel. This controls the amount of
+        blurring. Defaults to 1.0.
+
+    Returns
+    -------
+    np.ndarray
+        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
+    )
+
+
+def rotate(device_array: np.ndarray, angle: float) -> np.ndarray:
+    """
+    Rotate the input ndarray by a given angle.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be rotated.
+    angle : float
+        The angle of rotation in degrees. Positive values mean counter-clockwise
+        rotation.
+
+    Returns
+    -------
+    np.ndarray
+        The rotated array.
+    """
+    center = (device_array.shape[1] / 2, device_array.shape[0] / 2)
+    rotation_matrix = cv2.getRotationMatrix2D(center=center, angle=angle, scale=1)
+    rotated_device_array = cv2.warpAffine(
+        flatten(device_array),
+        M=rotation_matrix,
+        dsize=(device_array.shape[1], device_array.shape[0]),
+    )
+    return np.expand_dims(rotated_device_array, axis=-1)
+
+
+def erode(device_array: np.ndarray, kernel_size: int) -> np.ndarray:
+    """
+    Erode the input ndarray using a specified kernel size and number of iterations.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array representing the device geometry to be eroded.
+    kernel_size : int
+        The size of the kernel used for erosion.
+
+    Returns
+    -------
+    np.ndarray
+        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)
+
+
+def dilate(device_array: np.ndarray, kernel_size: int) -> np.ndarray:
+    """
+    Dilate the input ndarray using a specified kernel size.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array representing the device geometry to be dilated.
+    kernel_size : int
+        The size of the kernel used for dilation.
+
+    Returns
+    -------
+    np.ndarray
+        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)
+
+
+def flatten(device_array: np.ndarray) -> np.ndarray:
+    """
+    Flatten the input ndarray by summing the vertical layers and normalizing the result.
+
+    Parameters
+    ----------
+    device_array : np.ndarray
+        The input array to be flattened.
+
+    Returns
+    -------
+    np.ndarray
+        The flattened array with values scaled between 0 and 1.
+    """
+    return normalize(np.sum(device_array, axis=-1, keepdims=True))

prefab/models.py

@@ -0,0 +1,114 @@
+"""Models for the PreFab library."""
+
+import json
+from datetime import date
+
+from pydantic import BaseModel
+
+
+class Fab(BaseModel):
+    """
+    Represents a fabrication process in the PreFab model library.
+
+    Parameters
+    ----------
+    foundry : str
+        The name of the foundry where the fabrication process takes place.
+    process : str
+        The specific process used in the fabrication.
+    material : str
+        The material used in the fabrication process.
+    technology : str
+        The technology used in the fabrication process.
+    thickness : int
+        The thickness of the material used, measured in nanometers.
+    has_sidewall : bool
+        Indicates whether the fabrication has angled sidewalls.
+    """
+
+    foundry: str
+    process: str
+    material: str
+    technology: str
+    thickness: int
+    has_sidewall: bool
+
+
+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.dict(), default=str)
+
+
+ANT_NanoSOI = Fab(
+    foundry="ANT",
+    process="NanoSOI",
+    material="SOI",
+    technology="E-Beam",
+    thickness=220,
+    has_sidewall=False,
+)
+
+ANT_SiN = Fab(
+    foundry="ANT",
+    process="SiN",
+    material="SiN",
+    technology="E-Beam",
+    thickness=400,
+    has_sidewall=True,
+)
+
+ANT_NanoSOI_ANF1_d9 = Model(
+    fab=ANT_NanoSOI,
+    version="ANF1",
+    version_date=date(2024, 5, 6),
+    dataset="d9",
+    dataset_date=date(2024, 2, 6),
+    tag="",
+)
+
+ANT_SiN_ANF1_d1 = Model(
+    fab=ANT_SiN,
+    version="ANF1",
+    version_date=date(2024, 5, 6),
+    dataset="d1",
+    dataset_date=date(2024, 1, 31),
+    tag="",
+)
+
+models = dict(
+    ANT_NanoSOI=ANT_NanoSOI_ANF1_d9,
+    ANT_NanoSOI_ANF1_d9=ANT_NanoSOI_ANF1_d9,
+    ANT_SiN=ANT_SiN_ANF1_d1,
+    ANT_SiN_ANF1_d1=ANT_SiN_ANF1_d1,
+)

prefab/read.py

@@ -0,0 +1,293 @@
+"""Provides functions to create Devices from various data sources."""
+
+import re
+
+import cv2
+import gdstk
+import numpy as np
+
+from . import geometry
+from .device import Device
+
+
+def from_ndarray(
+    ndarray: np.ndarray, resolution: int = 1, binarize: bool = True, **kwargs
+) -> Device:
+    """
+    Create a Device from an ndarray.
+
+    Parameters
+    ----------
+    ndarray : np.ndarray
+        The input array representing the device layout.
+    resolution : int, optional
+        The resolution of the ndarray in nanometers per pixel, defaulting to 1 nm per
+        pixel. If specified, the input array will be resized based on this resolution to
+        match the desired physical size.
+    binarize : bool, optional
+        If True, the input array will be binarized (converted to binary values) before
+        conversion to a Device object. This is useful for processing grayscale images
+        into binary masks. Defaults to True.
+    **kwargs
+        Additional keyword arguments to be passed to the Device constructor.
+
+    Returns
+    -------
+    Device
+        A Device object representing the input array, after optional resizing and
+        binarization.
+    """
+    device_array = ndarray
+    device_array = cv2.resize(device_array, dsize=(0, 0), fx=resolution, fy=resolution)
+    if binarize:
+        device_array = geometry.binarize_hard(device_array)
+    return Device(device_array=device_array, **kwargs)
+
+
+def from_img(
+    img_path: str, img_width_nm: int = None, binarize: bool = True, **kwargs
+) -> Device:
+    """
+    Create a Device from an image file.
+
+    Parameters
+    ----------
+    img_path : str
+        The path to the image file to be converted into a Device object.
+    img_width_nm : int, optional
+        The desired width of the device in nanometers. If specified, the image will be
+        resized to this width while maintaining aspect ratio. If None, no resizing is
+        performed.
+    binarize : bool, optional
+        If True, the image will be binarized (converted to binary values) before
+        conversion to a Device object. This is useful for converting grayscale images
+        into binary masks. Defaults to True.
+    **kwargs
+        Additional keyword arguments to be passed to the Device constructor.
+
+    Returns
+    -------
+    Device
+        A Device object representing the processed image, after optional resizing and
+        binarization.
+    """
+    device_array = cv2.imread(img_path, flags=cv2.IMREAD_GRAYSCALE) / 255
+    if img_width_nm is not None:
+        scale = img_width_nm / device_array.shape[1]
+        device_array = cv2.resize(device_array, dsize=(0, 0), fx=scale, fy=scale)
+    if binarize:
+        device_array = geometry.binarize_hard(device_array)
+    return Device(device_array=device_array, **kwargs)
+
+
+def from_gds(
+    gds_path: str,
+    cell_name: str,
+    gds_layer: tuple[int, int] = (1, 0),
+    bounds: tuple[tuple[int, int], tuple[int, int]] = None,
+    **kwargs,
+):
+    """
+    Create a Device from a GDS cell.
+
+    Parameters
+    ----------
+    gds_path : str
+        The file path to the GDS file.
+    cell_name : str
+        The name of the cell within the GDS file to be converted into a Device object.
+    gds_layer : tuple[int, int], optional
+        A tuple specifying the layer and datatype to be used from the GDS file. Defaults
+        to (1, 0).
+    bounds : tuple[tuple[int, int], tuple[int, int]], optional
+        A tuple specifying the bounds for cropping the cell before conversion, formatted
+        as ((min_x, min_y), (max_x, max_y)), in units of the GDS file. If None, the
+        entire cell is used.
+    **kwargs
+        Additional keyword arguments to be passed to the Device constructor.
+
+    Returns
+    -------
+    Device
+        A Device object representing the specified cell from the GDS file, after
+        processing based on the specified layer.
+    """
+    gdstk_library = gdstk.read_gds(gds_path)
+    gdstk_cell = gdstk_library[cell_name]
+    device_array = _gdstk_to_device_array(
+        gdstk_cell=gdstk_cell, gds_layer=gds_layer, bounds=bounds
+    )
+    return Device(device_array=device_array, **kwargs)
+
+
+def from_gdstk(
+    gdstk_cell: gdstk.Cell,
+    gds_layer: tuple[int, int] = (1, 0),
+    bounds: tuple[tuple[int, int], tuple[int, int]] = None,
+    **kwargs,
+):
+    """
+    Create a Device from a gdstk cell.
+
+    Parameters
+    ----------
+    gdstk_cell : gdstk.Cell
+        The gdstk.Cell object to be converted into a Device object.
+    gds_layer : tuple[int, int], optional
+        A tuple specifying the layer and datatype to be used. Defaults to (1, 0).
+    bounds : tuple[tuple[int, int], tuple[int, int]], optional
+        A tuple specifying the bounds for cropping the cell before conversion, formatted
+        as ((min_x, min_y), (max_x, max_y)), in units of the GDS file. If None, the
+        entire cell is used.
+    **kwargs
+        Additional keyword arguments to be passed to the Device constructor.
+
+    Returns
+    -------
+    Device
+        A Device object representing the gdstk.Cell, after processing based on the
+        specified layer.
+    """
+    device_array = _gdstk_to_device_array(
+        gdstk_cell=gdstk_cell, gds_layer=gds_layer, bounds=bounds
+    )
+    return Device(device_array=device_array, **kwargs)
+
+
+def _gdstk_to_device_array(
+    gdstk_cell: gdstk.Cell,
+    gds_layer: tuple[int, int] = (1, 0),
+    bounds: tuple[tuple[int, int], tuple[int, int]] = None,
+) -> np.ndarray:
+    polygons = gdstk_cell.get_polygons(layer=gds_layer[0], datatype=gds_layer[1])
+    if bounds:
+        polygons = gdstk.slice(
+            polygons, position=(bounds[0][0], bounds[1][0]), axis="x"
+        )[1]
+        polygons = gdstk.slice(
+            polygons, position=(bounds[0][1], bounds[1][1]), axis="y"
+        )[1]
+        bounds = tuple(tuple(x * 1000 for x in sub_tuple) for sub_tuple in bounds)
+    else:
+        bounds = tuple(
+            tuple(1000 * x for x in sub_tuple)
+            for sub_tuple in gdstk_cell.bounding_box()
+        )
+    contours = [
+        np.array(
+            [
+                [
+                    [
+                        int(1000 * vertex[0] - bounds[0][0]),
+                        int(1000 * vertex[1] - bounds[0][1]),
+                    ]
+                ]
+                for vertex in polygon.points
+            ],
+            dtype=np.int32,
+        )
+        for polygon in polygons
+    ]
+    device_array = np.zeros(
+        (int(bounds[1][1] - bounds[0][1]), int(bounds[1][0] - bounds[0][0]))
+    )
+    cv2.fillPoly(img=device_array, pts=contours, color=(1, 1, 1))
+    device_array = np.flipud(device_array)
+    return device_array
+
+
+def from_sem(
+    sem_path: str,
+    sem_resolution: float = None,
+    sem_resolution_key: str = None,
+    binarize: bool = True,
+    bounds: tuple[tuple[int, int], tuple[int, int]] = None,
+    **kwargs,
+) -> Device:
+    """
+    Create a Device from a scanning electron microscope (SEM) image file.
+
+    Parameters
+    ----------
+    sem_path : str
+        The file path to the SEM image.
+    sem_resolution : float, optional
+        The resolution of the SEM image in nanometers per pixel. If not provided, it
+        will be extracted from the image metadata using the `sem_resolution_key`.
+    sem_resolution_key : str, optional
+        The key to look for in the SEM image metadata to extract the resolution.
+        Required if `sem_resolution` is not provided.
+    binarize : bool, optional
+        If True, the SEM image will be binarized (converted to binary values) before
+        conversion to a Device object. This is needed for processing grayscale images
+        into binary masks. Defaults to True.
+    bounds : tuple[tuple[int, int], tuple[int, int]], optional
+        A tuple specifying the bounds for cropping the image before conversion,
+        formatted as ((min_x, min_y), (max_x, max_y)). If None, the entire image is
+        used.
+    **kwargs
+        Additional keyword arguments to be passed to the Device constructor.
+
+    Returns
+    -------
+    Device
+        A Device object representing the processed SEM image.
+
+    Raises
+    ------
+    ValueError
+        If neither `sem_resolution` nor `sem_resolution_key` is provided.
+    """
+    if sem_resolution is None and sem_resolution_key is not None:
+        sem_resolution = get_sem_resolution(sem_path, sem_resolution_key)
+    elif sem_resolution is None:
+        raise ValueError("Either sem_resolution or resolution_key must be provided.")
+
+    device_array = cv2.imread(sem_path, flags=cv2.IMREAD_GRAYSCALE)
+    if sem_resolution is not None:
+        device_array = cv2.resize(
+            device_array, dsize=(0, 0), fx=sem_resolution, fy=sem_resolution
+        )
+    if bounds is not None:
+        device_array = device_array[
+            -bounds[1][1] : -bounds[0][1], bounds[0][0] : bounds[1][0]
+        ]
+    if binarize:
+        device_array = geometry.binarize_sem(device_array)
+    return Device(device_array=device_array, **kwargs)
+
+
+def get_sem_resolution(sem_path: str, sem_resolution_key: str) -> float:
+    """
+    Extracts the resolution of a scanning electron microscope (SEM) image from its
+    metadata.
+
+    Parameters
+    ----------
+    sem_path : str
+        The file path to the SEM image.
+    sem_resolution_key : str
+        The key to look for in the SEM image metadata to extract the resolution.
+
+    Returns
+    -------
+    float
+        The resolution of the SEM image in nanometers per pixel.
+
+    Raises
+    ------
+    ValueError
+        If the resolution key is not found in the SEM image metadata.
+    """
+    with open(sem_path, "rb") as file:
+        resolution_key_bytes = sem_resolution_key.encode("utf-8")
+        for line in file:
+            if resolution_key_bytes in line:
+                line_str = line.decode("utf-8")
+                match = re.search(r"-?\d+(\.\d+)?", line_str)
+                if match:
+                    value = float(match.group())
+                    if value > 100:
+                        value /= 1000
+                    return value
+    raise ValueError(f"Resolution key '{sem_resolution_key}' not found in {sem_path}.")