Monata API Boundaries

Monata separates stable public APIs from internal implementation details. The 0.1.x public names should usually live only in their owning modules rather than being carried through transitional facades. The only standing exception is a deliberately small root facade for foundational package concepts.

Stable public APIs

• monata.library, monata.cell, monata.registry, and monata.workspace for project/library/cell metadata and lookup.

• monata.netlist for native netlist IR types, mutation, and rendering: Circuit, SubCircuit, Element, Directive, SourceValue, MutationError, MutationProjection, apply_mutation, project_param_overrides, and render_ngspice. Circuit.to_spice(), SubCircuit.to_spice(), Element.to_spice(), Directive.to_spice(), ModelCard.to_spice(), and SourceValue.to_spice() are explicit convenience methods for rendering native objects through the same owned renderer. Native scopes also own stable element lookup and edit operations through methods such as get_element(), element(), remove_element(), and replace_element(), plus node-name inspection through get_node(), node(), and has_node(). Node helpers return native node-name strings rather than a separate public node object model. get_node(name, create=True) and node(name, create=True) may pre-register loose node names for authoring and topology handoff without rendering standalone SPICE lines. Attribute access such as scope.Rload is a convenience lookup for uniquely named elements and does not replace explicit lookup/edit APIs. Element.parameters, Directive.parameters, SourceValue.parameters, Element.get(), Directive.get(), SourceValue.get(), Element[...], Directive[...], SourceValue[...], and missing attribute lookup expose read-only access to native record parameters. Element.clone(), Directive.clone(), and SourceValue.clone() are native record-copy helpers for immutable-style edits before replacing or reusing records in a scope. Disabled elements remain addressable records through Element.enabled = False but are omitted by scope rendering. Element.comment is rendered as a preceding SPICE comment line by the owned renderer. Element.raw_suffix is the element-level one-line escape hatch for unsupported trailing tokens after structured parameters; prefer structured params whenever Monata can represent a token. Scope-level raw simulator text belongs in ordered raw directives through raw_directive() and raw_block(); this remains a line-oriented escape hatch rather than a second mutable netlist model. Convenience helpers such as Circuit.resistor() and Circuit.mos() reserve their Python argument names for structural fields like element name, nodes, value, and model. When a simulator parameter must use one of those names, use the explicit IR escape hatch: construct Element(..., params=...) and add it with Circuit.add(). monata.netlist.device_schema owns optional element/pin/parameter metadata records. monata.netlist.topology owns the optional editable node/pin graph that can be projected back into the record IR; the record IR remains the render/simulation boundary.

• monata.circuits for reusable circuit construction helpers such as CMOS transistor/gate helpers and source-subcircuit construction helpers. Project-specific topology recipes, such as a fixed library multiplier, belong in the owning circuit library.

• monata.corner for the canonical OperatingCorner model shared by techlib and simulation.

• monata.views.registry for registering and resolving view type factories.

• monata.cell.Cell.write_generated_view owns generated artifact writes and metadata commits. monata.generation owns generated symbol/netlist content construction and calls that public cell boundary.

• monata.techlib.registry, monata.techlib.schema, and monata.techlib.projection for techlib loading, registry discovery, schema records, PDK instance validation, and projection records. monata.techlib is a namespace package surface, not a compatibility facade.

• monata.projection for resolving PDK projection owner context and applying validated source-level PDK instances into netlist scopes.

• monata.parser for SPICE import and conversion entry points: parse_spice_to_circuit, import_spice_deck, import_spice_asset, spice_to_python, inspect_spice_import, inspect_spice_analysis, spice_to_sim_tasks, parse_spice_expression, render_spice_expression, walk_spice_expression, parse_source_subcircuit, ImportedAsset, SpiceImportPlan, SpiceImportStep, SpiceImportExpressionCheck, SpiceControlCommand, SpiceSourceDependency, SpiceImportIssue, SpiceAnalysisPlan, SpiceAnalysisStep, SpiceAnalysisMeasurement, SpiceAnalysisSweep, SpiceAnalysisIssue, SpiceExpression and its concrete expression record types, SourceSubcircuit, SourceSubcircuitInstance, SpiceParseError, and UnsupportedConstructError. SPICE import is a two-stage boundary: recognized commands are either projected into native Monata IR, used for import flow control, or preserved as raw directives for the simulator. Import inspection exposes those decisions and unsupported constructs without turning parsed SPICE into a second public netlist model. Analysis import is a separate parser boundary: deck-level .tran/.ac/.op and related commands may be projected into backend-neutral SimTask records while the base circuit is rendered without duplicate analysis directives. Pure task-style .control blocks may also be migrated when they contain only analysis, measurement, output-vector, and ignorable run/quit commands; stateful or side-effecting control scripts remain outside the SimTask migration contract. Imported .measure commands are exposed as plan records and filtered into the matching task’s circuit and metadata; they are not promoted into a second Monata measurement DSL. Imported .step param sweeps are exposed as sweep records and expand into multiple SimTask instances with param_overrides; imported .step temp sweeps expand into task operating corners. Step imports support list, linear, decade, and octave sweep forms at this analysis boundary. The native netlist IR still preserves .step as raw text outside the analysis-import boundary. String inputs are treated as SPICE text; filesystem reads require an explicit Path. The expression parser is a lightweight inspect/render frontend for SPICE math expressions; it does not evaluate parameters or own netlist semantics. Import plans may attach expression checks and warning diagnostics to expression-like fields, but native projection still preserves the original string values. LTspice/RKM number forms such as 2k3 are accepted only through explicit dialect options on expression-oriented APIs, not as the default SPICE number contract. .control blocks remain raw simulator text at projection time, but import plans classify internal commands so analysis/measure migration candidates and side-effecting control commands are visible. .include and .lib references are exposed as source dependency records with optional search-path resolution diagnostics; import inspection does not recursively load those files or replace monata.spice_library/project-library ownership. Common ngspice aliases and library-section markers such as .meas and .endl are accepted at the import boundary; projected measurements use Monata’s canonical measure directive representation.

• monata.eda.kicad for KiCad XML netlist import. The adapter parses KiCad components/nets, reports a component-level import plan, and projects supported components into native Circuit/Element records or a generated Monata netlist cell view. It can also export a supported netlist projection as Python builder source for editable handoff. It is a front-end adapter, not a schematic object model.

• monata.spice_library for indexing third-party SPICE model/subcircuit files. This is separate from monata.library, which remains the Monata project cell library abstraction. The index may expose lightweight category/tag metadata for discovery and may attach indexed items to native netlist scopes as .include/.lib references. Indexed items may return their original source .model/.subckt snippets for downstream import or inspection, but the library index does not own a full SPICE AST and does not define a fixed vendor or product catalog schema.

• monata.sim.analysis_spec, monata.sim.task, monata.sim.results, monata.sim.waveform, monata.sim.executor, and monata.sim.vector_names own the core simulation contracts. monata.sim.core is a stable convenience import bundle over those owner modules; it should not contain implementation logic or become a broad compatibility facade. Its export set is intentionally locked by public API tests; add a new core export only when the name belongs in the small simulation kernel rather than a specialized workflow module. Sweep and Monte Carlo orchestration belong in monata.sim.sweep and monata.sim.montecarlo; digital testbench orchestration belongs in monata.sim.digital_table and related digital owner modules. Those workflow modules are public owner-module APIs, but they are intentionally not part of the monata.sim.core compatibility bundle. monata.sim.task owns simulation input contracts such as SimTask, task defaults, output-name normalization, and SimArtifactOptions. monata.sim.results owns execution output contracts such as SimResult, SimStatus, AnalysisResult, waveform lookup, result payload aliases, and array-to-result construction. monata.sim.result_ops owns result-level numeric transforms such as derivative, integral, resampling, sampling, and windowing; AnalysisResult keeps thin method wrappers for ergonomic use. Typed Waveform/AnalysisResult objects may expose plotting-neutral data projections such as magnitude, phase, derivative, integral, and ordered numeric/unit-array column projection, including Bode traces derived from frequency-domain analysis results. monata.sim.vector_names owns output vector identity helpers such as normalize_vector_name() and VectorName. Its voltage_vector(), branch_current_vector(), node_current_vector(), device_parameter_vector(), internal_parameter_vector(), and expression_vector() helpers are Monata-owned request builders; bare SimTask.output_names entries remain node-voltage shorthand. Result groupings use explicit Monata names such as node_voltages_by_node, branch_currents_by_element, and element_parameters. Measurement pass/fail semantics remain in monata.measure. SimTask.metadata is descriptive user/task metadata, not a backend control channel. Backend-specific execution controls belong in SimTask.backend_options; simulator artifact persistence belongs in SimTask.artifacts/SimArtifactOptions. Backend results may promote stable Monata result descriptors such as analysis names, requested/observed vectors, measures, artifacts, and compact execution summaries to top-level result metadata, but backend-only diagnostics remain under the backend namespace such as metadata["ngspice"]. Monata-owned workflow control payloads use reserved, versioned namespaces under metadata["monata"]; digital truth-table task scheduling data lives in metadata["monata"]["digital_task_v1"] with schema monata.sim.digital-task.v1, while caller descriptive metadata remains at the task metadata top level. Simulation results that need digital task reconstruction carry that task metadata only through SimResult.metadata["task_metadata"]; older top-level control keys are not accepted.

• monata.sim.session for the stateful simulation-session builder facade over circuit directives, raw directive blocks, and backend-neutral SimTask creation. Session-level metadata, backend options, and artifact options are copied into tasks and may be overridden per task. Because the session facade is mutable, tasks snapshot the session circuit by default; explicit snapshot_tasks=False/snapshot=False opts back into sharing the live circuit object.

• monata.sim.analysis_spec for immutable user-facing analysis contracts and their generic canonical analysis names.

• monata.sim.cache for content-addressed SimTask fingerprints and optional filesystem result caching. The cache key is derived from simulation inputs such as rendered circuit text, analysis spec, corner, parameter overrides, output requests, backend options, task metadata, and referenced model/include/OSDI artifact digests. Timeout and artifact output destination remain outside the identity contract.

• monata.sim.backends for backend protocol, capability, task-validation, task-planning, and registry APIs. The built-in ngspice runner remains ngspice-subprocess; ngspice-shared is the same-simulator runner for libngspice command/session workflows and requires an available user-provided shared library. Backend extension points are explicit: implement Backend.run() for execution, ValidatingBackend.validate_task() for preflight failures, and PlanningBackend.plan_task() for backend-facing plan introspection. Ngspice backends preserve ordinary simulator and parser failures as failed SimResult values by default; set backend_options["raise_backend_exceptions"] = True when development or CI should surface backend adapter exceptions directly.

• monata.sim.capabilities for simulator model-flow profiles used when resolving model artifacts and device-level simulator support. These profiles describe a simulator family/dialect and model support; they are not backend registry entries and do not replace monata.sim.backends.BackendCapabilities.

• monata.sim.digital_table for the user-facing digital truth-table construction/execution facade, monata.sim.digital_results for digital truth-table result and propagation-delay row records, monata.sim.digital_claims for digital oracle/comparison records, and monata.sim.digital_projection for PDK projection helpers used by digital flows. Internal digital task construction and result extraction share explicit plan/schedule/stimulus-metadata records from monata.sim.digital_plan instead of depending on DigitalTruthTable private methods or untyped result metadata reads. Digital table timing options are behavioral contracts: skew_step offsets each input source transition and the corresponding extraction schedule by input index.

• Digital workflows do not have a compatibility aggregation module; import from the owner modules above. monata.sim is a namespace package surface, not a compatibility facade.

• monata.sim.export for simulation result serialization helpers, including HDF5 export/import through the default h5py runtime dependency.

• monata.sim.rawfile for loading external ngspice rawfiles into typed AnalysisResult/Waveform records. Rawfile parser records under monata.sim.backends remain backend implementation details. Ngspice-specific header fields such as circuit name, date, warnings, and TEMP/TNOM are preserved as result metadata. Optional node/element name lists may restore result display casing without changing the underlying raw vector provenance.

• monata.units and monata.physics for circuit-oriented scalar/array unit values, SPICE suffix parsing, and small sizing/thermal helper formulas.

Root facade

monata may re-export foundational names that are needed before a user chooses a simulation, circuit-construction, techlib, or backend workflow:

• Cell, Library, LibraryRegistry, and View.

• OperatingCorner.

• Common Monata errors.

• Quantity, Unit, and UnitArray.

The root facade must stay lightweight: importing monata must not import monata.sim, monata.sim.backends, backend implementation modules, or optional plotting/model execution dependencies.

Internal implementation details

• Import-time backend registration, simulator planning internals, parser record types such as monata.parser.deck.SpiceDeck, and view-loading mechanics are implementation details unless explicitly re-exported in the stable API.

• Python-backed schematic and testbench views are trusted project code. Calling View.load() or APIs that generate/load those views executes Python in the current process; Monata does not sandbox view code.

• Private attributes on netlist scopes and mutation indexes are not extension points.

• Generation implementation details live under monata.generation; higher-level cell methods may call those services but should not duplicate them.

• Projection algorithms live under monata.projection; higher-level library methods may call those services but should not duplicate them.

Ownership rule

When adding or moving an API:

1. Put the implementation and public export in the owner module.

2. Update callers and documentation to import from the owner module directly.

3. Do not add root-package exports unless the name belongs in the small foundational facade above.

4. Do not add new cross-module compatibility re-exports during pre-release development. Prefer owner-module imports over migration shims.

5. Cover boundary decisions with tests when the import path is user-facing.