Variables / $Parameter

<< Click to Display Table of Contents >>

Navigation:  The graphical user interface > Main Window > ATP menu > ATP Settings Dialog >

Variables / $Parameter


From version 5.9 ATPDraw supports an internal parser (TbcParser) as an alternative to $PARAMETERS and Pocket Calculator (PCVP) of ATP. The following differences apply for Internal Parser:

With the internal parser all data can be changed except extended data in XFMR and BCTRAN components. This applies also to data used in internal calculations (Param flag not used) for instance length in LCC section (_LCC) components, RL, and RLC line models. In LCC, most data can be parametrized with Variables.

6 character limit on all variables (not 5 as with the $PARAMETER implementation).

Period '.' in/after numerical values are not needed.

Nested variables allowed (no error message) but previous values used.

SEQ6 function replaced by SEQS

Different logical operators; =, <, >,<=, >=, <>, &, |, !  instead of  .EQ., .LT., .GT., .LE., .GE., .NE., .AND., .OR., .NOT., respectively. ATPDraw will automatically try to replace the logical operators.

Power operators '^' (preferred) and '**' (replaced by '^')

The special syntax @[ and @FILE are maintained without restrictions on the number of elements, see below.

The ATP is executed separately for each run (KNT = simulation number) so the total simulation time becomes longer. However, multi-core CPUs are utilized and ATP is ran in separate threads and in separate folders (run 2 in folder /1, run n in folder /n-1). A text file with the same name as the ATP-file and with extension '.log' is created with information about the vaues of variables for each run.


Functions of the internal parser:




Two parameter functions:

POW(base, exp), INTPOW(base,exp), MIN, MAX, MOD, LOGN(base, value) , ATAN2(y,x) {atan(y/x) in 4 quadrants}, HYPOT(x,y)=sqrt(x*x+y*y)


Statistical two parameter functions; return random sample from the distribution:

UNIFORM(a,b); f(x)=1/(b-a) for x in [a,b]; returns a floating point value between a and b

UNIFORMI(a,b); f(x)=1/(b-a) for x in [a,b]; returns an integer value between a and b

NORMAL(mu,sigma); f(x)=1/sigma/sqrt(2p)*exp(-0.5*((x-mu)/sigma)^2)

LOGNORMAL(M,sigma); f(x)=1/x/sigma/sqrt(2p)*exp(-0.5*(ln(x/M)/sigma)^2); M=exp(mu)

WEIBULL(scale, shape); f(x)=shape/scale*(x/scale)^(shape-1)*exp(-(x/scale)^shape)


Statistical bounded (from a to b) two parameter functions:

NORMALB(a,b, mu,sigma); f(x)=1/sigma/sqrt(2p)*exp(-0.5*((x-mu)/sigma)^2)

LOGNORMALB(a b, M,sigma); f(x)=1/x/sigma/sqrt(2p)*exp(-0.5*(ln(x/M)/sigma)^2); M=exp(mu)

WEIBULLB(a,b, scale, shape); f(x)=shape/scale*(x/scale)^(shape-1)*exp(-(x/scale)^shape)


Double log-normal distribution:

LOGNORMAL2(a,b,Ib,M1,sigma1,M2,sigma2) where a, b is the range, Ib is the boundary between regions (shielding failure and backflash). M1, sigma1 are for the low region, M2 and sigma2 are for the high region. Related to next CIGRE functions; M1=61.0, sigma1=1.33, M2=33.3, sigma2=0.605. Single parameter set found by setting Ib=b and M1=M2=31.1 and sigma1=sigma2=0.484.


Special distribution functions for lightning amplitudes:

LACIGRE(a b); cfd=0.5*(1+erf(ln(x/61)/sqrt(2)/1.33) for x<20 and 0.5*(1+erf(ln(x/33.3)/sqrt(2)/0.605) and x in [a,b>; a and b in kA, answer returned in A

LACIGRE1(a,b); cfd=0.5*(1+erf(ln(x/31.1)/sqrt(2)/0.484)) and x in [a,b>; a and b in kA, answer returned in A

LAIEEE(a,b); cfd=1/(1+(31/x)^2.6) and x in [a,b>; a and b in kA, answer returned in A


Three parameter function:

IF(bool, true, false); y=IF(x>3, 2, 4) returns y=2 if x>3 otherwise y=4.


Resident variables:

PI, KNT {simulation number; 1, 2...}


The Internal Parser is selected in ATP|Settings/Variables below the number of simulations (or in the Sidebar). The Internal Parser calculates the data values before executing ATP. For multiple runs ATP is thus executed in sequence utilizing multi-threading. On a multi-core machine this option could even be faster than ATP's PCVP sequential method. The Internal Parser will produce a *.log file (same name and folder as the case) that contains information of the actual data sent as parameters for each run. For this feature to work smoothly the user should execute ATP in Hidden mode with the direct method and avoid bat-files (see ATP connection Wizard, F10). Using the Internal Parser, ATP is executed many times and any diagnosis window will pop up and block the computer. For _LCC line length, freq, and rho variations, turn JMarti diagnosis off and for GNU-ATP edit graphics.aux and set NODISK=1.


The component MODELS|WriteMaxMin can be used to track extrema as function of the simulation number. This component will write the extrema (max or min) to the LIS-file and read back the values after the simulations. WriteMaxMin will go into multiple LIS-files in the case of Internal Parser usage. The WriteMaxMin component has a View button for plotting and Copy button to copy the MinOrMax, AsFunctionOf points to the Windows Clipboard. The WriteMaxMin component is used in the Optimization module.

DATA: AsFuncOf - Any variable, if zero the simulation number KNT is used

MaxOrMin - 0=Min, 1=Max

Tlimit - The input is ignored untilT>=Tlimit. Used to typically suppress initial transients

Idx - Unique identifier, set automatically by ATPDraw.

NODE: X. The standard is a single phase input, but this can be changed by the user. The user select the type of input from the Node dialog (as any other Model).



PCVP method (ATP's internal handling of variables)


Variables (using ATP's parser PCVP) was introduced in ATPDraw 3.0. The user is allowed to specify a 5-character text string instead of a data value in the component dialog box. A value is then assigned to this text string under the Variables tag of the ATP settings dialog box. In order to allow a variable for the data value its Param property must be set to unity under Edit Definitions|Data. In cases where the data value is used in calculations in the component (for instance the phase angle of a 3-phase AC source) variables are not allowed and the default value is in such cases used instead. Variables are also allowed for Models. If Number of simulations is larger than unity a POCKET CALCULATOR VARIES PARAMETERS card will be inserted and the simulation is repeated this number of times. The current simulation number is then available as the parameter 'KNT'. Under LIS Suppress the value of IOPCVP is set: 0: No LIS-file suppression, 1: Writes only extreama and parameters, 2: Writes only extrema, 3: Writes just the KNT information. IOPCVP must be zero for the Optimization or the WriteMaxMin module to work.


The text strings (variables) specified by the user appear to the left and the user now has to assign data values for variables. This is done in free format in the column to the right. All the specifications in Variables are declared as intermediate variables and the flag '$$' is automatically added at the end. The variables used in the circuit are then assigned to these variables and ATPDraw automatically adds underscore characters to obtain the maximum resolution. A variable 'RES' used for both high and low precision resistances will thus be declared twice (highest precision declared first) with 13 and 3 underscore characters added, respectively. The intermediate variable is renamed 'RESI'  (character 'I' for intermediate added). This process is hidden, however, but the result is seen in the final ATP file under the $Parameter declaration. You can also define intermediate variables ($$ is automatically added to the value field if the variable is not used in the circuit). Do not use underscore characters in the name of variables.


IMPORTANT! for the PCVP method:

Since only floating point numbers are supported by ATP always use a period '.'  after a number in the value field.


Several special new features are introduced in ATPDraw 5.5p2.


@[a b c d e ... ]

@FILE FileName Col

@LIN Lo Hi

@LOG Lo Hi

@POW Lo Hi P

@EXP Lo Hi P


MyVar=@[a b c d e f g]

First run (KNT=1): MyVar=a  

Second run (KNT=2): MyVar=b


Seventh run and beyond (KNT >=7): MyVar=g


The characters '@[' are used to identify this format. Space or comma can be used to separate the numbers (integer or floating point).

MyVar=@FILE FileName Col

 '@FILE' is the keyword, FileName is the name of a text file assumed stored in the ResultDirectory (same as final ATP file) (enclose the file name within " " if it contains space), and Col is an optional parameter identifying which column in the text file to use.

 The text file can have integer or floating point values in free format space or comma separated:

 34.5, 45.234567 1.23e-3

  2 3, 4

 If Col is not specified the first column of the file is loaded. The length of the file does not need the match the chosen Number of Simulations.

 First run (KNT=1): MyVar=First value of column Col (Col=2 -> 45.234567)

 Second run (KNT=2): MyVar=Second value of column Col (Col=2 -> 3.0)


 Both the '@[' and '@FILE' syntax requires a lot of intermediate variables. They both use the same implementation approach as shown below.

MyVar=@LIN Lo Hi

 '@LIN' is the keyword. Creates a linear space. MyVar=a*(KNT-1)+b

MyVar=@LOG Lo Hi

 '@LOG' is the keyword. Create a logarithmic space.  MyVar=10**(a*(KNT-1)+b)

MyVar=@POW Lo Hi P

 '@POW' is the keyword. MyVar = a*(KNT-1)**P+b    

MyVar=@EXP Lo Hi P

'@EXP' is the keyword. MyVar = a*P**(KNT-1)+b

If P ='e' this is replaced by exp(1)  

a and b are calculated based on Lo and Hi: First run (KNT=1) MyVar=Lo, Last run (KNT=Number of Simulations) MyVar=Hi.

This last last four options could easily be managed directly be the user.


Example of input of variables are shown in the figure below. All variables are declared as intermediate so that referencing is allowed. The variable MYVAR must be declared before RES which must come infront of CAP. The resulting $PARAMETER cards in the ATP file are shown after the figure. The logical summing style below will at some point be replace by the new SELECT feature of ATP's $PARAMETERS introduced in 2011. This will allow a larger number of variables. With the Internal parser mode this syntax, with its restrictions, is not used.





F01001=(KNT.EQ.1.)*2.3 $$                    {Special outcome of the '@[' or '@FILE' specification:

F01002=(KNT.EQ.2.)*4.6 $$                    {Fyyxxx: F=Factor, yy=array number (1-99 supported), xxx=index number (1-999 supported).

F01003=(KNT.EQ.3.)*5.3 $$

F01004=(KNT.EQ.4.)*2. $$

F01005=(KNT.GE.5.)*3.1 $$

MYVARI=F01001+F01002+F01003+F01004+F01005 $$ {In case of more that 9 items, intermediate variables Pyyzzz are introduced

RESI =4.5*MYVARI $$                          {'I' added to 'RES' to mark intermediate variable name

CAPI =12.3/RESI*KNT $$                       {RESI automatically substituted for RES here. KNT=Simulation number 1..5

MODVARI =2.3 $$                              {Simple/Normal value assignment

RES_____________=RESI                        {High precision RES declared first

RES___=RESI                                  {Low precision RES comes next

MODVAR__=MODVARI                             {Model data variable 8-character default resolution, modify the Digits property.

CAP_____________=CAPI                        {High precision capacitance



If you change the names in the left side column this will affect the text strings (variables) specified in the components. You will be request about what action to take. In the example below the user has change the variable RES to R. Thus the variable RES used in some component is now longer assinged. The user now has three options: He can reset the variable RES to zero or the default value (from the support file) or he can choose select parameter and then decide which of the variables MYVAR, CAP, MODVAR to replace RES.