evas-sim 0.1.0__tar.gz

evas_sim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zhishuai Zhang
+
+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.

evas_sim-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: evas-sim
+Version: 0.1.0
+Summary: Event-driven Verilog-A Simulator — pure-Python behavioral simulation
+Author: Zhishuai Zhang
+License: MIT
+Project-URL: Homepage, https://evas.tokenzhang.com
+Project-URL: Documentation, https://evas.tokenzhang.com
+Project-URL: Repository, https://github.com/Arcadia-1/EVAS
+Project-URL: Bug Tracker, https://github.com/Arcadia-1/EVAS/issues
+Keywords: verilog-a,simulation,mixed-signal,eda
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file
+
+# EVAS — Event-driven Verilog-A Simulator
+
+[![PyPI version](https://img.shields.io/pypi/v/evas-sim.svg)](https://pypi.org/project/evas-sim/)
+[![CI](https://github.com/Arcadia-1/EVAS/actions/workflows/ci.yml/badge.svg)](https://github.com/Arcadia-1/EVAS/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-evas.tokenzhang.com-blue)](https://evas.tokenzhang.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+EVAS is a lightweight, pure-Python behavioral simulator for digital/control-class
+Verilog-A models. It provides fast event-driven simulation with zero external
+EDA dependencies — no C compiler, no ngspice.
+
+📖 **Documentation:** [evas.tokenzhang.com](https://evas.tokenzhang.com) | [English](/en/)
+
+## Target Use Cases
+
+- Rapid behavioral verification of clocked digital blocks (comparators, ADCs, DACs, dividers, LFSRs, DFFs)
+- Event-driven models using `@cross`, `@above`, `transition()`, `@initial_step`
+- Voltage-mode contributions (`V() <+`)
+
+## Installation
+
+```bash
+pip install evas-sim
+```
+
+No C compiler, no ngspice. NumPy, Matplotlib, and Pandas are installed automatically.
+
+## Quickstart
+
+```bash
+# List all 15 bundled examples
+evas list
+
+# Run the clock divider example
+evas run clk_div
+
+# Run a specific testbench in a multi-testbench example
+evas run digital_basics --tb tb_not_gate.scs
+
+# Simulate your own netlist
+evas simulate path/to/tb.scs -o output/mydesign
+```
+
+`evas run clk_div` copies the Verilog-A model and Spectre testbench into
+`./clk_div/`, simulates it, and saves waveform data + a PNG plot to
+`./output/clk_div/`.
+
+## Bundled Examples
+
+| Name | Description |
+|------|-------------|
+| `clk_div` | Clock divider (ratio = 4) |
+| `clk_burst_gen` | Clock burst generator |
+| `digital_basics` | Basic gates: AND, NOT, OR, DFF, inverter chain |
+| `lfsr` | Linear feedback shift register |
+| `noise_gen` | Noise signal generator |
+| `ramp_gen` | Ramp signal generator |
+| `edge_interval_timer` | Edge-interval timer |
+| `d2b_4b` | 4-bit thermometer-to-binary decoder |
+| `dac_binary_clk_4b` | 4-bit binary DAC (clocked) |
+| `dac_therm_16b` | 16-bit thermometer DAC |
+| `adc_dac_ideal_4b` | 4-bit ideal ADC + DAC with sample-hold |
+| `cmp_strongarm` | StrongARM comparator |
+| `cmp_offset_search` | Comparator offset search algorithm |
+| `dwa_ptr_gen` | DWA pointer generator |
+| `sar_adc_dac_weighted_8b` | 8-bit weighted SAR ADC + DAC |
+
+## CSV Output Format
+
+All signals default to 6-digit scientific notation (`:.6e`). The `save` statement
+accepts an optional `:fmt` suffix per signal:
+
+| Suffix | Format | Example value |
+|--------|--------|---------------|
+| `:6e` | `:.6e` (default) | `4.500000e-01` |
+| `:10e` | `:.10e` | `4.5000000000e-01` |
+| `:2e` | `:.2e` | `4.50e-01` |
+| `:4f` | `:.4f` | `0.4500` |
+| `:d` | integer | `7` |
+
+```
+// With format hints
+save vin:10e vout:6e clk:2e dout_code:d
+```
+
+## Supported Verilog-A Features
+
+- Module declarations with parameters and port arrays
+- `@(cross(...))`, `@(above(...))` zero-crossing events
+- `@(initial_step)` initialization; combined events
+- `transition()` operator with delay, rise/fall times
+- `V(node)`, `V(a, b)` voltage access; `V(node) <+` voltage contributions
+- Arithmetic, logical, bitwise, shift, ternary operators
+- `for` loops, `if/else`, `begin/end` blocks
+- Integer and real variables, arrays, parameters with ranges
+- `` `include ``, `` `define ``, `` `default_transition `` preprocessor directives
+- SI suffixes; math functions: `ln`, `log`, `exp`, `sqrt`, `pow`, `abs`, `sin`, `cos`, `floor`, `ceil`, `min`, `max`
+- String parameters with `.substr()` method calls
+
+## Spectre Netlist Support
+
+- `vsource` with `dc`, `pulse`, `pwl`, `sin` types
+- `ahdl_include` for VA model files
+- `parameters` with expression evaluation
+- `tran` analysis with `stop` and `maxstep`
+- `save` signal selection with optional per-signal format specifiers
+
+## Limitations
+
+- No `I() <+` current contributions
+- No `ddt()`, `idt()` calculus operators
+- No MNA matrix solve (no KCL/KVL enforcement)
+- No transistor-level simulation
+- No AC or DC analysis (transient only)
+- No subcircuit hierarchy
+
+## Project Structure
+
+```
+EVAS/
+├── evas/
+│   ├── cli.py               # CLI entry point (evas simulate / run / list)
+│   ├── compiler/            # Verilog-A front-end (lexer, parser, AST)
+│   ├── simulator/           # Event-driven simulation engine + backend
+│   ├── netlist/             # Spectre .scs parser + orchestration runner
+│   ├── vams/                # VAMS include files (constants, disciplines)
+│   └── examples/            # 15 bundled example circuits
+├── docs/                    # Sphinx documentation (Chinese, default)
+├── docs_en/                 # Sphinx documentation (English)
+├── tests/
+└── pyproject.toml
+```
+
+## Development
+
+```bash
+git clone https://github.com/Arcadia-1/EVAS.git
+cd EVAS
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

evas_sim-0.1.0/README.md

@@ -0,0 +1,145 @@
+# EVAS — Event-driven Verilog-A Simulator
+
+[![PyPI version](https://img.shields.io/pypi/v/evas-sim.svg)](https://pypi.org/project/evas-sim/)
+[![CI](https://github.com/Arcadia-1/EVAS/actions/workflows/ci.yml/badge.svg)](https://github.com/Arcadia-1/EVAS/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-evas.tokenzhang.com-blue)](https://evas.tokenzhang.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+EVAS is a lightweight, pure-Python behavioral simulator for digital/control-class
+Verilog-A models. It provides fast event-driven simulation with zero external
+EDA dependencies — no C compiler, no ngspice.
+
+📖 **Documentation:** [evas.tokenzhang.com](https://evas.tokenzhang.com) | [English](/en/)
+
+## Target Use Cases
+
+- Rapid behavioral verification of clocked digital blocks (comparators, ADCs, DACs, dividers, LFSRs, DFFs)
+- Event-driven models using `@cross`, `@above`, `transition()`, `@initial_step`
+- Voltage-mode contributions (`V() <+`)
+
+## Installation
+
+```bash
+pip install evas-sim
+```
+
+No C compiler, no ngspice. NumPy, Matplotlib, and Pandas are installed automatically.
+
+## Quickstart
+
+```bash
+# List all 15 bundled examples
+evas list
+
+# Run the clock divider example
+evas run clk_div
+
+# Run a specific testbench in a multi-testbench example
+evas run digital_basics --tb tb_not_gate.scs
+
+# Simulate your own netlist
+evas simulate path/to/tb.scs -o output/mydesign
+```
+
+`evas run clk_div` copies the Verilog-A model and Spectre testbench into
+`./clk_div/`, simulates it, and saves waveform data + a PNG plot to
+`./output/clk_div/`.
+
+## Bundled Examples
+
+| Name | Description |
+|------|-------------|
+| `clk_div` | Clock divider (ratio = 4) |
+| `clk_burst_gen` | Clock burst generator |
+| `digital_basics` | Basic gates: AND, NOT, OR, DFF, inverter chain |
+| `lfsr` | Linear feedback shift register |
+| `noise_gen` | Noise signal generator |
+| `ramp_gen` | Ramp signal generator |
+| `edge_interval_timer` | Edge-interval timer |
+| `d2b_4b` | 4-bit thermometer-to-binary decoder |
+| `dac_binary_clk_4b` | 4-bit binary DAC (clocked) |
+| `dac_therm_16b` | 16-bit thermometer DAC |
+| `adc_dac_ideal_4b` | 4-bit ideal ADC + DAC with sample-hold |
+| `cmp_strongarm` | StrongARM comparator |
+| `cmp_offset_search` | Comparator offset search algorithm |
+| `dwa_ptr_gen` | DWA pointer generator |
+| `sar_adc_dac_weighted_8b` | 8-bit weighted SAR ADC + DAC |
+
+## CSV Output Format
+
+All signals default to 6-digit scientific notation (`:.6e`). The `save` statement
+accepts an optional `:fmt` suffix per signal:
+
+| Suffix | Format | Example value |
+|--------|--------|---------------|
+| `:6e` | `:.6e` (default) | `4.500000e-01` |
+| `:10e` | `:.10e` | `4.5000000000e-01` |
+| `:2e` | `:.2e` | `4.50e-01` |
+| `:4f` | `:.4f` | `0.4500` |
+| `:d` | integer | `7` |
+
+```
+// With format hints
+save vin:10e vout:6e clk:2e dout_code:d
+```
+
+## Supported Verilog-A Features
+
+- Module declarations with parameters and port arrays
+- `@(cross(...))`, `@(above(...))` zero-crossing events
+- `@(initial_step)` initialization; combined events
+- `transition()` operator with delay, rise/fall times
+- `V(node)`, `V(a, b)` voltage access; `V(node) <+` voltage contributions
+- Arithmetic, logical, bitwise, shift, ternary operators
+- `for` loops, `if/else`, `begin/end` blocks
+- Integer and real variables, arrays, parameters with ranges
+- `` `include ``, `` `define ``, `` `default_transition `` preprocessor directives
+- SI suffixes; math functions: `ln`, `log`, `exp`, `sqrt`, `pow`, `abs`, `sin`, `cos`, `floor`, `ceil`, `min`, `max`
+- String parameters with `.substr()` method calls
+
+## Spectre Netlist Support
+
+- `vsource` with `dc`, `pulse`, `pwl`, `sin` types
+- `ahdl_include` for VA model files
+- `parameters` with expression evaluation
+- `tran` analysis with `stop` and `maxstep`
+- `save` signal selection with optional per-signal format specifiers
+
+## Limitations
+
+- No `I() <+` current contributions
+- No `ddt()`, `idt()` calculus operators
+- No MNA matrix solve (no KCL/KVL enforcement)
+- No transistor-level simulation
+- No AC or DC analysis (transient only)
+- No subcircuit hierarchy
+
+## Project Structure
+
+```
+EVAS/
+├── evas/
+│   ├── cli.py               # CLI entry point (evas simulate / run / list)
+│   ├── compiler/            # Verilog-A front-end (lexer, parser, AST)
+│   ├── simulator/           # Event-driven simulation engine + backend
+│   ├── netlist/             # Spectre .scs parser + orchestration runner
+│   ├── vams/                # VAMS include files (constants, disciplines)
+│   └── examples/            # 15 bundled example circuits
+├── docs/                    # Sphinx documentation (Chinese, default)
+├── docs_en/                 # Sphinx documentation (English)
+├── tests/
+└── pyproject.toml
+```
+
+## Development
+
+```bash
+git clone https://github.com/Arcadia-1/EVAS.git
+cd EVAS
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

evas_sim-0.1.0/evas/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

evas_sim-0.1.0/evas/cli.py

@@ -0,0 +1,156 @@
+"""EVAS command-line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def _get_examples_root() -> Path:
+    """Return the path to the bundled examples directory."""
+    try:
+        from importlib.resources import files
+        pkg = files("evas.examples")
+        # On Python 3.9-3.10 with zip-safe=false, this returns a real Path
+        p = Path(str(pkg))
+        if p.is_dir():
+            return p
+    except Exception:
+        pass
+    # Fallback: locate relative to this file (editable installs)
+    return Path(__file__).parent / "examples"
+
+
+def _list_examples() -> list[str]:
+    root = _get_examples_root()
+    if not root.is_dir():
+        return []
+    return sorted(
+        d.name for d in root.iterdir()
+        if d.is_dir() and not d.name.startswith("_") and not d.name.startswith(".")
+    )
+
+
+def cmd_list(_args: argparse.Namespace) -> int:
+    names = _list_examples()
+    if not names:
+        print("No bundled examples found.", file=sys.stderr)
+        return 1
+    print(f"Available examples ({len(names)}):")
+    for name in names:
+        print(f"  {name}")
+    return 0
+
+
+def cmd_simulate(args: argparse.Namespace) -> int:
+    from evas.netlist.runner import evas_simulate
+    ok = evas_simulate(args.input, log_path=args.log, output_dir=args.output)
+    return 0 if ok else 1
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    from evas.netlist.runner import evas_simulate
+
+    name = args.name
+    examples_root = _get_examples_root()
+    src = examples_root / name
+    if not src.is_dir():
+        available = _list_examples()
+        print(f"Error: example '{name}' not found.", file=sys.stderr)
+        print(f"Available: {', '.join(available)}", file=sys.stderr)
+        return 1
+
+    # Copy example files to <cwd>/<name>/
+    dst = Path.cwd() / name
+    dst.mkdir(parents=True, exist_ok=True)
+
+    for f in src.iterdir():
+        if f.is_file() and not f.name.startswith("_"):
+            shutil.copy2(f, dst / f.name)
+
+    # Determine which .scs to run
+    if args.tb:
+        scs_file = dst / args.tb
+        if not scs_file.exists():
+            print(f"Error: testbench '{args.tb}' not found in {dst}", file=sys.stderr)
+            return 1
+    else:
+        # Prefer tb_<name>.scs; fall back to any single .scs
+        preferred = dst / f"tb_{name}.scs"
+        if preferred.exists():
+            scs_file = preferred
+        else:
+            scs_files = sorted(dst.glob("*.scs"))
+            if not scs_files:
+                print(f"Error: no .scs testbench found in {dst}", file=sys.stderr)
+                return 1
+            scs_file = scs_files[0]
+
+    output_dir = Path.cwd() / "output" / name
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"Running example '{name}': {scs_file.name} → {output_dir}")
+    env_backup = os.environ.get("EVAS_OUTPUT_DIR")
+    os.environ["EVAS_OUTPUT_DIR"] = str(output_dir)
+
+    try:
+        ok = evas_simulate(str(scs_file), output_dir=str(output_dir))
+    finally:
+        if env_backup is None:
+            os.environ.pop("EVAS_OUTPUT_DIR", None)
+        else:
+            os.environ["EVAS_OUTPUT_DIR"] = env_backup
+
+    if not ok:
+        return 1
+
+    # Run analyze_<name>.py if present
+    analyze = dst / f"analyze_{name}.py"
+    if analyze.exists():
+        import subprocess
+        print(f"Running analysis: {analyze.name}")
+        result = subprocess.run(
+            [sys.executable, str(analyze)],
+            cwd=str(dst),
+            env={**os.environ, "EVAS_OUTPUT_DIR": str(output_dir)},
+        )
+        return result.returncode
+
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="evas",
+        description="EVAS — Event-driven Verilog-A Simulator",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # evas simulate
+    p_sim = sub.add_parser("simulate", help="Simulate a Spectre .scs netlist")
+    p_sim.add_argument("input", help=".scs netlist file")
+    p_sim.add_argument("-o", "--output", default="./output",
+                       help="Output directory (default: ./output)")
+    p_sim.add_argument("-log", help="Log file path")
+    p_sim.set_defaults(func=cmd_simulate)
+
+    # evas run
+    p_run = sub.add_parser("run", help="Run a bundled example")
+    p_run.add_argument("name", help="Example name (see 'evas list')")
+    p_run.add_argument("--tb", metavar="FILE",
+                       help="Testbench filename override (default: tb_<name>.scs)")
+    p_run.set_defaults(func=cmd_run)
+
+    # evas list
+    p_list = sub.add_parser("list", help="List all available examples")
+    p_list.set_defaults(func=cmd_list)
+
+    args = parser.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()