How to use in Kicad a model from ngspice manual?

[gwideman]

The Ngspice user’s manual (version 42)) includes discussions of quite a number of models, and an example of how to use each in command-line ngspice.

But I’m not clear on how to use them in Kicad. So, for example, we have the potentiometer model (section 12.2.34):

Apot r0 w r1 potmod
.model potmod potentiometer(position=0.45 r=1k log=FALSE log_multiplier=1)

OK, how does that translate into things I can do in Kicad?

1. I’m guessing that I could stick the “.model…” statement into a text on the Kicad schematic? Or should I put it somewhere in the component’s “Simulation Model” dialog? Or does it belong in a file?

2. I don’t know at all what to do with the “Apot r0…” line. I guess “Apot” should be replaced by the Reference Id (RV1 say) on the schematic? And potmod associates RV1 with the .model statement. The other three items are to do with the three pins, but I’m not sure what to do with them. But the biggest problem is, I don’t know where to put this statement. I tried inserting it in RV1’s Model Editor > Code tab text box. But on running the simulation it just got deleted.

3. I notice that this model is from a chapter of the manual relating to XSPICE. From Kicad, does XSPICE have to be enabled or invoked somehow?

4. Even when the above items are resolved, where do we then fill in pot resistance and wiper position?

5. I was kind of expecting that if a Potentiometer model was supplied with ngspice, that it would be selectable in the Simulation Model Editor window, and there would be slots to fill in resistance and wiper position. The manual’s discussion includes a lengthy table of other parameters in the model, so I thought they might also show up in the UI as a table.

I’d appreciate if someone would fill in a few clues!

EDIT: I was intending for this topic to be about the general principles of using a model from the ngspice manual, and happen to have used potentiometer as an example. There is a separate thread about potentiometer models that has seen some useful progress, here:
Where is the built-in potentiometer model?

[Claudio.Lorini]

have you already read the available kicad documentation about simulation?
if not i’d start there:

Schematic Editor | 8.0 | English | Documentation | KiCad

[holger]

The general question how to add a code model (from chapter 12 of the ngspice manual) to a project may be answered with the following potentiometer example.

For some time now I have planned to add a small series on videos of potentiometer simulation to my video collection at https://www.youtube.com/@holger8105.

So I may take the following as a film script for Part II of the new videos.

What do we need when we want to simulate a potentiometer?

a symbol (may be Device:R_Potentiometer or Device:R_Potentiometer_Trim)

a ngspice model (which should display the total resistance and the wiper position
on the Eeschema canvas, to be easily adapted by the user)

ngspice already offers a code model for the potentiometer (see ngspice manual chapter 12.2.34, changed to 8.2.34 for upcoming ngspice-43). All code models (more than 70 are available) start with letter A on the instance line and require a .model line. As the code model syntax may be complex, and we want to have user adaptable parameters, in my view the best approach is to put the code model instance and its .model into a subcircuit, which then may be attached to the symbol in the usual way, as any other (vendor provided) subcircuit model.

Looking at the symbols, we have three nodes: 1 is the upper resistor connection, 2 the wiper, and 3 the lower resistor connection. Our subcircuit frame takes these nodes and their sequence (1, 2, 3) into account:

* code model for potentiometer
.subckt potia ru wp rl
.ends

Just adding the potentiometer code model (copy from the manual)

* code model for potentiometer
.subckt potia ru wp rl
Apot r0 w r1 potmod
.model potmod potentiometer(position=0.45 r=1k log=FALSE log_multiplier=1)
.ends

and adapting the node names (see the description in the manual) to make them connecting to the .subckt line:

* code model for potentiometer
.subckt potia ru wp rl
Apot rl wp ru potmod
.model potmod potentiometer(position=0.45 r=1k log=FALSE log_multiplier=1)
.ends

We might now attach this model to the symbol, but its not yet what we wanted. Changing the wiper position would require editing the model. Having more than one potentiometer in the circuit with different resistance values and wiper positions would require a different model for each potentiometer.

So lets define at least the total resistance and wiper position as user-adaptable parameters. Therefore we need a change to the .subckt line (adding the parameters) and the .model line (replacing the values by its parameters):

* code model for potentiometer
.subckt potia ru wp rl params: pos=0.45 Rtot=1k
Apot rl wp ru potmod
.model potmod potentiometer(position={pos} r={Rtot} log=FALSE log_multiplier=1)
.ends

Put these lines into a file, e.g. pot.mod, and attach the model to the symbol. The pin sequence is o.k. because we have it defined correctly in the .subckt line.

To make the parameters visible and editable on the Eeschema canvas, we need to do the following: After attaching, open again the “Simulation Model Editor” window. You now see the Parameters pos and Rtot and their Defaults. Copy the Defaults into the Value field, pos with 0.45 and Rtot with 1k. Close the window by o.k. . Back in the “Symbol Properties” window, scroll down to see the new field Sim.Params. Check its “Show” box. Uncheck the “Show” box of the Value field (no relevant information shown). Close the window by o.k. On the canvas, you may move the new text line “pos=0.45 Rtot=1k” to an appropriate position. Double clicking this line allows editing, entering new values for this specific symbol only.

[gwideman]

have you already read the available kicad documentation about simulation?

Yes.

[holger]

Indeed for the potentiometer, there is another way adding the ngspice model to the symbol. I will report on that method (as described in the Eeschema manual) later.

[gwideman]

@holger Let’s keep the alternative ways of handling potentiometers on the other concurrent discussion topic. I would like to ask you a followup regarding the general principles for these “A” models though. Coming up.

[gwideman]

@holger

1   * code model for potentiometer
2   .subckt potia ru wp rl params: pos=0.45 Rtot=1k
3   Apot rl wp ru potmod
4   .model potmod potentiometer(position={pos} r={Rtot} log=FALSE log_multiplier=1)
5   .ends

This code has a whole bunch of identifiers, and it would be great to have a succinct description of what their functions are, how they all relate/link/point to each other, and also how they are exposed in the Kicad UI.

There seem to be four different ids that refer in some way to the model:

• potia
• Apot
• potmod
• potentiometer

What are the distinct roles of each of these ids? Is “potentiometer” a model? Is “potmod” a model? These are nested somehow? Then what is an Apot?

We have some ids that refer to pins:

• Line 2: ru wp and rl
• Line 3: rl wp ru

(Upper resistor, wiper, lower resistor).
Is there some significance to them being in two different orders?

There are also ids that refer to parameters:

• 2 pos=0.45 Rtot=1k
• 4 potentiometer(position={pos} r={Rtot} log=FALSE log_multiplier=1)

I guess the idea here is that “potentiometer” is a built-in model/function/whatever, for which parameters pos and Rtot are being passed to local arguments position and r (with additional local arguments log and log_multiplier).

This is somewhat at odds with what’s exposed in Kicad, where the parameters are listed as “Resistance (r)” and “Wiper position (pos)”, where pos corresponds to line 2 here, but r corresponds to line 4 here.
I suspect just an artifact of you so speedily concocting this draft tutorial – but you can see for those of us trying to make sense of this, confusion abounds!

[BlackCoffee]

When it comes to NGspice, I consider Holger the ‘Guru’.

However, I play around to learn what works and doesn’t work for me and that results in different approaches leading to knowledge…

Below I show some options for consideration… beside’s using ‘Include’ and ‘sub-ckt’…

[gkeeth]

@gwideman

There seem to be four different ids that refer in some way to the model:

• potia
• Apot
• potmod
• potentiometer

What are the distinct roles of each of these ids? Is “potentiometer” a model? Is “potmod” a model? These are nested somehow? Then what is an Apot?

It works best to explain your bullets in reverse order.

• potentiometer is the device type - see the ngspice documentation section 12.2.34 for the definition of this and its arguments.
• potmod is the name of the model we’re defining (which is a potentiomenter device with specific parameters given, like the position, total resistance, and the fact that it’s linear)
• Apot is the name of the potentiometer instance we’re creating using the potmod model we defined. the A at the beginning tells ngspice that it’s a code model as opposed to a resistor or a subcircuit or a source or … If we wanted multiple instances of the potmod model within this subcircuit we could create Apot1, Apot2, etc.
• potia is the name of the subcircuit model we are defining to wrap our potentiometer. The three tokens after potia are the names of the nodes (pins) that are accessible from the higher level netlist. The params are modifiable “arguments” for lack of a better word with default values that can be overridden in the higher level netlist (or in the KiCad sim model editor GUI). If you look at the higher level netlist that uses this subcircuit, you will see that there is an instantiation of it that defines what the named nodes here are connected to. The subcircuit instantiation will have a name that starts with X for subcircuit (if the netlist is created with KiCad, this will be X + the symbol’s reference designator).

For further reading, see the ngspice manual:

• section 2.5 for subcircuit definitions
• section 2.1.3 for circuit elements in the netlist (instances) and their prefixes
• section 2.4 for device model definitions

[BlackCoffee]

Have you ever used Excel and realized it can do a bazillion things and the documentation itself is filled with confusion?

I found that to also be true with NGspice documentation - it’s good, no question about that but, I don’t need to know/do everything about it to do what I need to do.

I was lucky to stumble upon this 20-page tutorial that was wonderful for my learning needs - simple, and clear. It’s not for Kicad, rather it’s for Command-line however, realizing that and spending 10-Minutes with Kicad’s NGspice, I learned how to implement it into Kicad…

ADDED: To help bring Clarity to Gosh Ex#1 with respect to it in Kicad…

[gwideman]

Just a stand-alone reply to say thanks to @holger for the extensive amount of attention he’s paid to this discussion and the parallel one specifically on potentiometers.

[gwideman]

@BlackCoffee – thanks for your contribution! That tutorial presentation is indeed helpful.

Your inclination to clarify using annotated screen caps and listings is very much up my alley and to my liking.

To help bring Clarity to Gosh Ex#1 with respect to it in Kicad…

For other readers, “Gosh” is not an exclamation on the part of Black Coffee, it’s the name of the author of the suggested tutorial… though the name is actually Ghosh. Haha.