gsim 0.0.0__py3-none-any.whl → 0.0.2__py3-none-any.whl

gsim/palace/electrostatic.py

@@ -0,0 +1,622 @@
+"""Electrostatic simulation class for capacitance extraction.
+
+This module provides the ElectrostaticSim class for extracting
+capacitance matrices between terminals.
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+import warnings
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+from gsim.common import Geometry, LayerStack
+from gsim.palace.base import PalaceSimMixin
+from gsim.palace.models import (
+    ElectrostaticConfig,
+    MaterialConfig,
+    MeshConfig,
+    NumericalConfig,
+    SimulationResult,
+    TerminalConfig,
+    ValidationResult,
+)
+
+if TYPE_CHECKING:
+    from gdsfactory.component import Component
+
+
+class ElectrostaticSim(PalaceSimMixin, BaseModel):
+    """Electrostatic simulation for capacitance matrix extraction.
+
+    This class configures and runs electrostatic simulations to extract
+    the capacitance matrix between conductor terminals. Unlike driven
+    and eigenmode simulations, this does not use ports. Uses composition
+    (no inheritance) with shared Geometry and Stack components from gsim.common.
+
+    Example:
+        >>> from gsim.palace import ElectrostaticSim
+        >>>
+        >>> sim = ElectrostaticSim()
+        >>> sim.set_geometry(component)
+        >>> sim.set_stack(air_above=300.0)
+        >>> sim.add_terminal("T1", layer="topmetal2")
+        >>> sim.add_terminal("T2", layer="topmetal2")
+        >>> sim.set_electrostatic()
+        >>> sim.mesh("./sim", preset="default")
+        >>> results = sim.simulate()
+
+    Attributes:
+        geometry: Wrapped gdsfactory Component (from common)
+        stack: Layer stack configuration (from common)
+        terminals: List of terminal configurations
+        electrostatic: Electrostatic simulation configuration
+        materials: Material property overrides
+        numerical: Numerical solver configuration
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    # Composed objects (from common)
+    geometry: Geometry | None = None
+    stack: LayerStack | None = None
+
+    # Terminal configurations (no ports in electrostatic)
+    terminals: list[TerminalConfig] = Field(default_factory=list)
+
+    # Electrostatic simulation config
+    electrostatic: ElectrostaticConfig = Field(default_factory=ElectrostaticConfig)
+
+    # Material overrides and numerical config
+    materials: dict[str, MaterialConfig] = Field(default_factory=dict)
+    numerical: NumericalConfig = Field(default_factory=NumericalConfig)
+
+    # Stack configuration (stored as kwargs until resolved)
+    _stack_kwargs: dict[str, Any] = PrivateAttr(default_factory=dict)
+
+    # Internal state
+    _output_dir: Path | None = PrivateAttr(default=None)
+    _configured_terminals: bool = PrivateAttr(default=False)
+
+    # -------------------------------------------------------------------------
+    # Geometry methods
+    # -------------------------------------------------------------------------
+
+    def set_geometry(self, component: Component) -> None:
+        """Set the gdsfactory component for simulation.
+
+        Args:
+            component: gdsfactory Component to simulate
+
+        Example:
+            >>> sim.set_geometry(my_component)
+        """
+        self.geometry = Geometry(component=component)
+
+    @property
+    def component(self) -> Component | None:
+        """Get the current component (for backward compatibility)."""
+        return self.geometry.component if self.geometry else None
+
+    @property
+    def _component(self) -> Component | None:
+        """Internal component access (backward compatibility)."""
+        return self.component
+
+    # -------------------------------------------------------------------------
+    # Stack methods
+    # -------------------------------------------------------------------------
+
+    def set_stack(
+        self,
+        *,
+        yaml_path: str | Path | None = None,
+        air_above: float = 200.0,
+        substrate_thickness: float = 2.0,
+        include_substrate: bool = False,
+        **kwargs,
+    ) -> None:
+        """Configure the layer stack.
+
+        Args:
+            yaml_path: Path to custom YAML stack file
+            air_above: Air box height above top metal in um
+            substrate_thickness: Thickness below z=0 in um
+            include_substrate: Include lossy silicon substrate
+            **kwargs: Additional args passed to extract_layer_stack
+
+        Example:
+            >>> sim.set_stack(air_above=300.0, substrate_thickness=2.0)
+        """
+        self._stack_kwargs = {
+            "yaml_path": yaml_path,
+            "air_above": air_above,
+            "substrate_thickness": substrate_thickness,
+            "include_substrate": include_substrate,
+            **kwargs,
+        }
+        self.stack = None
+
+    # -------------------------------------------------------------------------
+    # Terminal methods
+    # -------------------------------------------------------------------------
+
+    def add_terminal(
+        self,
+        name: str,
+        *,
+        layer: str,
+    ) -> None:
+        """Add a terminal for capacitance extraction.
+
+        Terminals define conductor surfaces for capacitance matrix extraction.
+
+        Args:
+            name: Terminal name
+            layer: Target conductor layer
+
+        Example:
+            >>> sim.add_terminal("T1", layer="topmetal2")
+            >>> sim.add_terminal("T2", layer="topmetal2")
+        """
+        # Remove existing terminal with same name
+        self.terminals = [t for t in self.terminals if t.name != name]
+        self.terminals.append(
+            TerminalConfig(
+                name=name,
+                layer=layer,
+            )
+        )
+
+    # -------------------------------------------------------------------------
+    # Electrostatic configuration
+    # -------------------------------------------------------------------------
+
+    def set_electrostatic(
+        self,
+        *,
+        save_fields: int = 0,
+    ) -> None:
+        """Configure electrostatic simulation.
+
+        Args:
+            save_fields: Number of field solutions to save
+
+        Example:
+            >>> sim.set_electrostatic(save_fields=1)
+        """
+        self.electrostatic = ElectrostaticConfig(
+            save_fields=save_fields,
+        )
+
+    # -------------------------------------------------------------------------
+    # Material methods
+    # -------------------------------------------------------------------------
+
+    def set_material(
+        self,
+        name: str,
+        *,
+        type: Literal["conductor", "dielectric", "semiconductor"] | None = None,
+        conductivity: float | None = None,
+        permittivity: float | None = None,
+        loss_tangent: float | None = None,
+    ) -> None:
+        """Override or add material properties.
+
+        Args:
+            name: Material name
+            type: Material type (conductor, dielectric, semiconductor)
+            conductivity: Conductivity in S/m (for conductors)
+            permittivity: Relative permittivity (for dielectrics)
+            loss_tangent: Dielectric loss tangent
+
+        Example:
+            >>> sim.set_material("aluminum", type="conductor", conductivity=3.8e7)
+        """
+        if type is None:
+            if conductivity is not None and conductivity > 1e4:
+                type = "conductor"
+            elif permittivity is not None:
+                type = "dielectric"
+            else:
+                type = "dielectric"
+
+        self.materials[name] = MaterialConfig(
+            type=type,
+            conductivity=conductivity,
+            permittivity=permittivity,
+            loss_tangent=loss_tangent,
+        )
+
+    def set_numerical(
+        self,
+        *,
+        order: int = 2,
+        tolerance: float = 1e-6,
+        max_iterations: int = 400,
+        solver_type: Literal["Default", "SuperLU", "STRUMPACK", "MUMPS"] = "Default",
+        preconditioner: Literal["Default", "AMS", "BoomerAMG"] = "Default",
+        device: Literal["CPU", "GPU"] = "CPU",
+        num_processors: int | None = None,
+    ) -> None:
+        """Configure numerical solver parameters.
+
+        Args:
+            order: Finite element order (1-4)
+            tolerance: Linear solver tolerance
+            max_iterations: Maximum solver iterations
+            solver_type: Linear solver type
+            preconditioner: Preconditioner type
+            device: Compute device (CPU or GPU)
+            num_processors: Number of processors (None = auto)
+
+        Example:
+            >>> sim.set_numerical(order=3, tolerance=1e-8)
+        """
+        self.numerical = NumericalConfig(
+            order=order,
+            tolerance=tolerance,
+            max_iterations=max_iterations,
+            solver_type=solver_type,
+            preconditioner=preconditioner,
+            device=device,
+            num_processors=num_processors,
+        )
+
+    # -------------------------------------------------------------------------
+    # Validation
+    # -------------------------------------------------------------------------
+
+    def validate(self) -> ValidationResult:
+        """Validate the simulation configuration.
+
+        Returns:
+            ValidationResult with validation status and messages
+        """
+        errors = []
+        warnings_list = []
+
+        # Check geometry
+        if self.geometry is None:
+            errors.append("No component set. Call set_geometry(component) first.")
+
+        # Check stack
+        if self.stack is None and not self._stack_kwargs:
+            warnings_list.append(
+                "No stack configured. Will use active PDK with defaults."
+            )
+
+        # Electrostatic requires at least 2 terminals
+        if len(self.terminals) < 2:
+            errors.append(
+                "Electrostatic simulation requires at least 2 terminals. "
+                "Call add_terminal() to add terminals."
+            )
+
+        # Validate terminal configurations
+        for terminal in self.terminals:
+            if not terminal.layer:
+                errors.append(f"Terminal '{terminal.name}': 'layer' is required")
+
+        valid = len(errors) == 0
+        return ValidationResult(valid=valid, errors=errors, warnings=warnings_list)
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    def _resolve_stack(self) -> LayerStack:
+        """Resolve the layer stack from PDK or YAML."""
+        from gsim.common.stack import get_stack
+
+        yaml_path = self._stack_kwargs.pop("yaml_path", None)
+        stack = get_stack(yaml_path=yaml_path, **self._stack_kwargs)
+        self._stack_kwargs["yaml_path"] = yaml_path
+
+        for name, props in self.materials.items():
+            stack.materials[name] = props.to_dict()
+
+        self.stack = stack
+        return stack
+
+    def _build_mesh_config(
+        self,
+        preset: Literal["coarse", "default", "fine"] | None,
+        refined_mesh_size: float | None,
+        max_mesh_size: float | None,
+        margin: float | None,
+        air_above: float | None,
+        fmax: float | None,
+        show_gui: bool,
+    ) -> MeshConfig:
+        """Build mesh config from preset with optional overrides."""
+        if preset == "coarse":
+            mesh_config = MeshConfig.coarse()
+        elif preset == "fine":
+            mesh_config = MeshConfig.fine()
+        else:
+            mesh_config = MeshConfig.default()
+
+        overrides = []
+        if preset is not None:
+            if refined_mesh_size is not None:
+                overrides.append(f"refined_mesh_size={refined_mesh_size}")
+            if max_mesh_size is not None:
+                overrides.append(f"max_mesh_size={max_mesh_size}")
+            if margin is not None:
+                overrides.append(f"margin={margin}")
+            if air_above is not None:
+                overrides.append(f"air_above={air_above}")
+            if fmax is not None:
+                overrides.append(f"fmax={fmax}")
+
+            if overrides:
+                warnings.warn(
+                    f"Preset '{preset}' values overridden by: {', '.join(overrides)}",
+                    stacklevel=4,
+                )
+
+        if refined_mesh_size is not None:
+            mesh_config.refined_mesh_size = refined_mesh_size
+        if max_mesh_size is not None:
+            mesh_config.max_mesh_size = max_mesh_size
+        if margin is not None:
+            mesh_config.margin = margin
+        if air_above is not None:
+            mesh_config.air_above = air_above
+        if fmax is not None:
+            mesh_config.fmax = fmax
+        mesh_config.show_gui = show_gui
+
+        return mesh_config
+
+    def _generate_mesh_internal(
+        self,
+        output_dir: Path,
+        mesh_config: MeshConfig,
+        model_name: str,
+        verbose: bool,
+    ) -> SimulationResult:
+        """Internal mesh generation."""
+        from gsim.palace.mesh import MeshConfig as LegacyMeshConfig
+        from gsim.palace.mesh import generate_mesh
+
+        component = self.geometry.component if self.geometry else None
+
+        legacy_mesh_config = LegacyMeshConfig(
+            refined_mesh_size=mesh_config.refined_mesh_size,
+            max_mesh_size=mesh_config.max_mesh_size,
+            cells_per_wavelength=mesh_config.cells_per_wavelength,
+            margin=mesh_config.margin,
+            air_above=mesh_config.air_above,
+            fmax=mesh_config.fmax,
+            show_gui=mesh_config.show_gui,
+            preview_only=mesh_config.preview_only,
+        )
+
+        stack = self._resolve_stack()
+
+        if verbose:
+            logger.info("Generating mesh in %s", output_dir)
+
+        mesh_result = generate_mesh(
+            component=component,
+            stack=stack,
+            ports=[],  # No ports for electrostatic
+            output_dir=output_dir,
+            config=legacy_mesh_config,
+            model_name=model_name,
+            driven_config=None,  # No driven config for electrostatic
+        )
+
+        return SimulationResult(
+            mesh_path=mesh_result.mesh_path,
+            output_dir=output_dir,
+            config_path=mesh_result.config_path,
+            port_info=mesh_result.port_info,
+            mesh_stats=mesh_result.mesh_stats,
+        )
+
+    def _get_ports_for_preview(self, stack: LayerStack) -> list:
+        """Get ports for preview (none for electrostatic)."""
+        return []
+
+    # -------------------------------------------------------------------------
+    # Preview
+    # -------------------------------------------------------------------------
+
+    def preview(
+        self,
+        *,
+        preset: Literal["coarse", "default", "fine"] | None = None,
+        refined_mesh_size: float | None = None,
+        max_mesh_size: float | None = None,
+        margin: float | None = None,
+        air_above: float | None = None,
+        fmax: float | None = None,
+        show_gui: bool = True,
+    ) -> None:
+        """Preview the mesh without running simulation.
+
+        Args:
+            preset: Mesh quality preset ("coarse", "default", "fine")
+            refined_mesh_size: Mesh size near conductors (um)
+            max_mesh_size: Max mesh size in air/dielectric (um)
+            margin: XY margin around design (um)
+            air_above: Air above top metal (um)
+            fmax: Max frequency for mesh sizing (Hz)
+            show_gui: Show gmsh GUI for interactive preview
+
+        Example:
+            >>> sim.preview(preset="fine", show_gui=True)
+        """
+        from gsim.palace.mesh import MeshConfig as LegacyMeshConfig
+        from gsim.palace.mesh import generate_mesh
+
+        component = self.geometry.component if self.geometry else None
+
+        validation = self.validate()
+        if not validation.valid:
+            raise ValueError(
+                f"Invalid configuration:\n" + "\n".join(validation.errors)
+            )
+
+        mesh_config = self._build_mesh_config(
+            preset=preset,
+            refined_mesh_size=refined_mesh_size,
+            max_mesh_size=max_mesh_size,
+            margin=margin,
+            air_above=air_above,
+            fmax=fmax,
+            show_gui=show_gui,
+        )
+
+        stack = self._resolve_stack()
+
+        legacy_mesh_config = LegacyMeshConfig(
+            refined_mesh_size=mesh_config.refined_mesh_size,
+            max_mesh_size=mesh_config.max_mesh_size,
+            cells_per_wavelength=mesh_config.cells_per_wavelength,
+            margin=mesh_config.margin,
+            air_above=mesh_config.air_above,
+            fmax=mesh_config.fmax,
+            show_gui=show_gui,
+            preview_only=True,
+        )
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            generate_mesh(
+                component=component,
+                stack=stack,
+                ports=[],
+                output_dir=tmpdir,
+                config=legacy_mesh_config,
+            )
+
+    # -------------------------------------------------------------------------
+    # Convenience methods
+    # -------------------------------------------------------------------------
+
+    def show_stack(self) -> None:
+        """Print the layer stack table."""
+        from gsim.common.stack import print_stack_table
+
+        if self.stack is None:
+            self._resolve_stack()
+
+        if self.stack is not None:
+            print_stack_table(self.stack)
+
+    def plot_stack(self) -> None:
+        """Plot the layer stack visualization."""
+        from gsim.common.stack import plot_stack
+
+        if self.stack is None:
+            self._resolve_stack()
+
+        if self.stack is not None:
+            plot_stack(self.stack)
+
+    # -------------------------------------------------------------------------
+    # Mesh generation
+    # -------------------------------------------------------------------------
+
+    def mesh(
+        self,
+        output_dir: str | Path,
+        *,
+        preset: Literal["coarse", "default", "fine"] | None = None,
+        refined_mesh_size: float | None = None,
+        max_mesh_size: float | None = None,
+        margin: float | None = None,
+        air_above: float | None = None,
+        fmax: float | None = None,
+        show_gui: bool = False,
+        model_name: str = "palace",
+        verbose: bool = True,
+    ) -> SimulationResult:
+        """Generate the mesh and configuration files.
+
+        Args:
+            output_dir: Directory for output files
+            preset: Mesh quality preset ("coarse", "default", "fine")
+            refined_mesh_size: Mesh size near conductors (um)
+            max_mesh_size: Max mesh size in air/dielectric (um)
+            margin: XY margin around design (um)
+            air_above: Air above top metal (um)
+            fmax: Max frequency for mesh sizing (Hz) - less relevant for electrostatic
+            show_gui: Show gmsh GUI during meshing
+            model_name: Base name for output files
+            verbose: Print progress messages
+
+        Returns:
+            SimulationResult with mesh and config paths
+        """
+        mesh_config = self._build_mesh_config(
+            preset=preset,
+            refined_mesh_size=refined_mesh_size,
+            max_mesh_size=max_mesh_size,
+            margin=margin,
+            air_above=air_above,
+            fmax=fmax,
+            show_gui=show_gui,
+        )
+
+        validation = self.validate()
+        if not validation.valid:
+            raise ValueError(
+                f"Invalid configuration:\n" + "\n".join(validation.errors)
+            )
+
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        self._output_dir = output_dir
+
+        self._resolve_stack()
+
+        return self._generate_mesh_internal(
+            output_dir=output_dir,
+            mesh_config=mesh_config,
+            model_name=model_name,
+            verbose=verbose,
+        )
+
+    # -------------------------------------------------------------------------
+    # Simulation
+    # -------------------------------------------------------------------------
+
+    def simulate(
+        self,
+        output_dir: str | Path | None = None,
+        *,
+        verbose: bool = True,
+    ) -> dict[str, Path]:
+        """Run electrostatic simulation on GDSFactory+ cloud.
+
+        Args:
+            output_dir: Directory containing mesh files
+            verbose: Print progress messages
+
+        Returns:
+            Dict mapping result filenames to local paths
+
+        Raises:
+            NotImplementedError: Electrostatic is not yet fully implemented
+        """
+        raise NotImplementedError(
+            "Electrostatic simulation is not yet fully implemented on cloud. "
+            "Use DrivenSim for S-parameter extraction."
+        )
+
+
+__all__ = ["ElectrostaticSim"]