Capitulo 16

All material contained in this documentation is proprietary to Siemens Industry, Inc., Siemens Power Technologies International.

16-1

Chapter 16Program Automation

Chapter 16 - Program Automation

16.1 What is Program Automation?Program automation in PSSE provides the mechanism to control PSSE execution other than bydirect user interaction. This is the ability to define a set of operations for PSSE to perform in a fileof some kind (explained in the following sections) and to tell PSSE to use the instructions in thatfile as a single command. We will call these files Automation Files. There are two primary ways touse Automation Files:

As a program extension. In this case the user, in the course of using the program inter-actively, can decide to select an existing Automation File as the next instruction to theprogram.

For un-attended execution. This is commonly called batch execution. In this case theentirety of the users interaction would be the specification of the source of the instruc-tions for it to execute (although there may be other options specified at the same time).

Although there are a few minor exceptions, for the most part the specification of the instructions, i.e.the contents of the Automation File, is the same in both cases.

The following sections will concentrate on the first alternative. Near the end of the chapter is asection on batch execution. There is also a section on entering single commands; while not aprogram automation method it uses the commands defined here and is best understood in thiscontext.

16.2 Controlling PSSE Execution Using the APIActivity Application Program Interface

An Application Program Interface (API) is a set of callable routines for building software applica-tions. PSSE has a supported, documented API available for use with PSSE. The API is theprimary and recommended method for accessing PSSE functionality for automation. The PSSEAPI is described in PSSE Application Program Interface (API). That manual includes descriptionsof the syntax for using each API routine in each automation method in which it is supported. Notevery API routine is supported in every automation method.

In most cases the API manual will also describe the syntax for calling an equivalent Fortransubroutine.

Program Automation PSSE 33.4Automation Methods in PSSE Program Operation Manual


16-2

Siemens PTI will support users who make use of the API through the automation methodsdescribed here, such as batch commands and Python programs, only. No support is provided

for Fortran or, say, C applications developed by users of PSSE.

16.3 Automation Methods in PSSEActivity Automation Methods

There are six automation processors in PSSE:

An embedded Python interpreter (refer to Section 16.4 Python Programs)

The Batch (or BAT_) Command interpreter (Section 16.5 Batch Commands)

The Line Mode Interpreter (LMI) (Section 16.11 Line Mode Commands)

The PSSE Engineering Basic (PSEB) macro processor (Section 16.14 Building aResponse File, Power Flow Calculation)

The PSSE Simulation Run Assembler (PSAS) macro processor (Section 16.15Building a Response File, Dynamic Simulation)

The IPLAN simulator (Section 16.16 Launching an IPLAN Program File)

Only five file types are available in the GUI, because line mode commands and batch commandscan be intermingled in the same file, so the Response File file type (*.idv) is used for either (or both).

Some general observations are appropriate at this point:

Python and IPLAN are both programming languages, i.e. they can be used to write anykind of a program, not just control PSSE (although IPLANs features are fairly limited,relatively speaking).

IPLAN programs must be compiled (they do not need to be linked). The compiler(called IPLAN) is a Siemens PTI product and supplied with PSSE. The source filesare of file type *.ipl. The result (*.irf) are not object code files in the normal sense, buta unique format.

Python programs are interpreted (one command at a time is executed - no compilationis necessary); although Python does support optional byte-compilation.

PSEB and PSAS commands can also be embedded in Response Files, albeit in a par-ticular context.

Python programs can use existing IPLAN programs and Response Files. The otherautomation methods can all interact with each other.

Response Files, PSAS, and PSEB Command Files are free-format data files.

16.4 Python ProgramsPython is an OSI certified, freely available, object-oriented, interpreted programming language. Itssyntax and usage are well-documented on the web and in numerous publications, so we willconcentrate here solely on its interaction with PSSE.

A Python installer is included in the PSSE program installation package for your convenience. Thelanguage can also be downloaded from the official Python site at http://www.wxpython.org/. Pythonlanguage documentation, extension modules, book recommendations, and user forums are alsoavailable directly from this site. Siemens PTI recommends the following textbooks for reference:

PSSE 33.4 Program AutomationProgram Operation Manual Python Programs


16-3

Learning Python - Lutz and Ascher

Python Essential Reference - Beazley

Programming Python - Lutz

Python in a Nutshell - Martelli

Python Cookbook - Martelli and Ascher

Python Programming on Win32 - Hammond and Robinson

Siemens PTI supports the use of Python programs within PSSE, however, the languageitself is not supported nor maintained by Siemens PTI staff.

The PSSE installation package will also install the following freely available third-party extensionmodules:

wxPython (http://www.wxpython.org//)

win32all (Python Extensions for Windows) (http://sourceforge.net/projects/pywin32/)

Python files can be in source form (*.py, *.pyw) or byte-compiled (*.pyc). Python Files can be usedin PSSE in any of the following ways:

From Run Program Automation File (see Section 16.3 Automation Methods inPSSE)

At program startup by using the -pyfile option (see Section 16.9 Unattended Executionof PSSE)

16.4.1 PSSE Extension Modules For PythonOne of Pythons greatest strengths is its ability to be easily extended. These extensions can bewritten in Python or in system languages (C/C++, Fortran, etc.). Libraries and legacy code can betherefore be made accessible in Python. It is also an excellent transition language in that it cancommunicate with other programs and processes (e.g. Microsoft Excel). Extensions are accom-plished through the creation and use of packages that Python calls modules.

Many extension modules are currently available on the Internet for download including: numericprocessing and optimization, graphic and data visualization (plotting), database connectivity, graph-ical user interface programming, XML and text processing, network programming and connectionsto Microsoft Excel and Microsoft Access.

Your PSSE installation will include the following Python extension modules, documented inPSSE Application Program Interface, that can be imported into user programs inside or outside ofthe PSSE GUI:

excelpy - provides Python functions to interface with Excel; these functions can beused to create, populate and format Excel workbooks from Python.

pssarrays - provides Python functions to retrieve PSSE solution results

pssexcel - provides Python functions to export PSSE data or solution results toMicrosoft Excel spreadsheets.

pssplot - provides access to the PSSPlot API

psspy - provides access to the PSSE API

Program Automation PSSE 33.4Python Programs Program Operation Manual


16-4

Your PSSE installation will also include the following Python extension modules which can also beimported into user programs inside or outside of the PSSE GUI:

bsntools - a set of simple bus name manipulation tools

caspy - provides access to the Saved Case Data Extraction routines (USRCAS)

createusrdll - provides a graphical interface to create a user dll for dynamicssimulation

dyntools - tools for processing channel output files

excelexport - provides a graphical user interface to PSSEXCEL for exporting PSSEresults into Excel spreadsheets.

plot2word - provides a graphical user interface to WORDPY for inserting plot/picturefiles into a Microsoft Word document.

pssgrpg - provides functions intended to be used to supply valves to report nodes onI-line diagrams

redirect - some tools to connect I/O streams between PSSE and Python

sliderPy - provides functions to directly manipulate diagram elements

wordpy - provides Python functions to interface with Microsoft Word; these functionscan be used to create, populate, and format a Microsoft Word document from Python.This is especially useful to insert plot files (*.eps, *.wmf, *.png, etc.) created byPSSPLT/PSSPLOT or any picture file into a Word document.

These modules are fully supported as part of the PSSE program product. There are other Pythonmodules and programs that are supplied with PSSE that either support the above modules or areused by other program features. Modules that are designed as standalone programs (for example,createusrdll) are also supplied. In addition you will find several *.py files supplied in the Exampledirectory for you to use and modify as you see fit.

Each of the modules above provides built-in documentation which can be accessed via the Pythonhelp command. In the case of psspy, however, the result will be too voluminous to be useful. Asummary is available by entering:

help(psspy.psspyc)Help is also available for individual API routines, e.g:

help(psspy.pout)Some features of the psspy module that are not part of the API itself are documented in the docstring for psspy. Enter:

print psspy.__doc__

PSSE 33.4 Program AutomationProgram Operation Manual Python Programs


16-5

16.4.2 The Embedded Interpreter EnvironmentPSSE contains an embedded Python interpreter. This is what allows PSSE to execute Pythonfiles and commands. When the PSSE GUI is started, it initializes the Python interpreter andexecutes a few initial commands. Those commands are:

import syssys.path.append(pathname)import psspyimport pssplotimport os_i=psspy.getdefaultint()_f=psspy.getdefaultreal()_s=psspy.getdefaultchar()import sliderPyimport redirectredirect.py2psse()

(where pathname is a variable containing a value retrieved from the registry; you will generally notneed to be concerned with this)

The os and sys modules are supplied with Python and contain commonly used functions foraccessing operating system features. The psspy, pssplot, and redirect modules are defined above.The use of the _i, _f, and _s variables is explained in the section about default values in PythonFiles, below, and in the PSSE Application Program Interface (API). The redirect.py2psse() func-tion causes Pythons stdin (standard input) to use the function userin from the psspy module(psspy.userin) and Pythons stdout (standard output) and stderr (standard error) to be redirected toPSSEs progress device.

Note in particular that none of the modules are imported into the local name space. That means, forexample, that to use a PSSE API routine defined in the API manual as, say:

ierr = abc()You would need to reference it as:

ierr = psspy.abc()This is in keeping with standard practice for the Python community.

A Python program is shown below that performs the following:

1. Read a PSSE Saved Case file, savnw.sav, into working memory.

2. Solve the power flow.

3. Loop through the buses and print the bus number and area to the Report tab.

psspy.case('savnw.sav')psspy.fnsl((0,0,0,1,1,0,99,0))psspy.inibus(0)

while 1:

ierr,busnum,busname = psspy.nxtbus()

Program Automation PSSE 33.4Python Programs Program Operation Manual


16-6

if ierr!=0: break ierr,busarea = psspy.busint(busnum,'AREA') psspy.report('%s %s' % (busnum,busarea))

One idiosyncrasy of the current embedded interpreter is that results are not automatically echoedto the terminal as they are in the stand-alone Python interpreter. To view the values of expressionsyou must use the print command.

16.4.3 The External Interpreter EnvironmentPython programs that access PSSE functions can be used without starting the PSSE GUI.Python is installed with its own command line interpreter, its own integrated Development Environ-ment (IDE) - called IDLE -, and programs can be written to create their own GUIs. Any of these canuse the PSSE supplied extension modules shown above.

In order to use the PSSE supplied extension modules in this way, you must first make sure thatthe Python import path can find all the modules by name, and that the windows load path can findany required DLLs. The following example replicates the environment in the embedded interpreterexplained in the preceding section:

>>> import os,sys>>> sys.path.append(r"C:\Program Files\PTI\PSSE33\PSSBIN")>>> os.environ['PATH'] = r"C:\Program Files\PTI\PSSE33\PSSBIN;"

+ os.environ['PATH']>>> os.chdir(r"C:\work_dir")>>> import psspy>>> import redirect>>> _i=psspy.getdefaultint()>>> _f=psspy.getdefaultreal()>>> _s=psspy.getdefaultchar()>>> redirect.psse2py()>>> psspy.psseinit(80000)

This example assumes the standard PSSE installation location, and a starting bus size of 80000.Other values could have been chosen. Other techniques could be used as well. For example, if thePYTHONPATH and PATH variables already contained the PSSBIN directory, then they would notneed to be set here. If the current directory was to be the working directory then that statementwould not be necessary, either. The only absolutely critical statements are the import psspy andthe call to psseinit.

The import of pssplot is omitted in the example above because its functions depend on the PSSEGUI and cannot be used in this mode. There are some graphics functions in psspy for which this istrue as well.

16.4.4 The Embedded Interpreter VersionFor PSSE versions 31, 32, and 33 the standard interpreter supplied for python has incompatiblewith the PSSE GUI. As a result we have supplied a rebuilt copy of the interpreter that is installedwith PSSE. When you run the GUI, you are using this rebuilt interpreter. When you use theexternal interpreter, you are running the native installed version.

For most uses you will see no issues. However, certain third party modules (which ones is very diffi-cult to predict) will not load in the GUI for the same incompatibility reasons.

PSSE 33.4 Program AutomationProgram Operation Manual Batch Commands


16-7

Starting with release 33.4.0, a new command line switch has been supplied to allow you to run anyof several versions of Python with PSSE, including the native interpreter for 2.7, the version thatwe supply a rebuilt copy of. Through some internal conversions that we have developed, most ofthe original problems have been avoided. If you specify no command line switch then you will stillget the rebuilt interpreter. The shortcut in the Start Menu will specify -pyver 27.

16.5 Batch CommandsActivity Batch Commands

Batch commands are free-format forms of inputs to the PSSE API. What this means is best illus-trated by an example.

Lets say there is a PSSE API routine called abcd. It takes an integer argument (IVAL), a two-element integer array (IDATA) and returns a floating-point value and an integer return code. Thebatch command syntax for this hypothetical API routine would be:

BAT_ABCD IVAL IDATA(1) IDATA(2)In other words, three integers after the command name that correspond to the arguments IVAL, thefirst element of IDATA and the second element of IDATA, respectively. The returned values are notrepresented. Furthermore, if the function of the API routine was only to return those values, thenthere will not be a batch command syntax defined for it. The reason for this is that the batchcommands are not a language; there are no variables or logic controls. A batch command is reallydata to the batch command interpreter, which then calls the indicated API routine with the inputvalues defined after the command name.

The format of the batch commands is the same as the standard free-format rules used for allPSSE data files. The following additional rules apply to batch commands, though:

The command name itself is case insensitive, i.e. it doesnt matter whether you useupper case or lower case letters, or mix them (the documentation will always definethem as all upper case).

The commands may be continued on multiple lines. The interpreter keeps reading datauntil all the arguments that it needs for a given API routine are satisfied.

There is a special token, a semi-colon, that can be used to tell the interpreter that itshould return all remaining inputs to default settings for that particular API routine. Itmust be a separate token, not part of the previous value. In our example above,

BAT_ABCD 1 34 ;will reset the third value to the default value, but

BAT_ABCD 1 34;will return a syntax error because 34; is not a valid integer.

Batch commands can be used in Response Files or entered as Command Line input.

16.6 RecordingActivity Recording

The PSSE interface is capable of recording PSSE API commands. Recorded API commandscan be in the form of either Python statements or batch commands (Response File) depending ona specified user option. The easiest way to record a Python script (*.py, for Python statements) ora Response File (*.idv, for batch commands) for later execution is to use the I/O Control>Start

Program Automation PSSE 33.4Argument Passing Program Operation Manual


16-8

Recording option. Selecting this option will start the recorder. The entry of subsequent selectionsof PSSE commands will record the API routines used to an automation file for later use until theI/O Control>Stop Recording option is selected.

As an example, suppose you wanted to print power flow results to the Report View for buses 101,201, 205, 154, and 3001. To record these interactions:

1. Select I/O Control>Start Recording and select the type of file you wish to record: Python File (*.py) or Response File (*.idv).

2. Specify, say, busout.idv or busout.py as the filename depending on your selection of file type in Step 1, and open it.

3. Select File>Open, select savnw.sav, and open it.

4. Select Power Flow>Solution>Solve. The power flow solutions dialog is displayed. Solve it and then close it.

5. Select Power Flow>Reports>Bus based reports. The bus based reports dialog is displayed. Enter buses 101, 201, 205, 143, 3001 in the text box provided. Select Go and then close it.

6. Select I/O Control>Stop Recording.

Using a text editor, open the file busout.idv (Figure 16-1) or busout.py (Figure 16-2) and you will seethe following:

Figure 16-1. Response File Recorded by PSSE

Figure 16-2. Python File Recorded by PSSE

16.7 Argument PassingActivity Argument Passing

Arguments can be passed to a response file by using the Arguments button located on the[Select Program Automation File to Run] dialog.

Arguments can be passed to the following types of automation files:

Python files Response files IPLAN files

but how they are handled by each varies. Note that the dialog permits specifying arguments forPSAS and PSEB files, but those languages have no facility for retrieving the argument values.

@! File:"C:\Program Files\PTI\PSSE31\EXAMPLE\busout.idv", generated on TUE, AUG 17 2004 15:41BAT_CASE,'C:\Program Files\PTI\PSSE31\EXAMPLE\savnw.sav'BAT_FDNS,0,0,0,1,1,0,99,0BAT_BSYS,1,0,0.0,0.0,0,5,101,201,205,154,3001,0,0BAT_POUT,1,0

# File:"C:\Program Files\PTI\PSSE31\EXAMPLE\busout.py", generated on WED, AUG 18 2004 15:13psspy.case(r"""C:\Program Files\PTI\PSSE31\EXAMPLE\savnw.sav""")psspy.fdns([0,0,0,1,1,0,99,0])psspy.bsys(1,0,[0.0,0.0],0,[],5,[101,201,205,154,3001],0,[],0,[])psspy.pout(1,0)

PSSE 33.4 Program AutomationProgram Operation Manual Argument Passing


16-9

16.7.1 Arguments in Python FilesThe list argv in the module sys can be used to access the program arguments. Consider thefollowing Python program named arg0.py:

import sysprint sys.argv

When run using the Python interpreter from a Command Prompt the input is assumed to be spacedelimited and is parsed into separate values, e.g.:

Enter:

python arg0.py a list of wordsand the following is displayed:

['arg0.py', 'a', 'list', 'of', 'words']From within PSSE the input string is entered as a single argument. If the file arg0.py is selected(say, in the root directory of the C drive) and the string a list of words is entered in the argumentstring dialog box, the following will be displayed at the Progress tab:

Executing Python file:C:\LocalDocs\dev\testing\arg0.py['C:\\arg0.py', 'a list of words']

16.7.2 Arguments in Response FilesThe argument string is parsed according to the standard PSSE free-format input rules for strings.Arguments in the Response File are then replaced by simple string substitution. If an argumentcontains a blank, comma, or slash, the argument must be enclosed in single quotes; otherwise thequotes are optional.

A Response File that is receiving arguments has the appropriate argument, less any surroundingquotes, substituted by the input processor before the dialog input line is passed to PSSE itself.Arguments replace argument designator strings, which are of the form %n%, where < n > is one ofthe numbers 1 through 15. Any recording of input lines contains the argument values in place of theargument designator strings. A Response File may pass an argument that it receives to anotherResponse File, which it, in turn, initiates. It is usually good practice to place such argument desig-nators in quotes so that a single argument that contains blanks and/or commas not be interpretedby the designated Response File as multiple arguments.

An example of an argument would be %1%, which could appear anywhere in the file. In this case%1% would be replaced by the first value parsed from the argument string. Likewise %5% wouldbe replaced by the fifth value parsed from the argument string.

Response Files require that all arguments receive values. When a Response File references anargument that was not passed to it at the time it was initiated, an error condition occurs A usefultechnique is to document all arguments referenced in a Response File using the TEXT commandat the beginning of the Response File. This approach will help detect missing argument errorsbefore any lengthy computations specified in the Response File are performed.

The following are examples of specifying arguments to a response file that can be entered in thecommand line:

@INPUT , filename , 'argument 1' , 'argument 2' ... 'argument 15'

Program Automation PSSE 33.4Default Values Program Operation Manual


16-10

or:

@CHAIN , filename , 'argument 1' , 'argument 2' ... 'argument 15'

16.7.3 Arguments in IPLAN FilesThe entire argument string is placed in a buffer. The IPLAN command ARGUMENT can then beused to parse the string in any way - and repeatedly - using the standard PSSE free-format inputrules. Refer to Section 3.27 Program Arguments of the IPLAN Program Manual.

16.8 Default ValuesActivity Default Values

Many of the statements in automation files specify data for which defaults exist. The idea of a defaultvalue is one that is simply not specified. Typically this means that either some function or actionassociated with that value is ignored, or a specific documented value is used; that specific valuemight be a fixed value - say, zero - or the current value of some quantity in the network case or aprogram setting.

While it is possible in some programming languages for a value to be missing, the general case isthat in order to indicate this situation a special value is used. When input values are omitted in auto-mation files such special values are substituted for them. The various API routines check for thespecial values and take appropriate default actions when they are encountered.

Currently spaces and false are used for filenames and logical values when they are omitted. Thespecial values for integers, real numbers (floats), and characters (strings) are returned from the APIroutines GETDEFAULTINT, GETDEFAULTREAL, and GETDEFAULTCHAR. No assumptionsshould be made that these precise values will be identical from one release of the PSSE toanother. If it is necessary to acquire these values, always run the API routine to get the currentvalues.

Default values can be specified in references to API routines in Python Files. Data items can beomitted in Response Files. The concept of default values does not apply to IPLAN programs ingeneral, but there are some functions that take optional arguments, and because PUSH statementscan contain anything that could be in a Response File, any comments about Response Files willapply there. All data values are required in PSEB and PSAS files, unless the syntax specifically indi-cates otherwise.

16.8.1 Defaults in Python FunctionsThe Python language provides an easy mechanism for permitting optional arguments to functions.However it requires that each function be coded in such a way as to permit this. Not every one is.All the functions in the psspy module are coded in this way. For other modules delivered withPSSE please check the help facility.

16.8.2 Defaults and Keywords in Module psspyAll arguments to functions defined in module psspy may be omitted and default values will besupplied. All arguments to functions defined in module psspy may be specified by keyword.

In addition psspy contains a unique feature for specifying values for specific elements in an inputlist. This is best illustrated by example. Lets say a function mysub takes a single argument, opt,which is a 2-element list of integers, then the following are equivalent:

PSSE 33.4 Program AutomationProgram Operation Manual Unattended Execution of PSSE


16-11

mysub([_i,1])mysub(opt=[_i,1])mysub(opt2=1)mysub(opt=None,opt2=1)mysub(opt=[_i,42],opt2=1)mysub(opt2=1,opt=[_i,352])mysub(opt1=_i,opt2=1)

where _i is a variable equal to the default integer value.

What this means is that all the functions in psspy recognize special keywords formed by concate-nating any input list name and the string representation all the possible index values (starting at 1)and will use them to override just that specific element of the list.

16.8.3 Defaults in Recorded Python FilesWhen recording is enabled and the Python format is chosen, values for all arguments are specified.Where default values are recorded, actual values are used except for the following:

in place of default integer values, the variable _i is used.

in place of default float values, the variable _f is used.

in place of default string values (not filenames) the variable _s is used.

This will work directly inside of the PSSE GUI because those variable are automatically assignedthe appropriate values at program startup. This is why the statements

_i=psspy.getdefaultint()_f=psspy.getdefaultreal()_s=psspy.getdefaultchar()

are recommended in Section 16.4.3 The External Interpreter Environment.

16.8.4 Defaults in Response FilesBecause Response Files are simply free-format data files, an input value can be omitted by twocommas either together or separated by only spaces.

For batch commands there is a special token, a semi-colon, that can be used to tell the interpreterthat it should return all remaining inputs to the default settings (see Section 16.5 Batch Commands).

Files containing recorded batch commands will use consecutive commas for default values speci-fied to the API routine.

16.9 Unattended Execution of PSSEActivity Unattended Execution of PSSE

In some cases, it may be desirable to run PSSE in batch mode, that is, without any user interface.PSSE provides command line options that can be used for this purpose. In Section 16.9.1 Start-up Commands provides a list of all the available command line options; these four specificallypertain to this purpose:

-rspfile -pyfile -argstr -embed

Program Automation PSSE 33.4Unattended Execution of PSSE Program Operation Manual


16-12

note that the initial - is part of the command

-rspfile, -pyfile, and -argstr all expect to be followed by a string

-pyfile will be ignored if -rspfile is specified

-argstr and -embed will be ignored if neither -rspfile nor -pyfile are specified

the command line is blank delimited; if the string specified to -rspfile, -pyfile, or -argstrcontains a blank then the string must be quoted

if the same option is specified more than once, only the last one will be used

notwithstanding the previous point, the order of the options is unimportant

the string value for the -argstr option is the argument string (see Section 16.7 ArgumentPassing)

Provision is made for specifying only Response Files or Python Files. Both of those file types canuse other types of Automation Files so, indirectly at least, any type can be used.

The -embed option has the effect of suppressing the display of the PSSE GUI. If the AutomationFile terminates without stopping the execution of PSSE the GUI will be displayed at that time.

The following are a few points to be aware of when preparing to run PSSE in an unattended mode:

PSSE does not read input from stdin or write to stdout, so pipes cannot be used forbatch execution of PSSE.

Be aware of the nature of the operating system tool you are using to start PSSE. InMicrosoft Windows, for example, non-console application programs, such as PSSE,are executed asynchronously. This means that should you have a batch file that startsPSSE it will not wait for the program to stop before continuing on the next statementin the batch file.

When running in batch mode (i.e. with a startup automation file specified that stops theprogram) the Progress tab and Report tab output should be re-directed to a printer orfile, otherwise output will be sent to windows that would be closed when the programstops.

PSSE 33.4 Program AutomationProgram Operation Manual Running a Python Program


16-13

Here are some examples of starting PSSE from a Command Prompt:

psse33 -rspfile busout.idvpsse33 -pyfile busout.pypsse33 -pyfile busout.py -embedpsse33 -embed -pyfile "study number 2.py" -argstr 101

Appendix D - Command Line Options contains a complete list of all the command line options thatare available.

16.10 Running a Python Program

Python programs run in this manner execute in the embedded interpreter environment as describedin Section 16.4.2, The Embedded Interpreter Environment. All code runs in that local namespaceand can therefore be impacted by previous Python programs, or affect subsequent Pythonprograms. Specifically, local variables retain their bindings (values) for the entirety of the executionof PSSE. Use Modules, Classes, or functional programming techniques to create independentnamespaces.

Pythons interaction with PSSE is strictly through the API. PSSE functions can be executed, anddata can be retrieved from PSSEs working memory. API routines are provided to run ResponseFiles and IPLAN programs from within a Python program, so the other automation methods are inte-grated with Python in this way, and functionality that was developed using this other methods, whichall predate Pythons introduction into PSSE, is preserved and can be used with minimal rework.

16.11 Line Mode CommandsThe line mode was the primary method of controlling PSSE through rev 29 (and the only methodthrough rev 18). It was highly efficient, very thorough, but completely procedural. It was essentiallya question-and-answer session with a program that began with the question:

Activity?The appropriate response to this question was any of about 170-180 (in the last few releases) activ-ities that comprised the primary functions that PSSE could perform. Each activity name was fourcharacters long; most could be abbreviated. Some activities could accept optional suffixes whichmodified their behavior somewhat. Almost all would then ask a series of questions, unique to eachactivity, to which the user would respond to operate the program. Many of those activity names arepreserved today in API routines that perform similar functions.

Run Python Program - GUI

I/O Control>Start recording

[Select Program Automation File to Record]

Python file (*.py)

Interrupt Control Codes

None

Program Automation PSSE 33.4Line Mode Commands Program Operation Manual


16-14

Line mode commands can be used to automate PSSE through Response Files (*.idv), so calledbecause they contain responses to the questions that the command line of PSSE asks.

The modern GUI has replaced this previously common method of operation, but there is a wealthof existing Response Files containing line mode commands used to automate PSSE. ThereforePSSE currently contains a feature called the Line Mode Interpreter (LMI) - a new program writtento imitate the traditional line mode of PSSE, but that actually uses the PSSE API. In a way it isa translator from line mode to batch commands. It is not a perfect imitation, and those differencesare captured in PSSE Command Line Interface (CLI) Users Guide, Appendix A.

It is worth noting that, although the line mode now comprises a subset of the full functionality ofPSSE, for those functions it can perform, and for those users who are thoroughly familiar with thecommand line (and are good typists), the program can still be operated more quickly from thekeyboard than is physically possible with a point-and-click interface (i.e., a mouse). So whilecommand line capabilities are not likely to be enhanced in the future, its current operation is consid-ered to be an important feature of the program.

16.11.1 Mixing Line Mode and Batch CommandsResponse files can contain both line mode and batch commands. The batch commands can bethought of as additional activities of the line mode. They are not, and they are handled very differ-ently; but for purposes of understanding how they may be combined in the same file, that imageprovides the guidelines that need to be followed.

The format of the line mode commands also conforms to the PSSE standard free-format rules

16.11.2 Immediate CommandsThe line mode has been augmented over the years with a set of Immediate (@) Commands, socalled because their actions occur without the involvement of any of the API routines in PSSE.They are functions of a utility library (a Siemens PTI product) that is used by PSSE but separatelymaintained. Immediate Commands can also be mixed with line mode and batch commands. Unlikebatch commands, however, they can be used anywhere, even in the middle of a series of responsesto a particular activity using the command line. The following list is provided for convenience:

@CHAIN filename - Open the specified file as a chained response file.

@INPUT filename - Open the specified file as a nested response file.

@PAUSE - Temporarily suspend response file operation.

@CONTINUE - Resume PAUSEd response file operation.

@END - Close the current response file.

@SYSTEM command - Issue a designated operating system specific command

@RELEASE - display the PSSE release number and date, along with similar information about selected subsystems.

@DONGLE - display time used statistics for time lock users

@! - Ignore the entire line.

The last one, @!, will work from any input file. The others are only recognized from terminal input,such as a Response File.

PSSE 33.4 Program AutomationProgram Operation Manual Running a Response File


16-15

16.11.3 VersionThe LMI provides an additional feature that the original line mode did not - the ability to changeversions. As releases of PSSE come out, sometimes changes are necessary in the sequence ofline mode commands. The creates maintenance work for existing Response Files. The LMIprovides a command, VERSION, which displays or sets the version of the line mode languagebeing processed. Introduced at rev 31 of PSSE, it recognizes versions from rev 30 and newer, forexample:

VERSION 30 - sets the version to rev 30VERSION 31 - sets the version to rev 31etc.

VERSION - displays the current version

16.12 Running a Response FileIDEV

Executing activity IDEV in Line Mode should be considered an obsolete capability which is retainedfor backward compatibility purposes. Activity IDEV itself is not sensitive to any interrupt control codeoptions. While one or more Response Files are active, the CL interrupt control code may be usedto close all open Response Files.

16.12.1 Application Notes The Response File must contain PSSE Batch Commands and/or an exact image of the Line Modeuser responses which would normally be entered by the user from the Command Line and/or Imme-diate Commands. Therefore, the manual creation of a Response File, which is done with the texteditor, requires an intimate familiarity with these commands, particularly for dialog intensive Line

Run Response File - GUI

I/O Control>Run Program Automation file

[Select Program Automation File to Run]

Response file (*.idv)

Run Line Mode Activity IDEV - CLI

ACTIVITY?>>IDEV

Immediate Commands - CLI

@ input filename

OR

@ chain filename

Python Command

psspy.runrspnsfile Interrupt Control Codes

None

Program Automation PSSE 33.4Recording User Actions Program Operation Manual


16-16

Mode activities such as CHNG and ALTR.

16.13 Recording User ActionsActivity ECHO

The dialog echoing activity ECHO enables the writing of all subsequent user dialog input to a desig-nated file, which may subsequently be used as a Operation of activity ECHO.

Users of PSSEs traditional command line interface will be familiar with the activity ECHO. Itperforms a function similar in effect to the recording function in the current program. It is a verydifferent thing, however, and a remnant of it remains.

ECHO copies terminal input to a file. Because all PSSE input in a console application either camefrom a terminal or a device that imitated the terminal, that meant all (interactive) input. This capa-bility is retained in the PSSECMD console application.

The current recording function is a feature of the API routines. When they are called, if recording isenabled, they record a copy of their input in the designated format in the designated file; it doesntmatter how the call occurred - by menu selection, through line mode, from an automation file, etc.

The ECHO function still exists in the GUI, and it still does the same thing, i.e. copies all terminalinput to a file. The difference is that there is very little terminal input. The API routine userin, theIPLAN function INPUT (and INPUTLN), and the @pause immediate command all attempt to readfrom the terminal, which is handled in via a pop-up window. So data entered there will show up inan ECHO file.

Related to this is the traditional command line activity IDEV, meaning Input DEVice. IDEV was usedto replace the terminal with a file so that subsequent READs from the terminal would find theresponses in the file (hence the name Response File). IDEV never executed the commands in aResponse File, although that appeared to be the situation. The implementation of IDEV in the GUIdoes what most people would expect, therefore; it causes the commands in the Response File tobe interpreted by the LMI. This means, however, that IDEV no longer runs the way it used to, i.e.replaces terminal input with a file. That function is now performed by the API routineSET_INPUT_DEV. The outcome of that API is opening a file to respond to input requests from the

Additional Information

PSSE GUI Users Guide, Section 23.2.1, Response FilePSSE Command Line Interface (CLI) Users Guide,

Section 19.2, Assigning Interactive Input to a Response File

Run Line Mode Activity ECHO - CLI

ACTIVITY?>>ECHO

Interrupt Control Codes

None

PSSE 33.4 Program AutomationProgram Operation Manual Recording User Actions


16-17

terminal (except @pause which will still force an actual terminal read, handled via a pop-upwindow).

When activity ECHO is initiated, if a file for capturing responses had previously been opened withan earlier execution of activity ECHO, it is closed.

Program Automation PSSE 33.4Building a Response File, Power Flow Calculation Program Operation Manual


16-18

16.13.1 Application NotesWith a console application like PSSECMD the file built as a result of activity ECHO can be used asa PSSE Response File with @INPUT or @CHAIN or IDEV command to exactly reproduce asequence of PSSE activity commands and responses to instructions. Files written by activityECHO are source files which may be modified with the text editor (e.g., to specify different faultedbuses, switched branches, Saved Case and Snapshot File names, and so on) to tailor the originalset of user responses to the application at hand.

Activity ECHO copies to the designated file those user inputs that are entered into PSSE as partof the interactive dialog. In addition, whenever a PSSE bulk data input activity is reading data fromthe dialog input device (rather than from a bulk data input file), these data records are also recordedin the file. This applies to activities such as READ, Reading Power Flow Data Additions from theTerminal, RESQ, TRSQ, MCRE, and PSAS.

16.14 Building a Response File, Power Flow CalculationActivity PSEB

The power flow run assembler activity PSEB allows the user to specify routine power flow runs inan English-like language. Input to activity PSEB is taken either from a PSEB Command File or fromthe dialog input device. This can be in-stream in a Response File, typed into the command line inthe GUI, or entered at the console in PSSECMD. The output from activity PSEB is in the form of aPSSE Response File.

16.14.1 PSSE PSEB Macro LanguagePSEB (PSSE Engineering Basic) is a built-in macro language that supports PSSE Power Flowoperations through the use of English-like command macros. PSEB commands are created withina text file using a text editor. Each record is in the form of a command starting with a verb from a

Additional Information

PSSE Command Line Interface (CLI) Users Guide,Section 19.3, Recording User Actions

Run Activity PSEB - GUI

I/O Control>Run program Automation file


PSEB Command file (*.pse)

Run Line Mode Activity PSEB - CLI

ACTIVITY?>>PSEBENTER INPUT FILE NAME (0 TO EXIT, 1 FOR TERMINAL):

>>Interrupt Control Codes

None

PSSE 33.4 Program AutomationProgram Operation Manual Building a Response File, Power Flow Calculation


16-19

previously defined vocabulary. The PSEB commands are documented below and in the PSEBUsers Ready Reference.

PSEB commands do not interact with PSSE directly. The PSEB macro processor is really a trans-lator from the PSEB language to a Response File, which may contain a mixture of command lineand batch commands. The PSEB command line command normally automatically performs thecommands in the Response File after the translation. When used with the suffix CHECK (i.e. PSEB,CHECK) only the translation is performed. When using the PSEB API routine only the translation isperformed.

Each PSEB command begins with a verb from the vocabulary recognized by activity PSEB. Somecommands require additional keywords (e.g., BUS, BRANCH), numeric quantities (e.g., busnumber, load MW), and/or character identifiers (e.g., bus name, circuit identifier) in specific fields ofthe command format. Some commands provide for the optional specification of keywords, numeric,and/or character quantities; these are shown in the command syntax enclosed in braces ([ ]).

Where one of several keywords may be specified, they are shown in the command format enclosedin vertical bars (| |). One of the keywords listed must be entered in the field.

Each keyword or data value must be followed by one or more blanks. For clarity, a comma or equalsign may be used in place of, or in addition to, a blank space. For example, the following two PSEBcommands are equivalent:

OPEN TIE FROM BUS 153 TO BUS 154 CKT 2 OPEN TIE, FROM BUS = 153, TO BUS = 154, CKT = 2

Any field labeled bus id designates that a bus identifier is to be entered. When the numbers inputoption is in effect, the bus number must be specified; using the names input option, the extendedbus name enclosed in single quotes is required.

Any field labeled dc id designates that a two-terminal dc line name is to be entered. If the namecontains any blanks or special characters, it must be enclosed in single quotes.

I and R indicate that integer and real (i.e., it may include a decimal point) numeric values respec-tively are to be specified.

Many PSEB commands provide for the insertion of optional descriptive text in designated fields,indicated by [n] in the command syntax. For example, the following two PSEB commands translateinto the same PSSE dialog:

RECOVER FROM SAVNW.SAV RECOVER saved case FROM SAVNW.SAV

A dollar sign ( $ ) at the end of a PSEB command line is used to continue the command on thefollowing line. At least one space must precede the dollar sign. As many physical lines as requiredmay be used to specify a single PSEB command as long as all lines except the last one are termi-nated with a dollar sign. This multiline capability may be used with all PSEB commands except theUSE command (see below). In addition, each PSSE activity command and response to an instruc-tion entered in passthru mode (see below) must be entered on a single line.



16-20

16.14.2 PSEB CommandsThe detailed syntax of each PSEB command is given below and also on the PSSE EngineeringBasic PSEB Users Ready Reference sheet. Keywords shown in uppercase letters must be enteredas shown in either upper or lowercase characters.

HOLD [n] IN (saved-case-filename) [NOW]

The HOLD command is used to preserve the power flow working case in the designated Saved Case File; refer to Section 5.45 Creating a Saved Case File. When the HOLD command includes the optional keyword NOW, activity SAVE is immediately executed. In this case, the PSSE responses for activity SAVE are not written to the Response File being constructed by activity PSEB.

When the HOLD command does not include the optional keyword NOW, the appropriate entries in the Response File are made to save the working case during the subsequent execution of the Response File.

RECOVER [n] FROM (saved-case-filename)

The RECOVER command is used to access the designated Saved Case File; refer to Section 5.1 Retrieving a Power Flow Saved Case File. Activity CASE is executed immedi-ately and the PSSE responses for activity CASE are written to the Response File being constructed by activity PSEB. Note that the RECOVER command overwrites the working case. The HOLD command with the NOW option may be used before the RECOVER command to save the working case.



16-21

|MW | |MWP | |MWI |

|ALTER | |MWY | [ |MW | ] |CHANGE| |MVAR | LOAD [n] BUS (bus id) [LOAD (id)] TO (R) [ |MVAR| ]

|MVARQ| |MVARI| |MVARY|

This form of the ALTER command is used to change a specified component of a designated load at a designated bus to a specified value. If the optional load identifier tokens are omitted, a load identifier of 1 is assumed. The second token specified indicates the compo-nent of load as follows:

The value specified is always in MW or Mvar at unity voltage. Refer to Load Data.

SHED LOAD [n] BUS (bus id)

The SHED command is used to set all loads at the specified bus out-of-service. Refer to Load Data.

|MW ||ALTER | |MWG | [|MW |]|CHANGE| |MVAR | SHUNT [n] BUS (bus id) [SHUNT (id)] TO (R) [|MVAR|] |MVARB|

This form of the ALTER command is used to change a specified component of a specified fixed shunt at a designated bus to a specified value. If the optional shunt identifier tokens are omitted, a shunt identifier of 1 is assumed. The second token specified selects either the active (MW or MWG) or reactive (MVAR or MVARB) component of bus shunt. Values entered are in MW or Mvar at unity voltage. The reactive component is specified as a nega-tive quantity for an inductive load. Refer to Fixed Bus Shunt Data.

|ALTER ||CHANGE| BUS (bus id) CODE TO (I)

This form of the ALTER command is used to change the bus type code of a designated bus. Refer to Bus Data.

MW, MWP Active power component, constant power characteristic.MWI Active power component, constant current characteristic.MWY Active power component, constant admittance characteristic.MVAR, MVARQ Reactive power component, constant power characteristic.MVARI Reactive power component, constant current characteristic.MVARY Reactive power component, constant admittance characteristic; R is

negative for an inductive load.



16-22

|ALTER | |R| [|CKT | ]|CHANGE| |X| TO (R) [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT| (id)]

|B|

This form of the ALTER command is used to change the per unit resistance, reactance or charging of a designated non-transformer branch or two-winding transformer to a specified value. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. Refer to Non-Transformer Branch Data.

DROP PLANT [n] BUS (bus id)

This form of the DROP command is used to disconnect all generation at a specified bus. The bus type code is set to one; refer to Bus Data and Section 5.9.1 Equipment Status Changes.

RECONNECT PLANT [n] BUS (bus id)

This form of the RECONNECT command is used to reconnect generation at a specified bus. The bus type code is set to two; machine status flags are not changed. Refer to Bus Data, Generator Data, and Section 5.9.1 Equipment Status Changes.

|UNIT | DROP |GENERATOR| (id) [n] BUS (bus id)

|MACHINE | |LOAD ||SHUNT |

This form of the DROP command is used to disconnect a specified machine, load, or fixed shunt at a designated bus. The machine, load, or shunt status flag is set to zero; refer to Load Data, Fixed Bus Shunt Data, Generator Data, and Section 5.9.1 Equipment Status Changes.

|UNIT |RECONNECT |GENERATOR| (id) [n] BUS (bus id)

|MACHINE ||LOAD ||SHUNT |

This form of the RECONNECT command is used to reconnect a specified machine, load, or fixed shunt at a designated bus. The machine, load, or shunt status flag is set to 1; the bus type code is not changed. Refer to Bus Data, Load Data, Fixed Bus Shunt Data, Gener-ator Data, and Section 5.9.1 Equipment Status Changes.

DISCONNECT BUS (bus id)

This form of the DISCONNECT command is used to electrically disconnect a bus and all equipment connected to it. This command results in the use of activities DSCN and ORDR.

|DISCONNECT| |LINE | [|CKT | ]|TRIP | |TIE |[n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT| (id)]|OPEN | |BRANCH|

This form of the DISCONNECT command is used to remove a specified branch from service. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. The branch status flag is set to zero; refer to Non-Transformer Branch Data and Section 5.9.1 Equipment Status Changes.



16-23

|RECONNECT| |LINE | [|CKT | ]|CLOSE | |TIE | [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT|(id)]|RECLOSE | |BRANCH|

This form of the RECONNECT command is used to return a specified branch to service. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. The branch status flag is set to 1; refer to Non-Transformer Branch Data and Section 5.9.1 Equipment Status Changes.

|DISCONNECT| [|CKT | ]|TRIP |THREEWINDING [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT| (id)]|OPEN |

This form of the DISCONNECT command is used to remove all windings of a specified three-winding transformer from service. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. The transformer status flag is set to zero; refer to Trans-former Data and Section 5.9.1 Equipment Status Changes.

|DISCONNECT| [|CKT | ]|TRIP |THREEWINDING [n] AT [n] BUS (bus id) TO [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT| (id)]|OPEN |

This form of the DISCONNECT command is used to remove the winding connected to the bus specified as the AT bus of a specified three-winding transformer from service. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. The trans-former status flag is set to 2, 3 or 4; refer to Transformer Data and Section 5.9.1 Equipment Status Changes.

|RECONNECT| [|CKT | ]|CLOSE |THREEWINDING [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) TO [n] BUS (bus id) [|CIRCUIT| (id)]|RECLOSE |

This form of the RECONNECT command is used to return all windings of a specified three-winding transformer to service. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. The transformer status flag is set to 1; refer to Transformer Data and Section 5.9.1 Equipment Status Changes.

BLOCK DCLINE (dc id)

The BLOCK command is used to block a specified two-terminal dc line. The control mode is set to zero; refer to Two-Terminal DC Transmission Line Data.

UNBLOCK DCLINE (dc id)

The UNBLOCK command is used to unblock a specified two-terminal dc line. The control mode is set to 1 (i.e., the UNBLOCK command assumes power control mode). Refer to Two-Terminal DC Transmission Line Data.

|SETPOINT| SET DCLINE (dc id) |SCHEDULE| TO (R)

This form of the SET command is used to change the current or power demand (SETPOINT) or scheduled dc voltage (SCHEDULE) on a specified two-terminal dc line to a designated value; refer to Two-Terminal DC Transmission Line Data.

SET LOADFLOW TITLE LINE |1| TO (title)|2|

This form of the SET command is used to change the designated line of the two-line case heading to a specified string. The title may be up to 60 characters and must be enclosed in single quotes; refer to Case Identification Data.



16-24

|BUS |NET GENERATION [n] |BUSES| (bus id) [(bus id)...[(bus id)]]

This form of the NET command is used to net the generation with the load at specified buses; refer to activity GNET. Up to 25 buses may be specified in each use of this command.

NET GENERATION [n] FOR BUSES (I) THRU (I)

This form of the NET command is used to net the generation with the load at all buses within a specified bus number range; refer to activity GNET. This command is valid only when the bus input option is in its numbers setting.

SET SOLUTION OPTION[S] TO DEFAULT

This form of the SET command is used to instruct activity PSEB that subsequent SOLVE commands (see below) are to execute power flow solutions with the present power flow solution adjustment option settings honored. Refer to Sections 3.3.3 and 6.3.20 and activity OPTN.

SET SOLUTION OPTION[S] TO [|DISCRETE-TAP|],[|AREA-LOCKED|],[FLAT-START],[|DC-LOCKED|],[|SHUNT-LOCKED|],[|PHASE-SHIFT |][|DIRECT-TAP |] [|AREA-INTCHG|] [|DC-ADJUST|] [|SHUNT-ADJUST|] [|PSHFT-LOCKED|][|TAP-LOCKED |] [|TIES+LOADS |] [|SHN-ADJ-CONT|]

This form of the SET command is used to enable and/or disable the power flow adjustments to be used on subsequent power flow solutions initiated with the SOLVE command (see below). For any adjustment option not specified, the present program option setting is honored. Refer to Sections 3.3.3 and 6.3.20 and activity OPTN.

|FNSL| |FDNS| [ |AFTER (I) [ITERATION[S]]|]

SOLVE [n] USING |NSOL| [WITH VAR LIMITS [n] |IMMEDIATE[LY] |] |SOLV| [ |IGNORED |] |MSLV| |INLF|

The SOLVE command is used to execute one of the power flow solution activities. Solution options as established by the last SET SOLUTION OPTIONS command are honored; if no SET SOLUTION OPTIONS command was specified, the current solution adjustment option settings are honored. Refer to activities SOLV, MSLV, FNSL, NSOL, FDNS, INLF, and OPTN and Section 3.3.3 Program Run-Time Option Settings.

|PSS | |PASS | |PASSTHRU|

The PASSTHRU command is used to inform activity PSEB that subsequent command input is in the form of BAT_ records (refer to PSSE Application Program Interface (API)) and/or PSSE activity commands and responses to questions rather than in the form of PSEB commands. While passthru mode is in effect, each input to activity PSEB is simply appended without modification to the Response File being built. If input to activity PSEB is being taken from the users terminal, the prompt PASSTHRU: is issued while this mode is in effect. Passthru mode is terminated and PSEB command mode reinstated by entering the command FIN (see below). @INPUT and @CHAIN commands must not be specified while passthru mode is in effect; the IDEV activity command may be specified.



16-25

FIN

Terminate passthru mode (see above) and reinstate PSEB command mode.

|USE | |COPY| (response-file-filename) [arg1 ... [arg9]]|IDEV|

The USE command allows the user to include the BAT_ records (refer to PSSE Applica-tion Program Interface (API)) and/or PSSE line mode commands and responses to instructions which are contained in a Response File within the PSEB commands which define a PSSE calculation sequence. The USE filename command is converted to an @INPUT filename command and inserted into the Response File being constructed by activity PSEB. Note that entries in the designated file must be in the form of BAT_ records and/or activity commands and responses to questions rather than in the form of PSEB commands.

The designated file may contain @INPUT commands but must not contain any @CHAIN commands or IDEV activity commands. The designated file must be terminated with an @END command; it must not be terminated with an IDEV activity command or a FIN PSEB command.

EXECUTE (iplan-program-filename)

The EXECUTE command allows the user to include the execution of an IPLAN program within the PSEB commands which define a calculation sequence. The EXECUTE filename PSEB command is converted to an EXEC filename activity command (refer to activity EXEC) and inserted into the Response File being constructed by activity PSEB.

WATCH [OFF]

The WATCH command is used to enable or disable the echoing of responses generated from PSEB commands to the dialog output device (normally the users terminal). Response echoing is disabled upon entering activity PSEB; the PSEB command WATCH enables response echoing and WATCH,OFF disables it.

CHECK

The CHECK command instructs activity PSEB to bypass the automatic execution of the Response File that it constructs.

END

The END command terminates PSEB command input. Unless it is otherwise suppressed, the Response File constructed by activity PSEB is automatically executed.

ABORT

The ABORT command terminates activity PSEB and bypasses the automatic execution of the Response File that it has constructed.

HELP

This form of the HELP command displays the list of PSEB commands at the dialog output device (refer to Section 4.4 Virtual Output Devices).

Program Automation PSSE 33.4Building a Response File, Dynamic Simulation Program Operation Manual


16-26

HELP,command

This form of the HELP command displays the syntax format of the specified PSEB command at the dialog output device (refer to Section 4.4 Virtual Output Devices).

16.15 Building a Response File, Dynamic SimulationActivity PSAS

The simulation run assembler activity PSAS allows the user to specify dynamic simulation runs inan English-like language. Input to activity PSAS is taken either from a PSAS Command File or fromthe dialog input device. This can be in-stream in a Response File, typed into the command line inthe GUI, or entered at the console in PSSECMD. The output from activity PSAS is in the form of aPSSE Response File.

16.15.1 PSSE PSAS Macro LanguagePSAS (Simulation Run Assembler) is a built-in macro language that supports PSSE Dynamicssimulations through the use of English-like command macros. PSAS commands are created withina text file using a text editor. Each record is in the form of a command starting with a verb from apreviously defined vocabulary. The PSAS commands are documented below and in the PSASUsers Ready Reference.

PSAS commands do not interact with PSSE directly. The PSAS macro processor is really a trans-lator from the PSAS language to a Response File, which may contain a mixture of command lineand batch commands. The PSAS command line command normally automatically performs thecommands in the Response File after the translation. When used with the suffix CHECK (i.e. PSAS,CHECK) only the translation is performed. When using the PSAS API routine only the translation isperformed.

Additional InformationPSSE GUI Users Guide, Section 23.3.3, PSEB Command File, Power Flow Calculation

PSSE Command Line Interface (CLI) Users Guide, Section 19.4, Building a Response File, Power Flow Calculation

Run Activity PSAS - GUI

I/O Control>Run program Automation file


PSAS Command file (*.psa)

Run Line Mode Activity PSAS - CLI

ACTIVITY?>>PSASENTER INPUT FILE NAME (0 TO EXIT, 1 FOR TERMINAL):

>>Interrupt Control Codes

None

PSSE 33.4 Program AutomationProgram Operation Manual Building a Response File, Dynamic Simulation


16-27

16.15.2 PSAS CommandsEach PSAS command begins with a verb from the vocabulary recognized by activity PSAS. Somecommands require additional keywords (e.g., BUS, VAR), numeric quantities (e.g., bus number,VAR index), and/or character identifiers (e.g., dc line name, circuit identifier) in specific fields of thecommand format. Some commands provide for the optional specification of keywords, numericand/or character quantities; these are shown in the command syntax enclosed in braces ([ ]).

Where one of several keywords may be specified, they are shown in the command format enclosedin bars (| |). One of the keywords listed must be entered in the field.

Each keyword or data value must be followed by one or more blanks. For clarity, a comma or equalsign may be used in place of a blank space. For example, the following two PSAS commands areequivalent:

START OUTPUT SAVNW.PLT START, OUTPUT=SAVNW.PLT

Any field labeled bus id designates that a bus identifier is to be entered. When the numbers inputoption is in effect, the bus number must be specified; using the names input option, the extendedbus name enclosed in single quotes is required.

Any field labeled dc id designates that a two-terminal dc line name is to be entered. If the namecontains any blanks or special characters, it must be enclosed in single quotes.

I and R indicate that integer and real (i.e., it may include a decimal point) numeric values respec-tively are to be specified. C indicates that a one or two character alphanumeric value is to bespecified.

Many PSAS commands provide for the insertion of optional descriptive text in designated fields,indicated by [n] in the command syntax. For example, the following two PSAS commands translateinto the same PSSE dialog:

RECOVER FROM SAVNW.SNP AND SAVNW.SAV RECOVER snapshot and saved case FROM SAVNW.SNP AND SAVNW.SAV

A dollar sign ( $ ) at the end of a PSAS command line is used to continue the command on thefollowing line. At least one space must precede the dollar sign. As many physical lines as requiredmay be used to specify a single PSAS command as long as all lines except the last one are termi-nated with a dollar sign. This multiline capability may be used with all PSAS commands except theUSE command (see below). In addition, each PSSE activity command and response to an instruc-tion entered in passthru mode (see below) must be entered on a single line.

The detailed syntax of each PSAS command is given below and also on the PSSE Simulation RunAssembler PSAS Users Ready Reference sheet. Keywords shown in uppercase letters must beentered as shown in either upper or lowercase characters.

[|NOW |]HOLD[n]IN(snapshot-filename)AND(saved-case-filename) [|SIZE[S](I1)(I2)(I3)(I4)(I5)|]

The HOLD command is used to preserve dynamics working memory and the power flow working case in Snapshot and Saved Case Files respectively (refer to activities SNAP and SAVE). When the HOLD command includes the optional keyword NOW, activity SNAP and SAVE are immediately executed and the user specifies the number of dynamic simulation array elements to save in the same manner as when activity SNAP is specifically invoked.



16-28

In this case, the PSSE responses for activity SNAP and SAVE are not written to the Response File being constructed by activity PSAS.

When the HOLD command does not include the optional keyword NOW, the appropriate entries in the Response File are made to take a Snapshot and save the working case during the subsequent execution of the Response File. In this case, the user may optionally specify the keyword SIZES followed by the number of CONs, STATEs, VARs, ICONs and output channels to be preserved. If this keyword and its data are omitted, a blank response is generated in the Response File and, when the Response File is subsequently executed, activity SNAP preserves up to the next available positions in the respective dynamics data arrays.

RECOVER[n] FROM (snapshot-filename) AND (saved-case-filename) [NOFACT] [NOTYSL] [NORETURN]

The RECOVER command is used to access the designated Snapshot and Saved Case Files (refer to activities RSTR and CASE). Activities RSTR and CASE are executed imme-diately and the PSSE responses for activities RSTR, LOFL, and CASE are written to the Response File being constructed by activity PSAS. The activity commands FACT, TYSL, and RTRN are included in the Response File unless they are suppressed with one or more of the optional tokens NOFACT, NOTYSL and NORETURN. If NOFACT is specified, NOTYSL is assumed. If NORETURN is specified, NOFACT and NOTYSL are also assumed, and the next PSAS command must be either CONVERT, USE or PASS; the CONVERT command (see below) generates the RTRN activity command but in passthru mode (see below), the RTRN activity command must be specified before terminating passthru mode.

The RECOVER command overwrites dynamics working memory and the power flow working case. The HOLD command with the NOW option may be used before the RECOVER command to preserve these two sets of data.

|INITIALIZE| OUTPUT |(filename)| [SNAPSHOT |(filename)|]|START | |NONE | [ |NONE |]

This form of the START command is used to initialize the dynamic model in preparation for state-space simulations. The STRT activity command is generated with user specified channel output and Snapshot filename responses. The reserved token NONE may be used to indicate that the corresponding filename is not to be specified.

|INITIALIZE| EXTENDED [n] OUTPUT |(filename)| [n]|START | |NONE |

This form of the START command is used to initialize the dynamic model in preparation for extended term simulations. The MSTR activity command is generated with a user specified channel output filename response. The reserved token NONE may be used to indicate no channel output file is to be specified.

|TO | |CYCLE[S] |RUN [n] |FOR| (R) |SECOND[S]| [PRINT (I)] [PLOT (I)] [CRTPLT (I)]

The RUN command is used to perform dynamic simulation calculations with activity RUN or MRUN. If the RUN command is preceded by the START command (see above), the form of the START command determines whether activities RUN or MRUN is to be used. Other-wise, state-space simulations are assumed and activity RUN is used. The real value indi-cates the duration of the simulation calculation and may be specified in either seconds or cycles. It is the value of simulation time (i.e., TPAUSE) when the token TO precedes it and an incremental value of time when the token FOR precedes it. The optional integer tokens



16-29

and their corresponding keywords allow the user to specify channel printing and plotting intervals (refer to Section 14.10 Performing State-Space Simulation in Time Steps). By default, PRINT=20, PLOT=5 and CRTPLT=0.

|OFF| CONVERGENCE MONITOR |ON |

The CONVERGENCE MONITOR command is used to enable or disable the printing of the network solution convergence monitor during the execution of the PSSE activity calls generated by subsequent START and RUN commands (see above). By default, the convergence monitor is suppressed.



16-30

APPLY FAULT [n] BUS (bus id) [n]

This form of the APPLY FAULT command is used to apply a solidly grounded three-phase fault at the designated bus. The Response File being constructed by activity PSAS includes responses to use activity ALTR to change the fixed shunt at the bus to j(-2.109); refer to Bus Data, activity ALTR and Section 19.7.2 Applying Disturbances.

|Y | |MVA |APPLY FAULT [n] BUS (bus id) [n] |ADMITTANCE| (R1) (R2) |MHO[S]| [BASEKV (R)]

This form of the APPLY FAULT command is used to apply a fault with a specified fault admittance, (R1) + j(R2), at a designated bus. The Response File being constructed by activity PSAS includes responses to use activity ALTR to change the fixed shunt at the bus. (R2) should be entered as a negative number. Refer to Bus Data, activity ALTR and Section 19.7.2 Applying Disturbances.

If the MVA token is specified, the active and reactive components of fixed shunt at the bus are set to the values specified as (R1) and (R2) respectively; i.e., the fault admittance is specified in the same MVA units as is bus shunt.

If the MHO or MHOS token is specified, (R1) and (R2) are entered in mhos and activity PSAS converts them to the MVA units used for specifying bus shunts. If the optional base voltage tokens are specified, the base voltage specified on the PSAS command is used in the conversion calculation; otherwise, the base voltage contained in the working case for the designated bus is used. In either case, a positive base voltage value is required.

|Z |APPLY FAULT [n] BUS (bus id) [n] |IMPEDANCE| (R1) (R2) OHM[S] [BASEKV (R)]

This form of the APPLY FAULT command is used to apply a fault with a specified fault impedance,(R1) + j(R2), at a designated bus. The Response File being constructed by activity PSAS includesresponses to use activity ALTR to change the fixed shunt at the bus. (R2) should be entered as apositive number and (R1) and (R2) are specified in ohms. Activity PSAS converts them to the MVAunits used for specifying bus shunts. If the optional base voltage tokens are specified, the basevoltage specified on the PSAS command is used in the conversion calculation; otherwise, the basevoltage contained in the working case for the designated bus is used. In either case, a positive basevoltage value is

|L-G |SCMU |L-L | FAULT [n] BUS (bus id) [n] [ZL-G (R1) (R2)] [n] |L-L-G| [ZL-L (R3) (R4)] [n] [CONVERTDC] [n] [APPLYZCOREC]

The SCMU FAULT command is used to calculate and apply a single line-to-ground, line-to-line, or line-to-line-to-ground fault at a designated bus. For the L-G and L-L-G faults, (R1) and (R2) may optionally specify the complex line-to-ground fault impedance to be used; similarly, for the L-L and L-L-G faults, (R3) and (R4) may optionally specify the complex line-to-line fault impedance to be used. These impedances are specified in per unit. For any of these impedance values that are not specified, 0.0 is assumed.

If the optional token CONVERTDC is specified, dc lines and FACTS device boundary conditions are converted to constant admittance load for the fault calculation. Otherwise, they are neglected.

If the optional token APPLYZCOREC is specified, for those transformers which include a transformer impedance adjustment table, the same correction factor is applied to the zero



16-31

sequence impedance as is applied to the positive sequence impedance. Otherwise, trans-former zero sequence nominal impedances are used.

|L-G | |L-L | |L-L-G | [|CKT | ]SPCB |3PHASE| FAULT (R1) [n] FROM [n] BUS (bsid) TO [n] BUS (bsid) [n] [|CIRCUIT| (id)]

[n] [ZL-G (R2) (R3)] [n] [ZL-L (R4) (R5)] [n] [CONVERTDC] [n] [APPLYZCOREC]

This form of the SPCB FAULT command is used to calculate and apply a ground fault at a designated point along a transmission line. (R1) specifies the fault location as the fraction of the line from the FROM bus; the default value of 0.5 applies the fault at the midpoint of the line.

For the L-G and L-L-G faults, (R2) and (R3) may optionally specify the complex line-to-ground fault impedance to be used; similarly, for the L-L and L-L-G faults, (R4) and (R5) may optionally specify the complex line-to-line fault impedance to be used. These imped-ances are specified in per unit. For any of these impedance values that are not specified, 0.0 is assumed.


If the optional token APPLYZCOREC is specified, for those transformers which include a transformer impedance adjustment table, the same correction factor is applied to the zero sequence impedance as is applied to the positive sequence impedance. Otherwise, trans-former zero sequence nominal impedances are used.

[|CKT | ]SPCB 2PHASE OPEN [n] FROM [n] BUS (bsid) TO [n] BUS (bsid) [n] [|CIRCUIT| (id)]

[n] [CONVERTDC] [n] [APPLYZCOREC]

This form of the SPCB FAULT command is used to calculate and apply a transmission line unbalance with two of its three phases open.



[|CKT | ]SPCB 1PHASE OPEN [n] FROM [n] BUS (bsid) TO [n] BUS (bsid) [n] [|CIRCUIT| (id)]

[n] [PATH (R1) [ [n] [ZL-G (R2) (R3)] ] [n] [CONVERTDC] [n] [APPLYZCOREC]

This form of the SPCB FAULT command is used to calculate and apply a transmission line unbalance with one of its three phases open.

This branch unbalance may optionally include a ground fault at a designated point of the open phase by specifying the optional token PATH, along with (R1) which specifies the fault location as the fraction of the line from the FROM bus; the default value of 0.5 applies the



16-32

fault at the midpoint of the open phase. (R2) and(R3) may optionally specify the complex line-to-ground fault impedance in per unit to be used. For any of these impedance values that are not specified, 0.0 is assumed.



[|CKT | ]SPCB BREAKER OPEN [n] AT [n] BUS (bsid) TO [n] BUS (bsid) [n] [|CIRCUIT| (id)]

[n] [PATH (R1) [ [n] [ZL-G (R2) (R3)] ] [n] [CONVERTDC] [n] [APPLYZCOREC]

This form of the SPCB FAULT command is used to calculate and apply a transmission line unbalance with the breaker of one phase open. The breaker at the AT bus is assumed to be the open breaker.

This branch unbalance may optionally include a ground fault at a designated point of the open phase by specifying the optional token PATH, along with (R1) which specifies the fault location as the fraction of the line from the FROM bus; the default value of 0.5 applies the fault at the midpoint of the open phase. (R2) and(R3) may optionally specify the complex line-to-ground fault impedance in per unit to be used. For any of these impedance values that are not specified, 0.0 is assumed.



CLEAR FAULT [n] [BUS (bus id)]

CLEAR BUS [FAULT] [n] [BUS (bus id)]

These forms of the CLEAR command are used to clear bus faults which were previously applied with the APPLY FAULT command (see above). The Response File being con-structed by activity PSAS includes responses to use activity ALTR to change the fixed bus shunt at the bus back to its original value.

Activity PSAS remembers the faulted bus and the fixed bus shunt which was replaced with the fault admittance for up to ten bus faults. If the optional bus identification tokens are omitted, activity PSAS clears the last bus fault which was applied and which has not already been cleared.



16-33

|LINE | [|CKT | ] APPLY FAULT [n]|TIE |[n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [n][|CIRCUIT|(id)] [n]

|BRANCH|

This form of the APPLY FAULT command is used to apply a solidly grounded three-phase fault at the from bus end of a designated non-transformer branch. The Response File being constructed by activity PSAS includes responses to use activity ALTR to change the line shunt at the from bus end of the branch to j(-2.107). If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. Refer to Bus Data, activity ALTR and Section 19.7.2 Applying Disturbances.

|LINE | [|CKT | ] APPLY FAULT [n] |TIE | [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [n] [|CIRCUIT| (id)] [n]

|BRANCH| |Y | |MVA ||ADMITTANCE| (R1) (R2) |MHO[S]| [BASEKV (R)]

This form of the APPLY FAULT command is used to apply a fault with a specified fault admittance, (R1) + j(R2), at the from bus end of a designated non-transformer branch. The Response File being constructed by activity PSAS includes responses to use activity ALTR to change the line shunt at the from bus end of the branch. (R2) should be entered as a negative number. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. Refer to Non-Transformer Branch Data, activity ALTR and Section 19.7.2 Applying Disturbances.

If the MVA token is specified, the values specified as (R1) and (R2) are divided by the system base MVA and the active and reactive components respectively of the line shunt at the from bus end of the branch are set to these values. The fault admittance is therefore specified on the record is in the same MVA units as is bus shunt (refer to Bus Data).

If the MHO or MHOS token is specified, (R1) and (R2) are entered in mhos and activity PSAS converts them to the per unit values used for specifying line shunts. If the optional base voltage tokens are specified, the base voltage specified on the PSAS command is used in the conversion calculation; otherwise, the base voltage contained in the working case for the designated from bus is used. In either case, a positive base voltage value is required.

|LINE | [|CKT | ] APPLY FAULT [n] |TIE | [n] FROM [n] BUS (bus id) TO [n] BUS (bus id) [n] [|CIRCUIT| (id)] [n]

|BRANCH| |Z | |IMPEDANCE| (R1) (R2) OHM[S] [BASEKV (R)]

This form of the APPLY FAULT command is used to apply a fault with a specified fault impedance, (R1) + j(R2), at the from bus end of a designated non-transformer branch. The Response File being constructed by activity PSAS includes responses to use activity ALTR to change the line shunt at the from bus end of the branch. (R2) should be entered as a positive number and (R1) and (R2) are specified in ohms. Activity PSAS converts them to the per unit values used for specifying line shunts. If the optional base voltage tokens are specified, the base voltage specified on the PSAS command is used in the conversion cal-culation; otherwise, the base voltage contained in the working case for the designated from bus is used. In either case, a positive base voltage value is required. If the optional circuit identifier tokens are omitted, a circuit identifier of 1 is assumed. Refer to Non-Transformer Branch Data, activity ALTR and Section 19.7.2 Applying Disturbances.



16-34

Documents

Capitulo 16