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:

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 <changed source and tests>
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.