monata 0.1.0__tar.gz

monata-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+pip-wheel-metadata/
+.venv/
+.env
+.env.*
+!.env.example
+
+# Documentation build
+docs/_build/
+docs/api/monata/

monata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhangmai Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monata-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: monata
+Version: 0.1.0
+Summary: A lightweight EDA framework for circuit design and SPICE simulation workflows
+Project-URL: Homepage, https://github.com/lizhangmai/monata
+Project-URL: Repository, https://github.com/lizhangmai/monata
+Project-URL: Issues, https://github.com/lizhangmai/monata/issues
+Author: lizhangmai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analog,circuit,cmos,digital,eda,simulation,spice
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Requires-Dist: cffi
+Requires-Dist: h5py
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Monata
+
+Monata is a Python toolkit for circuit workflow automation. It provides a
+typed front end for organizing circuit projects, authoring SPICE-oriented
+netlists, running simulator tasks, and working with measurement and result
+data.
+
+Monata is designed as a lightweight Python package, not as a simulator
+distribution. It integrates with simulator and model-toolchain programs that
+users install in their own environments.
+
+## Features
+
+- Library, cell, and view organization for circuit projects.
+- Native circuit/netlist records with ngspice-compatible rendering.
+- Backend-neutral simulation tasks, result objects, sweeps, corners, Monte
+  Carlo flows, and measurements.
+- Built-in ngspice subprocess backend, plus a shared-library ngspice runner
+  for environments that provide `libngspice`.
+- Plotting and HDF5 result import/export available from the default install.
+- Optional technology-library packages, such as `monata-techlib`, for reusable
+  model metadata and redistributed model assets.
+
+## Installation
+
+```bash
+python -m pip install monata
+```
+
+Monata supports Python 3.11 and 3.12.
+
+## Quick Start
+
+Create a Monata library and build a small circuit:
+
+```python
+from monata import LibraryRegistry
+from monata.netlist import Circuit
+
+registry = LibraryRegistry()
+library = registry.create_library(path="work/analog", name="analog")
+cell = library.create_cell("rc_filter", description="RC low-pass filter")
+
+circuit = Circuit("rc low-pass")
+circuit.voltage("in", "vin", "0", "1")
+circuit.resistor("load", "vin", "vout", "1k")
+circuit.capacitor("hold", "vout", "0", "1n")
+
+print(cell.name)
+print(circuit.to_spice())
+```
+
+Run a simulation when a supported backend is installed:
+
+```python
+from monata.sim.core import DCSpec, LocalExecutor, SimTask
+
+task = SimTask(
+    circuit=circuit,
+    analysis_spec=DCSpec(source="Vin", start=0, stop=1, step=0.25),
+    output_names=["vout"],
+)
+
+result = LocalExecutor(max_workers=1).submit(task).result()
+if result.failed:
+    raise RuntimeError(result.error_message)
+
+print(result.waveforms["vout"])
+```
+
+The default backend is `ngspice-subprocess`, which runs a local `ngspice`
+executable from `PATH` or `CONDA_PREFIX/bin`.
+
+## External Tools
+
+The public `monata` package does not ship simulator binaries, shared simulator
+libraries, XSPICE code models, OpenVAF, Xyce, foundry PDKs, PTM model cards, or
+compiled OSDI binaries.
+
+Monata can use:
+
+- a user-installed `ngspice` executable through `ngspice-subprocess`;
+- a user-provided `libngspice` shared library through `ngspice-shared`;
+- separately installed technology-library packages such as `monata-techlib`.
+
+Users and downstream packagers remain responsible for installing external tools
+and complying with their upstream licenses.
+
+## Documentation
+
+Long-form documentation lives outside this source package:
+
+- Documentation repository: https://github.com/lizhangmai/monata-docs
+- Getting started: https://github.com/lizhangmai/monata-docs/tree/main/docs/getting-started
+- User guide: https://github.com/lizhangmai/monata-docs/tree/main/docs/user-guide
+- API boundaries: https://github.com/lizhangmai/monata-docs/blob/main/docs/reference/api-boundaries.md
+- Simulator and tool setup: https://github.com/lizhangmai/monata-docs/blob/main/docs/toolchain/external-tools.md
+- Maintainer notes: https://github.com/lizhangmai/monata-docs/tree/main/docs/maintainers
+
+## Security
+
+Monata project views can be Python source files. Loading schematic and testbench
+views executes that project code in the current Python process; view loading is
+not sandboxed. Open, load, generate, and simulate only trusted libraries and
+project workspaces.
+
+## License
+
+Monata's Python framework is licensed under the MIT License. See
+[`LICENSE`](LICENSE).

monata-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Monata
+
+Monata is a Python toolkit for circuit workflow automation. It provides a
+typed front end for organizing circuit projects, authoring SPICE-oriented
+netlists, running simulator tasks, and working with measurement and result
+data.
+
+Monata is designed as a lightweight Python package, not as a simulator
+distribution. It integrates with simulator and model-toolchain programs that
+users install in their own environments.
+
+## Features
+
+- Library, cell, and view organization for circuit projects.
+- Native circuit/netlist records with ngspice-compatible rendering.
+- Backend-neutral simulation tasks, result objects, sweeps, corners, Monte
+  Carlo flows, and measurements.
+- Built-in ngspice subprocess backend, plus a shared-library ngspice runner
+  for environments that provide `libngspice`.
+- Plotting and HDF5 result import/export available from the default install.
+- Optional technology-library packages, such as `monata-techlib`, for reusable
+  model metadata and redistributed model assets.
+
+## Installation
+
+```bash
+python -m pip install monata
+```
+
+Monata supports Python 3.11 and 3.12.
+
+## Quick Start
+
+Create a Monata library and build a small circuit:
+
+```python
+from monata import LibraryRegistry
+from monata.netlist import Circuit
+
+registry = LibraryRegistry()
+library = registry.create_library(path="work/analog", name="analog")
+cell = library.create_cell("rc_filter", description="RC low-pass filter")
+
+circuit = Circuit("rc low-pass")
+circuit.voltage("in", "vin", "0", "1")
+circuit.resistor("load", "vin", "vout", "1k")
+circuit.capacitor("hold", "vout", "0", "1n")
+
+print(cell.name)
+print(circuit.to_spice())
+```
+
+Run a simulation when a supported backend is installed:
+
+```python
+from monata.sim.core import DCSpec, LocalExecutor, SimTask
+
+task = SimTask(
+    circuit=circuit,
+    analysis_spec=DCSpec(source="Vin", start=0, stop=1, step=0.25),
+    output_names=["vout"],
+)
+
+result = LocalExecutor(max_workers=1).submit(task).result()
+if result.failed:
+    raise RuntimeError(result.error_message)
+
+print(result.waveforms["vout"])
+```
+
+The default backend is `ngspice-subprocess`, which runs a local `ngspice`
+executable from `PATH` or `CONDA_PREFIX/bin`.
+
+## External Tools
+
+The public `monata` package does not ship simulator binaries, shared simulator
+libraries, XSPICE code models, OpenVAF, Xyce, foundry PDKs, PTM model cards, or
+compiled OSDI binaries.
+
+Monata can use:
+
+- a user-installed `ngspice` executable through `ngspice-subprocess`;
+- a user-provided `libngspice` shared library through `ngspice-shared`;
+- separately installed technology-library packages such as `monata-techlib`.
+
+Users and downstream packagers remain responsible for installing external tools
+and complying with their upstream licenses.
+
+## Documentation
+
+Long-form documentation lives outside this source package:
+
+- Documentation repository: https://github.com/lizhangmai/monata-docs
+- Getting started: https://github.com/lizhangmai/monata-docs/tree/main/docs/getting-started
+- User guide: https://github.com/lizhangmai/monata-docs/tree/main/docs/user-guide
+- API boundaries: https://github.com/lizhangmai/monata-docs/blob/main/docs/reference/api-boundaries.md
+- Simulator and tool setup: https://github.com/lizhangmai/monata-docs/blob/main/docs/toolchain/external-tools.md
+- Maintainer notes: https://github.com/lizhangmai/monata-docs/tree/main/docs/maintainers
+
+## Security
+
+Monata project views can be Python source files. Loading schematic and testbench
+views executes that project code in the current Python process; view loading is
+not sandboxed. Open, load, generate, and simulate only trusted libraries and
+project workspaces.
+
+## License
+
+Monata's Python framework is licensed under the MIT License. See
+[`LICENSE`](LICENSE).

monata-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "monata"
+version = "0.1.0"
+description = "A lightweight EDA framework for circuit design and SPICE simulation workflows"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "lizhangmai" },
+]
+keywords = ["eda", "spice", "circuit", "simulation", "analog", "digital", "cmos"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "numpy",
+    "matplotlib",
+    "h5py",
+    "cffi",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "pyright",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/lizhangmai/monata"
+Repository = "https://github.com/lizhangmai/monata"
+Issues = "https://github.com/lizhangmai/monata/issues"
+
+[tool.hatch.build.targets.wheel]
+only-packages = true
+packages = ["src/monata"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/monata/",
+    "tests/",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]
+exclude = [
+    "data/",
+    "examples/",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers"]
+markers = [
+    "fast: quick unit or contract tests suitable for the default development loop",
+    "integration: cross-module workflows, external fixtures, or end-to-end persistence paths",
+    "native: tests that execute or depend on native simulator backends or external simulator binaries",
+    "slow: broad or computationally heavier suites kept out of the fast development loop",
+]
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+target-version = "py311"
+
+[tool.pyright]
+exclude = [
+    "**/__pycache__",
+    "build",
+    "dist",
+]
+extraPaths = ["src", "tests"]
+include = ["src/monata", "tests"]
+pythonVersion = "3.11"

monata-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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