librelane 2.4.0__py3-none-any.whl

librelane/common/drc.py

@@ -0,0 +1,246 @@
+# Copyright 2020-2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import io
+import re
+import json
+import shlex
+from enum import IntEnum
+from decimal import Decimal, InvalidOperation
+from dataclasses import dataclass, field, asdict
+from typing import List, Optional, Tuple, Dict
+
+BoundingBox = Tuple[Decimal, Decimal, Decimal, Decimal]  # microns
+
+
+@dataclass
+class Violation:
+    rules: List[Tuple[str, str]]  # (layer, rule)
+    description: str
+    bounding_boxes: List[BoundingBox] = field(default_factory=list)
+
+    @property
+    def layer(self) -> str:
+        return self.rules[0][0]
+
+    @property
+    def rule(self) -> str:
+        return self.rules[0][1]
+
+    @property
+    def category_name(self) -> str:
+        return f"{self.layer}.{self.rule}"
+
+
+illegal_overlap_rx = re.compile(r"between (\w+) and (\w+)")
+
+
+@dataclass
+class DRC:
+    """
+    A primitive database representing DRC violations generated by a design.
+    """
+
+    module: str
+    violations: Dict[str, Violation]
+
+    @classmethod
+    def from_magic(
+        Self,
+        report: io.TextIOWrapper,
+    ) -> Tuple["DRC", int]:
+        """
+        Parses a report generated by Magic into a DRC object.
+
+        :param report: A **text** input stream containing the report in question.
+            You can pass the result of ``open("drc.rpt")``, for example.
+        :returns: A tuple of the DRC object and an int representing the number
+            of DRC violations.
+        """
+
+        class State(IntEnum):
+            drc = 0
+            data = 1
+            header = 10
+
+        MAGIC_SPLIT_LINE = "-" * 40
+        MAGIC_RULE_LINE_PARSER = re.compile(r"^(.+?)(?:\s*\((.+)\))?$")
+        MAGIC_RULE_RX = re.compile(r"([\w\-]+)\.([\w\-]+)")
+
+        violations: Dict[str, Violation] = {}
+
+        violation: Optional[Violation] = None
+        state = State.header
+        module = "UNKNOWN"
+        counter = 0
+        bbox_count = 0
+        for i, line in enumerate(report):
+            line = line.strip()
+            if ("[INFO]" in line) or (line == ""):
+                continue
+
+            if MAGIC_SPLIT_LINE in line:
+                if state.value > 0:
+                    violation = None
+                    state = State.drc
+                else:
+                    state = State.data
+            elif state == State.header:
+                module = line
+            elif state == State.drc:
+                match = MAGIC_RULE_LINE_PARSER.match(line)
+                assert match is not None, "universal regex did not match string"
+                description = match[0]
+                rules = []
+                if rules_raw := match[2]:
+                    for match in MAGIC_RULE_RX.finditer(rules_raw):
+                        layer = match[1]
+                        rule = match[2]
+                        rules.append((layer, rule))
+                if len(rules) == 0:
+                    rules = [("UNKNOWN", f"UNKNOWN{counter}")]
+                violation = Violation(rules, description)
+                counter += 1
+            elif state == State.data:
+                assert violation is not None, "Parser reached an inconsistent state"
+                try:
+                    coord_list = [Decimal(coord[:-2]) for coord in line.split()]
+                except InvalidOperation:
+                    raise ValueError(
+                        f"invalid bounding box at line {i}: number is invalid"
+                    )
+
+                if len(coord_list) != 4:
+                    raise ValueError(
+                        f"invalid bounding box at line {i}: bounding box has {len(coord_list)}/4 elements"
+                    )
+
+                bounding_box: BoundingBox = (
+                    coord_list[0],
+                    coord_list[1],
+                    coord_list[2],
+                    coord_list[3],
+                )
+
+                violation.bounding_boxes.append(bounding_box)
+                violations[violation.category_name] = violation
+                bbox_count += 1
+
+        return (Self(module, violations), bbox_count)
+
+    @classmethod
+    def from_magic_feedback(
+        Self, feedback: io.TextIOWrapper, cif_scale: Decimal, module: str
+    ) -> Tuple["DRC", int]:
+        bbox_count = 0
+        violations: Dict[str, Violation] = {}
+        last_bounding_box: Optional[BoundingBox] = None
+        lex = shlex.shlex(feedback.read(), posix=True)
+        components = list(lex)
+        while len(components):
+            instruction = components.pop(0)
+            if instruction == "box":
+                if len(components) < 4:
+                    raise ValueError(
+                        "Invalid syntax: 'box' command has less than 4 arguments"
+                    )
+                lx, ly, ux, uy = components[0:4]
+                last_bounding_box = (
+                    Decimal(lx) * cif_scale,
+                    Decimal(ly) * cif_scale,
+                    Decimal(ux) * cif_scale,
+                    Decimal(uy) * cif_scale,
+                )
+                bbox_count += 1
+                components = components[4:]
+            elif instruction == "feedback":
+                try:
+                    subcmd = components.pop(0)
+                except IndexError:
+                    raise ValueError("feedback not given subcommand")
+                if subcmd != "add":
+                    raise ValueError(f"Unsuppoorted feedback subcommand {subcmd}")
+
+                try:
+                    rule = components.pop(0)
+                    _ = components.pop(0)
+                except IndexError:
+                    raise ValueError(
+                        "Invalid syntax: 'feedback add' command has less than 2 arguments"
+                    )
+                vio_layer = "UNKNOWN"
+                vio_rulenum = f"UNKNOWN{len(violations)}"
+                if "Illegal overlap" in rule:
+                    vio_rulenum = "ILLEGAL_OVERLAP"
+                    if match := illegal_overlap_rx.search(rule):
+                        vio_layer = "-".join((match[1], match[2]))
+                if rule not in violations:
+                    violations[rule] = Violation([(vio_layer, vio_rulenum)], rule, [])
+                if last_bounding_box is None:
+                    raise ValueError("Attempted to add feedback without a box selected")
+                violations[rule].bounding_boxes.append(last_bounding_box)
+        violations = {vio.category_name: vio for vio in violations.values()}
+        return (Self(module, violations), bbox_count)
+
+    def dumps(self):
+        """
+        :returns: The DRC object as a JSON string.
+        """
+        return json.dumps(asdict(self))
+
+    def to_klayout_xml(self, out: io.BufferedIOBase):
+        """
+        Converts the DRC object to a KLayout-compatible XML database.
+
+        :param out: A **binary** output stream to the target XML file.
+            You can pass the result of ``open("drc.xml",  "wb")``, for example.
+        """
+        from lxml import etree as ET
+
+        with ET.xmlfile(out, encoding="utf8", buffered=False) as xf:
+            xf.write_declaration()
+            with xf.element("report-database"):
+                # 1. Cells
+                with xf.element("cells"):
+                    with xf.element("cell"):
+                        name = ET.Element("name")
+                        name.text = self.module
+                        xf.write(name)
+                # 2. Categories
+                with xf.element("categories"):
+                    for _, violation in self.violations.items():
+                        with xf.element("category"):
+                            name = ET.Element("name")
+                            name.text = violation.category_name
+                            description = ET.Element("description")
+                            description.text = violation.description
+                            xf.write(name, description)
+                # 3. Items
+                with xf.element("items"):
+                    for _, violation in self.violations.items():
+                        for bounding_box in violation.bounding_boxes:
+                            with xf.element("item"):
+                                cell = ET.Element("cell")
+                                cell.text = self.module
+                                category = ET.Element("category")
+                                category.text = f"'{violation.category_name}'"
+                                visited = ET.Element("visited")
+                                visited.text = "false"
+                                multiplicity = ET.Element("multiplicity")
+                                multiplicity.text = str(len(violation.bounding_boxes))
+                                xf.write(cell, category, visited, multiplicity)
+                                with xf.element("values"):
+                                    llx, lly, urx, ury = bounding_box
+                                    value = ET.Element("value")
+                                    value.text = f"polygon: ({llx},{lly};{urx},{lly};{urx},{ury};{llx},{ury})"
+                                    xf.write(value)

librelane/common/generic_dict.py

@@ -0,0 +1,319 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+import json
+import dataclasses
+from enum import Enum
+from decimal import Decimal
+from collections import UserString
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Hashable,
+    ItemsView,
+    Iterator,
+    Mapping,
+    Sequence,
+    Type,
+    TypeVar,
+    Tuple,
+    Optional,
+)
+
+from .misc import idem
+from .types import is_string
+
+
+class GenericDictEncoder(json.JSONEncoder):
+    """
+    A JSON encoder for :class:`GenericDict` objects. Also handles some types not
+    necessarily handled by the default JSON encoder, i.e., UserString, os.PathLike,
+    Decimals, etcetera.
+
+    It is recommended to use :meth:`GenericDict.to_json` unless you know what
+    you're doing.
+    """
+
+    def default(self, o):
+        if isinstance(o, GenericDict):
+            return o.to_raw_dict()
+        elif isinstance(o, os.PathLike) or isinstance(o, UserString):
+            return str(o)
+        elif not isinstance(o, type) and dataclasses.is_dataclass(o):
+            return dataclasses.asdict(o)
+        elif isinstance(o, Enum):
+            return o.name
+        elif isinstance(o, Decimal):
+            if o.is_infinite() or o.as_integer_ratio()[1] != 1:
+                return float(o)
+            else:
+                return int(o)
+        return o
+
+
+KT = TypeVar("KT", bound=Hashable)
+VT = TypeVar("VT")
+
+
+class GenericDict(Mapping[KT, VT]):
+    """
+    A dictionary with generic keys and values that is compatible with Python 3.8.1.
+
+    :param copying: A base Mapping object to copy values from.
+    :param overrides: Another mapping object to override the value from `copying`
+        with.
+    """
+
+    _data: Dict[KT, VT]
+
+    def __init__(
+        self,
+        copying: Optional[Mapping[KT, VT]] = None,
+        /,
+        overrides: Optional[Mapping[KT, VT]] = None,
+    ) -> None:
+        super().__init__()
+        self.__data = {}
+        copying = copying or {}
+        overrides = overrides or {}
+
+        for key, value in copying.items():
+            self.__data[key] = value
+        for key, value in overrides.items():
+            self.__data[key] = value
+
+    def __getitem__(self, key: KT) -> VT:
+        return self.__data[key]
+
+    def __setitem__(self, key: KT, item: VT):
+        self.__data[key] = item
+
+    def __delitem__(self, key: KT):
+        del self.__data[key]
+
+    def __len__(self) -> int:
+        return len(self.__data)
+
+    def __repr__(self) -> str:
+        return self.to_raw_dict().__repr__()
+
+    def __iter__(self) -> Iterator[KT]:
+        return iter(self.__data)
+
+    def __eq__(self, __o: object) -> bool:
+        if not (isinstance(__o, GenericDict) or isinstance(__o, dict)):
+            raise NotImplementedError()
+
+        rhs = __o
+        if isinstance(__o, GenericDict):
+            rhs = __o.to_raw_dict()
+
+        lhs = self.to_raw_dict()
+
+        return rhs == lhs
+
+        # ---
+        for key in set(self.keys()).union(__o.keys()):
+            if key not in self or key not in __o:
+                return False
+            if self[key] != __o[key]:
+                return False
+        return True
+
+    def pop(self, key: KT, /) -> VT:
+        """
+        :param key: The key to pop the value for.
+        :returns: The value for key. Raises ``IndexError`` if the key does not
+            exist. The key/value pair is then deleted from the dictionary.
+        """
+        value = self[key]
+        del self[key]
+        return value
+
+    T = TypeVar("T", bound="GenericDict")
+
+    def copy(self: T) -> T:
+        """
+        Convenience replacement for `object.__class__(object)`, which would
+        create a copy of the ``GenericDict`` object.
+
+        :returns: The copy
+        """
+        return self.__class__(self)
+
+    def to_raw_dict(self) -> dict:
+        """
+        :returns: A copy of the underlying Python built-in ``dict`` for this class.
+        """
+        return self.__data.copy()
+
+    def get_encoder(self) -> Type[GenericDictEncoder]:
+        """
+        :returns: A JSON encoder handling GenericDict objects.
+        """
+        return GenericDictEncoder
+
+    def keys(self):
+        """
+        :returns: A set-like object providing a view of the keys of the GenericDict object.
+        """
+        return self.__data.keys()
+
+    def values(self):
+        """
+        :returns: A set-like object providing a view of the values of the GenericDict object.
+        """
+        return self.__data.values()
+
+    def items(self) -> ItemsView[KT, VT]:
+        """
+        :returns: A set-like object providing a view of the GenericDict object as (key, value) tuples.
+        """
+        return self.__data.items()
+
+    def dumps(self, **kwargs) -> str:
+        """
+        :param kwargs: Passed to ``json.dumps``.
+        :returns: A JSON string representing the the GenericDict object.
+        """
+        if "indent" not in kwargs:
+            kwargs["indent"] = 4
+        return json.dumps(self.to_raw_dict(), cls=self.get_encoder(), **kwargs)
+
+    def check(self, key: KT, /) -> Tuple[Optional[KT], Optional[VT]]:
+        """
+        Checks if a key exists and returns a tuple in the form ``(key, value)``.
+
+        :param key: The key in question
+        :returns: If the key does not exist, the value of ``key`` will be ``None`` and so will
+            ``value``. If the key exists, ``key`` will be the key being checked for
+            existence and ``value`` will be the value assigned to said key in the
+            GenericDict object.
+
+            Do note ``None`` is a valid value for some keys, so simply
+            checking if the second element ``is not None`` is insufficient to check
+            whether a key exists.
+        """
+        return (key if key in self.__data else None, self.get(key))
+
+    def update(self, incoming: "Mapping[KT, VT]"):
+        """
+        A convenience function to update multiple values in the GenericDict object
+        at the same time.
+        :param incoming: The values to update
+        """
+        for key, value in incoming.items():
+            self[key] = value
+
+    def update_reorder(self, incoming: "Mapping[KT, VT]"):
+        """
+        A convenience function to update multiple values in the GenericDict object
+        at the same time. Pre-existing keys are deleted first so the values in
+        incoming are emplaced at the end of the dictionary.
+
+        :param incoming: The values to update
+        """
+        for key, value in incoming.items():
+            if key in self:
+                del self[key]
+            self[key] = value
+
+
+class GenericImmutableDict(GenericDict[KT, VT]):
+    __lock: bool
+
+    def __init__(
+        self,
+        copying: Optional[Mapping[KT, VT]] = None,
+        /,
+        *args,
+        **kwargs,
+    ) -> None:
+        super().__init__(copying, *args, **kwargs)
+        self.__lock = True
+
+    def __setitem__(self, key: KT, item: VT):
+        if self.__lock:
+            raise TypeError(f"{self.__class__.__name__} is immutable")
+        return super().__setitem__(key, item)
+
+    def __delitem__(self, key: KT):
+        if self.__lock:
+            raise TypeError(f"{self.__class__.__name__} is immutable")
+        return super().__delitem__(key)
+
+    def __delattr__(self, attr: str):
+        if self.__lock:
+            raise TypeError(f"{self.__class__.__name__} is immutable")
+        return super().__delattr__(attr)
+
+    def __setattr__(self, attr: str, value: Any):
+        try:
+            if self.__lock:
+                raise TypeError(f"{self.__class__.__name__} is immutable")
+        except AttributeError:
+            pass
+        return super().__setattr__(attr, value)
+
+    def copy_mut(self) -> GenericDict[KT, VT]:
+        return GenericDict(self)
+
+
+# Screw this, if you can figure out how to type hint mapping in dictionary out
+# and non-mapping in sequence out in Python, be my guest
+def copy_recursive(input, translator: Callable = idem):
+    """
+    Copies any arbitrarily-deep nested structure of Mappings and/or Sequences.
+
+    :param input: The input nested structure
+    :param translator: Before an object is appended, this function will be
+        called to process the value.
+
+        By default, :func:`idem` is called.
+    :returns: The copy.
+
+        All sequences will become built-in ``list``\\(s) and all mappings will
+        become built-in ``dict``\\(s).
+    """
+
+    def recursive(input, visit_stack: list, *, sequence_cls=list, mapping_cls=dict):
+        if id(input) in visit_stack:
+            raise ValueError("Circular reference found in target object")
+
+        visit_stack.append(id(input))
+
+        result: Any = input
+
+        if isinstance(input, Mapping):  # Mappings are Sequences, but not vice versa
+            result = mapping_cls()
+            for key, value in input.items():
+                result[key] = recursive(value, visit_stack)
+        elif dataclasses.is_dataclass(input) and not isinstance(input, type):
+            replace = {}
+            as_dict = dataclasses.asdict(input)
+            for key, value in as_dict.items():
+                replace[key] = recursive(value, visit_stack)
+            result = dataclasses.replace(input, **replace)
+        elif not is_string(input) and isinstance(input, Sequence):
+            result = sequence_cls()
+            for value in input:
+                result.append(recursive(value, visit_stack))
+
+        visit_stack.pop()
+
+        result = translator(result)
+        return result
+
+    return recursive(input, [])

librelane/common/metrics/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Metrics Module
+-----------------------
+
+Classes and functions for dealing with Metrics based on the `METRICS2.1 <https://github.com/ieee-ceda-datc/datc-rdf-Metrics4ML>`_ standard.
+"""
+from . import library
+from .metric import MetricAggregator, MetricComparisonResult, Metric
+from .util import parse_metric_modifiers, aggregate_metrics, MetricDiff