Skip to content

Commit 07ab200

Browse files
Add BJT audio preamplifier circuit and associated files
- Created a new SPICE netlist for a BJT audio preamplifier circuit. - Added SVG files for the circuit schematic and response summary. - Introduced a TOML configuration file for the schematic layout. - Updated test suite to include tests for the new BJT audio preamplifier. - Enhanced the cookbook schematic tool to support BJT components.
1 parent d6879a4 commit 07ab200

12 files changed

Lines changed: 855 additions & 20 deletions

File tree

‎.agents/skills/cookbook-schematic/references/layout-format.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@ Optional fields:
7373
- `color`, `fill`: CSS colors.
7474
- `reverse`, `flip`: SchemDraw orientation controls.
7575

76-
Common `kind` values include `resistor`, `resistor-iec`, `capacitor`,
76+
Common `kind` values include `bjt-npn`, `bjt-pnp`, `resistor`,
77+
`resistor-iec`, `capacitor`,
7778
`capacitor-polarized`, `inductor`, `diode`, `zener`, `schottky`, `led`,
7879
`source-v`, `source-i`, `source-pulse`, `source-sin`, `buffer`, and `block`.
7980

‎CIRCUIT_COOKBOOK_PLAN.md‎

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The repository contains the infrastructure needed for this direction:
1919
- `circuits/a-devices` demonstrates a strong example format: runnable
2020
netlists, `.SAVE`, `.PLOT`, `.MEAS`, explanatory guides, and automated
2121
verification.
22-
- `circuits/cookbook` contains four complete application-oriented recipes
22+
- `circuits/cookbook` contains five complete application-oriented recipes
2323
across the pure-SPICE and CustomComponents tracks.
2424
- `tools/cookbook-schematic` renders deterministic, accessible SVG schematics
2525
from a SPICE netlist plus a compact `schematic.toml` layout. Its validator
@@ -42,8 +42,8 @@ equations, assumptions, measurements, and educational value.
4242

4343
The initial cookbook milestone is complete:
4444

45-
- Rectifier power supply, PWM DAC, ideal-diode power OR, and simple PLL recipes
46-
are present in the user-facing catalog.
45+
- Rectifier power supply, PWM DAC, BJT audio preamplifier, ideal-diode power
46+
OR, and simple PLL recipes are present in the user-facing catalog.
4747
- Every current recipe has a runnable `.cir`, full guide, checked-in
4848
`schematic.toml`, generated `schematic.svg`, and accessible `response.svg`.
4949
- All current schematic layouts display every parsed netlist component and
@@ -52,9 +52,10 @@ The initial cookbook milestone is complete:
5252
- The data-driven `CircuitCookbookTests` suite compiles and simulates all
5353
current recipes and enforces their measurement ranges.
5454

55-
The next circuit should be the BJT audio preamplifier. It expands the
56-
pure-SPICE track with operating-point and AC analysis instead of adding another
57-
transient-only example.
55+
The next circuit should be the RC sensor-noise filter and input protector. It
56+
adds an approachable Simple recipe after the Medium BJT preamplifier while
57+
introducing frequency-domain attenuation, step response, and clamp-current
58+
measurements.
5859

5960
## Cookbook Tracks
6061

@@ -87,7 +88,7 @@ story. These recipes should be approachable without prior simulator expertise.
8788
| Circuit | Track | Status | Practical use | What it measures and teaches |
8889
| --- | --- | --- | --- | --- |
8990
| PWM-to-analog converter | Pure SPICE | Complete | Recover an analog control voltage from a microcontroller PWM output | Duty-cycle average, ripple, settling time, and cascaded filtering |
90-
| RC sensor-noise filter and input protector | Pure SPICE | Planned | Condition a noisy low-voltage sensor before an ADC input | Cutoff frequency, step response, attenuation, and clamp current |
91+
| RC sensor-noise filter and input protector | Pure SPICE | Next | Condition a noisy low-voltage sensor before an ADC input | Cutoff frequency, step response, attenuation, and clamp current |
9192
| BJT relay or solenoid driver with flyback diode | Pure SPICE | Planned | Drive an inductive load safely from a logic-level signal | Base drive, coil current, saturation voltage, turn-off transient, and flyback decay |
9293
| RC switch debouncer with Schmitt-trigger buffer | CustomComponents | Planned | Convert a bouncing mechanical switch into a clean digital edge | Threshold hysteresis, rejected pulse width, propagation delay, and output edge count |
9394
| Loaded voltage divider and emitter-follower buffer | Pure SPICE | Planned | Scale a battery or sensor voltage without heavily loading its source | Divider error, input impedance, output impedance, bias error, and headroom |
@@ -104,7 +105,7 @@ should introduce realistic design tradeoffs while remaining easy to modify.
104105
| --- | --- | --- | --- | --- |
105106
| Rectifier, reservoir, and Zener regulator | Pure SPICE | Complete | Produce filtered low-voltage DC from an isolated AC secondary | Startup, diode conduction, reservoir ripple, load regulation, and load steps |
106107
| Ideal-diode redundant power input | CustomComponents | Complete | OR two supplies with automatic failover and reverse-current blocking | Source priority, failover dip, handback, standby current, and reverse current |
107-
| BJT audio preamplifier | Pure SPICE | Next | Raise a small audio signal to a useful level for a following stage | Bias point, AC gain, bandwidth, clipping, loading, and Fourier distortion |
108+
| BJT audio preamplifier | Pure SPICE | Complete | Raise a small audio signal to a useful level for a following stage | Bias point, AC gain, bandwidth, clipping, loading, and Fourier distortion |
108109
| 555 monostable pulse stretcher and PWM controller | Packaged subcircuit | Planned | Create a fixed-duration event pulse and an adjustable LED or fan drive | Pulse width, duty range, frequency, reset behavior, and load response |
109110
| Active anti-alias filter and ADC buffer | Pure SPICE | Planned | Limit sensor bandwidth and drive a sampling input cleanly | Passband gain, cutoff, attenuation, phase shift, settling, and output loading |
110111
| Class-AB headphone or line-output buffer | Pure SPICE | Planned | Drive a low-impedance audio load from a small-signal source | Quiescent current, crossover distortion, voltage swing, output power, and efficiency |
@@ -128,8 +129,8 @@ simulations and a deeper stability or timing explanation.
128129
| Linear bench supply with current limiting and foldback | Pure SPICE | Planned | Provide a regulated DC output that survives overload and short-circuit conditions | Line regulation, load regulation, loop response, current limit, foldback, and device dissipation |
129130
| Digital frequency counter and tachometer | CustomComponents | Planned | Count input events over a fixed gate interval and retain a readable result | Gate timing, count accuracy, overflow, latch timing, reset sequencing, and low-frequency error |
130131

131-
Keep the backlog balanced as recipes are completed. After the BJT
132-
preamplifier, prefer a simple circuit before starting another difficult one.
132+
Keep the backlog balanced as recipes are completed. Build the Simple RC
133+
sensor-noise filter next before starting another Difficult circuit.
133134
This roadmap is a candidate pool, not a commitment to publish all 24 circuits.
134135
Apply the selection criteria before promotion and keep the published catalog
135136
small enough to maintain well.
@@ -150,8 +151,9 @@ The starting sequence established three complementary examples:
150151
Demonstrated that CustomComponents can form a complete mixed-signal system,
151152
rather than only isolated device examples.
152153

153-
The ideal-diode redundant power input was the first follow-on application. The
154-
next addition is the BJT audio preamplifier.
154+
The ideal-diode redundant power input was the first follow-on application, and
155+
the BJT audio preamplifier was the second. The next addition is the Simple RC
156+
sensor-noise filter and input protector.
155157

156158
## Current Repository Structure and Growth Path
157159

@@ -175,6 +177,12 @@ circuits/
175177
schematic.toml
176178
schematic.svg
177179
response.svg
180+
bjt-audio-preamplifier/
181+
README.md
182+
bjt-audio-preamplifier.cir
183+
schematic.toml
184+
schematic.svg
185+
response.svg
178186
custom-components/
179187
ideal-diode-power-or/
180188
README.md
@@ -274,7 +282,7 @@ Each guide should begin with a compact table similar to this:
274282
| Requires | SpiceSharpParser core |
275283
| Dialect | Portable SPICE |
276284
| Analyses | OP, AC, TRAN |
277-
| Difficulty | Intermediate |
285+
| Difficulty | Medium |
278286
| Verified with | SpiceSharpParser 3.4.x |
279287

280288
For custom circuits, `Requires` should explicitly name
@@ -366,7 +374,8 @@ stable across several additional circuits.
366374

367375
## Immediate Next Steps
368376

369-
1. Add the BJT audio preamplifier with OP, AC, and transient measurements.
377+
1. Add the RC sensor-noise filter and input protector with AC, transient, and
378+
clamp-current measurements.
370379
2. Define and trial the recipe manifest on the BJT recipe and one existing
371380
pure-SPICE recipe.
372381
3. Migrate the remaining cookbook test cases after the manifest format is

‎circuits/README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,11 @@ documented design calculations, and automated regression coverage.
99

1010
| Circuit | Track | Analyses | Difficulty | Main lesson |
1111
| --- | --- | --- | --- | --- |
12-
| [Rectifier power supply](cookbook/pure-spice/rectifier-power-supply/README.md) | Pure SPICE | TRAN | Intermediate | Rectification, reservoir ripple, Zener regulation, and a load step |
13-
| [PWM digital-to-analog converter](cookbook/pure-spice/pwm-dac/README.md) | Pure SPICE | TRAN | Beginner | Duty-cycle averaging, ripple attenuation, and settling |
14-
| [Ideal-diode redundant power input](cookbook/custom-components/ideal-diode-power-or/README.md) | CustomComponents | TRAN | Intermediate | Supply OR-ing, automatic failover, handback, and reverse-current blocking |
15-
| [Simple phase-locked loop](cookbook/custom-components/simple-pll/README.md) | CustomComponents | TRAN | Advanced | Phase detection, loop filtering, and voltage-controlled oscillation |
12+
| [Rectifier power supply](cookbook/pure-spice/rectifier-power-supply/README.md) | Pure SPICE | TRAN | Medium | Rectification, reservoir ripple, Zener regulation, and a load step |
13+
| [PWM digital-to-analog converter](cookbook/pure-spice/pwm-dac/README.md) | Pure SPICE | TRAN | Simple | Duty-cycle averaging, ripple attenuation, and settling |
14+
| [BJT audio preamplifier](cookbook/pure-spice/bjt-audio-preamplifier/README.md) | Pure SPICE | OP, AC, TRAN, FOUR | Medium | Biasing, gain, bandwidth, coupling, loading, and harmonic distortion |
15+
| [Ideal-diode redundant power input](cookbook/custom-components/ideal-diode-power-or/README.md) | CustomComponents | TRAN | Medium | Supply OR-ing, automatic failover, handback, and reverse-current blocking |
16+
| [Simple phase-locked loop](cookbook/custom-components/simple-pll/README.md) | CustomComponents | TRAN | Difficult | Phase detection, loop filtering, and voltage-controlled oscillation |
1617

1718
## Other Runnable Examples
1819

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# BJT Audio Preamplifier
2+
3+
This circuit is a single-transistor common-emitter voltage amplifier for a
4+
small audio or sensor signal. A 20 mV peak, 1 kHz input from a 600 ohm source
5+
becomes approximately 0.678 V peak-to-peak at a 47 kohm load. The stage uses a
6+
12 V supply and biases its collector near mid-supply for useful output
7+
headroom.
8+
9+
| Property | Value |
10+
| --- | --- |
11+
| Requires | `SpiceSharp-Parser` |
12+
| Dialect | Portable-style SPICE |
13+
| Analyses | OP, AC, TRAN, FOUR |
14+
| Difficulty | Medium |
15+
| Verified with | SpiceSharpParser 3.4.x repository tests |
16+
| External cross-check | Not yet performed |
17+
18+
## Design Targets
19+
20+
| Target | Value |
21+
| --- | ---: |
22+
| Supply | 12 V |
23+
| Source impedance | 600 ohm |
24+
| Load | 47 kohm |
25+
| Nominal input | 20 mV peak at 1 kHz |
26+
| Collector bias | About 6 V |
27+
| Midband voltage gain | 14 to 20 V/V |
28+
| Audio passband | At least 20 Hz to 20 kHz |
29+
| Small-signal THD | Below 0.5 percent at 1 kHz |
30+
31+
## Schematic
32+
33+
![Common-emitter BJT audio preamplifier schematic](schematic.svg)
34+
35+
The node and component names match
36+
[`bjt-audio-preamplifier.cir`](bjt-audio-preamplifier.cir). `RE1` supplies
37+
local AC feedback, while `RE2` establishes most of the DC emitter
38+
resistance. `CE` bypasses `RE2` at audio frequencies.
39+
40+
## Runnable Netlist
41+
42+
The complete circuit is in
43+
[`bjt-audio-preamplifier.cir`](bjt-audio-preamplifier.cir). Its amplifier core
44+
is:
45+
46+
```spice
47+
R1 vcc base 82k
48+
R2 base 0 18k
49+
Q1 collector base emitter Q2N3904
50+
RC vcc collector 4.7k
51+
RE1 emitter emitter_bypass 220
52+
RE2 emitter_bypass 0 820
53+
CE emitter_bypass 0 100u
54+
```
55+
56+
The checked-in transistor model is intentionally compact and reproducible. It
57+
includes finite current gain, Early effect, junction capacitances, base and
58+
terminal resistances, and forward/reverse transit times.
59+
60+
## How It Works
61+
62+
`R1` and `R2` form a divider that holds the base near 2.1 V.
63+
The base-emitter junction subtracts about 0.67 V, leaving the emitter near
64+
1.44 V. Approximately 1.4 mA then flows through the 1.04 kohm total emitter
65+
resistance.
66+
67+
The collector current creates a voltage drop across `RC`, placing the collector
68+
at 5.505 V. When the input voltage rises, collector current rises and the
69+
collector voltage falls, so a common-emitter stage inverts the signal.
70+
71+
`CIN` prevents the source from disturbing the divider's DC bias. `COUT` removes
72+
the collector's DC level before the signal reaches `RL`. `RE1` improves
73+
bias stability, gain predictability, and linearity. `CE` makes `RE2` a low
74+
AC impedance through most of the audio band, recovering voltage gain without
75+
giving up its DC feedback.
76+
77+
## Design Calculations
78+
79+
Ignoring base current, the divider predicts:
80+
81+
$$
82+
V_B=12\frac{18\text{k}}{82\text{k}+18\text{k}}=2.16\ \text{V}
83+
$$
84+
85+
The simulated base voltage is 2.113 V because the transistor loads the divider.
86+
With the measured 1.440 V emitter voltage:
87+
88+
$$
89+
I_E\approx\frac{1.440}{220+820}=1.385\ \text{mA}
90+
$$
91+
92+
The approximate small-signal emitter resistance is:
93+
94+
$$
95+
r_e\approx\frac{25.8\ \text{mV}}{1.385\ \text{mA}}=18.6\ \Omega
96+
$$
97+
98+
At midband, `CE` largely bypasses the 820 ohm resistor. A first-order gain
99+
estimate is therefore:
100+
101+
$$
102+
|A_v|\approx\frac{4.7\text{k}\parallel47\text{k}}{220+r_e}
103+
=17.9\ \text{V/V}
104+
$$
105+
106+
The measured gain is 16.94 V/V after including the transistor model, source
107+
loading, and incomplete bypass impedance. From a 20 mV peak input, this predicts
108+
roughly 0.678 V peak-to-peak, matching the transient measurement.
109+
110+
## Simulation Setup
111+
112+
`.OP` verifies the quiescent base, emitter, and collector voltages. `.AC` uses a
113+
1 V small-signal source and sweeps 10 Hz to 100 MHz with 40 points per decade.
114+
This makes `VM(output)` numerically equal to voltage gain in V/V and captures
115+
both coupling-capacitor and transistor-model roll-off.
116+
117+
`.TRAN` runs 20 cycles of the 1 kHz input with a 2 us maximum timestep.
118+
Measurements use the final five cycles after coupling-capacitor startup has
119+
settled. `.FOUR` analyzes the last complete output period through the ninth
120+
harmonic.
121+
122+
`.SAVE` requests the source, input, base, collector, emitter, and output
123+
voltages. `.PLOT` requests the AC output magnitude.
124+
125+
![Verified BJT preamplifier response summary](response.svg)
126+
127+
## Verified Measurements
128+
129+
| Measurement | Expected range | Verified result |
130+
| --- | ---: | ---: |
131+
| Collector DC bias | 4.5 to 6.5 V | 5.505 V |
132+
| Base DC bias | 1.9 to 2.3 V | 2.113 V |
133+
| Emitter DC bias | 1.2 to 1.7 V | 1.440 V |
134+
| Gain at 20 Hz | 11 to 16 V/V | 13.309 V/V |
135+
| Gain at 1 kHz | 14 to 20 V/V | 16.941 V/V |
136+
| Gain at 20 kHz | 14 to 20 V/V | 16.942 V/V |
137+
| Gain at 1 MHz | 13 to 20 V/V | 16.437 V/V |
138+
| Lower -3 dB point | 10 to 20 Hz | 16.077 Hz |
139+
| Upper -3 dB point | 2 to 8 MHz | 4.002 MHz |
140+
| Settled output swing | 0.55 to 0.80 V p-p | 0.678 V p-p |
141+
| Settled output average | -10 to 10 mV | 0.884 mV |
142+
143+
The netlist-native Fourier result reports 0.108 percent THD at 1 kHz. The
144+
second harmonic is 0.108 percent of the fundamental; the remaining measured
145+
harmonics are much smaller. Fourier output is asserted separately from the
146+
`.MEAS` table because `.FOUR` produces structured harmonic data rather than a
147+
scalar `.MEAS` result.
148+
149+
## Experiments
150+
151+
- Remove `CE` to observe the large gain reduction and improved linearity from
152+
the full 1.04 kohm emitter degeneration.
153+
- Reduce `CIN` to 100 nF and measure the higher low-frequency cutoff.
154+
- Change `RL` to 10 kohm to see collector loading reduce the gain.
155+
- Raise the input amplitude until the collector approaches saturation or the
156+
supply rail, then compare the waveform and THD with the small-signal result.
157+
- Change `RE1` to trade gain for linearity and bias tolerance.
158+
- Sweep transistor current gain or temperature to see why divider bias and
159+
emitter degeneration matter.
160+
161+
## Model Boundary
162+
163+
This example is a voltage preamplifier, not a power amplifier. The 47 kohm load
164+
represents a following high-impedance stage; it cannot drive a speaker or low-
165+
impedance headphones directly.
166+
167+
The compact generic 2N3904-style model is suitable for teaching bias,
168+
small-signal gain, coupling, and first-order distortion. It does not guarantee
169+
the behavior of a particular vendor part. The circuit omits resistor and
170+
capacitor tolerances, transistor noise, microphone bias, PCB coupling,
171+
electromagnetic interference, thermal self-heating, supply decoupling, and a
172+
volume control. The simulated upper cutoff depends strongly on the compact
173+
model's capacitance and transit-time parameters.
174+
175+
## Running and Testing
176+
177+
Compile and simulate it from C#:
178+
179+
```csharp
180+
using System;
181+
using SpiceSharpParser;
182+
using SpiceSharpParser.Common;
183+
184+
SpiceCompilationResult result =
185+
SpiceCompiler.CompileFile("bjt-audio-preamplifier.cir");
186+
187+
if (!result.Success)
188+
{
189+
throw new InvalidOperationException(
190+
string.Join(Environment.NewLine, result.Diagnostics));
191+
}
192+
193+
foreach (var simulation in result.Model.Simulations)
194+
{
195+
simulation.Execute(result.Model.Circuit);
196+
}
197+
```
198+
199+
Run the cookbook quality gate and regression test:
200+
201+
```powershell
202+
.\tools\cookbook-schematic\.venv\Scripts\cookbook-report
203+
204+
dotnet test src/SpiceSharpParser.Tests/SpiceSharpParser.Tests.csproj `
205+
--filter 'FullyQualifiedName~CircuitCookbookTests'
206+
```
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
BJT audio preamplifier
2+
VCC vcc 0 12
3+
VSIG source 0 SIN(0 20m 1k) AC 1
4+
RS source input 600
5+
CIN input base 1u
6+
R1 vcc base 82k
7+
R2 base 0 18k
8+
Q1 collector base emitter Q2N3904
9+
RC vcc collector 4.7k
10+
RE1 emitter emitter_bypass 220
11+
RE2 emitter_bypass 0 820
12+
CE emitter_bypass 0 100u
13+
COUT collector output 10u
14+
RL output 0 47k
15+
16+
.MODEL Q2N3904 NPN(Is=6.734f Bf=416.4 Br=0.7374 Vaf=74.03
17+
+ Cje=3.638p Cjc=4.493p Rb=10 Rc=1 Re=0.1 Tf=301.2p Tr=239.5n)
18+
19+
.OP
20+
.AC DEC 40 10 100Meg
21+
.TRAN 2u 20m 0 2u
22+
23+
.MEAS OP collector_bias FIND V(collector) AT=0
24+
.MEAS OP base_bias FIND V(base) AT=0
25+
.MEAS OP emitter_bias FIND V(emitter) AT=0
26+
.MEAS AC gain_20hz FIND VM(output) AT=20
27+
.MEAS AC gain_1khz FIND VM(output) AT=1k
28+
.MEAS AC gain_20khz FIND VM(output) AT=20k
29+
.MEAS AC gain_1mhz FIND VM(output) AT=1Meg
30+
.MEAS AC lower_3db WHEN VM(output)=11.98 RISE=1
31+
.MEAS AC upper_3db WHEN VM(output)=11.98 FALL=1
32+
.MEAS TRAN output_pp PP V(output) FROM=15m TO=20m
33+
.MEAS TRAN output_average AVG V(output) FROM=15m TO=20m
34+
35+
.FOUR 1k V(output)
36+
.SAVE V(source) V(input) V(base) V(collector) V(emitter) V(output)
37+
.PLOT AC VM(output)
38+
.END

0 commit comments

Comments
 (0)