moonbit-spice

    Download zip
    Author
    Version
    0.2.0
    License
    MIT
    Last updated
    2 months ago
    Downloads
    32

    No dependencies

    #moonbit-spice

    moonbit-spice is a reusable SPICE-like circuit analysis library written in MoonBit. It turns a readable netlist into a validated circuit model, assembles modified nodal analysis (MNA) equations, solves DC, AC, and transient operating points, and emits structured results for teaching tools, design utilities, scripts, and WASM front ends.

    #Core capabilities

    • SPICE-like parsing with blank lines, comments, directives, duplicate-name detection, and engineering suffixes (k, meg, m, u, n, p).
    • Resistors, capacitors, inductors, diodes, independent current sources, and independent voltage sources.
    • Dense MNA with partial pivoting, residual diagnostics, singular-system reporting, deterministic node ordering, and circuit topology inventory.
    • DC operating-point analysis with explicit warnings for DC approximations.
    • Complex MNA for frequency-domain AC analysis, gain curves, impedance helpers, and transfer-function models.
    • Backward-Euler RLC transient analysis, companion models, traces, settling metrics, and signal-processing utilities.
    • Sparse matrices with conjugate-gradient/Jacobi solvers, matrix diagnostics, topology graph views, and deterministic parameter/sensitivity analysis.
    • Engineering design helpers for component selection, uncertainty propagation, netlist editing, validation, and machine-readable reports.
    • CSV, text, and Markdown output that can be consumed by a CLI or a notebook.

    The implementation keeps model boundaries explicit: DC diode behavior uses a documented fixed-drop approximation, while AC and transient solvers expose the linearized models they actually solve. Unsupported or singular cases return a structured SpiceError instead of silently fabricating a result.

    #Quick start

    let circuit = @spice.parse_netlist(
    "V1 in 0 10\nR1 in out 1k\nR2 out 0 1k",
    )
    let result = @spice.dc(circuit)
    println(result.summary())

    From the repository root:

    moon fmt --check moon check --deny-warn moon test --deny-warn moon run cmd/spice

    The sample input is also available at examples/voltage-divider.cir.

    #CLI

    moon run cmd/spice runs a deterministic voltage-divider smoke example and prints a Markdown report. It is deliberately dependency-free so a fresh MoonBit checkout can run it without a package manager or native runtime library.

    The library API is the stable integration surface. Applications can read a file, call parse_netlist, choose dc or analyze, and serialize with report_csv, report_markdown, or SimulationResult::summary.

    #Architecture

    netlist text -> parser and validation -> Circuit / Device model -> model validation and topology -> dense or sparse MNA stamping -> DC / AC / transient solver -> metrics, traces, and diagnostics -> CSV / text / Markdown report

    The src/ package keeps public data structures and the analysis boundary in one place. Matrix, sparse, topology, AC, transient, signal, design, reporting, and benchmark utilities are split into focused files so callers can reuse the smallest useful unit.

    #Benchmarks

    The reproducible fixtures and commands live in benchmarks/. They measure the real parser, MNA, topology, formatting, and CLI paths. Run:

    Measure-Command { moon test --deny-warn } Measure-Command { moon run cmd/spice }

    The checked-in record reports one Windows run with MoonBit stable v0.10.9. Timings remain host-specific; CI stores command output as an artifact instead of presenting a local number as a universal claim.

    #Tests and boundary coverage

    Tests cover voltage-divider/current-source solutions, suffix parsing, duplicate devices, result exports, matrix residuals, topology connectivity, ordered sweeps, invalid transient grids, AC complex MNA, transient RLC stepping, sparse iterative solvers, netlist diagnostics, design helpers, signal/control models, batch analysis, graph editing, uncertainty, and quality reports. The local gate is:

    moon fmt --check moon check --deny-warn moon test --deny-warn moon info

    #CI

    GitHub Actions runs the current stable MoonBit installer on Ubuntu, macOS, and Windows. It checks all targets, formatting, public interface generation, warnings, tests, and the CLI smoke path. A separate workflow records deterministic benchmark artifacts. See .github/workflows/ci.yml.

    #License

    Released under the MIT License. The project is an independent MoonBit implementation. The example circuits are small educational fixtures and do not include copied third-party source or proprietary model files.