Scripting in IPSA+ 1.6.8

5 downloads 21680 Views 996KB Size Report
Perform Harmonic penetration and sensitivity calculations and get all the results ... The following script is all the python code required to read an IPSA IIF network file, perform a load flow and print .... FaultPlotinCycles - Fault Plot Time cycles.
Scripted IPSA 1.6.8 reference manual

Scripting in IPSA+ 1.6.8 IPSA+ now has a scripted extension library for Python. This enables IPSA+ to be run without a user interface from within a Python shell. This guide provides a full reference to all the IPSA+ objects and their callable functions exposed through Python. This reference guide refers to IPSA+ versions 1.6.7 and greater.

Introduction This section gives a brief background to the IPSA scripting environment. Note that this documentation is based on the internal TNEI wiki site – the external site is not currently available.

Why Python We chose Python for a number of reasons: • • • •

it's simple to use it's a mature and well documented language it can be used to create/modify Excel spreadsheet files oh and it's free

The Scripted IPSA+ dll The Python extension dll contains quite a lot of IPSA+ (about 80%): • • • • • • • •

The data model - all the IPSA+ network and analysis data The IIF file reading library Licensing - it requires a valid IPSA+ license Database, UDM and Protection data model - not directly accessible Load flow - the IPSA+ load flow and engine loading utilities Fault Level - the IPSA+ fault level and engine loading utilities Harmonics - the IPSA+ harmonics and engine loading utilities Plugins – the IPSA+ plugin handling routines – not directly accessible yet – but operational in the analysis options

Current Features The following actions are possible: • • • • • • • • •

Read and write IPSA+ iif network files Full access to view and/or modify all the network data - including the analyis parameters Add, edit and view extension data Perform Load flow studies and get all the results Perform Fault level studies and get all the results Perform Harmonic penetration and sensitivity calculations and get all the results Create XML results files Compare XML results files Debugging and utility options

December 2011

1 Of 31

Scripted IPSA 1.6.8 reference manual •

Compare two IPSA+ networks

A simple example The following script is all the python code required to read an IPSA IIF network file, perform a load flow and print out the busbar results. from ipsa import * ipsasys = IscInterface() net = ipsasys.ReadFile("refinery.iif") bok = net.DoLoadFlow(); if bok: busbars = net.GetBusbars() print "Load Flow results:" print "" print "BusName Vmag(kV)" print "====================" for bus in busbars.itervalues(): name = bus.GetName() vm = bus.GetVoltageMagnitudekV() res = "%-8s %10.5f" % (name, vm) print res else: print "Load Flow failed!"

Limitations When IPSA+ would normally request a user response to a Yes/No question the extension dll requires a console to allow the user to answer the question. This is not difficult to setup - just add the directory you installed python in, to the $PATH variable, and use a command console Hint: Start Menu->Run Program -> "cmd". If you do not wish to do this the default behaviour is to respond with a "Yes" - this may be changed if desired using the IscInterface.SetReplyOverride() function. Alternatively it is also possible to allow Qt Yes/No dialogs to be displayed just as IPSA+ would do. This does not require the use of a console.

Accessing C++ objects in Python When IPSA+ returns non-simple data types, e.g. lists, pairs or maps, the objects will volatile and may often be overwritten by another function call. So it is important to copy values to local Python variables immediately after they are returned, otherwise as soon as you overwrite them the references in Python space are will be changed - hence the appearance of post modification. For example after running a Harmonic penetration study, and wanting to add branch currents to a list, use something like: currents = list() prVal = branch1.GetCurrents(21) cCurrent = complex(prVal[1],prVal[2]) currents.append(cCurrent)

December 2011

2 Of 31

Scripted IPSA 1.6.8 reference manual

The IscAnalysis class The IscAnalysis class provides access to IPSA+ analysis data, to set and get study control values

Data access The following functions are available to set and get data values: • • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



GetBValue(nFieldIndex) - returns a boolean value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful

• • •

SetBValue(nFieldIndex, bValue) - set the value for the field nFieldIndex from a boolean nValue, returns true if set

Load Flow settings The following fields are available for IscAnalysis data for the Load flow: • • • • • • • • • • • • • • • •

IscAnalysis.Convergence - Accuracy for load flow solution IscAnalysis.MaxIterations - Maximum number of iterations to run the load flow IscAnalysis.UndervoltagePU - Lower voltage limit for busbars (reporting only) IscAnalysis.OvervoltagePU - Upper voltage limit for busbars (reporting only) IscAnalysis.RatingSetUsed - The class of branch rating to be used e.g. Summer, Winter, etc. IscAnalysis.LockTaps - Lock all transformer taps IscAnalysis.NoPhaseShift - Do not apply phase shifts to load flow IscAnalysis.TapOscIterStart - Start counting transformer tap oscillations IscAnalysis.TapOscSuccessive - Successive iterations of tap oscillation IscAnalysis.TapOscLimit - Tap oscillation limit IscAnalysis.TapOscIterEnd - End counting transformer tap oscillations IscAnalysis.FillkARatings - Auto3matically complete kA rating fields for lines IscAnalysis.UseLoadScaling - Enable scaling of loads in the LF calculation IscAnalysis.RealLoadScale - Factor used to scale all real loads (default = 1.0) IscAnalysis.ReactiveLoadScale - Factor used to scale all reactive loads (default = 1.0) IscAnalysis.CheckProtection - Check protection devices after load flow

Flat Start settings The following are available to set the flat start: •

IscAnalysis.FSSetBusbarVoltages

December 2011

3 Of 31

Scripted IPSA 1.6.8 reference manual • • • • • • • • •

IscAnalysis.FSIgnoreVoltageControlSettings IscAnalysis.FSVoltageMagnitudePU IscAnalysis.FSVoltageAngleDeg IscAnalysis.FSSetTransformerTaps IscAnalysis.FSIgnoreFixedTaps IscAnalysis.FSNominalTaps IscAnalysis.FSTapStartPC IscAnalysis.FSSetInductionMachineSlips IscAnalysis.FSSlipPC

Fault Level settings The following fields are available for IscAnalysis data for the Fault Level: • • • • • • • • • • • • • • • • • • •

IscAnalysis.FaultStudyType - Type of fault study IscAnalysis.FaultTime - Time of fault IscAnalysis.FaultResistance - Fault resistance IscAnalysis.FaultReactance - Fault reactance IscAnalysis.FaultEngineType - Type of fault, such as line-line-line IscAnalysis.FaultEngineResultType - Type of fault value, such as asymmetric peak IscAnalysis.MaxFaultIterations - Maximum number of iterations to run the fault level IscAnalysis.FaultFlatStart - Set 1 p.u. voltages before calculating fault IscAnalysis.UseSaturatedImpedances - Use generator saturated impedances in fault calculation IscAnalysis.AssumeAVRAction - Assume generator impedances decay to transient rather than steady state values IscAnalysis.CalculateCurrent - Calculate fault currents. This option is disabled unless all busbars have nominal voltages IscAnalysis.BusbarsToFault - List of busbars to apply faults on IscAnalysis.SingleBusToFault - Busbar to apply fault on IscAnalysis.BranchToFault - Branch to apply fault on IscAnalysis.DistanceAlongBranch - Distance along branch to apply fault IscAnalysis.FaultPlotSteps - Fault Plot Steps per iteration IscAnalysis.FaultPlotMaxTime - Fault Plot Max Time (S) IscAnalysis.FaultPlotinCycles - Fault Plot Time cycles IscAnalysis.FaultPlotinkA - Fault Plot Current in kA

Harmonic Penetration settings The following fields are available for IscAnalysis data for Harmonic analysis: • • • • • • • • •

IscAnalysis.HarmonicStudyType) - Type of harmonic study. IscAnalysis.FundamentalTHD) - Use fundamental voltage for THD calculation. IscAnalysis.MinimumHarmonicOrder) - Minimum harmonic order. IscAnalysis.MaximumHarmonicOrder) - Maximum harmonic order. IscAnalysis.HarmonicWaveformBusbar) - Busbar to produce waveform for. IscAnalysis.HarmonicSequence) - Sequence network to use for harmonics. IscAnalysis.HarmonicUseLongLines) - Global override use long lines. IscAnalysis.HarmonicGlobalLineModel) - Global override line model. IscAnalysis.HarmonicGlobalTransformerModel) - Global override transformer model.

December 2011

4 Of 31

Scripted IPSA 1.6.8 reference manual • • • • •

IscAnalysis.HarmonicGlobalShuntModel) - Global override shunt model. IscAnalysis.HarmonicGlobalLoadModel) - Global override load model. IscAnalysis.HarmonicOffNominalFrequencyHz) - Off-nominal frequency (Hz). IscAnalysis.HarmonicOnlyScanResonant) - Only scan harmonic resonants in detail. IscAnalysis.HarmonicScanStepSizePU) - Step size for harmonic sensitivity scans (pu).

Load Flow results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

Fault Level Results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

Harmonic Penetration results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

The IscBranch class The IscBranch class provides access to an IPSA+ branch, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values:

• • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • • •

GetIValue(nFieldIndex) GetDValue(nFieldIndex) GetSValue(nFieldIndex) GetBValue(nFieldIndex)



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful SetBValue(nFieldIndex, bValue) - set the value for the field nFieldIndex from a boolean nValue, returns true if set



• • •

December 2011

-

returns returns returns returns

an integer value for the field nFieldIndex an real value for the field nFieldIndex an string value for the field nFieldIndex a boolean value for the field nFieldIndex

5 Of 31

Scripted IPSA 1.6.8 reference manual The following functions are available to set and get data values for multi-section lines: • • • • • • • •

GetIValue(nFieldIndex, nFieldIndex , for section GetDValue(nFieldIndex, nFieldIndex , for section GetSValue(nFieldIndex, nFieldIndex , for section GetBValue(nFieldIndex, nFieldIndex , for section

nSection) nSection nSection) nSection nSection) nSection nSection) nSection

- returns an integer value for the field - returns an real value for the field - returns an string value for the field - returns a boolean value for the field

SetIValue(nFieldIndex, nValue, nSection) - set the value for the field nFieldIndex from an integer nValue, for section nSection, returns true if successful SetDValue(nFieldIndex, dValue, nSection) - set the value for the field nFieldIndex from an real dValue, for section nSection, returns true if successful SetSValue(nFieldIndex, strValue, nSection) - set the value for the field nFieldIndex from an string strValue, for section nSection, returns true if successful SetBValue(nFieldIndex, bValue, nSection) - set the value for the field nFieldIndex from a boolean nValue, for section nSection, returns true if set

The following fields are available for Branches: • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

IscBranch.FromBusName - sending busbar name - Get only IscBranch.ToBusName - receiving busbar name - Get only IscBranch.Name - real name - Get only IscBranch.Type - type - Circuit or Transformer - Get only IscBranch.Status - Line status IscBranch.ResistancePU - Positive sequence resistance IscBranch.ReactancePU - Positive sequence reactance IscBranch.SusceptancePU - Positive sequence susceptance IscBranch.ZSResistancePU - Zero sequence resistance IscBranch.ZSReactancePU - Zero sequence reactance IscBranch.ZeroImpedance - Zero impedance line IscBranch.SwitchTime1Sec - Line switching time 1 IscBranch.SwitchTime2Sec - Line switching time 2 IscBranch.Monitor - Monitor the line in TS IscBranch.HarmRC0 - Harmonic constant IscBranch.HarmRC12 - Harmonic constant IscBranch.HarmRC1 - Harmonic constant IscBranch.HarmRC2 - Harmonic constant IscBranch.HarmRC3 - Harmonic constant IscBranch.DbType1 - First database type IscBranch.DbType2 - Second database type IscBranch.DbLength1 - First database length IscBranch.DbLength2 - Second database length IscBranch.DbPar1 - Number of lines of database type 1 in parallel - Get only IscBranch.DbPar2 - Number of lines of database type 2 in parallel - Get only IscBranch.DbTranType - Transformer database type - Get only IscBranch.DbTranPar - Number of transformers in parallel (database only) - Get only IscBranch.SummerMVA - Summer branch rating IscBranch.SummerSendkA - Summer branch rating send end IscBranch.SummerRecvkA - Summer branch rating receive end IscBranch.WinterMVA - Winter branch rating IscBranch.WinterSendkA - Winter branch rating send end

December 2011

6 Of 31

Scripted IPSA 1.6.8 reference manual • • • • • • • • • • •

IscBranch.WinterRecvkA - Winter branch rating receive end IscBranch.ShortMVA - Short term branch rating IscBranch.ShortSendkA - Short term branch rating send end IscBranch.ShortRecvkA - Short term branch rating receive end IscBranch.StdMVA - Standard branch rating IscBranch.StdSendkA - Standard branch rating send end IscBranch.StdRecvkA - Standard branch rating receive end IscBranch.UdmID - UDM ID - Get only IscBranch.UdmDevEnd - Device end - Get only IscBranch.UdmCtrlType - UDM Type - Get only IscBranch.UdmCtrlUID - UDM control ID - Get only

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • • • • • • • • • • • • •

GetVoltagekVRecv() GetSendPowerMagnitudeMVA() GetSendPowerMagnitudekVA() GetSendRealPowerMW() GetSendReactivePowerMVAr() GetSendRealPowerkW() GetSendReactivePowerkVAr() GetReceivePowerMagnitudeMVA() GetReceivePowerMagnitudekVA() GetReceiveRealPowerMW() GetReceiveReactivePowerMVAr() GetReceiveRealPowerkW() GetReceiveReactivePowerkVAr() GetLossesMW() GetLossesMVAr() GetLosseskW() GetLosseskVAr()

Fault Level Results To get fault level Results after running a fault level study, (all return real values): •

• • • • •

GetComponentMagnitude(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent GetComponentMagnitudeByK(nComponent) GetComponentAngleRad(nComponent) GetComponentAngleDeg(nComponent) GetASymMagnitude(nPhase) GetASymMagnitudeByK(nPhase)

December 2011

7 Of 31

Scripted IPSA 1.6.8 reference manual

Harmonic Penetration results In general harmonic results return lists or maps (in C++ terms) of results. These map directly to Python tuples or dicts so that standard python iterators can be used. For more specific details see the harmonics example code. The following functions are used to retrieve the Harmonics results for branches: • • • •

GetCurrentOrders() - returns a list of doubles of Impedance Orders. GetCurrents(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order. GetImpedanceOrders() - returns a list of doubles of Impedance Orders. GetImpedances(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order.

The IscBreaker class The IscBreaker class provides access to an IPSA+ breaker, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values:

• • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful



• •

The following fields are available for Breakers: • • • • • • • • • • •

IscBreaker.BusName - Busbar name - Get only IscBreaker.BusToName - Busbar name - Get only IscBreaker.Name - Real name - Get only IscBreaker.Status - Status IscBreaker.Type - Location of the breaker IscBreaker.DbType - Data base Type IscBreaker.MakePeakkA - Make Peak kA IscBreaker.BreakRMSkA - Break RMS kA IscBreaker.BreakDCPC - Break DC % IscBreaker.BreakTimemS - Break operation Time in mS IscBreaker.BreakerType - Breaker type

December 2011

8 Of 31

Scripted IPSA 1.6.8 reference manual

Load Flow results There are no Breaker specific results at present.

Fault Level Results There are no Breaker specific results at present.

Harmonic Penetration results There are no Breaker specific results at present.

The IscBusbar class The IscBusbar class provides access to an IPSA+ busbar, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values:

• • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName) - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful



• •

The following fields are available for Busbars: • • • • • • • • • • •

IscBusbar.Name - Name - Get only IscBusbar.NomVoltkV - Nominal bus voltage in kV IscBusbar.ControlType - The type of busbar, e.g. slack, PV, PQ, etc. - Get only IscBusbar.VoltPU - Result voltage magnitude IscBusbar.VoltAngleRad - Result voltage angle IscBusbar.Comment - Comments - Get only IscBusbar.CtlBusbar - Controlling busbar IscBusbar.VMinPU - Minimum voltage limit for PQ control IscBusbar.VMaxPU - Maximum voltage limit for PQ control IscBusbar.QMinMVAr - Minimum reactive power limit for PV control IscBusbar.QMaxMVAr - Maximum reactive power limit for PV control

December 2011

9 Of 31

Scripted IPSA 1.6.8 reference manual •

IscBusbar.OperatingTimeSec - Breaker operating time (for protection)

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • • • • • • • • • • • • • • • • • • • • • • • •

GetVoltageMagnitudePU() GetVoltageMagnitudekV() GetVoltageAngleRad() GetVoltageAngleDeg() GetMismatchMagnitudeMVA() GetMismatchMagnitudekVA() GetRealMismatchMW() GetReactiveMismatchMVAr() GetRealMismatchkW() GetReactiveMismatchkVAr() GetGenerationMagnitudeMVA() GetGenerationMagnitudekVA() GetRealGenerationMW() GetReactiveGenerationMVAr() GetRealGenerationkW() GetReactiveGenerationkVAr() GetInductionMagnitudeMVA() GetInductionMagnitudekVA() GetRealInductionMW() GetReactiveInductionMVAr() GetRealInductionkW() GetReactiveInductionkVAr() GetLoadMagnitudeMVA() GetLoadMagnitudekVA() GetRealLoadMW() GetReactiveLoadMVAr() GetRealLoadkW() GetReactiveLoadkVAr()

Fault Level Results To get fault level Results after running a fault level study, (all return real values): •

• • • • •

GetComponentMagnitude(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent GetComponentMagnitudeByK(nComponent) GetComponentAngleRad(nComponent) GetComponentAngleDeg(nComponent) GetACComponent() GetACComponentByK()

December 2011

10 Of 31

Scripted IPSA 1.6.8 reference manual • • • • • • • • • • • • • • • • • • • •

GetDCComponent() GetDCComponentByK() GetDCPercentage() Get2ndHarmonic() Get2ndHarmonicByK() GetDCXoverR() GetDCTheveninX() GetDCTheveninR() GetRedVoltagePU() GetRedVoltAngleDeg() GetYellowVoltagePU() GetYellowVoltAngleDeg() GetBlueVoltagePU() GetBlueVoltAngleDeg() GetPositiveVoltagePU() GetPositiveVoltAngleDeg() GetNegativeVoltagePU() GetNegativeVoltAngleDeg() GetZeroVoltagePU() GetZeroVoltAngleDeg()

Harmonic Penetration results In general harmonic results return lists or maps (in C++ terms) of results. These map directly to Python tuples or dicts so that standard python iterators can be used. For more specific details see the harmonics example code. The following functions are used to retrieve the Harmonics results for busbars. Note that they return engine values so complex values will be in rectangular form, and percentages in PU: • • • • • • • • • • •

GetVoltageOrders() - returns a list of doubles of Voltage Orders. GetVoltages(const double dOrder) - returns a pair of doubles of Voltages for a particular Voltage Order. GetIntegerImpedanceOrders() - returns a list of doubles of Impedance Orders. GetImpedances(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order. GetInjectionOrders() - returns a list of doubles of Injection Orders. GetInjections(const double dOrder) - returns a pair of doubles of Injections for a paricular Injection Order. GetResonances() - returns a list of pairs of doubles of Resonances. GetMaximumDistortion() - returns a pair of doubles of Maximum Distortion. GetVoltageSum() - returns the Voltage Sum. GetDistortionFactor( - returns the Distortion Factor. GetDistortion(dOrder) - returns the Distortion at a particular Voltage Order.

The IscCompareData class The IscCompareData class provides access to the differences returned during a network comparison run using an IscNetComparator object. It is used to variables of a different type in a single data item - as the result of a field comparison.

December 2011

11 Of 31

Scripted IPSA 1.6.8 reference manual

Data access The following functions are available to get data values: •

IsSet()) - returns true if the data has been set.



Type()) - returns the type of data stored, one of: • IscCompareData.NoType • IscCompareData.Integer • IscCompareData.Double • IscCompareData.String • IscCompareData.Boolean

• • • •

n()) - returns the integer stored. d()) - returns the double value stored. b()) - returns the true/false value stored. str()) - returns the string stored.

Load Flow results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

Fault Level Results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

Harmonic Penetration results As this is not a plant item there are no results. It is used to set the runtime parameters for the analysis.

The IscFilter class The IscFilter class provides access to an IPSA+ filter, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values:

• • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



December 2011

12 Of 31

Scripted IPSA 1.6.8 reference manual • • •

SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful

The following fields are available for Filters: • • • • • • • • • • •

IscFilter.BusName - Busbar Name - Get only IscFilter.Name - Real Name - Get only IscFilter.Status - Status IscFilter.FilterType - Filter Type. IscFilter.Ground - Grounded or not. IscFilter.Data1 - Data1 parameter for the filter IscFilter.Data2 - Data2 parameter for the filter IscFilter.Data3 - Data3 parameter for the filter IscFilter.Data4 - Data4 parameter for the filter IscFilter.Data5 - Data5 parameter for the filter IscFilter.Data6 - Data6 parameter for the filter

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • •

GetPowerMagnitudeMVA() GetPowerMagnitudekVA() GetRealPowerMW() GetReactivePowerMVAr() GetRealPowerkW() GetReactivePowerkVAr()

Fault Level Results There are no Filter specific results at present.

Harmonic Penetration results There are no Filter specific results at present.

The IscGridInfeed class The IscGridInfeed class provides access to an IPSA+ grid infeed, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values: •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars)

December 2011

13 Of 31

Scripted IPSA 1.6.8 reference manual • • •

SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful

• • •

SetHarmZmag(mdHarmZmag) - set the values for Harmonic magnitudes from an map of doubles → doubles pairs (the first double being the harmonic order and the second being the magnitude)



SetHarmZang(mdHarmZang) - set the values for Harmonic angles from an map of doubles → doubles pairs (the first double being the harmonic order and the second being the angle)

The following fields are available for Grid Infeeds: • • • • • • • • • • • • • • •

IscGridInfeed.BusName - Busbar name - Get only IscGridInfeed.Name - Real name - Get only IscGridInfeed.Status - Status IscGridInfeed.VoltPU - Per unit voltage target IscGridInfeed.VoltBandwidthPC - Bandwidth of acceptable busbar voltage IscGridInfeed.CtlBusbar - Controlled busbar IscGridInfeed.GenMW - Generated real power IscGridInfeed.GenMVAr - Generated reactive power IscGridInfeed.PeakLLL - Peak LLL (MVA). IscGridInfeed.RMSLLL - RMS LLL (MVA). IscGridInfeed.X2RLLL - X2R LLL. IscGridInfeed.PeakLG - Peak LG (MVA). IscGridInfeed.RMSLG - RMS LG (MVA). IscGridInfeed.Tac - AC decay time constant (seconds). IscGridInfeed.Tbreak - RMS fault time (seconds).

To change the power in the load flow engine only: •

SetLFPower(dPMW, dQMVAr) - where dPMW is the new real power in MW, and dQMVAr is the reactive power in MVAr.

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • • •

GetVoltageMagnitudePU() GetVoltageAngleRad() GetVoltageAngleDeg() GetPowerMagnitudeMVA() GetPowerMagnitudekVA() GetRealPowerMW() GetReactivePowerMVAr()

December 2011

14 Of 31

Scripted IPSA 1.6.8 reference manual • •

GetRealPowerkW() GetReactivePowerkVAr()

Fault Level Results To get fault level Results after running a fault level study, (all return real values): •

GetComponentMagnitude(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent



GetComponentMagnitudeByK(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent



GetComponentAngleRad(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent



GetComponentAngleDeg(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent

• • • • • • •

GetACComponent() GetACComponentByK() GetDCComponent() GetDCComponentByK() GetDCPercentage() Get2ndHarmonic() Get2ndHarmonicByK()

December 2011

15 Of 31

Scripted IPSA 1.6.8 reference manual

Harmonic Penetration results In general harmonic results return lists or maps (in C++ terms) of results. These map directly to Python tuples or dicts so that standard python iterators can be used. For more specific details see the harmonics example code. The following functions are used to retrieve the Harmonics results for grid infeed: • • • •

GetCurrentOrders() - returns a list of doubles of Impedance Orders. GetCurrents(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order. GetImpedanceOrders() - returns a list of doubles of Impedance Orders. GetImpedances(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order.

The IscGroup class The IscBreaker class provides access to an IPSA+ group, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values: • • • • • • •





GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetMembers() - returns a dictionary containing all the IscNetComponent objects in the network using their names as the key AddMember(Item) - adds Item to the group RemoveMember(Item) - removes an item from the group GetNumMembers() - returns the number of members of the group GetType() - get the group type, one of: • IscGroup.GroupArea • IscGroup.GroupSingle • IscGroup.GroupMixed • IscGroup.GroupLoad • ]]IscGroup.GroupProtection • IscGroup.GroupLoadTransfer GetItemType() - gets the item type is one of: • IscNetComponent.Busbar • IscNetComponent.Load • IscNetComponent.Generator • IscNetComponent.Filter • IscNetComponent.IndMachine • IscNetComponent.Line • IscNetComponent.Transformer IsMember(Item) - returns true if Item is a member of a group

Load Flow results There are no Group specific results at present. December 2011

16 Of 31

Scripted IPSA 1.6.8 reference manual

Fault Level Results There are no Group specific results at present.

Harmonic Penetration results There are no Group specific results at present.

The IscInterface class The IscInterface class is the main interface class provided in the extension Dll. It must be created prior to any other references to IPSA+ objects. To create an instance from Python: ipsaintf = IscInterface() The IscInterface object can then be used to read networks from file and compare them.

Network creation The following functions are available to crate network objects: • •

ReadFile(filename) - reads a network from file, where filename is the name of the file (as a string), and returns an IscNetwork object if successful. CreateNetwork() - creates a new empty network, and returns an IscNetwork object if successful.

Network Deletion The following function is used to delete a network: •

DeleteNetwork(network) - where networkis the IscNetwork object to be deleted. Note that this will also reset the UID seed to 1 after the last network object is deleted.

It should always be used rather than simply deleting from python with the del operator.

Run time options The following run time option setting functions are available: •

SetReplyOverride(bOverride,bYes,bUseQt) - set bOverride to 1 to allow overrides to IPSA+ y/n questions, set bYes to 0 to reply with a No or to 1 to reply with Yes. Note that the default values for these are both 1, i.e. all questions will be automatically answered with Yes. Setting the bUseQt to 1 will enable Qt dialogs to be displayed, with the bOverride and bYes settings being ignored.



SetReplyMaxPerOperation(nMaxAutoReplies) - set nMaxAutoReplies to the maximum number of default replies that are given during a single analysis option before the opposite response is given. For example using:

ipsaintf = IscInterface() ipsaintf.SetReplyMaxPerOperation(5) Then when a Load Flow is run after replying Y (Yes) 5 times, N will be passed terminating possible looping beahaviour. Note that the counter is reset after each IPSA analysis function is December 2011

17 Of 31

Scripted IPSA 1.6.8 reference manual run, allowing the next run to reply up to 5 times again.

License and version information • • • • • • • • • • • • • • •

GetVersion() - returns IPSA+ version as a string. HasLoadFlow() - returns true if you have a load flow license. HasFaultLevel() - returns true if you have a fault level license. HasTransient() - returns true if you have a transient license. HasProtection() - returns true if you have a protection license. HasHarmonics() - returns true if you have a Harmonics license. HasUDM() - returns true if you have a UDM license. HasDC() - returns true if you have a DC license. HasStaticCon() - returns true if you have a static converter license. HasTandemGen() - returns true if you have a Tandem Generator license. HasNonLinDevs() - returns true if you have a Non Linear Devs license. HasAutomation() - returns true if you have a Automation license. IsLimitedSize() - returns true if you are running a limited busbar version GetMaxBusbars() - returns max number of busbars if it is a limited busbar version - 0 if unlimited GetLicenseInfo() - returns the license info as a string.

Comparing networks To compare two networks the following functions are available: • •

CreateNetComparator(IscNetwork* pNetwork1, IscNetwork* pNetwork2) - create a network comparison object. Requires two existing IscNetwork objects to be compared. DeleteNetComparator(IscNetComparator* pCompare) - delete a network comparison object.

Comparing results To compare two XML results file the following functions are available: •



CompareIXMLResults(dTolerance,dSmallest,strFile1Name,strFile2Name) – compares two XML results files. Requires two existing XML files to be compared. Returns true if the results arew the same. GetIXMLResultsDiffs(dTolerance,dSmallest,strFile1Name,strFile2Name) compares two XML results files. Requires two existing XML files to be compared. Returns a string of differences.

Debugging Options To aid the development of scripted applications a number of new debugging routines have been added. At present they allow logging and timing of the Load Flow routines. The following functions are available: • • • •

IsLogging() - returns whether logging is on or not. GetDate() - returns the date as a string. GetUser() - returns the user as a string. GetHost() - returns the PC name as a string.

December 2011

18 Of 31

Scripted IPSA 1.6.8 reference manual • • • • • •

GetLogFileName() - returns the log file name. DbgSetLFLogFileName(strName) - set the name of the load flow log file. DbgStartLFLogging() - start logging of all LF engine calls. DbgStopLFLogging() - stop logging of all LF engine calls. DbgShowLFTimings(bShow) - turn on/off LF timings, set bShow to 1 to show timings, 0 to turn them off. DbgShowFLTimings(bShow) - turn on/off FL timings, set bShow to 1 to show timings, 0 to turn them off.

The IscLoad class The IscLoad class provides access to an IPSA+ load, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values:

• • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful



• •

The following fields are available for Loads: • • • • •

IscLoad.BusName - Busbar Name - Get only IscLoad.Name - Real Name - Get only IscLoad.Status - Status IscLoad.RealMW - Real Power (MW) IscLoad.ReactiveMVAr - Reactive Power (MVAr)

To change the power in the load flow engine only: •

SetLFPower(dPMW, dQMVAr) - where dPMW is the new real power in MW, and dQMVAr is the reactive power in MVAr.

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • •

GetPowerMagnitudeMVA() GetPowerMagnitudekVA() GetRealPowerMW()

December 2011

19 Of 31

Scripted IPSA 1.6.8 reference manual • • •

GetReactivePowerMVAr() GetRealPowerkW() GetReactivePowerkVAr()

Fault Level Results There are no Load results at present - they are essentially the same MW/MVar values specified in the data.

Harmonic Penetration results There are no Load specific Harmonic results.

The IscNetComparator class The IscNetComparator class provides a mechanism to compare two networks passed as IscNetwork objects. It is created using the IscInterface class.

Run time settings The following functions are available to get and set run time values: • • • • • •

GetTolerance() - returns the Tolerance used to perform the comparison. GetDisplayVerbosity() - returns the display verbosity used to perform the comparison. GetUsePercent() - returns the tolerance is specified in % used to perform the comparison. SetTolerance(dTolerance) - set the tolerance for the comparison using dTolerance. SetDisplayVerbosity(nVerbosity) - set the displayverbosity for the comparison using nVerbosity. SetUsePercent(bUsePercent) - set whether to run the comparison as a % difference using bUsePercent.

Comparison functions The following comparison functions are available: • • • • • • •

CompareBusbars() - compare the Busbars only. CompareBranches() - compare the Branches only. CompareTransformers() - compare the Transformers only. CompareLoads() - compare the Loads only. CompareSynMachines() - compare the Synchronous Machines only. CompareIndMachines() - compare the Induction Machines only. CompareAll() - compare the entire networks.

Comparison results In general comparison results return lists or maps (in C++ terms) of results. These map December 2011

20 Of 31

Scripted IPSA 1.6.8 reference manual directly to Python tuples or dicts so that standard python iterators can be used. For more specific details see the comparison example code. The following functions are used to retrieve the results of the comparison: • • • • • • • • • • • • • • •

GetVoltageMismatchBusbars() - returns a map of busbar names and voltages of mismatching voltage busbars, GetOnlyNet1Busbars() - returns a map of busbars only present in network 1. GetOnlyNet2Busbars() - returns a map of busbars only present in network 2. GetOnlyNet1Branches() - returns a map of branchs only present in network 1. GetOnlyNet2Branches() - returns a map of branchs only present in network 2. GetOnlyNet1Transformers() - returns a map of transformers only present in network 1. GetOnlyNet2Transformers() - returns a map of transformers only present in network 2. GetOnlyNet1Loads() - returns a map of loads only present in network 1. GetOnlyNet2Loads() - returns a map of loads only present in network 2. GetOnlyNet1SynMachine() - returns a map of synchronous machines only present in network 1. GetOnlyNet2SynMachine() - returns a map of synchronous machines only present in network 2. GetOnlyNet1IndMachine() - returns a map of induction machines only present in network 1. GetOnlyNet2IndMachine() - returns a map of induction machines only present in network 2. GetDifferentComponents() - returns a list of IscNetComponent of different components, GetDifferences(IscNetComponent) - returns a map of FieldType to IscCompareData for a particular component.

The IscNetComponent class The IscNetComponent class is the base class for all IPSA+ components. All functions that are exposed (described below) are also accessible via the derived classes.

Data access The following functions are available to set and get data values:

• •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName) - sets the IPSA+ internal name as a string from strName

• • •

GetFieldType(nFieldIndex) - returns the field type as a string for nFieldIndex. GetFieldName(nFieldIndex) - returns the field name as a string for nFieldIndex. GetDataType() - returns the type of object as a string.



GetType() - returns the type of object, i.e. the type of derived class that this object is. One of: • Busbar • Load • Generator • IndMachine



December 2011

21 Of 31

Scripted IPSA 1.6.8 reference manual • • • •

Line Transformer HarmonicFilter Breaker

Extension Data It is possible to add extension data to an object of any type. The definitions of the data extension fields are held as static data associated with the derived class, i.e. only one copy exists per class. The actual field values on each instanced object are stored with the instance. At present extension data is only accessible through the IPSA+ scripting interface. However all extension data is handled transparently by the IPSA+ filing modules - both inside IPSA+ 1.6.3 and inside the scripting library. All extension data fields are persistent when filed - but currently invisibile inside IPSA+ itself. It should also be mentioned that extension data can only be added to derived classes not to IscNetComponent itself, in fact in core IPSA+ the class is pure, and no there is no function to create an IscNetComponent through the scripting - only derived classes are allowed.

Extension data functions To add extension data to a class: • • • • • •

AddDataExtension(strName, nDefault) - adds an integer data field named strName and returns the new field index. Set the default value to nDefault. AddDataExtension(strName, dDefault) - adds a double data field named strName and returns the new field index. Set the default value to dDefault. AddDataExtension(strName, strDefault) - adds a string data field named strName and returns the new field index. Set the default value to strDefault. AddListIntDataExtension(strName) - adds a list of integers data field named strName and returns the new field index. Set the default value to and empty list. AddListDblDataExtension(strName) - adds a list of doubles data field named strName and returns the new field index. Set the default value to and empty list. AddListStrDataExtension(strName) - adds a list of strings data field named strName and returns the new field index. Set the default value to and empty list.

Note that sets and gets for simple data types (int, double and string) use the standard set/get functions for each derived class. To retrieve the values of complex extension data: • • • • • •

GetListIntExtensionValue(nFieldIndex, nIndex) - get the list ints of for nFieldIndex GetListDblExtensionValue(nFieldIndex, nIndex) - get the list of doubles for nFieldIndex GetListStrExtensionValue(nFieldIndex, nIndex) - get the list of strings for nFieldIndex GetListIntSize(nFieldIndex) - get the size of the list of ints for nFieldIndex GetListDblSize(nFieldIndex) - get the size of the list of doubles for nFieldIndex GetListStrSize(nFieldIndex) - get the size of the list of strings for nFieldIndex

To set the values of complex extension data: • •

SetListIntExtensionValue(nFieldIndex, nIndex, nValue) - set the value of a int in a list of ints for nFieldIndex at position nIndex to a value nValue. SetListDblExtensionValue(nFieldIndex, nIndex, dValue) - set the value of a

December 2011

22 Of 31

Scripted IPSA 1.6.8 reference manual

• • • •

double in a list of doubles for nFieldIndex at position nIndex to a value dValue. SetListStrExtensionValue(nFieldIndex, nIndex, strValue) - set the value of a string in a list of strings for nFieldIndex at position nIndex to a value strValue. PushBackListDblExtensionValue(nFieldIndex, dValue) - add an item to the end of a list of doubles for nFieldIndex. PushBackListIntExtensionValue(nFieldIndex, nValue) - add an item to the end of a list of ints for nFieldIndex. PushBackListStrExtensionValue(nFieldIndex, strValue) - add an item to the end of a list of strings for nFieldIndex.

Component Differences It is possible (but untested - need to try this - sez jbh!) to get the data differences between two components: • • •

Different(IscNetComponent, dTolerance, bUsePercent) - returns true if the data is different . GetDifferences(IscNetComponent, dTolerance, bUsePercent, lDifferences) doubt if this will work... GetDifferences(IscNetComponent, dTolerance, bUsePercent, pmDifferences) doubt if this will work...

Load Flow results Results are not generic so should be accessed through the derived class.

Fault Level Results Results are not generic so should be accessed through the derived class.

Harmonic Penetration results Results are not generic so should be accessed through the derived class.

The IscNetwork class This object provides the main access to an IPSA+ network. It is generally created as the result to a call to IscInterface().ReadFile(name).

Accessing Network components The folowing functions are available to get maps of components: • • • •

GetBusbars() - returns a dictionary containing all the IscBusbar objects in the network using their names as the key GetBranches() - returns a dictionary containing all IscBranch objects in the network using their names as the key GetTransformers() - returns a dictionary containing all IscTransformer objects in the network using their names as the key GetLoads() - returns a dictionary containing all IscLoad objects in the network using

December 2011

23 Of 31

Scripted IPSA 1.6.8 reference manual

• • • •

their names as the key GetSynMachines() - returns a dictionary containing all IscSynMachine objects in the network using their names as the key GetGridInfeeds() - returns a dictionary containing all IscGridInfeed objects in the network using their names as the key GetIndMachines() - returns a dictionary containing all IscIndMachine objects in the network using their names as the key GetHarmonicSources() - returns a dictionary containing all IscHarmonicSource objects in the network using their names as the key

The following functions retrieve a single item by name: • • • • • • • •

GetBusbar(name) - returns an IscBusbar object for the Busbar named name GetBranch(name) - returns an IscBranch object for the Branch named name GetTransformer(name) - returns an IscTransformer object for the Transformer named name GetLoad(name) - returns an IscLoad object for the Load named name GetSynMachine(name) - returns an IscSynMachine object for the SynMachine named name GetGridInfeed(name) - returns an IscGridInfeed object for the GridInfeed named name GetIndMachine(name) - returns an IscIndMachine object for the IndMachine named name GetHarmonicSource(name) - returns an IscHarmonicSource object for the HarmonicSource named name

Network Properties The following functions set and get network properties: • • • • • • • •

GetVersion() - returns the version of the network. GetAuthor() - returns the author of the network. GetCreateDate() - returns the creation date of the network. GetTitle() - returns the title of the network. GetComment() - returns the comment defined for the network. GetBase() - returns the system base in MVA of the network. GetFrequency() - returns the frequency of the network. GetSlackBusbar(nArea) - returns an IscBusbar object for the Busbar for area number nArea.

• • • • • • •

SetAuthor(string) - sets the author of the network. SetCreateDate(string) - sets the creation date of the network. SetTitle(string) - sets the title of the network. SetComment(string) - sets the comment defined for the network. SetBase(double) - sets the system base in MVA of the network. SetFrequency(double) - sets the frequency of the network. SetSlackBusbar(Busbar, nArea) - sets the slack busbar for area number nArea from an IscBusbar object for the Busbar.

Analysis functions To set parameters for analysis use its IscAnalysis object: •

GetAnalysis() - returns an IscAnalysis object for the network which contains the

December 2011

24 Of 31

Scripted IPSA 1.6.8 reference manual analysis parameters The following functions are used to perform analysis: •

DoLoadFlow(bNoEngineLoad, bDontUpdateData) - performs a load flow calculation, returns true if it succeeded. Set bNoEngineLoad to 0 (the default) to load the engine from the IPSA model before doing a load flow calculation. Setting it to 1 skips the load from the IPSA model and uses whatever network is currently loaded in the engine. Set bDontUpdateData to 0 (the default) to allow the Load Flow results to be written back to the network model data (e.g. Busbar voltages and angles). Setting it to 1 skips this stage, so the network model remains the same as was loaded. Note that calling the function with no arguments is allowed and works as if it has been called with bNoEngineLoad and bDontUpdateData set to 0.



DoLoadFlowNoStop(bNoEngineLoad, bDontUpdateData) - performs a load flow calculation, returns true if it succeeded. The flags are the same as for DoLoadFlow(bNoEngineLoad, bDontUpdateData), but this function is not interactive, i.e. it will always run to completion. For example if the number of iterations are set too low, rather than ask to continue it will stop in a non-converged state.



GetLFMessages() - returns the messages as dictionary of message items. Each item consists of an integer message code and the message text. SaveLFState() - Saves the current LF state and returns a state handle to restore it with RestoreLFState(nStateIndex) - Restore the LF state nStateIndex DeleteAllLFStates() - Delete all LF saved states SetFlatStart() - set the network to a flat start. NB - you should have set the values for the flat start in the analysis data first. DoFaultLevel() - performs a fault level calculation, returns true if it succeeded DoIECFaultLevel() - performs an IEC fault level calculation, returns true if it succeeded DoHarmPenetration() - performs a harmonic penetration calculation, returns true if it succeeded DoHarmSensitivity() - performs a harmonic sensitivity calculation, returns true if it succeeded

• • • • • • • •

Filing To create IPSA iif network files use: •

WriteFile(filename) - writes the network in its current state to filename, the name of the file (as a string)

Creating network items The following functions are available to create new network items: • • • • • •

CreateBusbar(Name) - returns an IscBusbar object for the newly created busbar. CreateBranch(FromBusbar, ToBusbar ,Name) - returns an IscBranch object for the newly created branch. CreateTransformer(FromBusbar, ToBusbar,Name) - returns an IscTransformer object for the newly created transformer. CreateLoad(Busbar, Name) - returns an IscLoad object for the newly created load. CreateIndMachine(Busbar, Name) - returns an IscIndMachine object for the newly created induction machine. CreateSynMachine(Busbar, Name) - returns an IscSynMachine object for the newly

December 2011

25 Of 31

Scripted IPSA 1.6.8 reference manual

• • • • •

created synchronous machine. CreateGridInfeed(Busbar, Name) - returns an IscGridInfeed object for the newly created grid infeed. CreateFilter(Busbar, Name) - returns an IscFilter object for the newly created filter. CreateHarmonicSource(Busbar, Name) - returns an IscHarmonicSource object for the newly created harmonic source. CreateBreaker(Branch, Type, Name) - returns an IscBreaker, object for the newly created breaker. CreateGroup(Name, Type) - returns an IscGroup object for the newly created group. Type is one of: • IscGroup.GroupArea • IscGroup.GroupSingle • IscGroup.GroupMixed • IscGroup.GroupLoad • IscGroup.GroupProtection

Deleting network items The following functions are available to delete network items: • • • • • • • • • •

DeleteBusbar(IscBusbar) - deletes a Busbar - pass an IscBusbar object for deletion. DeleteBranch(IscBranch) - deletes a Branch - pass an IscBranch object for deletion. DeleteTransformer(IscTransformer) - deletes a Transformer - pass an IscTransformer object for deletion. DeleteLoad(IscLoad) - deletes a Load - pass an IscLoad object for deletion. DeleteIndMachine(IscIndMachine) - deletes a IndMachine? - pass an IscIndMachine object for deletion. DeleteSynMachine(IscSynMachine) - deletes a SynMachine? - pass an IscSynMachine object for deletion. DeleteSynMachine(IscGridInfeed) - deletes a GridInfeed? - pass an IscGridInfeed object for deletion. DeleteFilter(IscFilter) - deletes a Filter - pass an IscFilter object for deletion. DeleteBreaker(IscBreaker) - deletes a Breaker - pass an IscBreaker object for deletion. DeleteGroup(IscGroup) - deletes a Group - pass an IscGroup object for deletion.

The IscSynMachine class The IscSynMachine class provides access to an IPSA+ generator, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values: • • • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

December 2011

26 Of 31

Scripted IPSA 1.6.8 reference manual • • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful

• •

The following fields are available for Generators: • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

IscSynMachine.BusName - Busbar name - Get only IscSynMachine.Name - Real name - Get only IscSynMachine.Status - Status IscSynMachine.VoltPU - Per unit voltage target IscSynMachine.VoltBandwidthPC - Bandwidth of acceptable busbar voltage IscSynMachine.CtlBusbar - Controlled busbar IscSynMachine.GenMW - Generated real power IscSynMachine.GenMVAr - Generated reactive power IscSynMachine.GenMVArMax - Maximum reactive power limit for PV control IscSynMachine.GenMVArMin - Minimum reactive power limit for PV control IscSynMachine.SynResistancePU - Positive sequence or armature resistance IscSynMachine.SynReactancePU - Positive sequence or d-axis synchronous reactance IscSynMachine.ZSResistancePU - Zero sequence resistance IscSynMachine.ZSReactancePU - Zero sequence reactance IscSynMachine.DAxisTrXPU - D-axis transient reactance IscSynMachine.DAxisTrTCSec - D-axis transient open-circuit time constant IscSynMachine.DAxisStrXPU - D-axis subtransient reactance IscSynMachine.DAxisStrTCSec - D-axis subtransient open-circuit time constant IscSynMachine.QAxisXPU - Q-axis synchronous reactance IscSynMachine.QAxisTrXPU - Q-axis transient reactance IscSynMachine.QAxisTrTCSec - Q-axis transient open-circuit time constant IscSynMachine.QAxisStrXPU - Q-axis subtransient reactance IscSynMachine.QAxisStrTCSec - Q-axis subtransient open-circuit time constant IscSynMachine.InertiaSec - Inertia constant IscSynMachine.DampFactor - Damping factor IscSynMachine.PotierXPU - Potier reactance (required only if a Saturation Factor is entered) IscSynMachine.SaturationFact - pu field current required to generate 1.2 pu voltage on open circuit IscSynMachine.TID - ID for two generators to share the same prime mover - Get only IscSynMachine.PMaxMW - Maximum machine real power IscSynMachine.QMaxMVAr - Maximum machine reactive power IscSynMachine.SMaxMVA - Maximum machine apparent power IscSynMachine.SatDAxisXPU - Saturated d-axis synchronous reactance IscSynMachine.SatDAxisTrXPU - Saturated d-axis transient reactance IscSynMachine.SatDAxisTrTCSec - Saturated d-axis transient open-circuit time constant IscSynMachine.SatDAxisStTrXPU - Saturated d-axis subtransient reactance IscSynMachine.SatDAxisStrTCSec - Saturated d-axis subtransient open-circuit time constant IscSynMachine.SatQAxisStrXPU - Saturated q-axis subtransient reactance

December 2011

27 Of 31

Scripted IPSA 1.6.8 reference manual • • • • • • • • • •

IscSynMachine.DbGenType - Database type - Get only IscSynMachine.DbGenPar - Number of database generators in parallel - Get only IscSynMachine.QMinMVAr - Maximum reactive power the machine can absorb IscSynMachine.DistFactor - Distribution factor (for future use in rescheduling) IscSynMachine.GenCostPerMW - Cost of generating real power IscSynMachine.AbsCostPerMW - Cost of absorbing real power IscSynMachine.GenCostPerMVAr - Cost of generating reactive power IscSynMachine.AbsCostPerMVAr - Cost of absorbing reactive power IscSynMachine.DispPMaxPC - Maximum economic dispatch as a % to the machine maximum power IscSynMachine.DispPMinPC - Minimum economic dispatch as a % to the machine maximum powe

To change the power in the load flow engine only: •

SetLFPower(dPMW, dQMVAr) - where dPMW is the new real power in MW, and dQMVAr is the reactive power in MVAr.

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • • • • •

GetVoltageMagnitudePU() GetVoltageAngleRad() GetVoltageAngleDeg() GetPowerMagnitudeMVA() GetPowerMagnitudekVA() GetRealPowerMW() GetReactivePowerMVAr() GetRealPowerkW() GetReactivePowerkVAr()

Fault Level Results To get fault level Results after running a fault level study, (all return real values): •

GetComponentMagnitude(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent



GetComponentMagnitudeByK(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent

December 2011

28 Of 31

Scripted IPSA 1.6.8 reference manual •

GetComponentAngleRad(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent



GetComponentAngleDeg(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent

• • • • • • •

GetACComponent() GetACComponentByK() GetDCComponent() GetDCComponentByK() GetDCPercentage() Get2ndHarmonic() Get2ndHarmonicByK()

Harmonic Penetration results In general harmonic results return lists or maps (in C++ terms) of results. These map directly to Python tuples or dicts so that standard python iterators can be used. For more specific details see the harmonics example code. The following functions are used to retrieve the Harmonics results for synchronous machines: • • • •

GetCurrentOrders() - returns a list of doubles of Impedance Orders. GetCurrents(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order. GetImpedanceOrders() - returns a list of doubles of Impedance Orders. GetImpedances(const double dOrder) - returns a pair of doubles of Impedances for a particular Impedance Order.

The IscTransformer class The IscTransformer class provides access to an IPSA+ transformer, to set and get data values and to retrieve load flow and fault level results.

Data access The following functions are available to set and get data values: • •

GetName() - gets the name as a string - this is the name Python knows the object by (only identical to the IPSA+ name for busbars) SetName(strName) - sets the name as a string from strName

December 2011

29 Of 31

Scripted IPSA 1.6.8 reference manual • •

GetRealName() - gets the actual IPSA+ internal name as a string SetRealName(strName); - sets the IPSA+ internal name as a string from strName

• • •

GetIValue(nFieldIndex) - returns an integer value for the field nFieldIndex GetDValue(nFieldIndex) - returns an real value for the field nFieldIndex GetSValue(nFieldIndex) - returns an string value for the field nFieldIndex



SetIValue(nFieldIndex, nValue) - set the value for the field nFieldIndex from an integer nValue, returns true if successful SetDValue(nFieldIndex, dValue) - set the value for the field nFieldIndex from an real dValue, returns true if successful SetSValue(nFieldIndex, strValue) - set the value for the field nFieldIndex from an string strValue, returns true if successful

• •

The following fields are available for Transformers: • • • • • • • • • • • • • • • • • • • • • • • •

IscTransformer.FromBusName - sending busbar name - Get only IscTransformer.ToBusName - receiving busbar name - Get only IscTransformer.BranchName - Branch name - Get only IscTransformer.Name - real name - Get only IscTransformer.Winding - Transformer winding connection, specified as sending end winding, receiving end winding, and phase shift IscTransformer.TapNominalPC - Nominal tap position, optionally used in a flat start. IscTransformer.TapStartPC - Present tap position, used as a starting point for the next load flow. IscTransformer.MinTapPC - Minimum tap position, normally negative or zero. IscTransformer.TapStepPC - Tap increment. This defaults to 0.01 if left blank. IscTransformer.MaxTapPC - Maximum tap position, normally positive or zero. IscTransformer.DxDTap - Change in reactance with tap change. This value is used in compounding only, not (for example) fault level. IscTransformer.SpecVPU - Target voltage. Positive means control 'to' busbar, negative means control 'from' busbar. Magnitudes less than 0.5 pu mean fixed tap. IscTransformer.RBWidthPC - Full bandwidth of the voltage sensing relay. This should be larger than tap step size. IscTransformer.CompRPC - Line drop compensation resistance in percent on the compensation rating base. IscTransformer.CompXPC - Line drop compensation reactance in percent on the compensation rating base. IscTransformer.RatingMVA - Rating used for line drop compensation impedances. This can be a different value from the branch rating used for overloads. IscTransformer.PhShiftDeg - Phase shift angle. A positive value makes the receiving end voltage lead the sending end voltage. IscTransformer.SpecPowerMW - Quad Booster target power in MW - can be specified as zero. IscTransformer.SpecPowerAtSend - Control the power at the from side of the transformer IscTransformer.MinPhShiftDeg - Min Phase shift angle - both angle limits are required for Power control. IscTransformer.MaxPhShiftDeg - Max Phase shift angle - both angle limits are required for Power control. IscTransformer.PhShiftStepDeg - Phase shift Step - default value is 0.01 degrees. IscTransformer.DbType - Transformer database type including both tap and impedance information. - Get only IscTransformer.DbParallel - Number of transformers in parallel. This is only used for database transformers - Get only

December 2011

30 Of 31

Scripted IPSA 1.6.8 reference manual

Load Flow results To get load flow Results after running a load flow study, (all return real values): • • • • • • • • •

GetControlledBusbarName() GetSpecVoltagePU() GetActualVoltagePU() GetTapPC() GetMinTapPC() GetMaxTapPC() GetPhShiftDeg() GetPhShiftRad() GetHasCompounding()

Fault Level Results To get fault level Results after running a fault level study, (all return real values): •

• • • • • • • • • •

GetComponentMagnitudeFrom(nComponent) where nComponent is one of: • IscBusbar.MaxComponent • IscBusbar.RedComponent • IscBusbar.YellowComponent • IscBusbar.BlueComponent • IscBusbar.PositiveComponent • IscBusbar.NegativeComponent • IscBusbar.ZeroComponent GetComponentMagnitudeFromByK(nComponent) GetComponentAngleFromRad(nComponent) GetComponentAngleFromDeg(nComponent) GetComponentMagnitudeTo(nComponent) GetComponentMagnitudeToByK(nComponent) GetComponentAngleToRad(nComponent) GetComponentAngleToDeg(nComponent) GetASymMagnitude(nPhase) GetASymMagnitudeByK(nPhase) GetUseASymMagnitude()

Harmonic Penetration results The resulsts for Transformers are accessed via their associated IscBranch component.

December 2011

31 Of 31