monata 0.1.0__py3-none-any.whl

monata/__init__.py

@@ -0,0 +1,35 @@
+"""Monata — a lightweight EDA framework for circuit design."""
+
+from __future__ import annotations
+
+from monata.cell import Cell
+from monata.category import Category
+from monata.corner import OperatingCorner
+from monata.errors import (
+    CellNotFoundError,
+    LibraryNotFoundError,
+    ViewAlreadyModifiedError,
+    ViewNotFoundError,
+    ViewNotGeneratedError,
+)
+from monata.library import Library
+from monata.registry import LibraryRegistry
+from monata.units import Quantity, Unit, UnitArray
+from monata.views import View
+
+__all__ = [
+    "Cell",
+    "CellNotFoundError",
+    "Category",
+    "Library",
+    "LibraryNotFoundError",
+    "LibraryRegistry",
+    "OperatingCorner",
+    "Quantity",
+    "Unit",
+    "UnitArray",
+    "View",
+    "ViewAlreadyModifiedError",
+    "ViewNotFoundError",
+    "ViewNotGeneratedError",
+]

monata/_config.py

@@ -0,0 +1,105 @@
+"""Internal TOML persistence helpers for Monata workspace metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from monata._paths import toml_string
+
+
+def read_toml(path: Path) -> dict[str, Any]:
+    with path.open("rb") as file:
+        return tomllib.load(file)
+
+
+def reject_unknown_fields(
+    data: Mapping[str, Any], allowed: frozenset[str], subject: str
+) -> None:
+    unknown = sorted(key for key in data if key not in allowed)
+    if unknown:
+        raise ValueError(f"{subject} has unknown fields: {', '.join(unknown)}")
+
+
+def cell_config(name: str, *, description: str = "") -> dict[str, Any]:
+    return {"cell": {"name": name, "description": description}, "views": {}}
+
+
+def category_config(name: str, *, description: str = "") -> dict[str, Any]:
+    return {"category": {"name": name, "description": description}}
+
+
+def write_category_config(path: Path, config: Mapping[str, Any]) -> None:
+    category = config["category"]
+    lines = [f'[category]\nname = "{toml_string(category["name"])}"\n']
+    if "description" in category:
+        lines.append(f'description = "{toml_string(category["description"])}"\n')
+    path.write_text("".join(lines))
+
+
+def write_cell_config(path: Path, config: Mapping[str, Any]) -> None:
+    cell = config["cell"]
+    lines = [f'[cell]\nname = "{toml_string(cell["name"])}"\n']
+    if "description" in cell:
+        lines.append(f'description = "{toml_string(cell["description"])}"\n')
+    lines.append("\n[views]\n")
+    for view_type, view_config in config.get("views", {}).items():
+        parts = ", ".join(f"{key} = {toml_value(value)}" for key, value in view_config.items())
+        lines.append(f"{view_type} = {{ {parts} }}\n")
+    path.write_text("".join(lines))
+
+
+def write_library_config(
+    path: Path,
+    *,
+    name: str,
+    tech_model_paths: Iterable[Any],
+    description: str = "",
+    techlib_attachments: Iterable[str] = (),
+    default_corner: str | None = None,
+) -> None:
+    model_paths = ", ".join(toml_value(model_path) for model_path in tech_model_paths)
+    lines = [
+        f'[library]\nname = "{toml_string(name)}"\n',
+        f'description = "{toml_string(description)}"\n\n',
+        f"[technology]\nmodel_paths = [{model_paths}]\n",
+    ]
+    attachments = list(techlib_attachments)
+    if attachments or default_corner is not None:
+        techlibs = ", ".join(toml_value(attachment) for attachment in attachments)
+        lines.extend(["\n[attachments]\n", f"techlibs = [{techlibs}]\n"])
+        if default_corner is not None:
+            lines.append(f'default_corner = "{toml_string(default_corner)}"\n')
+    path.write_text("".join(lines))
+
+
+def write_project_config(
+    path: Path,
+    *,
+    name: str,
+    libraries: Iterable[Mapping[str, str]] = (),
+) -> None:
+    lines = [f'[project]\nname = "{toml_string(name)}"\n']
+    for entry in libraries:
+        lines.extend([
+            "\n[[libraries]]\n",
+            f'name = "{toml_string(entry["name"])}"\n',
+            f'path = "{toml_string(entry["path"])}"\n',
+        ])
+    path.write_text("".join(lines))
+
+
+def toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(toml_value(item) for item in value) + "]"
+    return f'"{toml_string(value)}"'

monata/_home.py

@@ -0,0 +1,47 @@
+"""Monata-managed mutable state locations."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def monata_home(explicit: str | Path | None = None) -> Path | None:
+    """Return the configured Monata home root, if one is configured."""
+
+    if explicit is not None:
+        return Path(explicit)
+    env = os.environ.get("MONATA_HOME")
+    return Path(env) if env else None
+
+
+def default_user_cache_root() -> Path:
+    """Return the platform-neutral user cache root used when MONATA_HOME is unset."""
+
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg)
+    return Path(os.path.expanduser("~/.cache"))
+
+
+def monata_cache_dir(*, home: str | Path | None = None) -> Path:
+    """Return the generic Monata cache directory for a configured home/default."""
+
+    root = monata_home(home)
+    if root is not None:
+        return root / "cache"
+    return default_user_cache_root() / "monata"
+
+
+def monata_registry_dir(*, home: str | Path | None = None) -> Path | None:
+    """Return the optional Monata registry directory when a home root exists."""
+
+    root = monata_home(home)
+    return root / "registry" if root is not None else None
+
+
+def monata_logs_dir(*, home: str | Path | None = None) -> Path | None:
+    """Return the optional Monata logs directory when a home root exists."""
+
+    root = monata_home(home)
+    return root / "logs" if root is not None else None

monata/_json.py

@@ -0,0 +1,57 @@
+"""Shared JSON-safe value coercion helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+def json_safe(value: Any, *, strict: bool = False) -> Any:
+    """Return a recursively JSON-compatible representation of common Monata values."""
+
+    result = _json_safe(value)
+    if strict:
+        json.dumps(result)
+    return result
+
+
+def json_safe_dict(values: Mapping[str, Any]) -> dict[str, Any]:
+    return {str(key): json_safe(value) for key, value in dict(values).items()}
+
+
+def _json_safe(value: Any) -> Any:
+    if hasattr(value, "to_dict"):
+        return json_safe(value.to_dict())
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, np.generic):
+        return json_safe(value.item())
+    if isinstance(value, complex):
+        return {"real": value.real, "imag": value.imag}
+    if isinstance(value, np.ndarray):
+        if np.iscomplexobj(value):
+            return {
+                "real": np.real(value).tolist(),
+                "imag": np.imag(value).tolist(),
+            }
+        return json_safe(value.tolist())
+    if isinstance(value, Mapping):
+        return json_safe_dict(value)
+    if isinstance(value, list | tuple):
+        return [json_safe(item) for item in value]
+    if isinstance(value, set | frozenset):
+        return [json_safe(item) for item in sorted(value, key=str)]
+    if hasattr(value, "item"):
+        try:
+            return json_safe(value.item())
+        except ValueError:
+            pass
+    if hasattr(value, "tolist"):
+        return json_safe(value.tolist())
+    return value

monata/_paths.py

@@ -0,0 +1,73 @@
+"""Shared path/name validation helpers for filesystem-backed APIs."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from typing import Any
+
+
+_SAFE_PATH_SEGMENT_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def validate_path_segment(value: Any, label: str = "name") -> str:
+    """Return a safe single path segment or raise a stable ValueError."""
+
+    if value is None:
+        raise ValueError(f"{label} must be a single safe path segment: {value}")
+    text = str(value)
+    path = Path(text)
+    if (
+        not text
+        or _SAFE_PATH_SEGMENT_RE.match(text) is None
+        or path.is_absolute()
+        or len(path.parts) != 1
+        or text in {".", ".."}
+    ):
+        raise ValueError(f"{label} must be a single safe path segment: {text}")
+    return text
+
+
+def expand_path(path: str | Path) -> Path:
+    """Return a path with environment variables and user markers expanded."""
+
+    return Path(os.path.expandvars(str(path))).expanduser().absolute()
+
+
+def walk_files(path: str | Path, *, follow_symlinks: bool = False) -> Iterator[Path]:
+    """Yield files below a path in deterministic traversal order."""
+
+    root = Path(path)
+    if root.is_file():
+        yield root
+        return
+
+    for current_root, dirnames, filenames in os.walk(root, followlinks=follow_symlinks):
+        dirnames.sort()
+        for filename in sorted(filenames):
+            yield Path(current_root) / filename
+
+
+def find_file(file_name: str | Path, directories: Iterable[str | Path]) -> Path:
+    """Return the first matching file name found under the provided directories."""
+
+    name = str(file_name)
+    if not name or Path(name).name != name:
+        raise ValueError(f"file_name must be a file name: {file_name}")
+
+    roots = tuple(directories)
+    for directory in roots:
+        for path in walk_files(directory):
+            if path.name == name:
+                return path
+
+    searched = ", ".join(str(directory) for directory in roots) or "<none>"
+    raise FileNotFoundError(f"file {name!r} not found under: {searched}")
+
+
+def toml_string(value: Any) -> str:
+    """Escape a value for a basic TOML string."""
+
+    return str(value).replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\t", "\\t")

monata/_types.py

@@ -0,0 +1,8 @@
+"""Lightweight internal type aliases shared across public owner modules."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+ReferenceMode = Literal["concrete", "logical"]
+NetlistProjectionMode = Literal["none", "concrete", "logical"]

monata/category.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from monata._config import (
+    category_config,
+    cell_config,
+    read_toml,
+    reject_unknown_fields,
+    write_category_config,
+    write_cell_config,
+)
+from monata._paths import validate_path_segment
+from monata.errors import CellNotFoundError
+
+CATEGORY_CONFIG_FILENAME = "category.toml"
+CELL_CONFIG_FILENAME = "cell.toml"
+_CATEGORY_CONFIG_FIELDS = frozenset({"category"})
+_CATEGORY_TABLE_FIELDS = frozenset({"name", "description"})
+
+
+def _validate_category_config(config: Mapping[str, Any]) -> None:
+    reject_unknown_fields(config, _CATEGORY_CONFIG_FIELDS, "category.toml")
+    try:
+        category = config["category"]
+    except KeyError as exc:
+        raise ValueError("category.toml is missing [category]") from exc
+    if not isinstance(category, Mapping):
+        raise ValueError("[category] must be a table")
+    reject_unknown_fields(category, _CATEGORY_TABLE_FIELDS, "category table")
+
+
+class Category:
+    """Filesystem-backed library category containing cells and subcategories."""
+
+    def __init__(self, path, library):
+        self._path = Path(path)
+        self._library = library
+        self._config = None
+        self._cells_cache = None
+        self._categories_cache = None
+
+    @classmethod
+    def create(cls, path, library, *, name: str, description: str = "") -> "Category":
+        safe_name = validate_path_segment(name, "category name")
+        category_dir = Path(path)
+        category_dir.mkdir(parents=True, exist_ok=False)
+        write_category_config(
+            category_dir / CATEGORY_CONFIG_FILENAME,
+            category_config(safe_name, description=description),
+        )
+        return cls(category_dir, library)
+
+    def _load_config(self):
+        if self._config is None:
+            self._config = read_toml(self._path / CATEGORY_CONFIG_FILENAME)
+            _validate_category_config(self._config)
+        return self._config
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def library(self):
+        return self._library
+
+    @property
+    def name(self) -> str:
+        return self._load_config()["category"]["name"]
+
+    @property
+    def qualified_name(self) -> str:
+        return self.path_relative_to_library().as_posix()
+
+    def path_relative_to_library(self) -> Path:
+        return self._path.relative_to(self._library.path)
+
+    def _cell_path(self, name: str) -> tuple[str, Path]:
+        safe_name = validate_path_segment(name, "cell name")
+        return safe_name, self._path / safe_name
+
+    def _scan_cells(self) -> dict[str, Path]:
+        if self._cells_cache is None:
+            self._cells_cache = {}
+            for entry in self._path.iterdir():
+                if entry.is_dir() and (entry / CELL_CONFIG_FILENAME).exists():
+                    self._cells_cache[entry.name] = entry
+        return self._cells_cache
+
+    def _scan_categories(self) -> dict[str, Path]:
+        if self._categories_cache is None:
+            self._categories_cache = {}
+            for entry in self._path.iterdir():
+                if entry.is_dir() and (entry / CATEGORY_CONFIG_FILENAME).exists():
+                    self._categories_cache[entry.name] = entry
+        return self._categories_cache
+
+    def list_cells(self) -> list[str]:
+        return sorted(self._scan_cells())
+
+    def list_categories(self) -> list[str]:
+        return sorted(self._scan_categories())
+
+    def get_category(self, path: str) -> "Category":
+        return self._library.get_category(f"{self.qualified_name}/{path}")
+
+    def create_category(self, name: str, description: str = "") -> "Category":
+        category = self._library.create_category(f"{self.qualified_name}/{name}", description=description)
+        self._categories_cache = None
+        return category
+
+    def create_cell(self, name: str, description: str = ""):
+        from monata.cell import Cell
+
+        safe_name, cell_dir = self._cell_path(name)
+        if cell_dir.exists():
+            raise FileExistsError(f"Cell already exists: {self.qualified_name}/{safe_name}")
+        cell_dir.mkdir()
+        write_cell_config(cell_dir / CELL_CONFIG_FILENAME, cell_config(safe_name, description=description))
+        self._cells_cache = None
+        self._library._clear_cell_cache()
+        return Cell(cell_dir, self._library, category=self)
+
+    def __getitem__(self, name: str):
+        from monata.cell import Cell
+
+        cells = self._scan_cells()
+        if name not in cells:
+            raise CellNotFoundError(name, self._library.name)
+        return Cell(cells[name], self._library, category=self)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._scan_cells()
+
+    def __iter__(self):
+        return iter(self._scan_cells())

monata/cell.py

@@ -0,0 +1,179 @@
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from monata._config import read_toml, reject_unknown_fields, write_cell_config
+from monata._paths import validate_path_segment
+from monata._types import NetlistProjectionMode
+from monata.errors import ViewAlreadyModifiedError, ViewNotFoundError
+from monata.views.registry import (
+    ViewConfig,
+    create_registered_view,
+    create_registered_view_config,
+    generate_registered_view,
+)
+
+_CELL_CONFIG_FIELDS = frozenset({"cell", "views"})
+_CELL_TABLE_FIELDS = frozenset({"name", "description"})
+
+
+def _validate_cell_config(config: Mapping[str, Any]) -> None:
+    reject_unknown_fields(config, _CELL_CONFIG_FIELDS, "cell.toml")
+    try:
+        cell = config["cell"]
+    except KeyError as exc:
+        raise ValueError("cell.toml is missing [cell]") from exc
+    if not isinstance(cell, Mapping):
+        raise ValueError("[cell] must be a table")
+    reject_unknown_fields(cell, _CELL_TABLE_FIELDS, "cell table")
+    views = config.get("views", {})
+    if not isinstance(views, Mapping):
+        raise ValueError("[views] must be a table")
+    for view_type, view_config in views.items():
+        safe_view_type = validate_path_segment(view_type, "view type")
+        if not isinstance(view_config, Mapping):
+            raise ValueError(f"view {safe_view_type} config must be a table")
+
+
+class Cell:
+    def __init__(self, path, library, *, category=None):
+        self._path = Path(path)
+        self._library = library
+        self._category = category
+        self._config = None
+
+    def _load_config(self):
+        if self._config is None:
+            self._config = read_toml(self._path / "cell.toml")
+            _validate_cell_config(self._config)
+        return self._config
+
+    @property
+    def name(self) -> str:
+        return self._load_config()["cell"]["name"]
+
+    @property
+    def library(self):
+        return self._library
+
+    @property
+    def category(self):
+        if self._category is not None:
+            return self._category
+        return self._infer_category()
+
+    @property
+    def category_path(self) -> str | None:
+        category = self.category
+        return category.qualified_name if category is not None else None
+
+    @property
+    def qualified_name(self) -> str:
+        category_path = self.category_path
+        return f"{category_path}/{self.name}" if category_path else self.name
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def _infer_category(self):
+        library_path = getattr(self._library, "path", None)
+        if library_path is None:
+            return None
+        try:
+            relative_parent = self._path.parent.relative_to(Path(library_path))
+        except ValueError:
+            return None
+        if relative_parent == Path("."):
+            return None
+        category_path = Path(library_path) / relative_parent
+        if not (category_path / "category.toml").exists():
+            return None
+        from monata.category import Category
+
+        self._category = Category(category_path, self._library)
+        return self._category
+
+    def _views_config(self) -> dict[str, ViewConfig]:
+        return self._load_config().get("views", {})
+
+    def list_views(self) -> list:
+        return sorted(self._views_config().keys())
+
+    def __getitem__(self, view_type: str):
+        views = self._views_config()
+        if view_type not in views:
+            raise ViewNotFoundError(view_type, self.name)
+        cfg = views[view_type]
+        return create_registered_view(self, view_type, cfg)
+
+    def __contains__(self, view_type: str) -> bool:
+        return view_type in self._views_config()
+
+    def _is_generated_view(self, view_type: str) -> bool:
+        config = self._views_config().get(view_type)
+        if config is None:
+            return True
+        return bool(config.get("generated", True))
+
+    def _ensure_generated_view_writable(self, view_type: str, *, force: bool) -> None:
+        if not self._is_generated_view(view_type) and not force:
+            raise ViewAlreadyModifiedError(view_type, self.name)
+
+    def _set_view_config(self, view_type: str, view_config: ViewConfig) -> None:
+        config = self._load_config()
+        config.setdefault("views", {})[view_type] = view_config
+        write_cell_config(self._path / "cell.toml", config)
+        self._config = None
+
+    def _register_generated_view(self, view_type: str, *, entry: str) -> None:
+        self._set_view_config(
+            view_type,
+            create_registered_view_config(view_type, entry=entry, generated=True),
+        )
+
+    def write_generated_view(
+        self,
+        view_type: str,
+        *,
+        entry: str,
+        content: str,
+        force: bool = False,
+    ) -> Path:
+        """Write a generated view artifact and commit its view metadata."""
+
+        self._ensure_generated_view_writable(view_type, force=force)
+        view_path = self._path / entry
+        view_path.write_text(content)
+        self._register_generated_view(view_type, entry=entry)
+        return view_path
+
+    def create_view(self, view_type: str, **kwargs):
+        view_cfg = create_registered_view_config(view_type, **kwargs)
+        self._set_view_config(view_type, view_cfg)
+
+        return self[view_type]
+
+    def generate_symbol(self, force: bool = False) -> Path:
+        return self.generate_view("symbol", force=force)
+
+    def generate_netlist(
+        self,
+        force: bool = False,
+        format: str = "cir",
+        *,
+        projection: NetlistProjectionMode = "none",
+        registry: Any = None,
+        corner: Any = None,
+    ) -> Path:
+        return self.generate_view(
+            "netlist",
+            force=force,
+            format=format,
+            projection=projection,
+            registry=registry,
+            corner=corner,
+        )
+
+    def generate_view(self, view_type: str, **kwargs) -> Path:
+        return generate_registered_view(self, view_type, **kwargs)

monata/circuits/__init__.py

@@ -0,0 +1,29 @@
+"""Reusable circuit construction helpers built on top of Monata netlists."""
+
+from monata.circuits.cmos import (
+    TransistorParams,
+    add_inverter,
+    add_nand2,
+    add_nmos,
+    add_nor2,
+    add_pmos,
+    add_transmission_gate,
+    transistor_params,
+)
+from monata.circuits.source import (
+    build_source_subcircuit_instances,
+    source_subcircuit_ports,
+)
+
+__all__ = [
+    "TransistorParams",
+    "add_inverter",
+    "add_nand2",
+    "add_nmos",
+    "add_nor2",
+    "add_pmos",
+    "add_transmission_gate",
+    "build_source_subcircuit_instances",
+    "source_subcircuit_ports",
+    "transistor_params",
+]