feat(tidy3d): FXC-4043-add-support-of-custom-drc-args-in-drc-runner

Author: marcorudolphflex

CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added multimode support to `WavePort` in the smatrix plugin, allowing multiple modes to be analyzed per port.
 - Added support for `.lydrc` files for design rule checking in the `klayout` plugin.
 - Added a Gaussian inverse design filter option with autograd gradients and complete padding mode coverage.
+- Added support for argument passing to DRC file when running checks with `DRCRunner.run(..., drc_args={key: value})` in klayout plugin.
 
 ### Breaking Changes
 - Edge singularity correction at PEC and lossy metal edges defaults to `True`.

tests/test_plugins/klayout/drc/test_drc.py

@@ -11,30 +11,153 @@
 
 import tidy3d as td
 from tidy3d.exceptions import FileError
-from tidy3d.plugins.klayout.drc.drc import DRCRunner
+from tidy3d.plugins.klayout.drc.drc import DRCConfig, DRCRunner, run_drc_on_gds
 from tidy3d.plugins.klayout.drc.results import DRCResults, parse_violation_value
 from tidy3d.plugins.klayout.util import check_installation
 
 filepath = Path(os.path.dirname(os.path.abspath(__file__)))
+KLAYOUT_PLUGIN_PATH = "tidy3d.plugins.klayout"
+
+
+def _basic_drc_config_kwargs(tmp_path: Path) -> dict[str, Path | bool]:
+    """Return minimal kwargs needed to instantiate DRCConfig in tests."""
+
+    drc_runset = tmp_path / "test.drc"
+    drc_runset.write_text('source($gdsfile)\nreport("DRC", $resultsfile)\n')
+    gdsfile = tmp_path / "test.gds"
+    gdsfile.write_text("")
+    resultsfile = tmp_path / "results.lyrdb"
+    return {
+        "gdsfile": gdsfile,
+        "drc_runset": drc_runset,
+        "resultsfile": resultsfile,
+        "verbose": False,
+    }
 
 
 def test_check_klayout_not_installed(monkeypatch):
     """check_installation raises when KLayout is not on PATH.
 
     Use monkeypatch to simulate absence, avoiding reliance on CI environment.
     """
-    monkeypatch.setattr("tidy3d.plugins.klayout.util.which", lambda _cmd: None)
+    monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.util.which", lambda _cmd: None)
     with pytest.raises(RuntimeError):
         check_installation(raise_error=True)
 
 
 def test_check_klayout_installed(monkeypatch):
     """check_installation returns a path and does not raise when present."""
     fake_path = "/usr/local/bin/klayout"
-    monkeypatch.setattr("tidy3d.plugins.klayout.util.which", lambda _cmd: fake_path)
+    monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.util.which", lambda _cmd: fake_path)
     assert check_installation(raise_error=True) == fake_path
 
 
+def test_runner_passes_drc_args_to_config(monkeypatch, tmp_path):
+    """Ensure DRCRunner forwards drc_args into the generated DRCConfig."""
+
+    drc_runset = tmp_path / "test.drc"
+    drc_runset.write_text('source($gdsfile)\nreport("DRC", $resultsfile)\n')
+    gdsfile = tmp_path / "test.gds"
+    gdsfile.write_text("")
+    resultsfile = tmp_path / "results.lyrdb"
+    captured_config = {}
+
+    def mock_run_drc_on_gds(config):
+        captured_config["config"] = config
+        return DRCResults.load(filepath / "drc_results.lyrdb")
+
+    monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.drc.drc.run_drc_on_gds", mock_run_drc_on_gds)
+
+    runner = DRCRunner(drc_runset=drc_runset, verbose=False)
+    user_args = {"foo": "bar", "baz": "1"}
+    runner.run(source=gdsfile, resultsfile=resultsfile, drc_args=user_args)
+
+    assert captured_config["config"].drc_args == user_args
+
+
+def test_run_drc_on_gds_appends_custom_args(monkeypatch, tmp_path):
+    """run_drc_on_gds adds extra -rd pairs for drc_args."""
+
+    drc_runset = tmp_path / "test.drc"
+    drc_runset.write_text('source($gdsfile)\nreport("DRC", $resultsfile)\n')
+    gdsfile = tmp_path / "test.gds"
+    gdsfile.write_text("")
+    resultsfile = tmp_path / "results.lyrdb"
+
+    monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.drc.drc.check_installation", lambda **_: None)
+
+    captured_cmd = {}
+
+    class DummyCompleted:
+        def __init__(self):
+            self.returncode = 0
+            self.stdout = b""
+            self.stderr = b""
+
+    def fake_run(cmd, capture_output):
+        captured_cmd["cmd"] = cmd
+        return DummyCompleted()
+
+    monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.drc.drc.run", fake_run)
+    monkeypatch.setattr(
+        f"{KLAYOUT_PLUGIN_PATH}.drc.drc.DRCResults.load",
+        lambda resultsfile: DRCResults(violations_by_category={}),
+    )
+
+    config = DRCConfig(
+        gdsfile=gdsfile,
+        drc_runset=drc_runset,
+        resultsfile=resultsfile,
+        verbose=False,
+        drc_args={"string_arg": "text", "numeric_value": 1},
+    )
+
+    run_drc_on_gds(config)
+
+    expected_tail = ["-rd", "string_arg=text", "-rd", "numeric_value=1"]
+    assert captured_cmd["cmd"][-len(expected_tail) :] == expected_tail
+
+
+def test_drc_config_args_require_mapping(tmp_path):
+    """drc_args must be a mapping and refuses other iterables."""
+
+    kwargs = _basic_drc_config_kwargs(tmp_path)
+    with pytest.raises(pd.ValidationError):
+        DRCConfig(**kwargs, drc_args=["not", "a", "mapping"])
+
+
+def test_drc_config_args_reject_reserved_keys(tmp_path):
+    """Reserved keys such as gdsfile cannot be overridden via drc_args."""
+
+    kwargs = _basic_drc_config_kwargs(tmp_path)
+    with pytest.raises(pd.ValidationError):
+        DRCConfig(**kwargs, drc_args={"gdsfile": "custom.gds"})
+
+
+def test_drc_config_args_stringify_values(tmp_path):
+    """Non-string keys and values are coerced to strings by the validator."""
+
+    kwargs = _basic_drc_config_kwargs(tmp_path)
+    config = DRCConfig(**kwargs, drc_args={1: Path("foo"), "flag": True})
+
+    assert config.drc_args == {"1": "foo", "flag": "True"}
+
+
+def test_drc_config_args_unstringifiable_value(tmp_path):
+    """Non-stringifiable drc_args values should raise a ValidationError."""
+
+    class Unstringifiable:
+        def __str__(self):
+            raise RuntimeError("cannot stringify")
+
+    kwargs = _basic_drc_config_kwargs(tmp_path)
+
+    with pytest.raises(
+        pd.ValidationError, match="Could not coerce keys and values of drc_args to strings."
+    ):
+        DRCConfig(**kwargs, drc_args={"bad": Unstringifiable()})
+
+
 class TestDRCRunner:
     """Test DRCRunner"""
 
@@ -147,6 +270,7 @@ def run(
         source,
         td_object_gds_savefile,
         resultsfile,
+        drc_args=None,
         **to_gds_file_kwargs,
     ):
         """Calls DRCRunner.run with dummy run_drc_on_gds()"""
@@ -155,13 +279,14 @@ def run(
         def mock_run_drc_on_gds(config):
             return DRCResults.load(filepath / "drc_results.lyrdb")
 
-        monkeypatch.setattr("tidy3d.plugins.klayout.drc.drc.run_drc_on_gds", mock_run_drc_on_gds)
+        monkeypatch.setattr(f"{KLAYOUT_PLUGIN_PATH}.drc.drc.run_drc_on_gds", mock_run_drc_on_gds)
 
         runner = DRCRunner(drc_runset=drc_runsetfile, verbose=verbose)
         return runner.run(
             source=source,
             td_object_gds_savefile=td_object_gds_savefile,
             resultsfile=resultsfile,
+            drc_args=drc_args,
             **to_gds_file_kwargs,
         )
 

tidy3d/plugins/klayout/drc/drc.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Mapping
 from pathlib import Path
 from subprocess import run
-from typing import Any, Union
+from typing import Any, Optional, Union
 
 import pydantic.v1 as pd
 from pydantic.v1 import validator
@@ -46,6 +47,11 @@ class DRCConfig(Tidy3dBaseModel):
         title="Verbose",
         description="Whether to print logging.",
     )
+    drc_args: dict[str, str] = pd.Field(
+        default_factory=dict,
+        title="DRC File Arguments",
+        description="Optional key/value pairs forwarded to KLayout as -rd <key>=<value> definitions.",
+    )
 
     @validator("gdsfile")
     def _validate_gdsfile_filetype(cls, v: pd.FilePath) -> pd.FilePath:
@@ -82,6 +88,34 @@ def _validate_drc_runset_format(cls, v: pd.FilePath) -> pd.FilePath:
                 )
         return v
 
+    @validator("drc_args", pre=True)
+    def _validate_drc_args_stringable(cls, v: Any) -> dict[str, str]:
+        """Coerce all keys and values in drc_args to strings."""
+        if v is None:
+            return {}
+        if not isinstance(v, Mapping):
+            raise ValidationError("drc_args must be a mapping of keys to values.")
+        try:
+            v = {str(k): str(v) for k, v in v.items()}
+        except Exception as e:
+            raise ValidationError("Could not coerce keys and values of drc_args to strings.") from e
+        return v
+
+    @validator("drc_args")
+    def _validate_drc_args_reserved(cls, v: dict[str, str]) -> dict[str, str]:
+        """Ensure user arguments do not override the reserved keys."""
+
+        reserved_keys = {"gdsfile", "resultsfile"}
+        conflicts = reserved_keys.intersection(v)
+        if conflicts:
+            conflict_str = ", ".join(sorted(conflicts))
+            raise ValidationError(
+                f"Invalid DRC argument key(s) {conflict_str}: these names are reserved and automatically "
+                "managed by Tidy3D."
+            )
+
+        return v
+
 
 class DRCRunner(Tidy3dBaseModel):
     """A class for running KLayout DRC. Can be used to run DRC on a Tidy3D object or a GDS file.
@@ -125,8 +159,9 @@ def run(
         source: Union[Geometry, Structure, Simulation, Path],
         td_object_gds_savefile: Path = DEFAULT_GDSFILE,
         resultsfile: Path = DEFAULT_RESULTSFILE,
+        drc_args: Optional[dict[str, str]] = None,
         **to_gds_file_kwargs: Any,
-    ) -> None:
+    ) -> DRCResults:
         """Runs KLayout's DRC on a GDS file or a Tidy3D object. The Tidy3D object can be a :class:`.Geometry`, :class:`.Structure`, or :class:`.Simulation`.
 
         Parameters
@@ -137,6 +172,8 @@ def run(
             The path to save the Tidy3D object to. Defaults to ``"layout.gds"``.
         resultsfile : Path
             The path to save the KLayout DRC results file to. Defaults to ``"drc_results.lyrdb"``.
+        drc_args : Optional[dict[str, str]] = None
+            Additional key/value pairs passed through to KLayout as ``-rd key=value`` CLI arguments.
         **to_gds_file_kwargs
             Additional keyword arguments to pass to the Tidy3D object-specific ``to_gds_file()`` method.
 
@@ -176,6 +213,7 @@ def run(
             drc_runset=self.drc_runset,
             resultsfile=resultsfile,
             verbose=self.verbose,
+            drc_args={} if drc_args is None else drc_args,
         )
         return run_drc_on_gds(config=config)
 
@@ -208,19 +246,21 @@ def run_drc_on_gds(config: DRCConfig) -> DRCResults:
             f"Running KLayout DRC on GDS file '{config.gdsfile}' with runset '{config.drc_runset}' and saving results to '{config.resultsfile}'..."
         )
     # run klayout DRC as a subprocess
-    output = run(
-        [
-            "klayout",
-            "-b",
-            "-r",
-            config.drc_runset,
-            "-rd",
-            f"gdsfile={config.gdsfile}",
-            "-rd",
-            f"resultsfile={config.resultsfile}",
-        ],
-        capture_output=True,
-    )
+    cmd = [
+        "klayout",
+        "-b",
+        "-r",
+        config.drc_runset,
+        "-rd",
+        f"gdsfile={config.gdsfile}",
+        "-rd",
+        f"resultsfile={config.resultsfile}",
+    ]
+
+    for key, value in config.drc_args.items():
+        cmd.extend(["-rd", f"{key}={value}"])
+
+    output = run(cmd, capture_output=True)
 
     if output.returncode != 0:
         raise RuntimeError(f"KLayout DRC failed with error message: '{output.stderr}'.")