openuv 1.0.0__py3-none-any.whl

euv/__init__.py

@@ -0,0 +1,19 @@
+"""euv — Open Source Extreme Ultraviolet Lithography Simulator
+=============================================================
+
+OpEnUV (Open Source EUV) is a modular, GPU-accelerated simulator for
+extreme ultraviolet (EUV) lithography at 13.5 nm wavelength.
+
+Key capabilities:
+  • Rigorous coupled-wave analysis (RCWA) for mask-3D effects
+  • Transfer-matrix method (TMM) for multilayer mirror optics
+  • Abbe/Hopkins partially coherent imaging at NA 0.33 / 0.55
+  • LPP tin-plasma source model (literature-fitted)
+  • Stochastic resist simulation (CAR/MOR, secondary-electron cascade)
+  • GDSII/OASIS layout import/export
+  • REST API and Python SDK for pipeline integration
+
+License: Apache-2.0
+"""
+
+__version__ = "1.0.0"

euv/accel/__init__.py

@@ -0,0 +1,25 @@
+"""GPU Acceleration Layer — device management, VRAM budgeting, chunked
+processing, and mixed-precision helpers for OpEnUV.
+
+The ``accel`` package decouples simulation code from hardware details,
+providing transparent fallback between CPU and GPU, memory-aware
+workload sizing, and precision policies that maximise throughput on
+consumer GPUs.
+
+Submodules
+----------
+device
+    Device selection, introspection, and default dtype management.
+vram_budget
+    Analytical VRAM estimators for RCWA and Abbe imaging, plus OOM
+    pre-checks and a human-readable budget report.
+chunked
+    Chunked (source-point) Abbe summation and layer-wise RCWA for
+    fitting large problems into available memory.
+mixed_precision
+    Context-aware dtype switching: ``complex64`` vs ``complex128``,
+    ``float32`` vs ``float64``, with per-operation policy
+    recommendations.
+"""
+
+from __future__ import annotations

euv/accel/chunked.py

@@ -0,0 +1,124 @@
+"""Chunked processing kernels for GPU memory-limited simulations.
+
+Processes large problems — many source points (Abbe) or many RCWA
+layers — in batches, accumulating intermediate results on the GPU
+without exceeding the VRAM budget.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from euv.aerial.abbe import abbe_image
+
+
+def chunked_abbe(
+    mask_fft: torch.Tensor,
+    source_points: torch.Tensor,
+    fx: torch.Tensor,
+    fy: torch.Tensor,
+    pupil: torch.Tensor,
+    na: float = 0.33,
+    chunk_size: int = 32,
+    period_m: float = 64e-9,
+    wavelength_m: float = 13.5e-9,
+) -> torch.Tensor:
+    """Compute the aerial image via chunked Abbe summation.
+
+    Iterates over source points in chunks of *chunk_size*, computing
+    the partial coherent image for each chunk and accumulating into
+    the final result.  This trades a small loop overhead for a
+    significantly reduced peak GPU memory footprint.
+
+    For each chunk, the source tensor is zeroed everywhere except for
+    the chunk's source points, and ``abbe_image`` runs on that masked
+    source.  Results are summed across chunks.
+
+    Parameters
+    ----------
+    mask_fft : (G, G) complex128
+        2D FFT of the mask transmission.
+    source_points : (Sx, Sy) float64
+        Full illumination source intensity distribution.
+    fx, fy : (G, G) float64
+        Normalised frequency coordinates from ``pupil_grid()``.
+    pupil : (G, G) complex128 or float64
+        Pupil transmission function.
+    na : float
+        Numerical aperture.
+    chunk_size : int
+        Maximum number of source points to process per chunk
+        (default 32).  Lower values reduce peak memory but increase
+        Python loop overhead.
+
+    Returns
+    -------
+    aerial : (G, G) float64
+        Normalised aerial image intensity, matching the output of
+        ``abbe_image`` run on the full source (within numerical
+        precision).
+    """
+    G = mask_fft.shape[0]
+    device = mask_fft.device
+    dtype = source_points.dtype
+
+    # Identify all non-zero source point indices
+    src_mask = source_points > 0
+    src_indices = torch.nonzero(src_mask)  # (n_src, 2)
+    n_src = src_indices.shape[0]
+
+    if n_src == 0:
+        return torch.zeros(G, G, dtype=torch.float64, device=device)
+
+    # Extract source weights at non-zero positions
+    weights = source_points[src_mask]  # (n_src,)
+
+    aerial = torch.zeros(G, G, dtype=torch.float64, device=device)
+
+    for start in range(0, n_src, chunk_size):
+        end = min(start + chunk_size, n_src)
+        chunk_indices = src_indices[start:end]
+
+        # Build a source tensor that is zero everywhere except the
+        # chunk's source points.  This is the simplest approach and
+        # matches the abbe_image interface exactly.
+        chunk_source = torch.zeros_like(source_points)
+        # Set the chunk's source points
+        chunk_source[chunk_indices[:, 0], chunk_indices[:, 1]] = weights[start:end]
+
+        # Compute partial aerial image for this chunk
+        partial = abbe_image(mask_fft, chunk_source, fx, fy, pupil, na, period_m=period_m, wavelength_m=wavelength_m)
+        aerial = aerial + partial
+
+    return aerial
+
+
+def chunked_rcwa(
+    geometry_profile: torch.Tensor,
+    chunk_size_mb: int = 500,
+) -> torch.Tensor:
+    """Process RCWA layers in chunks to stay within a memory budget.
+
+    .. note::
+
+       This is a placeholder implementation.  The full RCWA chunked
+       solver will cascade per-layer S-matrices in groups rather than
+       all at once.  Currently returns the input unchanged to
+       validate the API contract.
+
+    Parameters
+    ----------
+    geometry_profile : (N, ...) complex128
+        Permittivity profile through the mask stack, with the first
+        dimension indexing the vertical layer.
+    chunk_size_mb : int
+        Target memory budget per chunk in megabytes (default 500).
+
+    Returns
+    -------
+    torch.Tensor
+        The input profile (placeholder — full chunked RCWA to be
+        implemented in a future release).
+    """
+    _ = chunk_size_mb  # reserved for future use
+    return geometry_profile

euv/accel/device.py

@@ -0,0 +1,88 @@
+"""Device selection, introspection, and default dtype management.
+
+Provides a single source of truth for which hardware (CPU / CUDA GPU)
+simulation kernels run on, and what precision the tensor operations
+use by default.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+import torch
+
+
+def select_device(prefer_gpu: bool = True) -> torch.device:
+    """Return the best available device.
+
+    Parameters
+    ----------
+    prefer_gpu : bool
+        If ``True`` (default) and a CUDA-capable GPU is available,
+        returns ``device(type='cuda')``.  Otherwise returns
+        ``device(type='cpu')``.
+
+    Returns
+    -------
+    torch.device
+    """
+    if prefer_gpu and torch.cuda.is_available():
+        return torch.device("cuda")
+    return torch.device("cpu")
+
+
+def device_info(device: torch.device) -> Dict[str, object]:
+    """Return a dictionary of hardware properties for *device*.
+
+    Parameters
+    ----------
+    device : torch.device
+
+    Returns
+    -------
+    dict
+        Keys:
+        - ``name`` — device name string (e.g. ``"NVIDIA A100"`` or ``"cpu"``).
+        - ``vram_gb`` — total GPU memory in GiB, or 0.0 for CPU.
+        - ``compute_capability`` — CUDA compute capability ``(major, minor)``
+          tuple, or ``None`` for CPU.
+    """
+    if device.type == "cuda":
+        idx = device.index if device.index is not None else 0
+        name = torch.cuda.get_device_name(idx)
+        vram_gb = torch.cuda.get_device_properties(idx).total_mem / (1024**3)
+        cap = torch.cuda.get_device_capability(idx)
+        return {
+            "name": name,
+            "vram_gb": round(vram_gb, 2),
+            "compute_capability": cap,
+        }
+    return {
+        "name": "cpu",
+        "vram_gb": 0.0,
+        "compute_capability": None,
+    }
+
+
+def set_default_dtype(
+    complex_dtype: torch.dtype = torch.complex128,
+    real_dtype: torch.dtype = torch.float64,
+) -> None:
+    """Set PyTorch's default floating-point and complex dtypes.
+
+    Call this once at the start of a simulation to establish the
+    precision regime for the entire module.
+
+    Parameters
+    ----------
+    complex_dtype : torch.dtype
+        Default complex type (e.g. ``torch.complex128`` or
+        ``torch.complex64``).
+    real_dtype : torch.dtype
+        Default real type (e.g. ``torch.float64`` or ``torch.float32``).
+    """
+    torch.set_default_dtype(real_dtype)
+    # torch does not have a global set_default_complex_dtype in older
+    # versions; instead we ensure the default dtype is set correctly
+    # and rely on complex tensors being constructed explicitly.
+    _ = complex_dtype  # kept for API symmetry / future use

euv/accel/mixed_precision.py

@@ -0,0 +1,102 @@
+"""Mixed-precision helpers for GPU memory reduction.
+
+Provides dtype conversion utilities and a policy engine that
+recommends the appropriate precision for each operation based on
+the available VRAM.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+import torch
+
+
+def autocast_complex(tensor: torch.Tensor) -> torch.Tensor:
+    """Downcast a complex tensor to ``complex64`` if it is currently
+    ``complex128`` and the precision loss is acceptable.
+
+    Parameters
+    ----------
+    tensor : torch.Tensor
+        Input tensor.  Passed through unchanged if it is not complex
+        or already ``complex64``.
+
+    Returns
+    -------
+    torch.Tensor
+        ``complex64`` tensor if the input was ``complex128``,
+        otherwise the original tensor.
+    """
+    if tensor.is_complex() and tensor.dtype == torch.complex128:
+        return tensor.to(torch.complex64)
+    return tensor
+
+
+def real_only(complex_tensor: torch.Tensor) -> torch.Tensor:
+    """Return the real component of a complex tensor, halving its
+    memory footprint.
+
+    Useful for storing intermediate results when only the magnitude
+    (not the phase) is needed, e.g. the accumulated aerial image
+    intensity.
+
+    Parameters
+    ----------
+    complex_tensor : torch.Tensor
+        Complex-valued input tensor.
+
+    Returns
+    -------
+    torch.Tensor
+        Real part as a ``float64`` (or ``float32``) tensor.
+    """
+    return complex_tensor.real
+
+
+def precision_policy(vram_gb: float = 14) -> Dict[str, torch.dtype]:
+    """Recommend a dtype per operation based on the available VRAM.
+
+    The policy balances numerical accuracy against memory footprint:
+
+    - **Low VRAM** (< 6 GiB): use ``complex64`` / ``float32``
+      everywhere.
+    - **Mid VRAM** (6–12 GiB): use ``complex64`` for intermediate
+      buffers, ``float64`` for accumulation.
+    - **High VRAM** (≥ 12 GiB): use ``complex128`` / ``float64``
+      for full double-precision accuracy.
+
+    Parameters
+    ----------
+    vram_gb : float
+        Available GPU memory in GiB (default 14).
+
+    Returns
+    -------
+    dict
+        Keys:
+        - ``spectrum`` — dtype for the mask diffraction spectrum.
+        - ``pupil`` — dtype for the pupil transmission.
+        - ``image`` — dtype for the accumulated aerial image.
+        - ``rcwa_eigen`` — dtype for the RCWA eigenvalue solve.
+    """
+    if vram_gb < 6:
+        return {
+            "spectrum": torch.complex64,
+            "pupil": torch.complex64,
+            "image": torch.float32,
+            "rcwa_eigen": torch.complex64,
+        }
+    if vram_gb < 12:
+        return {
+            "spectrum": torch.complex64,
+            "pupil": torch.complex64,
+            "image": torch.float64,  # accumulate in double
+            "rcwa_eigen": torch.complex64,
+        }
+    return {
+        "spectrum": torch.complex128,
+        "pupil": torch.complex128,
+        "image": torch.float64,
+        "rcwa_eigen": torch.complex128,
+    }

euv/accel/vram_budget.py

@@ -0,0 +1,211 @@
+"""Analytical VRAM estimators for RCWA and Abbe imaging.
+
+All formulas are based on the dominant tensor allocations for each
+kernel.  Use these estimates to pre-check whether a configuration
+will fit on the target GPU before launching the solver.
+"""
+
+from __future__ import annotations
+
+
+def estimate_rcma_vram(
+    n_orders: int,
+    n_layers: int,
+    dtype_bytes: int = 16,
+) -> int:
+    """Estimate the GPU memory required for an RCWA solve.
+
+    Dominant allocation: the per-layer eigenproblem in the Fourier
+    modal method.  The eigenvalue matrix has shape ``(M, M)`` where
+    ``M = 2 * n_orders + 1``, and the S-matrix cascade stores a
+    handful of ``(M, M)`` matrices per layer.
+
+    Parameters
+    ----------
+    n_orders : int
+        Number of Fourier orders (positive integer, :math:`M = 2n+1`).
+    n_layers : int
+        Number of vertical layers in the mask stack.
+    dtype_bytes : int
+        Bytes per complex element (default 16 for ``complex128``).
+
+    Returns
+    -------
+    int
+        Estimated memory in bytes.
+    """
+    M = 2 * n_orders + 1
+    # Per layer: eigenvalue matrix A (M×M), eigenvectors W (M×M),
+    # eigenvalues q² (M,), S-matrix cascade (a few M×M).
+    # Rough rule: 4 × M² per layer.
+    bytes_per_layer = 4 * M * M * dtype_bytes
+    total = n_layers * bytes_per_layer
+
+    # Additional overhead for the profile and Toeplitz matrices
+    overhead = 128 * 1024 * 1024  # 128 MB safety margin
+    return total + overhead
+
+
+def estimate_abbe_vram(
+    grid_size: int,
+    n_source_points: int,
+    dtype_bytes: int = 8,
+) -> int:
+    """Estimate the GPU memory for a full Abbe aerial-image solve.
+
+    The dominant memory comes from the intermediate coherent images
+    accumulated over source points (each image is ``grid_size ×
+    grid_size × dtype_bytes``).
+
+    Parameters
+    ----------
+    grid_size : int
+        Pixel grid dimension (``G × G``).
+    n_source_points : int
+        Number of non-zero illumination source points.
+    dtype_bytes : int
+        Bytes per element of the accumulated image (default 8 for
+        ``float64``).
+
+    Returns
+    -------
+    int
+        Estimated memory in bytes.
+    """
+    # Per source point: shifted spectrum (G×G complex128), filtered
+    # (G×G complex128), IFFT (G×G complex128), intensity (G×G float64).
+    # The accumulation buffer is G×G float64.
+    # Roughly 4 × G² × 16 + G² × 8 bytes per iteration,
+    # but we estimate total peak as the sum of one iteration's working
+    # set plus the accumulation buffer.
+    gb_per_source = 4 * grid_size * grid_size * 16  # 4 complex buffers
+    acc_buf = grid_size * grid_size * 8  # float64 accumulator
+    peak = gb_per_source + acc_buf
+    # Overhead: pupil, source, coordinate grids
+    overhead = 64 * 1024 * 1024  # 64 MB
+    return peak + overhead
+
+
+def max_harmonics_for_vram(
+    vram_budget_gb: float = 14,
+    n_layers: int = 12,
+) -> int:
+    """Return the maximum number of Fourier orders (:math:`M`) that fit
+    in *vram_budget_gb*.
+
+    Uses the RCWA estimate (dominant memory scales as
+    :math:`M^2`).  Walks upward from ``M = 3`` until the budget is
+    exceeded.
+
+    Parameters
+    ----------
+    vram_budget_gb : float
+        Available GPU memory in GiB (default 14 — typical consumer
+        card with 16 GB physical and ~2 GB reserved by the OS).
+    n_layers : int
+        Number of RCWA layers (default 12).
+
+    Returns
+    -------
+    int
+        Maximum odd *M* (number of Fourier orders) that fits.
+    """
+    budget_bytes = int(vram_budget_gb * (1024**3))
+
+    # RCWA orders: M = 2 * n_orders + 1, so n_orders = (M-1)//2
+    # We search for the largest odd M that fits.
+    lo, hi = 3, 3
+    # Exponential probe
+    while estimate_rcma_vram((hi - 1) // 2, n_layers) <= budget_bytes:
+        hi *= 2
+        if hi > 2000:  # safety cap
+            break
+
+    best = 3
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        M = mid if mid % 2 == 1 else mid + 1  # ensure odd
+        n_orders = (M - 1) // 2
+        if estimate_rcma_vram(n_orders, n_layers) <= budget_bytes:
+            best = M
+            lo = M + 2
+        else:
+            hi = M - 2
+    return best
+
+
+def check_oom(total_bytes: int, vram_gb: float = 14) -> None:
+    """Raise :class:`MemoryError` if *total_bytes* exceeds the VRAM
+    budget.
+
+    Parameters
+    ----------
+    total_bytes : int
+        Estimated memory requirement in bytes.
+    vram_gb : float
+        Available VRAM in GiB (default 14).
+
+    Raises
+    ------
+    MemoryError
+        If the estimated memory exceeds the budget.
+    """
+    budget = vram_gb * (1024**3)
+    if total_bytes > budget:
+        used_gb = total_bytes / (1024**3)
+        raise MemoryError(
+            f"Estimated memory {used_gb:.2f} GiB exceeds "
+            f"budget of {vram_gb:.1f} GiB.  Reduce problem size "
+            "(e.g. fewer Fourier orders, fewer layers, or smaller "
+            "grid) or switch to chunked processing."
+        )
+
+
+def vram_report() -> str:
+    """Return a formatted string with VRAM estimates for common
+    OpEnUV configurations.
+
+    The report tabulates the RCWA and Abbe memory footprints
+    across a range of typical problem sizes so the user can
+    quickly gauge hardware requirements.
+
+    Returns
+    -------
+    str
+    """
+    lines = [
+        "=" * 72,
+        "  OpEnUV — VRAM Budget Report",
+        "=" * 72,
+        "",
+        "  RCWA estimates (complex128, 12 layers):",
+        "  " + "-" * 50,
+        f"    {'Orders':>8}  {'M':>5}  {'Est. VRAM':>12}",
+        "    " + "-" * 30,
+    ]
+    for n_orders in [11, 15, 21, 31, 41, 51]:
+        M = 2 * n_orders + 1
+        est = estimate_rcma_vram(n_orders, n_layers=12)
+        est_gb = est / (1024**3)
+        lines.append(f"    {n_orders:>8}  {M:>5}  {est_gb:>10.2f} GiB")
+
+    lines += [
+        "",
+        "  Abbe estimates (complex128, float64 accumulator):",
+        "  " + "-" * 50,
+        f"    {'Grid':>8}  {'Src pts':>8}  {'Est. VRAM':>12}",
+        "    " + "-" * 30,
+    ]
+    for grid in [128, 256, 512, 1024]:
+        for n_src in [100, 500]:
+            est = estimate_abbe_vram(grid, n_src)
+            est_gb = est / (1024**3)
+            lines.append(f"    {grid:>4}²  {n_src:>8}  {est_gb:>10.2f} GiB")
+
+    lines += [
+        "",
+        "  Max Fourier orders (M) for 14 GiB budget:",
+        f"    M_max = {max_harmonics_for_vram(14)}",
+        "=" * 72,
+    ]
+    return "\n".join(lines)

euv/aerial/__init__.py

@@ -0,0 +1,20 @@
+"""Aerial image formation — partially coherent imaging.
+
+Submodules
+----------
+abbe
+    Abbe's method: sum over illumination source points for the
+    physically correct aerial image with mask-3D corrections.
+hopkins
+    Hopkins/TCC method: precomputed transmission cross coefficient
+    for accelerated O(N² log N) imaging via sum of coherent systems
+    (SOCS).  Thin-mask approximation suitable for OPC loops.
+pupil
+    Projection pupil: numerical aperture, anamorphic (4×/8× for
+    High-NA EUV), Zernike aberrations, flare.
+source
+    Illumination source shapes: conventional (disk), annular,
+    dipole (XY), quasar (CQuad), and custom free-form.
+"""
+
+from __future__ import annotations