circuitsnap

Сними — симулируй. Превратите рисунок схемы — фото, набросок или просто описание — в живую симуляцию в Falstad's CircuitJS1.

Поставляется в виде MCP-сервера (чтобы Claude и другие ассистенты могли собирать схемы), CLI и библиотеки.

$ circuitsnap build rc.json
https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgo...

$ 1 0.000005 10.20027730826997 50 5 50
v 128 64 192 64 0 0 40 5 0 0 0.5
r 384 64 448 64 0 10000
c 128 176 192 176 0 0.000001 0 0
...

Откройте URL — и схема заработает.

Почему

Просьба к языковой модели напрямую записать файловый формат CircuitJS1 не работает. Формат позиционный и не прощает ошибок — v 128 64 192 64 0 0 40 5 0 0 0.5 содержит шесть хвостовых параметров, чей порядок, единицы и битовые флаги можно узнать только из исходников симулятора на Java. Неправильная догадка даёт схему, которая открывается без ошибок и симулируется неправильно, а это худший из возможных сбоев: пользователь не может его заметить.

circuitsnap переносит эту работу в код, покрытый тестами. Модель описывает что с чем соединено; эта библиотека берёт на себя формат, геометрию, экранирование и кодирование.

Related MCP server: circuit-sim-mcp

Установка

npm install -g circuitsnap

Как MCP-сервер

{
  "mcpServers": {
    "circuitsnap": { "command": "npx", "args": ["-y", "circuitsnap-mcp"] }
  }
}

(circuitsnap — это CLI; circuitsnap-mcp — это stdio-сервер. circuitsnap mcp также запускает сервер, если вы предпочитаете один бинарный файл.)

Для Claude Code также скопируйте skills/circuitsnap/ в .claude/skills/, чтобы получить рабочий процесс /circuitsnap, который охватывает чтение рисунка и проверку результата.

Использование

Опишите схему в виде списка соединений (netlist) — компоненты и имена цепей, без координат:

{
  "title": "RC lowpass",
  "components": [
    { "id": "V1", "kind": "voltage",   "nodes": ["gnd", "in"],  "value": 5 },
    { "id": "R1", "kind": "resistor",  "nodes": ["in", "out"],  "value": "10k" },
    { "id": "C1", "kind": "capacitor", "nodes": ["out", "gnd"], "value": "1uF" }
  ]
}

Выводы с одинаковым именем цепи соединены. Вот и вся модель.

circuitsnap build rc.json          # URL + circuit text
circuitsnap build rc.json --url    # just the URL
circuitsnap elements               # pin order and parameters for every kind
circuitsnap decode "<share-url>"   # read someone else's circuit

В качестве библиотеки:

import { snap } from 'circuitsnap';

const { url, text, diagnostics } = snap({
  components: [
    { id: 'V1', kind: 'voltage',  nodes: ['gnd', 'in'], value: 5 },
    { id: 'R1', kind: 'resistor', nodes: ['in', 'gnd'], value: '1k' },
  ],
});
console.log(url.url);

Значения

Инженерная нотация, записанная так, как человек пишет её на схеме:

M — это мега, а m — милли; так принято на схемах. В SPICE M означает милли — такая трактовка превратила бы подписанный вручную резистор «10M» в 10 миллиом.

Элементы

wire, resistor, capacitor, inductor, voltage, rail, ground, switch, diode, led, current, labeledNode, transistor, opamp, output, probe, text.

Выполните circuitsnap elements, чтобы узнать порядок выводов, параметры, единицы измерения и значения по умолчанию. Порядок выводов важен: транзистор — [base, collector, emitter], операционный усилитель — [minus, plus, out].

Земля

Используйте имя цепи gnd (или ground, 0, vss). Эти выводы получают настоящий символ земли, а не подпись — у помеченного узла с именем «gnd» нет опорного потенциала 0 В, и решатель остался бы без точки отсчёта. circuitsnap выдаёт предупреждение, если в схеме вообще нет земли.

Как это работает

Конвейер выглядит так: netlist -> валидация -> размещение -> генерация -> URL, и только этап чтения рисунка требует модели. О двух решениях стоит знать:

• Цепи связываются именованными метками, а не проложенными проводами. Автотрассировщик, который корректен на 95%, создаёт схемы, которые выглядят правильно, но симулируются неправильно. Метку рядом с выводом можно проверить. Выходные данные читаются как иерархическая схема.

• Мы генерируем устаревший текстовый формат, а не XML. Текущий апстрим пишет XML, но по-прежнему читает текст, поэтому текст — единственный формат, который загружается и в старых, и в новых сборках.

Подробное обоснование — в docs/ARCHITECTURE.md, а справочник по формату файлов, полученный из исходного кода апстрима со ссылками на строки, — в docs/FORMAT.md.

Корректность

Формат получен обратной разработкой, поэтому корректность критически важна:

• 372 схемы из апстрима проходят цикл «туда и обратно» с точным совпадением байтов.

• Сгенерированный результат проверяется на совпадение выводов, правильность экранирования и битовые флаги, которые апстрим принудительно выставляет.

• Проверка вживую: сгенерированные схемы загружаются в настоящий симулятор, и напряжения в узлах считываются обратно. Так была проверена геометрия многовыводных компонентов: повторитель на операционном усилителе должен действительно повторять входной сигнал, а транзистор должен сообщать fwd active при Ic/Ib = β.

npm run reference:fetch   # clone upstream (not vendored; see docs/LICENSING.md)
npm test

Тестовый набор не выполняет сетевых запросов.

Лицензия

circuitsnap распространяется по лицензии MIT. CircuitJS1 — по GPL-2.0-or-later, авторы — Paul Falstad и Iain Sharp; в этом проекте он не поставляется и не модифицируется — circuitsnap генерирует файлы в его формате и открывает его URL. Полное обоснование — в docs/LICENSING.md, включая то, как этот проект учитывает сигналы falstad.com для AI-краулеров (кратко: никакого обхода сайтов и скрейпинга, тесты полностью офлайн, а --base-url позволяет указать на вашу собственную самостоятельно размещённую копию).

Проект не аффилирован с авторами CircuitJS1 и не имеет их одобрения.