Skip to content

Commit 489e6c2

Browse files
marcin-golebiowskimarcin-golebiowski
committed
feat: Add README.md for SpiceSharpParser.CustomComponents package
1 parent e487b4b commit 489e6c2

2 files changed

Lines changed: 170 additions & 0 deletions

File tree

‎src/SpiceSharpParser.CustomComponents/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# SpiceSharpParser.CustomComponents
2+
3+
[![NuGet](https://img.shields.io/nuget/v/SpiceSharpParser.CustomComponents.svg)](https://www.nuget.org/packages/SpiceSharpParser.CustomComponents)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/LICENSE)
5+
6+
`SpiceSharpParser.CustomComponents` is the optional companion package for
7+
[SpiceSharpParser](https://github.com/SpiceSharp/SpiceSharpParser). It adds
8+
LTspice-compatible components and reusable functional subcircuits while keeping
9+
the resulting circuit compatible with the normal SpiceSharp simulation API.
10+
11+
The package targets .NET Standard 2.0 and .NET 8.0.
12+
13+
## Installation
14+
15+
```shell
16+
dotnet add package SpiceSharpParser.CustomComponents
17+
```
18+
19+
The package depends on `SpiceSharp-Parser`, so a separate parser package
20+
reference is not required.
21+
22+
## Enable Custom Netlist Components
23+
24+
The original parser/reader flow keeps parsing, translation, and simulation as
25+
explicit steps. Enable the custom mappings on `SpiceSharpReader` before calling
26+
`Read`:
27+
28+
```csharp
29+
using System.IO;
30+
using System.Linq;
31+
using SpiceSharpParser;
32+
using SpiceSharpParser.CustomComponents;
33+
34+
string netlistText = File.ReadAllText("circuit.cir");
35+
var compatibility = CompatibilityOptions.LTspice;
36+
37+
// Parse the SPICE text.
38+
var parser = new SpiceNetlistParser();
39+
parser.Settings.Compatibility = compatibility;
40+
var parsed = parser.ParseNetlist(netlistText);
41+
42+
// Translate the parsed model into SpiceSharp objects.
43+
var reader = new SpiceSharpReader();
44+
reader.Settings.Compatibility = compatibility;
45+
reader.Settings.UseCustomComponents();
46+
var model = reader.Read(parsed.FinalModel);
47+
48+
// Run the analysis defined by .OP, .TRAN, .AC, or .DC in the netlist.
49+
var simulation = model.Simulations.Single();
50+
simulation.Execute(model.Circuit);
51+
```
52+
53+
`UseCustomComponents()` adds custom-aware mappings for `A`, `C`, `D`, and `L`
54+
elements. Call it before `Read`, and use the same compatibility settings for
55+
the parser and reader. Ordinary diode, capacitor, and inductor syntax continues
56+
to use the standard SpiceSharp implementations.
57+
58+
## Included Components
59+
60+
| Family | Supported forms |
61+
| --- | --- |
62+
| LTspice A-devices | `SRFLOP`, `DFLOP`, `PHASEDET`, `COUNTER`, `SAMPLEHOLD`, `OTA`, `VARISTOR`, and `MODULATOR`/`MODULATE` |
63+
| Ideal diodes | LTspice-style `.MODEL D(...)` parameters such as `Ron`, `Roff`, `Vfwd`, reverse clamp, smoothing, and current limits |
64+
| Nonlinear capacitors | Charge-defined capacitors using `Q=<expression>` |
65+
| Nonlinear inductors | Flux-defined inductors using `Flux=<expression>` |
66+
| Digital subcircuits | Gates, Schmitt inputs, tri-state drivers, multiplexers, an adder, decoder, comparator, open-drain output, latches, flip-flops, a counter, phase detector, and functional 555 timer |
67+
| Analog subcircuits | Sample-and-hold, operational transconductance amplifier, voltage-controlled varistor, and frequency/amplitude modulator |
68+
69+
## A-device Quick Reference
70+
71+
Every native LTspice A-device has eight terminal positions followed by its
72+
model name.
73+
74+
```spice
75+
A<name> n1 n2 n3 n4 n5 n6 n7 n8 <model> [parameter=value ...]
76+
```
77+
78+
| Model | What it does |
79+
| --- | --- |
80+
| `SRFLOP` | Stores one bit using asynchronous set and reset inputs |
81+
| `DFLOP` | Captures a data bit on a clock edge |
82+
| `PHASEDET` | Produces signed current pulses from input-edge timing error |
83+
| `COUNTER` | Counts clock edges and generates a repeating output sequence |
84+
| `SAMPLEHOLD` | Samples an analog voltage and holds the captured value |
85+
| `OTA` | Converts differential input voltages into a limited output current |
86+
| `VARISTOR` | Provides a bidirectional voltage-controlled clamp; like a programmable surge-protection varistor |
87+
| `MODULATOR` | Generates an amplitude-controlled waveform whose frequency moves between `Space` and `Mark` |
88+
89+
Terminal 8 is the common node. A terminal position is unused when it repeats
90+
that common node. If common is not ground, a literal `0` is an active connection
91+
to global ground, not an unused terminal. Unused outputs are electrically
92+
detached; an unused `MODULATOR` amplitude input selects the native amplitude of
93+
1.
94+
95+
Example:
96+
97+
```spice
98+
* Divide a clock by four
99+
VCLOCK clock 0 PULSE(0 5 5n 100p 100p 2n 10n)
100+
VRESET reset 0 0
101+
102+
ACOUNT clock reset 0 0 0 qb q 0 COUNTER Cycles=4 Duty=0.5
103+
RQ q 0 10k
104+
RQB qb 0 10k
105+
106+
.tran 100p 42n 0 100p UIC
107+
.save V(clock) V(q) V(qb)
108+
.plot tran V(clock) V(q) V(qb)
109+
.meas tran q_at_30n FIND V(q) AT=30n
110+
.print tran V(q)
111+
.end
112+
```
113+
114+
## Programmatic Subcircuit Use
115+
116+
The embedded libraries can also add components directly to a SpiceSharp
117+
`Circuit`:
118+
119+
```csharp
120+
using SpiceSharp;
121+
using SpiceSharp.Components;
122+
using SpiceSharpParser.CustomComponents.Digital;
123+
124+
var circuit = new Circuit(
125+
new VoltageSource("VDD", "vdd", "0", 5.0),
126+
new VoltageSource("VA", "a", "0", 5.0),
127+
new VoltageSource("VB", "b", "0", 5.0),
128+
new Resistor("RLOAD", "y", "0", 10_000.0));
129+
130+
var digital = DigitalSubcircuitLibrary.LoadBuiltIn();
131+
digital.AddBinaryGate(
132+
circuit,
133+
DigitalGateKind.Nand2,
134+
instanceName: "XU1",
135+
firstInputNode: "a",
136+
secondInputNode: "b",
137+
outputNode: "y",
138+
positiveSupplyNode: "vdd",
139+
negativeSupplyNode: "0");
140+
```
141+
142+
Use `AnalogSubcircuitLibrary.LoadBuiltIn()` for the four analog functional
143+
models.
144+
145+
## Compatibility Notes
146+
147+
- A-device support is experimental and intentionally limited to the eight
148+
documented families.
149+
- `MODULATOR` requires both `Mark` and `Space`; `COUNTER` requires `Cycles`.
150+
- `SAMPLEHOLD Td` is rejected because its native delayed timing semantics are
151+
not implemented.
152+
- Sweep-dependent A-device parameters are rejected instead of being silently
153+
frozen at one value.
154+
- The digital and analog libraries are functional macromodels, not
155+
transistor-level replicas of a specific physical part.
156+
157+
## Documentation and Examples
158+
159+
- [A-device guide](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/src/docs/articles/a-devices.md)
160+
- [Runnable A-device examples](https://github.com/SpiceSharp/SpiceSharpParser/tree/main/circuits/a-devices)
161+
- [Digital subcircuit reference](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/src/docs/articles/digital-subcircuits.md)
162+
- [Analog subcircuit reference](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/src/docs/articles/analog-subcircuits.md)
163+
- [Ideal diode guide](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/src/docs/articles/ideal-diode.md)
164+
- [Nonlinear passive guide](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/src/docs/articles/nonlinear-passives.md)
165+
166+
## License
167+
168+
MIT. See the repository [license](https://github.com/SpiceSharp/SpiceSharpParser/blob/main/LICENSE).

‎src/SpiceSharpParser.CustomComponents/SpiceSharpParser.CustomComponents.csproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
<RepositoryType></RepositoryType>
1212
<PackageTags>circuit electronics spice custom components ideal diode nonlinear capacitor inductor digital logic schmitt tri-state multiplexer timer 555</PackageTags>
1313
<PackageId>SpiceSharpParser.CustomComponents</PackageId>
14+
<PackageReadmeFile>README.md</PackageReadmeFile>
1415
<Product>SpiceSharpParser.CustomComponents</Product>
1516
<Description>Custom SpiceSharp components for SpiceSharpParser integrations.</Description>
1617
<PackageReleaseNotes>0.1.1 hardens LTspice A-device models with unused-terminal semantics, native zero-delay and PHASEDET defaults, OTA limit and Cout fixes, nonleaking state, stable modulation, clock-independent edge capture, continuous varistor leakage, and explicit SAMPLEHOLD Td rejection.</PackageReleaseNotes>
@@ -42,6 +43,7 @@
4243
</ItemGroup>
4344

4445
<ItemGroup>
46+
<None Include="README.md" Pack="true" PackagePath="\" />
4547
<EmbeddedResource Include="Analog\Netlists\standard-analog.lib"
4648
LogicalName="SpiceSharpParser.CustomComponents.Analog.standard-analog.lib" />
4749
<None Include="Analog\Netlists\standard-analog.lib"

0 commit comments

Comments
 (0)