# Monata Roadmap TODO Monata's target is to become the project/workflow framework for the circuit toolchain while covering practical SPICE execution, import, measurement, model-management, and experiment workflows. This roadmap is organized by delivery horizon: - **Completed foundation** records capabilities that should be preserved. - **Near-term roadmap** contains implementation-sized work that can be planned, tested, and delivered without changing simulator scope. - **Mid-term roadmap** contains product-scale capabilities that need one or two foundation steps first. - **Long-term roadmap** contains ecosystem or product bets that need explicit design, licensing, or deployment decisions before implementation. - **Deferred simulator expansion** is intentionally separate. Do not infer new simulator backends from general roadmap items. ## Current Baseline Monata already has: - `Project -> Library -> Cell -> schematic/netlist/testbench view` workflow. - Native Python circuit authoring for compact R/C/L/V/I/M/X/subcircuit flows. - Broad netlist IR coverage for common SPICE primitives, dot commands, directives, source waveforms, raw control lines, and imported raw fallback. - Monata-owned parser/import path with source-located structured errors, continuation handling, `.control` grouping, common dot commands, expression coverage, full-deck import, subcircuit/model asset import, and `cir2py`-style conversion from imported IR. - Shared structured mutation resolver for global params, element values, element params, source values, subcircuit instance params, ambiguity errors, and explicit raw-directive fallback. - `SimTask` / `SimResult` as the simulator boundary. - Stable `ngspice-subprocess` execution for DC, transient, AC, operating point, noise, sensitivity, pole-zero, distortion, transfer-function, and Fourier flows. - Typed `AnalysisResult` / `Waveform` access, legacy `SimResult.waveforms[name]` numpy-compatible arrays, ASCII/binary rawfile parsing, complex AC vectors, branch currents, and plotting-neutral derived transforms. - Measurement results, `Spec` / `SpecTable`, Python metric evaluation, analysis summaries, and local Experiment persistence. - Sweep, corner, Monte Carlo, optimizer, and native ngspice projection through the shared mutation layer. - Monte Carlo process/global variation, mismatch pairs, seed/sample metadata, LocalExecutor native-mode capability, deterministic task-expanded fallback, and numpy-only result column helpers. - Project-scale model tooling: content-hash cache, OpenVAF/ADMS compiler wrappers, model registry entries, OSDI discovery, family/level/version resolution, project-local model manifests, relative relocation, and model/corner projection into simulation tasks. - User-facing delivery helpers: tested examples, JSON result export/import, optional plotting helpers, documentation notes, and backend capability discovery. ## Guardrails - Preserve the Library/Cell/View workflow as the top-level user model. - Keep `SimTask` / `SimResult` as the backend boundary. - Ordinary simulator failures should return structured failed `SimResult` objects with reason metadata where practical. - Keep plain Python numbers accepted everywhere existing Monata code accepts them. - Keep `SimResult.waveforms` compatible while typed result adoption grows. - Prefer structured IR mutation. Use raw/text fallback only when the target has explicit provenance and cannot be represented structurally. - Do not add runtime dependencies to core Monata without a clear user-facing need and tests. Plotting, heavy export, docs, database, cloud, GUI, and backend-specific packages should remain optional. - Do not bundle third-party PDKs, device models, or license-sensitive example decks in the package. - Keep `ngspice-subprocess` as the stable reference backend until a later explicit simulator-expansion plan proves another backend. ## Verification Baseline For Monata source work, use the editable environment: ```bash pixi run --manifest-path test/pixi.toml -e monata-dev test-monata-src-targeted pixi run --manifest-path test/pixi.toml -e monata-dev test-monata-src pixi run --manifest-path test/pixi.toml -e monata-dev ruff check src/monata/src/monata src/monata/tests pixi run --manifest-path test/pixi.toml -e monata-dev pyright git -C src/monata diff --check ``` Use packaged integration only when validating built artifacts or package installation behavior. ## Completed Foundation ### P1 - Netlist IR And Source Authoring (done) - Native element authoring and deterministic ngspice rendering. - Structured source helpers and source-value validation. - Stable element identity and lookup semantics. ### P2 - Typed Values, Waveforms, And Result Ergonomics (done) - Monata-owned unit/value helpers. - Typed waveform metadata and plotting-neutral transforms. - Result lookup and legacy waveform compatibility. ### P3 - Rawfile Coverage And Native Analysis Expansion (done) - ASCII/binary rawfile parsing for real and complex vectors. - AC complex vector handling and branch-current support. - Native sensitivity, pole-zero, distortion, transfer-function, and Fourier analysis specs. ### P4 - Measures, Specs, And Analysis Workflow Closure (done) - Simulator `.measure` parsing. - `Spec` / `SpecTable` integration. - Python metrics, common analysis summaries, and Experiment persistence. ### P5 - Parser, Import, And Round-Trip Deck Support (done) - Monata-owned parser/import path. - Full-deck import to canonical Cell netlist view. - Subcircuit/model asset import. - Representative round-trip and `cir2py` coverage. ### P6 - Structured Mutation, Corners, Monte Carlo, And Optimizer Integration (done) - Shared structured mutation resolver. - Sweep, corner, Monte Carlo, optimizer, and ngspice backend projection through one mutation model. - Explicit ambiguity, raw fallback, and backend failure behavior. ### P7 - Model, PDK, And Project Library Closure (done) - Structured model diagnostics and project-local `models.toml` manifest. - Candidate-preserving registry indexes and strict ambiguity diagnostics. - Content-hash cache keys that include input identity/content and include provenance. - Project manifest load/save APIs with relative path relocation and validation. - Manifest-backed model/corner projection into `SimTask.osdi_paths`, `.include`, `.lib`, and provenance metadata without mutating caller circuits. - Reusable device metadata for family/module/model/parameter inspection without bundling PDK assets or adding UI dependencies. ### P8 - User-Facing Delivery (done) - `monata.examples` workflows for native authoring, imported deck round-trip, synthetic model registry usage, and Experiment persistence. - Lightweight JSON result export/import preserving numpy-compatible waveform access and typed result metadata. - Optional plotting helpers for `Waveform` and Bode-style `AnalysisResult` views. - Tests anchoring examples, export, plotting, and editable source workflows. ### P9 Phase 1 - Backend Capability Contract (done) - `BackendCapabilities` and registry-level capability discovery. - `ngspice-subprocess` capability metadata for analyses, result modes, source/mutation support, model artifact support, and runner/parser contracts. - Structured unsupported-task `SimResult` helpers. - Tests proving default built-ins remain exactly `ngspice-subprocess` and dummy backend fixtures stay test-local. ## Near-Term Roadmap Near-term work should be implementation-sized and should not require new simulator backends, GUI product decisions, third-party PDK licensing decisions, or external production infrastructure. ### P10 - Package Smoke, Docs, And Release Hygiene **Goal:** Close the remaining delivery gap between editable source validation and installed-package confidence. **In Scope** - Installed-package import/API smoke tests. - Installed-package native ngspice smoke. - Parser round-trip smoke against the packaged environment. - Model registry smoke with synthetic fixtures. - Closed-loop project workflow smoke against the packaged environment. - Documentation build or doc-link validation for examples that are meant to be user-facing. - Release notes that call out unsupported dialects/backends and optional dependencies. **Acceptance Gates** - Editable source suite remains green. - Packaged smoke suite runs without relying on editable `src/monata`. - Docs/release notes reference tested APIs only. - No new core runtime dependency is introduced. ### P11 - Experiment Storage Backend Boundary **Goal:** Make Experiment persistence pluggable before adding database or cloud storage. **In Scope** - Define a small storage backend protocol for saving/loading Experiment metadata, measures, summaries, corners, optimizer metadata, and result artifacts. - Keep the existing filesystem storage as the default backend. - Add stable schema/version metadata for saved experiments. - Add migration/compatibility checks for old local saves. - Add a SQLite backend only after the filesystem boundary is stable. - Keep large waveform storage explicit and inspectable. **Acceptance Gates** - Existing Experiment save/load tests pass through the filesystem backend. - A synthetic compatibility fixture can be loaded after schema version checks. - SQLite, if added, is optional and tested separately. - No cloud credentials or external services are required. ### P12 - Distributed Executor Foundation **Goal:** Let Monata submit batches outside one local process without changing simulation APIs. **In Scope** - Clarify executor contracts for task serialization, working directories, environment discovery, artifact collection, logs, and structured failures. - Add a local multiprocessing or job-directory executor as the first distributed-shaped backend. - Add retry/timeout/concurrency controls. - Preserve `LocalExecutor` behavior. - Keep simulator selection explicit; do not add new simulator backends. **Acceptance Gates** - Sweep/corner/Monte Carlo tasks can run through the new executor path. - Failed tasks produce structured `SimResult` failures with logs/provenance. - Artifacts and metadata round-trip without relying on process-local state. - Existing `LocalExecutor` tests remain green. ## Mid-Term Roadmap Mid-term work is product-scale but still local/offline. It should build on P10 through P12 rather than bypass them. ### P13 - PDK Metadata To Symbol/Schematic Generation **Goal:** Generate usable symbol and schematic artifacts from Monata-owned device/model metadata. **Prerequisites** - P7 model/device metadata is stable enough to describe families, modules, model names, pin order, parameters, and documentation hints. - A synthetic PDK fixture exists for tests. **In Scope** - Device metadata fields for pin order, pin direction, default parameters, symbol shape hints, and schematic instance rules. - Symbol view generation from synthetic PDK/device metadata. - Schematic instance generation or update helpers for registered devices. - Validation for missing pins, ambiguous model/subcircuit mappings, and incompatible metadata. - No bundled third-party PDK. **Acceptance Gates** - Synthetic metadata can generate deterministic symbol views. - Generated schematic instances can render to valid ngspice netlists. - Missing or ambiguous metadata produces clear diagnostics. - Existing hand-authored views remain compatible. ### P14 - Local Project Browser / Editor Integration Boundary **Goal:** Prepare Monata for GUI/editor integration without committing to a specific UI stack too early. **Prerequisites** - Project, storage, and generated view APIs are stable. - Common workflows can be driven through non-interactive Python APIs. **In Scope** - A UI-neutral project service API for listing libraries, cells, views, manifests, models, experiments, and runnable testbenches. - Commands for opening/generating views, running simulations, and reading result summaries. - Structured event/progress/log objects that a GUI, CLI, or editor plugin can consume. - Optional CLI or text-mode browser as a validation surface. **Out Of Scope** - Choosing VS Code vs web vs desktop UI as part of this batch. - Building a full graphical schematic editor. **Acceptance Gates** - A non-UI test can drive project browsing, simulation, and result inspection through the service API. - No GUI dependency is required in core Monata. - The API is stable enough for a later UI-specific package. ### P15 - SPICE Dialect Coverage Matrix And Fixture Corpus **Goal:** Replace vague "exhaustive dialect compatibility" with measurable coverage and diagnostics. **In Scope** - Dialect coverage matrix for ngspice, PSpice, HSpice, Spectre, and Xyce syntax families. - Golden fixture corpus for supported elements, dot commands, expressions, control blocks, model/subcircuit patterns, and known unsupported constructs. - Import diagnostics that explain unsupported syntax without corrupting the imported project. - Compatibility reports generated from tests. **Out Of Scope** - Claiming exhaustive compatibility. - Adding new simulator execution backends. **Acceptance Gates** - Coverage reports distinguish supported, partially supported, and unsupported constructs. - Unsupported dialect features fail with source-located diagnostics. - Existing parser/import workflows remain green. ## Long-Term Roadmap Long-term work needs explicit product, licensing, deployment, or ecosystem decisions before implementation. Treat each item as a separate design project. ### L1 - GUI / Editor Product **Needed Before Implementation** - Choose the first product surface: VS Code plugin, web UI, desktop app, or CLI browser. - Define the target workflow: project browsing, schematic viewing, symbol editing, simulation launch, result plotting, model management, or all of these. - Decide packaging and optional dependency boundaries. - Reuse P14 service APIs instead of binding GUI code to internal model classes. ### L2 - Third-Party PDK Acquisition **Needed Before Implementation** - License and redistribution policy. - Source allowlist and version pinning. - Hash verification, cache layout, provenance metadata, and offline behavior. - User consent and diagnostic flows for restricted or manually supplied PDKs. **Likely First Step** - Prefer "user-provided PDK registration, validation, and indexing" before any automatic download/acquisition workflow. ### L3 - Cloud Or Database-Backed Experiment Storage **Needed Before Implementation** - Stable local storage backend boundary from P11. - Schema migration policy. - Large waveform/object storage strategy. - Query/index requirements. - Credential, tenancy, and offline-mode decisions for cloud storage. **Likely First Step** - Add SQLite after filesystem storage is versioned. Add object/cloud storage only after local query semantics are proven. ### L4 - Production Distributed Simulation **Needed Before Implementation** - Executor foundation from P12. - Cluster/cloud environment model. - Artifact transport, result collection, logs, retries, cancellation, and observability. - Security boundaries for running user decks remotely. **Likely First Step** - Add Slurm/job-array support after local job-directory execution is stable. ### L5 - Full Schematic-Symbol / PDK UI **Needed Before Implementation** - Generated symbol/schematic artifacts from P13. - GUI/editor boundary from P14. - PDK registration and validation policy from L2. - Editing semantics for generated vs user-authored artifacts. ## Deferred Simulator Expansion These are not part of the near-term roadmap unless a future task explicitly asks for new simulator support. ### Xyce Backend - Add a Xyce renderer for a supported common IR subset. - Add a subprocess runner and result parser for a narrow initial analysis set. - Integrate model/library artifacts only through the P7 contract. - Add package/environment detection and clear missing-tool diagnostics. - Keep ngspice tests as the reference compatibility gate. ### VACASK Backend - Add VACASK only after the backend contract and model artifact contract are proven by Xyce or another constrained second backend. - Clarify OSDI/plugin handling and result parsing before widening analysis coverage. - Avoid coupling VACASK-specific behavior into common Monata APIs. ### Optional ngspice Shared Library Backend Add ngspice shared-library support only if it provides clear value beyond the subprocess path, such as interactive commands, `alter`, `show` / `showmod`, stepping, halt/resume, or external source callbacks. It must register as an additional backend capability and must not replace `ngspice-subprocess`.