Dynamic (or Primitive) File Descriptions

A dynamic model is defined algebraically, it takes some electrical or physical properties as arguments and generates the S-Parameters based on these parameters, as opposed to a static model where the S-Parameters are fixed at the time of measurement/ modeling. Be aware that in the documentation I tend to use the phrase "dynamic" model to contrast against the "static" Touchstone model. However, when I first started coding Mason I used the phrase "primitive" ... so for historical reasons consider these terms interchangeable.

The algebraic models are installed with Mason, and can be found using a link in the Start Menu under "Circuit Mason".

This following is an advanced topic not required for using Circuit Mason. Rather, it is important if you want to extend the Mason Libraries. These libraries (XML files including the required algebra) are installed in a "documents" folder, e.g.

C:\Users\[your user name]\AppData\Local\CircuitMason\mason_models; your location may vary but during install the exact folder will be opened for reference, and you can find a link to the folder under the Start Menu entry for Circuit Mason.

All of the dynamic items in Mason are defined in text files. This makes the creation of new tool boxes possible without having to understand the source code. Since the primitives are not compiled, a very slight penalty in run time is incurred; a trade-off for convenience. Actually, the default dynamic components that come with the Mason installer are compiled into the code, so if you change the XML models you won't see a change in the results unless you set the appropriate flag, which tells Mason to use the XML files and not the pre-compiled functions.

Both File based (Touchstone) and Dynamic (Primitive) components can also be inverted for de-embedding.

The primitive file is broken into the following sections.

Basic attributes

Three attributes must be defined for a primitive: the alias, a shortened version of the alias, and the number of ports for the device. The aliases are the same as for the file-based components.

<primitive alias=”lossless_transmission_line”

alias_short=”TL”

ports=”2”></primitive>

Comments can be nested for documentation.

Arguments

Primitives can have a variable number of arguments associated with them; their values are not known until run-time. The names of these arguments are under the <primitive> root.

It is not technically required to use the double-underscore when defining these arguments; it is strongly advised to make sure there is not variable confusion when assigning variables to the arguments. There is a clean separation between the variables contained within the primitive calculations (described below); unfortunately at the interface between the circuit and the primitive if you have an argument "theta" and a variable "theta", this can cause problems with the math parser. Changes in the code to fix this have hurt the run time unacceptably.

Comments can be nested for documentation.

For future compatibility, units are being added as part of the definition of select variables (please see units).

Assumptions

Some values of the arguments may not be valid for the design equations used. For example, a curved microstrip model may have some requirements for the radius and width of the bend.

If an assumption fails, all the calculations and will be sent to the console.

Calculations

Ultimately, the S-Parameters should be defined by variables following the pattern: S_r_d, where ‘r’ is the reflection port and ‘d’ is the driven port. While other calculations may proceed it, “S_1_1” must be the first of the S-Parameters to be defined, and after S_1_1 all calculations should be S-Parameters.

Previous versions had a limit for the number of variables and characters in the equations. This limit has been removed.

<calculation

equation=”S_1_1=G1+U2*T1*T2*G3/(1-G2*G3*U2)”>

</calculation>

Synthesis (optional)

“Synthesis” tags are used by PrimCalc to define which variables called out in the calculations are to be called out. Generally these are electrical properties for which one might want to design (such as line impedance) or simply calculate (such as conductor loss).

<synthesis name="Z0"> Impedance (ohms) </synthesis>

<synthesis name="alpha_c">Conductor loss (dB/m) </synthesis>

PCB (optional)

To simplify the transition from schematic -> simulation -> layout, tags can be included that describe the physical layout of the primitive. Currently this flow is designed to complement the DxDesigner-PADS system. The analog and digital design can be done in DxDesigner. The RF design can be done using TinyCAD and Mason. Nets can be named in TinyCAD to match up with DxDesigner and therefore interface between the designs.

The format for describing the footprint uses muParser expressions to describe the (x,y) locations (in meters). Multiple pieces of copper can be defined. The arguments are available as variables (though calculations are not). Every time ‘y’ is defined, a new point is written. To simplify the parser, there can be no space between ‘y’ and ‘=’. The line width of the copper fill can also be specified (default is 200µm).

Terminals are round pads which are meant to be placed on top of copper. Terminals can also be vias, in which case the via radius must also be given. The terminals will match up to the local nodes of the component in the order they are places (the first terminal position is local node 1).

Valid layer definitions are the numbers -2 to 12, where a number describes a specific layer (-2 for top, -1 for inner, 0 for bottom, other numbers for specific layers).

The connections define how two pieces will be connected- the place the neighbor should latch onto in the coordinate system local to the local device. The normal vector (the direction facing away from the device at that connection point) is defined by the "rot" (rotation) variable: 0 is +y, 90 is -x, 180 is -y, and 270 is +x (the convention of PADS).

A free variable called "_rotate" is provided which allows microstrip and stripline components to be flipped properly. See "mcurve.xml" for how that works. _rotate can have a value from 0 to 7 and corresponds to the "rotation" states in TinyCAD: up, down, left, right, mirror up, mirror down, mirror left, and mirror right, respectively. To be honest, I used trial and error at 3am to fix this.

<pcb>

</copper>

</terminal>

</terminal>

</connection>

</connection>

</pcb>

In addition to adding pieces of copper, copper pour and plane keepouts can be added using the same description as copper pieces. The only difference is the line width does not need to be defined.:

</keepout>

</keepout>

Also, you can define a solder pad using the same basic format as the copper pad. Layer 21 is the Top Solder layer, layer 28 is Bottom Solder. The paste layers could also be defined in this manner. Using the solder layer definition allows one to keep the mask on the combined decal except where smart components define solder. (Note: July 24, 2013: I will be working on adding solder pads to smart footprints over the next few weeks).

<calculation equation="PP= 1.5e-3" /> pin pitch

<calculation equation="RP = 2.08e-3" /> row pitch (centers)

<calculation equation="PW = 0.66e-3" /> pin width

<calculation equation="PL = 1.57e-3" /> pin length

<calculation equation="XX = -1" /> pin width

<calculation equation="YY = 1" /> pin length

</solder>

Copper, keepouts, and solder can also be defined using an arc (examine the curved microstrip line for an example). Rather than using x,y for the calculation, the following equations are defined (‘yr’ must be defined last):

- xa, ya
  - - beginning of the arc
- ab
  - - beginning angle of the arc (in degrees)
- aa
  - - number of degrees in the arc (in degrees)
- xl,yl
  - - Lower left point of the rectangle around the circle of the arc (please note these are L’s in the variable name, not ones)
- xr,yr
  - - Upper right point of the rectangle around the circle of the arc

Please note that the following variable names are special and should only be used for defining lines and arcs: x, y, xa, ya, ab, aa, xl, yl, xr, yr.

Example primitive file: a lossless transmission line

<?xml version="1.0"?>

<primitive alias="lossless_transmission_line"

alias_short="TL"

ports="2">

This is a lossless transmission line.

<argument name="z0"> The line impedance (in ohms)

</argument>

<argument name="theta"> The electrical length (in degrees)

</argument>

<argument name="f0"> The center frequency (in Hertz)

</argument>

</calculation>

</calculation>

</calculation>

<calculation equation="S_1_2 = T1*T3*U1 + T1*T3*G2*G3*U1*U2

/ (1-G2*G3*U2) "> </calculation>

</primitive>

Additional Constraints

In order to improve run time, a technique has been written which reads the XML files and creates code which compiles into Mason. In order to simplify the process of folding in the XML files into Mason, the following constraints are required:

1. All numbers must be written as decimals, so instead of a "1", write "1.0"; instead of "2", write "2.0", etc.
2. For powers, use pow(x,y) instead of x^y
3. Remember, variables are complex- so use real(var) for such things as comparisons ("c>0" should be "real(c)>0")

When generating a primitive file based on a collection of primitive files, the following constraints are required:

1. You cannot use S_x_y variables in equations (e.g., S_2_1 = S_1_2 is not allowed because of the S_1_2 term).