feat: add canonical PDK stack and material resolution

[vvahidd]

Context

gsim currently has multiple stack and material paths. PDK extraction uses a legacy stack model and fallback material database, while simulator backends perform separate resolution. This creates inconsistent geometry, material, and optical-property behavior.

pdks PR #145 defines the target PDK schema: explicit LayerLevel geometry, material tokens, MaterialCard optical regimes, and wavelength/frequency snapshots. The schema package is declaration-focused, so gsim needs a runtime adapter and canonical resolver.

Goal

Create one schema-aware resolver used by new backends and available for later Meep migration. Existing gsim.meep behavior remains supported and is not changed by this issue.

Proposed API

from gsim.common.pdk import resolve_passive_pcell

resolved = resolve_passive_pcell(
    pdk=pdk,
    component="straight",
    settings={"length": 10},
    wavelength_um=1.55,
)

Return a resolved object containing:

• instantiated gdsfactory component;
• PDK and LayerStack;
• derived-layer-expanded component;
• normalized layer records with z geometry and mesh order;
• resolved optical material snapshots;
• ports and port-to-layer mapping;
• component bounds.

Requirements

• Accept explicit PDK object/module, or active PDK.
• Accept PCell name or callable plus settings.
• Instantiate through the PDK API.
• Apply derived layers before polygon extraction.
• Treat explicit zmin, thickness, sidewall_angle, and mesh_order as authoritative.
• Resolve every referenced LayerLevel.material token through the PDK material registry/linker.
• Select the MaterialCard.optical regime and evaluate one snapshot at requested wavelength.
• Fail clearly on unknown material, material=None, missing optical regime, invalid wavelength, or missing optical quantity.
• Do not use legacy MATERIALS_DB, chemistry guesses, synthetic fallback materials, or warning-and-skip behavior.
• Define canonical handling of stack dictionary keys versus LayerLevel.name.
• Expose enough information for both FDTD and future Meep migration.
• Keep ModelCard separate. ModelCard describes device behavioral models, not layer material resolution.
• Require axis-aligned ports for initial passive-device support, or return an explicit unsupported-port error.

Suggested adapter boundary:

class OpticalMaterialResolver(Protocol):
    def snapshot(
        self,
        material_name: str,
        *,
        wavelength_um: float,
    ) -> MaterialSnapshot: ...

Acceptance criteria

• Works with an explicit PDK and active PDK.
• Loads named and callable PCells.
• Derived layers appear in resolved geometry.
• Every referenced material resolves to one wavelength snapshot.
• Missing or invalid material produces an actionable exception.
• Tests cover a fake PDK plus at least one real gdsfactory PDK.
• Tests prove no legacy fallback material is silently inserted.
• Resolver output can be consumed by the future gsim.fdtd.Simulation backend.

Out of scope

• Gmsh generation.
• ZapFDTD JSON generation.
• Full dispersive-material support in ZapFDTD.
• Breaking or removing the existing Meep backend.