circuit.yaml 포맷 명세 (v0.1)

이 문서는 규범(normative) 명세입니다. 튜토리얼은 docs/17-workflow/01-circuit-format.md를 보세요.

examples/ 아래 102개 회로가 전부 이 명세를 따릅니다. 명세와 예제가 어긋나면 명세가 아니라 둘 중 하나가 버그입니다.

요구 수준 표기 — MUST(반드시) / SHOULD(권장) / MAY(선택)

1. 파일

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

../../의 깊이는 파일 위치에 맞춥니다(examples/<장>/<이름>.yaml이면 ../../).

2. 최상위 키

정의되지 않은 최상위 키는 에러입니다(오타를 잡기 위해 additionalProperties: false).

3. meta

lesson은 링크 체커가 검사합니다. 존재하지 않는 경로면 테스트가 실패합니다. 커리큘럼과 예제가 따로 썩는 것을 막는 장치입니다.

4. components

각 원소는 매핑이며 다음 키만 허용합니다.

ref의 접두 문자는 관례를 SHOULD 따릅니다: R(저항) C(커패시터) L(인덕터) D(다이오드) Q(BJT) M(MOSFET) U(IC) V(전압원) I(전류원) SW(스위치) K(결합).

4.1 부품 타입과 핀

핀 이름은 대소문자를 구분하며, 여기 적힌 것 외에는 에러입니다.

⚠️ opamp의 v+/v-는 생략할 수 없습니다. 전원핀을 결선하지 않으면 SPICE에서 부유 노드가 되어 해가 안 나오거나 엉뚱한 값이 나옵니다. circuit check가 W306으로 잡습니다.

핀 이름에 +나 -가 들어가면 YAML에서 따옴표가 필요합니다:

nets:
  IN:  [RS.2, U1.'in+']     # ← 작은따옴표 MUST
  OUT: [U1.out, R2.2]       # ← 특수문자 없으면 불필요

4.2 params

기생 파라미터(esr/esl/cp/dcr)는 도구가 등가 회로로 전개합니다. 무엇이 모델링됐는지 명시하고 싶으면 11-07처럼 등가 회로를 직접 쓰는 편이 낫습니다(SHOULD).

5. 값 표기

value와 수치형 params는 문자열 또는 숫자입니다.

5.1 문법

<숫자>[<접두어>][<단위문자>]        예: 10k, 4.7u, 100n, 1MEG
<정수><접두어><소수부>              예: 4k7 = 4.7k, 2R2 = 2.2
<지수표기>                          예: 1e-6, 1.5E3

5.2 접두어

5.3 ★ M의 의미 — 이 포맷의 가장 중요한 규정

이 포맷은 공학 관례를 따르고, SPICE로 변환할 때 M → MEG로 바꿉니다.

⚠️ 대소문자 구분이 없는 SPICE에서 1M을 메가로 알고 썼다가 1000배 틀리는 것은 가장 흔한 사고 중 하나입니다(0-03). 이 포맷은 그 함정을 원천 차단합니다. 혼동이 걱정되면 1MEG을 쓰세요 — 양쪽에서 동일합니다.

단위 문자(Ω, F, H, V, A)는 쓰지 않습니다. 타입이 단위를 결정합니다.

6. nets

nets:
  <넷이름>: [<ref>.<핀>, <ref>.<핀>, ...]

6.1 예약 넷

VCC/VDD/VEE/VSS는 예약어가 아니지만, EasyEDA 내보내기에서 전원 플래그 심볼로 변환되므로 전원 레일에 SHOULD 사용합니다.

7. analyses

• sweep: dec | oct | lin
• source: 전압/전류원의 ref
• out: 넷 이름
• 시간·주파수 값은 §5 표기 사용 (1n, 100MEG)

해석 1개당 ngspice 프로세스 1개를 띄웁니다. 여러 해석을 한 파일에 넣어도 서로 간섭하지 않습니다.

8. expect — 측정 검증

각 원소는 하나의 측정을 기술합니다. 이 블록이 “손계산 = 시뮬레이션 = EasyEDA”를 자동 확인하는 지점입니다.

8.1 공통 필드

8.2 측정 종류와 대상 지정

expect:
  - {measure: v, node: OUT, value: 1.667, tol: 1%}
  - {measure: i, through: D1, value: 9.1m, tol: 15%}
  - {measure: p, of: R1, max: 0.25}
  - {measure: gain_db, node: OUT, at: 1k, analysis: ac, value: -3, tol: 0.5}
  - {measure: v, node: OUT, at: 1m, analysis: tran, value: 3.16, tol: 3%}
  - {measure: noise_input, at: 1k, analysis: noise, value: 57.8n, tol: 10%}

8.3 판정

tol 없이 value만 주면 기본 1% 상대 허용오차입니다.

💡 저항의 전류·전력은 노드 전압에서 해석적으로 계산합니다((V₁−V₂)/R). ngspice의 @r1[i] 문법이 버전마다 다르기 때문입니다.

8.4 EasyEDA 연동

expect에 등장하는 모든 node에는 내보내기 시 전압 프로브가 자동으로 붙습니다. EasyEDA에서 파일을 열고 Ctrl+R만 누르면, 우리가 검증한 그 노드가 이미 프로브되어 있습니다(17-04).

9. ideal / real 쌍 규약

11~13장과 16장의 예제는 같은 회로의 두 버전을 SHOULD 제공합니다.

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

기생 성분의 영향을 말이 아니라 시뮬 파형의 차이로 보여주는 것이 목적입니다.

10. 최소 예제

# 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}

11. 버전 정책

12. 명세 자체의 검증

이 명세가 지켜지는지는 다음으로 확인합니다.

문서의 코드블록과 examples/의 파일이 어긋나면 테스트가 실패합니다. 둘 중 하나만 고치는 일이 생기지 않게 하는 장치입니다.