circuit

circuit.yaml 포맷

한 줄 요약 — 회로를 텍스트로 적습니다. 사람이 읽고 쓸 수 있으면서, 검증·시뮬레이션·EasyEDA 내보내기가 모두 이 파일 하나에서 나옵니다.

왜 텍스트인가

이점설명
버전 관리git diff로 변경 추적
검증 자동화규칙 엔진이 읽을 수 있음
시뮬레이션SPICE 넷리스트(netlist)로 변환
EasyEDA 내보내기JSON 생성
채팅으로 생성LLM이 쓰기 쉬움
재현성같은 파일 = 같은 회로

회로의 본질은 넷리스트(연결 관계)입니다 (0-04). 그것을 가장 직접적으로 표현한 것이 이 포맷입니다.

기본 구조

부하가 걸린 분압기 회로도R110kΩV15VR210kΩRL10kΩ부하VINOUTGND
부하가 걸린 분압기
# yaml-language-server: $schema=../../schema/circuit.schema.json
meta:
  name: 부하가 걸린 분압기
  lesson: docs/01-dc-basics/04-voltage-divider.md
  note: RL을 바꿔가며 출력이 어떻게 무너지는지 본다

components:
  - {ref: V1, type: vdc, value: 5}
  - {ref: R1, type: r,   value: 10k, params: {power_rating: 0.25}}
  - {ref: R2, type: r,   value: 10k, params: {power_rating: 0.25}}
  - {ref: RL, type: r,   value: 10k, label: 부하}

nets:
  VIN: [V1.p, R1.1]
  OUT: [R1.2, R2.1, RL.1]
  GND: [V1.n, R2.2, RL.2]

analyses:
  - {type: op}

expect:
  - {measure: v, node: OUT, value: 1.667, tol: 1%}
  - {measure: p, of: R1, max: 0.25}

섹션별 설명

meta

필드설명
name회로 이름 (한국어 가능)
lesson관련 학습 문서 경로
note설명

components

필드설명
ref참조 지정자 (R1, C2, U1) — 중복 불가
type부품 타입 (아래 표)
value값 (10k, 4k7, 100n, 1MEG)
model반도체 모델명 (2N3904, 1N4148)
params부품별 추가 파라미터
label한국어 설명

nets

nets:
  넷이름: [부품.핀, 부품.핀, ...]
  • GND는 예약어 — SPICE의 노드 0
  • 넷 이름은 ASCII (^[A-Za-z_][A-Za-z0-9_+.-]*$)
  • 한국어는 label과 meta에만

analyses

타입파라미터
op(없음) — DC 동작점(operating point)동작점 operating point신호가 없을 때 트랜지스터가 앉아 있는 전압·전류 자리로, 여기가 어긋나면 증폭이 잘려 나갑니다.자세히 보기 →
dcsource, start, stop, step
trantstep, tstop, tstart, uic
acsweep(dec/lin), points, fstart, fstop
noiseout, source, sweep, points, fstart, fstop

expect — 측정 검증

형태예
DC 노드 전압{measure: v, node: OUT, value: 2.5, tol: 1%}
소자 전류{measure: i, through: R1, value: 250u, tol: 2%}
전력 상한{measure: p, of: R1, max: 0.25}
과도응답(transient response)과도응답 transient response입력이 갑자기 바뀐 뒤 출력이 자리를 잡기까지의 움직임으로, 정상상태 해석으로는 안 보입니다.자세히 보기 → 특정 시각{measure: v, node: OUT, at: 1m, analysis: tran, value: 3.16, tol: 3%}
AC 이득{measure: gain_db, node: OUT, at: 1k, analysis: ac, value: -3, tol: 0.5}

tol: "1%"(상대) 또는 숫자(절대). min/max만 줘도 됩니다.

💡 expect가 “측정이 잘 되는지”를 자동 검증하는 지점입니다. 손계산 → 시뮬레이션 → EasyEDA가 같은 값을 내는지 확인합니다.

부품 타입

type핀SPICE
r1, 2R
c1, 2C
c_pol+, -C (극성 검사)
l1, 2L
vdcp, nV … DC
vacp, nV … AC
vsinp, nV … SIN
vpulsep, nV … PULSE
idc / iac / ipulsep, nI
da, kD
leda, kD (전류제한 검사)
zenera, kD
q_npn / q_pnpc, b, eQ
m_nmos / m_pmosd, g, sM
opampin+, in-, out, v+, v-X (subckt)
sw1, 2, cp, cnS
k (결합(coupling))—K

부품 목록(BOM) 조회:

circuit parts            # 사람용
circuit parts --json     # 도구·스킬용

기생 성분 표현

11~13장과 16장의 예제는 기생 성분(parasitic)기생 성분 parasitics부품과 배선이 표기값 말고 원치 않게 함께 갖는 저항·용량·인덕턴스로, 고주파에서 회로의 성질을 바꿔 놓습니다.자세히 보기 →을 명시합니다 (11-07).

방법 1 — 파라미터

components:
  - {ref: C1, type: c, value: 100n, params: {esr: 0.02, esl: 0.5n}}
  - {ref: R1, type: r, value: 1MEG, params: {cp: 0.2p}}

방법 2 — 명시적 등가회로 (권장)

이름 없는 회로 회로도RC120mΩESRLC1500pHESLC1100nFRAILN1N2GND
이름 없는 회로
components:
  - {ref: C1,  type: c, value: 100n}
  - {ref: RC1, type: r, value: 0.02, label: ESR}
  - {ref: LC1, type: l, value: 0.5n, label: ESL}
nets:
  RAIL: [LC1.1]
  N1:   [LC1.2, RC1.1]
  N2:   [RC1.2, C1.1]
  GND:  [C1.2]

무엇을 모델링했는지 명확하고, 어떤 시뮬레이터에서도 동작합니다.

★ ideal / real 쌍

examples/11-parasitics/electrode-buffer-ideal.yaml   # 기생 없음
examples/11-parasitics/electrode-buffer-real.yaml    # 기생 포함

두 시뮬레이션을 비교하면 기생 성분의 영향을 파형으로 볼 수 있습니다.

값 표기

표기의미
4k74.7 kΩ
10k10 kΩ
1MEG 또는 1M1 MΩ
100n100 nF
4u74.7 µF
2R22.2 Ω
1e-6지수 표기

⚠️ SPICE에서 1M은 밀리(0.001)입니다 (0-03). 이 포맷은 공학 관례(1M = 메가) 를 따르고, SPICE로 변환할 때 1MEG으로 바꿔줍니다. 이 함정에 빠지지 않습니다.

스키마와 에디터 지원

파일 첫 줄에 스키마를 지정하면 VS Code 등에서 자동완성과 검증이 됩니다.

# yaml-language-server: $schema=../../schema/circuit.schema.json

schema/circuit.schema.json은 도구가 자동 생성하고 저장소에 커밋됩니다.

⚖️ 포맷 설계 트레이드오프

선택✅⚠️
YAML사람이 읽고 쓰기 쉬움, 주석 가능들여쓰기 민감
JSON도구 친화주석 없음, 장황
SPICE 넷리스트 직접시뮬레이터 직결검증·EasyEDA에 정보 부족, 가독성
회로도 파일시각적텍스트 diff 불가, 도구 종속
넷 중심 표기연결이 명확, 검증 쉬움회로도로 시각화 필요
부품 중심 표기부품 정보 집중연결 파악 어려움

🔌 이 포맷에서 나오는 것들

circuit.yaml 하나에서 다섯 가지가 나옵니다.

명령나오는 것문서
circuit checkERC 검증 결과02
circuit sim / testngspice 측정값03
circuit exportEasyEDA JSON04
circuit previewSVG 회로도—
circuit explain한국어 설명—

하나의 파일에서 전부 나옵니다.

연습문제

문제 1. 다음 회로를 circuit.yaml로 쓰세요: 9 V 전원, 1 kΩ과 2 kΩ 직렬, 중간점이 출력.

exercises/17-01-divider-yaml.yaml
풀이
9V 분압기 회로도R11kΩV19VR22kΩVINOUTGND
9V 분압기
meta:
  name: 9V 분압기

components:
  - {ref: V1, type: vdc, value: 9}
  - {ref: R1, type: r, value: 1k}
  - {ref: R2, type: r, value: 2k}

nets:
  VIN: [V1.p, R1.1]
  OUT: [R1.2, R2.1]
  GND: [V1.n, R2.2]

analyses:
  - {type: op}

expect:
  - {measure: v, node: OUT, value: 6.0, tol: 1%}

VOUT=9×23=6V_{OUT} = 9\times\frac{2}{3} = 6 V

문제 2. 이 포맷에서 GND가 예약어인 이유는?

exercises/17-01-ground-reference.yaml
풀이

SPICE에서 노드 0이 접지이고, 모든 회로는 접지 기준이 있어야 풀립니다.

GND 넷을 자동으로 노드 0에 매핑하면:

  1. 사용자가 매번 지정할 필요 없음
  2. 접지 없는 회로를 검증 단계에서 잡을 수 있음 (E201)
  3. EasyEDA 내보내기에서 접지 심볼로 변환

⚠️ 접지가 없으면 SPICE가 singular matrix 오류를 냅니다 (2-02). 검증기가 시뮬레이션 전에 잡아줍니다.

다음 → 02 검증 (ERC)