Ngspice Sky130

Sky130 Ngspice Skill

Use this skill when a Razavi-Bench task benefits from checking a circuit intuition with ngspice and the bundled Sky130 1.8 V primitive models. You are not required to simulate every task. Use ngspice when it can answer a clearly stated electrical question; skip it when the task is mainly conceptual, topological, or under-specified.

Do not treat simulation as the answer. Many tasks are qualitative, depend on small-signal assumptions, or omit exact device sizes and bias points. A simulation is useful only if the deck topology, held-fixed condition, bias condition, device sizes, and measured quantity match the question you are answering. If a Sky130 simulation conflicts with a textbook trend, first check whether you changed the assumptions.

This is simulation-assisted reasoning, not grounded PDK truth. Some tasks are property-strong: a small equation deck or simplified netlist can reproduce the exact trend or mechanism the question asks about. Other tasks are topology-only, state-counting, or sign-convention tasks where simulation should be skipped.

Environment

In the Razavi-Bench ngspice-sky130 setting:

• task files are in /app;
• Sky130 models are in /tools/ngspice-sky130/models;
• example decks are in /tools/ngspice-sky130/examples;
• this skill, when installed for Claude Code, is in /app/.claude/skills/ngspice-sky130.

The core include is:

.include "/tools/ngspice-sky130/models/sky130.lib.spice"

If you are running from a checkout instead of Vela, use a relative path to simulator/ngspice-sky130/models/sky130.lib.spice.

Required Geometry Units

Sky130 instance geometry is expressed in SI units. Every device must use explicit suffixes, for example:

Xn d g s b sky130_fd_pr__nfet_01v8 w=1.26u l=0.15u

Never write unitless geometry such as w=1.26 l=0.15. Ngspice interprets those values as meters. The W/L ratio can leave a DC trend looking plausible while absolute current, transconductance, capacitance, AC response, and transient behavior are wrong by many orders of magnitude. Before trusting a deck, inspect at least one absolute operating-point quantity or capacitance and confirm that the dimensions carry u suffixes.

Bundled Assets

The skill includes reusable Sky130 templates and runners:

assets/
├── run_op_probe.py        # Render and run one operating-point probe
├── run_examples.py        # Run standard sanity-check examples
├── sky130_common.py       # Model discovery, template rendering, ngspice runner
├── templates/             # Small OP probes: nfet, pfet, CS, source follower
└── netlist/               # Standard examples: RC, I-V, CS AC, mirror, TG Ron

The standard examples write generated decks and logs to ./ngspice_outputs/ by default, or to $SKY130_NGSPICE_OUTPUT_DIR if set. Treat these as scratch artifacts. Do not edit files under .claude/skills unless the user is improving the skill itself; copy a generated deck into /app before adapting it for a task.

Decision Workflow

Before running ngspice, write down the intended use of simulation in one sentence:

I will simulate <quantity/trend> while holding <condition> fixed, because the task asks about <same condition>.

If you cannot fill in that sentence honestly, do not simulate. Answer from analog reasoning and state the missing information.

Use this order:

1. Read /app/instruction.md and inspect any PNGs in /app.
2. Identify the intended analysis assumption: long-channel vs. PDK device, fixed current vs. fixed voltage/overdrive, fixed geometry ratio vs. fixed width/length, small-signal vs. large-signal, open-loop vs. feedback.
3. Classify the question by probe family using the general table below. Do this from the task itself; do not rely on per-task routing hints.
4. Decide whether ngspice can test the same assumption.
5. If yes, run a minimal deck and use the result as supporting evidence.
6. If no, skip simulation and give the analog-circuit answer directly.

Do not run a generic MOS probe merely because this skill is available. A generic probe is useful only to learn syntax or to check the simulator installation; it is not evidence for an unrelated task.

Minimal Simulation Workflow

1. Decide what the simulation is supposed to test: operating point, sign, trend, pole, gain, impedance, or switch resistance.
2. Create a new deck under /app, or copy an example from /tools/ngspice-sky130/examples.
3. Check that the deck matches the question. Do not blindly reuse example topology, sizes, bias, or held-fixed conditions.
4. Run:

ngspice -b /app/your_deck.cir > /app/your_deck.log 2>&1

5. Read the log, compare it against the theoretical mechanism, then write only the final reasoning to /app/answer.md.

Zero-Start Quickstart

If you have never used ngspice in this environment and the task appears simulation-suitable, do this first:

ls -la /app
ls -la /tools/ngspice-sky130/models
ls -la /tools/ngspice-sky130/examples
ngspice --version

You may run a known-good probe to learn syntax:

python3 /app/.claude/skills/ngspice-sky130/assets/run_op_probe.py \
  --template nfet_op \
  --out /app/nfet_op.cir

sed -n '1,120p' /app/nfet_op.cir
sed -n '1,160p' /app/nfet_op.log

This teaches the three essential pieces, but it is not task evidence unless the task is actually an NMOS operating-point probe:

• a deck includes sky130.lib.spice;
• the transistor instance name Xn maps to ngspice operating-point variables such as @m.xn.msky130_fd_pr__nfet_01v8[gm];
• .control ... print ... .endc prints values into the log.

After that, copy the closest generated deck and change only what the question requires. If no generated deck matches the task topology and assumptions, do not force it.

Available helper templates:

nfet_op
pfet_op
common_source_op
source_follower_op

Example:

python3 /app/.claude/skills/ngspice-sky130/assets/run_op_probe.py \
  --template source_follower_op \
  --out /app/source_follower_op.cir

To see the broader example set:

python3 /app/.claude/skills/ngspice-sky130/assets/run_examples.py --example all
python3 /app/.claude/skills/ngspice-sky130/assets/run_examples.py --example nmos_iv
python3 /app/.claude/skills/ngspice-sky130/assets/run_examples.py --example cs_ac

Available standard examples:

rc_tran
rc_ac
nmos_iv
cs_ac
current_mirror
tgate_ron

Choosing A Probe

Before writing a deck, classify the task. Use ngspice only when the task has a concrete electrical quantity that can be probed under a stated bias condition and a clear held-fixed condition.

If the figure or prompt omits sizes, loads, bias currents, clock waveforms, or initial conditions, state the missing assumption. A simulation with invented values can support a trend, but it cannot replace the reasoning. If different reasonable assumptions give different answers, say so.

Supported Probe Families

Use these generic probe families for any Razavi-Bench task. They are public skill capabilities, not per-task hints:

Backend-Callable Skill Contract

A backend can expose this skill uniformly for all tasks by providing the same files and tools every time:

/app/instruction.md
/app/figure-*.png
/tools/ngspice-sky130/models
/tools/ngspice-sky130/examples
/app/.claude/skills/ngspice-sky130

Do not give the agent a task-specific list of recommended probes, expected simulation value, or known useful deck. The agent should infer the probe family from the task statement and figure. The backend may log which files were created and whether ngspice was invoked, but scoring should still use only /app/answer.md.

A reasonable agent workflow is:

1. State the analog mechanism before simulation.
2. State the probe family and held-fixed condition.
3. Build the smallest deck that tests that condition.
4. Compare the result with the mechanism.
5. Put only the conclusion and any concise supporting trend in /app/answer.md.

If the agent cannot state the mechanism and held-fixed condition, it should not simulate.

Generic Equation Deck Pattern

For textbook or under-specified questions, an equation-level ngspice deck is often better than a fabricated transistor-level circuit. Use this form when the task asks about a formula or scaling law:

* Example: compute a trend directly from stated equations.
Vx x 0 1

.control
dc Vx 1 4 1
let scale=v(x)
let quantity=<expression involving scale>
print scale quantity
.endc

.end

This is appropriate for trends such as gm scaling, Rin formulas, oscillator frequency scaling, Miller multiplication, feedback input conductance, or phase-noise proportionalities. Clearly label it as an equation-level probe.

Generic Port-Probe Pattern

For resistance and impedance questions, use an explicit test source at the port whose impedance is being asked about:

* Example pattern: inject 1 A AC and read V/I.
Itest in 0 AC 1

.control
ac dec 20 1 1e9
let zin=v(in)/1
print zin
.endc

.end

Deactivate or small-signal-ground independent sources according to the circuit question. If the required port is ambiguous, resolve the topology first instead of probing an arbitrary node.

Generic Sky130 Device Pattern

Use the bundled Sky130 devices for sanity checks where the question is about a specific transistor topology, region, local gain sign, or operating-point quantity. Keep the device dimensions, bias, and load simple and explicitly stated.

Do not use this pattern to override textbook assumptions. For example, a minimum-channel BSIM result may fail to show an ideal long-channel trend; in that case, use a long-channel equation probe and mention the PDK caveat.

Common Checks

Operating point:

.op
.control
run
print v(out)
let gm=@m.xn.msky130_fd_pr__nfet_01v8[gm]
let gds=@m.xn.msky130_fd_pr__nfet_01v8[gds]
print gm gds
.endc

Small-signal gain estimate:

let gain_cs=-gm/(gds+1/20000)
print gain_cs

Source-follower estimate:

let gain_sf=gm/(gm+@m.xn.msky130_fd_pr__nfet_01v8[gmbs]+1/10000)
print gain_sf

Sanity checks before trusting a result:

• Is the device in the intended region? Check vds, vgs, threshold, and vdsat when possible.
• Are you holding the same quantity fixed as the question? For example, fixed overdrive, fixed current, fixed geometry ratio, and fixed VGS can produce different trends.
• Are the model limits relevant? A Sky130 short-channel simulation may disagree with a long-channel textbook assumption.
• Is the result a model artifact or bias artifact? If the result is surprising, rerun with a second bias or derive the expected trend before trusting it.
• Does the sign convention match the circuit? PMOS and NMOS signs can look different while the small-signal form is equivalent.
• Does the question provide enough numerical detail for simulation? If not, state the assumption and use simulation only as a qualitative sanity check.
• Did the deck answer the same question? A common-source example does not answer a source-follower question; a fixed-VGS sweep does not answer a fixed-current design question.

When Not To Simulate

Skip simulation, or treat it only as secondary evidence, when:

• the question asks for a pure topology classification;
• the figure lacks enough device sizes, loads, or bias points;
• the intended answer is a long-channel textbook trend;
• the question asks about sign conventions, model form, or feedback interpretation.
• you would need to invent most of the circuit, bias, or waveform details.

In these cases, write the analog reasoning directly and mention any assumptions.

Writing The Final Answer

The grader reads /app/answer.md, not your .cir files or logs. Your final answer should include:

• the circuit conclusion;
• the key analog mechanism;
• the relevant assumption, if simulation required one;
• at most one concise simulation-backed number or trend, only if it truly supports the conclusion.

Do not paste raw ngspice logs into /app/answer.md.

Helper Scripts

The assets/ directory contains small Python helpers that copy templates into /app, run ngspice, and print parsed output. They are convenience tools, not required.

Example:

python3 /app/.claude/skills/ngspice-sky130/assets/run_op_probe.py \
  --template nfet_op \
  --out /app/nfet_op.cir

Then inspect /app/nfet_op.log.