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

gsim/palace/models/__init__.py

@@ -0,0 +1,53 @@
+"""Pydantic models for Palace EM simulation configuration.
+
+This module provides Pydantic v2 models for configuring Palace simulations,
+offering validation, serialization, and a clean API.
+
+Submodules:
+    - geometry: GeometryConfig
+    - stack: MaterialConfig (Layer/Stack are in gsim.common.stack)
+    - ports: PortConfig, CPWPortConfig, TerminalConfig, WavePortConfig
+    - mesh: MeshConfig
+    - numerical: NumericalConfig
+    - problems: DrivenConfig, EigenmodeConfig, ElectrostaticConfig, etc.
+    - results: SimulationResult, ValidationResult
+"""
+
+from __future__ import annotations
+
+from gsim.palace.models.geometry import GeometryConfig
+from gsim.palace.models.mesh import MeshConfig
+from gsim.palace.models.numerical import NumericalConfig
+from gsim.palace.models.ports import (
+    CPWPortConfig,
+    PortConfig,
+    TerminalConfig,
+    WavePortConfig,
+)
+from gsim.palace.models.problems import (
+    DrivenConfig,
+    EigenmodeConfig,
+    ElectrostaticConfig,
+    MagnetostaticConfig,
+    TransientConfig,
+)
+from gsim.palace.models.results import SimulationResult, ValidationResult
+from gsim.palace.models.stack import MaterialConfig
+
+__all__ = [
+    "CPWPortConfig",
+    "DrivenConfig",
+    "EigenmodeConfig",
+    "ElectrostaticConfig",
+    "GeometryConfig",
+    "MagnetostaticConfig",
+    "MaterialConfig",
+    "MeshConfig",
+    "NumericalConfig",
+    "PortConfig",
+    "SimulationResult",
+    "TerminalConfig",
+    "TransientConfig",
+    "ValidationResult",
+    "WavePortConfig",
+]

gsim/palace/models/geometry.py

@@ -0,0 +1,34 @@
+"""Geometry configuration models for Palace simulations.
+
+This module contains Pydantic models for geometry-related settings.
+Note: The actual gdsfactory Component is stored directly on the simulation
+classes since it's not serializable with Pydantic.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class GeometryConfig(BaseModel):
+    """Configuration for geometry settings.
+
+    This model stores metadata about the component being simulated.
+    The actual Component object is stored separately on simulation classes.
+
+    Attributes:
+        component_name: Name of the component being simulated
+        bounds: Bounding box as (xmin, ymin, xmax, ymax)
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    component_name: str | None = None
+    bounds: tuple[float, float, float, float] | None = Field(
+        default=None, description="Bounding box (xmin, ymin, xmax, ymax)"
+    )
+
+
+__all__ = [
+    "GeometryConfig",
+]

gsim/palace/models/mesh.py

@@ -0,0 +1,95 @@
+"""Mesh configuration models for Palace simulations.
+
+This module contains Pydantic models for mesh generation configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class MeshConfig(BaseModel):
+    """Configuration for mesh generation with COMSOL-style presets.
+
+    Attributes:
+        refined_mesh_size: Mesh size near conductors (um)
+        max_mesh_size: Maximum mesh size in air/dielectric (um)
+        cells_per_wavelength: Number of mesh cells per wavelength
+        margin: XY margin around design (um)
+        air_above: Air above top metal (um)
+        fmax: Maximum frequency for mesh sizing (Hz)
+        boundary_conditions: List of boundary conditions for each face
+        show_gui: Show gmsh GUI during meshing
+        preview_only: Generate preview only, don't save mesh
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    refined_mesh_size: float = Field(default=5.0, gt=0)
+    max_mesh_size: float = Field(default=300.0, gt=0)
+    cells_per_wavelength: int = Field(default=10, ge=1)
+    margin: float = Field(default=50.0, ge=0)
+    air_above: float = Field(default=100.0, ge=0)
+    fmax: float = Field(default=100e9, gt=0)
+    boundary_conditions: list[str] | None = None
+    show_gui: bool = False
+    preview_only: bool = False
+
+    @model_validator(mode="after")
+    def set_default_boundary_conditions(self) -> Self:
+        """Set default boundary conditions if not provided."""
+        if self.boundary_conditions is None:
+            self.boundary_conditions = ["ABC", "ABC", "ABC", "ABC", "ABC", "ABC"]
+        return self
+
+    @classmethod
+    def coarse(cls, **kwargs: float | bool | list[str] | None) -> Self:
+        """Fast mesh for quick iteration (~2.5 elements per wavelength).
+
+        This preset is suitable for initial debugging and quick checks.
+        Not recommended for accurate results.
+        """
+        defaults: dict[str, float | int | bool | list[str] | None] = {
+            "refined_mesh_size": 10.0,
+            "max_mesh_size": 600.0,
+            "cells_per_wavelength": 5,
+        }
+        defaults.update(kwargs)
+        return cls(**defaults)  # type: ignore[arg-type]
+
+    @classmethod
+    def default(cls, **kwargs: float | bool | list[str] | None) -> Self:
+        """Balanced mesh matching COMSOL defaults (~5 elements per wavelength).
+
+        This preset provides a good balance between accuracy and computation time.
+        Suitable for most simulations.
+        """
+        defaults: dict[str, float | int | bool | list[str] | None] = {
+            "refined_mesh_size": 5.0,
+            "max_mesh_size": 300.0,
+            "cells_per_wavelength": 10,
+        }
+        defaults.update(kwargs)
+        return cls(**defaults)  # type: ignore[arg-type]
+
+    @classmethod
+    def fine(cls, **kwargs: float | bool | list[str] | None) -> Self:
+        """High accuracy mesh (~10 elements per wavelength).
+
+        This preset provides higher accuracy at the cost of increased
+        computation time. Use for final production simulations.
+        """
+        defaults: dict[str, float | int | bool | list[str] | None] = {
+            "refined_mesh_size": 2.0,
+            "max_mesh_size": 70.0,
+            "cells_per_wavelength": 20,
+        }
+        defaults.update(kwargs)
+        return cls(**defaults)  # type: ignore[arg-type]
+
+
+__all__ = [
+    "MeshConfig",
+]

gsim/palace/models/numerical.py

@@ -0,0 +1,66 @@
+"""Numerical solver configuration models for Palace simulations.
+
+This module contains Pydantic models for numerical solver settings.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class NumericalConfig(BaseModel):
+    """Numerical solver configuration.
+
+    Attributes:
+        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)
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    # Element order
+    order: int = Field(default=2, ge=1, le=4)
+
+    # Linear solver
+    tolerance: float = Field(default=1e-6, gt=0)
+    max_iterations: int = Field(default=400, ge=1)
+    solver_type: Literal["Default", "SuperLU", "STRUMPACK", "MUMPS"] = "Default"
+
+    # Preconditioner
+    preconditioner: Literal["Default", "AMS", "BoomerAMG"] = "Default"
+
+    # Device
+    device: Literal["CPU", "GPU"] = "CPU"
+
+    # Partitioning
+    num_processors: int | None = None  # None = auto
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        solver_config: dict[str, str | int | float] = {
+            "Tolerance": self.tolerance,
+            "MaxIterations": self.max_iterations,
+        }
+
+        if self.solver_type != "Default":
+            solver_config["Type"] = self.solver_type
+
+        if self.preconditioner != "Default":
+            solver_config["Preconditioner"] = self.preconditioner
+
+        return {
+            "Order": self.order,
+            "Solver": solver_config,
+        }
+
+
+__all__ = [
+    "NumericalConfig",
+]

gsim/palace/models/ports.py

@@ -0,0 +1,137 @@
+"""Port configuration models for Palace simulations.
+
+This module contains Pydantic models for port definitions:
+- PortConfig: Single-element lumped port configuration
+- CPWPortConfig: Coplanar waveguide (two-element) port configuration
+- TerminalConfig: Terminal for electrostatic simulations
+- WavePortConfig: Wave port (domain boundary with mode solving)
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class PortConfig(BaseModel):
+    """Configuration for a single-element lumped port.
+
+    Lumped ports can be inplane (horizontal, on single layer) or
+    via (vertical, between two layers).
+
+    Attributes:
+        name: Port name (must match component port name)
+        layer: Target layer for inplane ports
+        from_layer: Bottom layer for via ports
+        to_layer: Top layer for via ports
+        length: Port extent along direction (um)
+        impedance: Port impedance (Ohms)
+        excited: Whether this port is excited
+        geometry: Port geometry type ("inplane" or "via")
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    name: str
+    layer: str | None = None
+    from_layer: str | None = None
+    to_layer: str | None = None
+    length: float | None = Field(default=None, gt=0)
+    impedance: float = Field(default=50.0, gt=0)
+    excited: bool = True
+    geometry: Literal["inplane", "via"] = "inplane"
+
+    @model_validator(mode="after")
+    def validate_layer_config(self) -> Self:
+        """Validate layer configuration based on geometry type."""
+        if self.geometry == "inplane" and self.layer is None:
+            raise ValueError("Inplane ports require 'layer' to be specified")
+        if self.geometry == "via" and (
+            self.from_layer is None or self.to_layer is None
+        ):
+            raise ValueError("Via ports require both 'from_layer' and 'to_layer'")
+        return self
+
+
+class CPWPortConfig(BaseModel):
+    """Configuration for a coplanar waveguide (CPW) port.
+
+    CPW ports consist of two elements (upper and lower gaps) that are
+    excited with opposite E-field directions to create the CPW mode.
+
+    Attributes:
+        upper: Name of the upper gap port on the component
+        lower: Name of the lower gap port on the component
+        layer: Target conductor layer
+        length: Port extent along direction (um)
+        impedance: Port impedance (Ohms)
+        excited: Whether this port is excited
+        name: Optional name for the CPW port (default: "cpw_{lower}")
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    upper: str = Field(description="Name of upper gap port")
+    lower: str = Field(description="Name of lower gap port")
+    layer: str = Field(description="Target conductor layer")
+    length: float = Field(gt=0, description="Port extent in um")
+    impedance: float = Field(default=50.0, gt=0)
+    excited: bool = True
+    name: str | None = Field(
+        default=None, description="CPW port name (default: cpw_{lower})"
+    )
+
+    @property
+    def effective_name(self) -> str:
+        """Get the effective port name."""
+        return self.name if self.name else f"cpw_{self.lower}"
+
+
+class TerminalConfig(BaseModel):
+    """Configuration for a terminal (for electrostatic capacitance extraction).
+
+    Terminals define conductor surfaces for capacitance matrix extraction
+    in electrostatic simulations.
+
+    Attributes:
+        name: Terminal name
+        layer: Target conductor layer
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    name: str
+    layer: str
+
+
+class WavePortConfig(BaseModel):
+    """Configuration for a wave port (domain boundary with mode solving).
+
+    Wave ports are used for domain-boundary ports where mode solving
+    is needed. This is an alternative to lumped ports for more accurate
+    S-parameter extraction.
+
+    Attributes:
+        name: Port name (must match component port name)
+        layer: Target conductor layer
+        mode: Mode number to excite
+        excited: Whether this port is excited
+        offset: De-embedding distance in um
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    name: str
+    layer: str
+    mode: int = Field(default=1, ge=1, description="Mode number to excite")
+    excited: bool = True
+    offset: float = Field(default=0.0, ge=0, description="De-embedding distance in um")
+
+
+__all__ = [
+    "CPWPortConfig",
+    "PortConfig",
+    "TerminalConfig",
+    "WavePortConfig",
+]

gsim/palace/models/problems.py

@@ -0,0 +1,195 @@
+"""Problem-specific configuration models for Palace simulations.
+
+This module contains Pydantic models for different simulation types:
+- DrivenConfig: Frequency-domain driven simulation (S-parameters)
+- EigenmodeConfig: Eigenmode/resonance simulation
+- ElectrostaticConfig: Electrostatic capacitance extraction
+- MagnetostaticConfig: Magnetostatic inductance extraction
+- TransientConfig: Time-domain simulation
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class DrivenConfig(BaseModel):
+    """Configuration for driven (frequency sweep) simulation.
+
+    This is used for S-parameter extraction and frequency response analysis.
+
+    Attributes:
+        fmin: Minimum frequency in Hz
+        fmax: Maximum frequency in Hz
+        num_points: Number of frequency points
+        scale: Frequency spacing ("linear" or "log")
+        adaptive_tol: Adaptive tolerance (0 disables adaptive)
+        adaptive_max_samples: Maximum samples for adaptive refinement
+        compute_s_params: Whether to compute S-parameters
+        reference_impedance: Reference impedance for S-params (Ohms)
+        excitation_port: Name of port to excite (None = first port)
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    fmin: float = Field(default=1e9, gt=0, description="Min frequency in Hz")
+    fmax: float = Field(default=100e9, gt=0, description="Max frequency in Hz")
+    num_points: int = Field(default=40, ge=1, description="Number of frequency points")
+    scale: Literal["linear", "log"] = "linear"
+
+    # Adaptive options
+    adaptive_tol: float = Field(
+        default=0.02, ge=0, description="Adaptive tolerance (0 disables adaptive)"
+    )
+    adaptive_max_samples: int = Field(default=20, ge=1)
+
+    # S-parameter options
+    compute_s_params: bool = True
+    reference_impedance: float = Field(default=50.0, gt=0)
+
+    # Excitation
+    excitation_port: str | None = Field(
+        default=None, description="Port to excite (None = first port)"
+    )
+
+    @model_validator(mode="after")
+    def validate_frequency_range(self) -> Self:
+        """Validate that fmin < fmax."""
+        if self.fmin >= self.fmax:
+            raise ValueError(f"fmin ({self.fmin}) must be less than fmax ({self.fmax})")
+        return self
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        freq_step = (self.fmax - self.fmin) / max(1, self.num_points - 1) / 1e9
+        return {
+            "Samples": [
+                {
+                    "Type": "Linear" if self.scale == "linear" else "Log",
+                    "MinFreq": self.fmin / 1e9,
+                    "MaxFreq": self.fmax / 1e9,
+                    "FreqStep": freq_step,
+                    "SaveStep": 0,
+                }
+            ],
+            "AdaptiveTol": max(0, self.adaptive_tol),
+        }
+
+
+class EigenmodeConfig(BaseModel):
+    """Configuration for eigenmode (resonance) simulation.
+
+    This is used for finding resonant frequencies and mode shapes.
+
+    Attributes:
+        num_modes: Number of modes to find
+        target: Target frequency in Hz for mode search
+        tolerance: Eigenvalue solver tolerance
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    num_modes: int = Field(
+        default=10, ge=1, alias="N", description="Number of modes to find"
+    )
+    target: float | None = Field(default=None, description="Target frequency in Hz")
+    tolerance: float = Field(
+        default=1e-6, gt=0, description="Eigenvalue solver tolerance"
+    )
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        config: dict = {
+            "N": self.num_modes,
+            "Tol": self.tolerance,
+        }
+        if self.target is not None:
+            config["Target"] = self.target / 1e9  # Convert to GHz
+        return config
+
+
+class ElectrostaticConfig(BaseModel):
+    """Configuration for electrostatic (capacitance matrix) simulation.
+
+    Attributes:
+        save_fields: Number of field solutions to save
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    save_fields: int = Field(default=0, ge=0, description="Number of fields to save")
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        return {
+            "Save": self.save_fields,
+        }
+
+
+class MagnetostaticConfig(BaseModel):
+    """Configuration for magnetostatic (inductance matrix) simulation.
+
+    Attributes:
+        save_fields: Number of field solutions to save
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    save_fields: int = Field(default=0, ge=0, description="Number of fields to save")
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        return {
+            "Save": self.save_fields,
+        }
+
+
+class TransientConfig(BaseModel):
+    """Configuration for transient (time-domain) simulation.
+
+    Attributes:
+        max_time: Maximum simulation time in ns
+        excitation: Excitation waveform type
+        excitation_freq: Excitation frequency in Hz (for sinusoidal)
+        excitation_width: Pulse width in ns (for gaussian)
+        time_step: Time step in ns (None = adaptive)
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    excitation: Literal["sinusoidal", "gaussian", "ramp", "smoothstep"] = "sinusoidal"
+    excitation_freq: float | None = Field(
+        default=None, description="Excitation frequency in Hz"
+    )
+    excitation_width: float | None = Field(
+        default=None, description="Pulse width in ns (for gaussian)"
+    )
+    max_time: float = Field(description="Maximum simulation time in ns")
+    time_step: float | None = Field(
+        default=None, description="Time step in ns (None = adaptive)"
+    )
+
+    def to_palace_config(self) -> dict:
+        """Convert to Palace JSON config format."""
+        config: dict = {
+            "Type": self.excitation.capitalize(),
+            "MaxTime": self.max_time,
+        }
+        if self.excitation_freq is not None:
+            config["ExcitationFreq"] = self.excitation_freq / 1e9  # Convert to GHz
+        if self.excitation_width is not None:
+            config["ExcitationWidth"] = self.excitation_width
+        if self.time_step is not None:
+            config["TimeStep"] = self.time_step
+        return config
+
+
+__all__ = [
+    "DrivenConfig",
+    "EigenmodeConfig",
+    "ElectrostaticConfig",
+    "MagnetostaticConfig",
+    "TransientConfig",
+]