goolx

package module
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 27, 2021 License: MIT Imports: 10 Imported by: 3

README

Go Reference Go Report Card

Overview

Disclaimer: This project is not endorsed or affiliated with ASPEN Inc.

goolx is an unofficial Go wrapper around ASPEN's Oneliner API. It can be utilized to create programs which interact with Oneliner through the provided API functions. Additionally, it provides helper functions for common analysis tasks.

The goal of this module is to provide generic unopinionated abstractions for fault analysis. These functions can be used as a building block for useful fault analysis application development.

This library is in Version 0.x.x, and may have breaking API changes during development.

Installation

It is required users of this Go module have authorized licenses for the underlying ASPEN software v15.4 or newer. Obtaining this third-party software is outside the scope of this README.

The module can be installed using the following go get command.

go get -u github.com/readpe/goolx

This library is only designed for use on Windows 386 architecture. To properly build, ensure your GOOS and GOARCH environment variables are set appropriately:

GOOS=windows
GARCH=386

Usage Example

import (
	"fmt"
	"log"

	"github.com/readpe/goolx"
	"github.com/readpe/goolx/constants"
	"github.com/readpe/goolx/model"
)

func main() {
	c := goolx.NewClient()
	defer c.Release() // releases api dll at function return

	// Print the olxapi info.
	info := c.Info()
	fmt.Println(info)

	// Load a oneliner case into memory.
	err := c.LoadDataFile("system.olr")
	if err != nil {
		log.Fatal(err)
	}

	// Loop through all buses in case using NextEquipment iterator.
	buses := c.NextEquipment(constants.TCBus)
	for buses.Next() {
		hnd := buses.Hnd()

		// Get bus data
		b, err := model.GetBus(c, hnd)
		if err != nil {
			log.Println(fmt.Errorf("could not get bus data: %v", err))
			continue
		}
		fmt.Printf("found bus %s %fkV with handle: %d", b.Name, b.KVNominal, b.HND)
	}
}

Acknowledgements

Thanks to ASPEN Inc. for providing the Python API which inspired the development of this module.

Documentation

Index

Examples

Constants

View Source 
const (
	OnelinerVersionSupported = 15.4
	OnelinerBuildSupported   = 17321
)

Supported Oneliner Version/Build

View Source 
const (
	KiB = 1 << (10 * 1)
	MiB = 1 << (10 * 2)
)

Byte size constants

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents a new goolx api client.

func NewClient 

func NewClient() *Client

NewClient returns a new goolx Client instance.

func (*Client) AppendObjMemo added in v0.0.8 

func (c *Client) AppendObjMemo(hnd int, s string) error

AppendObjMemo appends a new line followed by s to the object memo field.

func (*Client) AppendObjTags added in v0.0.7 

func (c *Client) AppendObjTags(hnd int, newTags ...string) error

AppendObjTags appends the provided tags to the object tag string. Does not check for duplicate tags

func (*Client) BuildNumber 

func (c *Client) BuildNumber() (int, error)

BuildNumber parses the build number from the olxapi.dll info function.

func (*Client) CloseDataFile added in v0.0.4 

func (c *Client) CloseDataFile() error

CloseDataFile closes the currently loaded *.olr data file.

func (*Client) DeleteEquipment added in v0.0.4 

func (c *Client) DeleteEquipment(hnd int) error

DeleteEquipment deletes the equipment with the provided handle.

func (*Client) DoFault added in v0.0.3 

func (c *Client) DoFault(hnd int, config *FaultConfig) error

DoFault runs a fault for the given equipment handle with the providedfault configurations. PickFault or NextFault must be called prior to accessing results data.

func (*Client) DoSteppedEvent added in v0.0.4 

func (c *Client) DoSteppedEvent(hnd int, cfg *SteppedEventConfig) error

DoSteppedEvent runs a stepped event analysis for the given equipment with the provided config parameters.

func (*Client) EquipmentType 

func (c *Client) EquipmentType(hnd int) (int, error)

EquipmentType returns the equipment type code for the equipment with the provided handle

func (*Client) FaultDescription added in v0.0.4 

func (c *Client) FaultDescription(index int) string

FaultDescription returns the fault description string for the specified index.

func (*Client) FindBusByName added in v0.0.4 

func (c *Client) FindBusByName(name string, kv float64) (int, error)

FindBusByName returns the bus handle for the given bus name and kv, if found

func (*Client) FindBusNo 

func (c *Client) FindBusNo(n int) (int, error)

FindBusNo returns the bus with the provided bus number. Or returns 0 and an error if not found.

func (*Client) GetData 

func (c *Client) GetData(hnd int, tokens ...int) Data

GetData returns data for the object handle, and all parameter tokens provided. The data for each token can be retrieved using the Scan method on the Data type. This is similar to the Row.Scan in the sql package.

func (*Client) GetObjMemo added in v0.0.8 

func (c *Client) GetObjMemo(hnd int) (string, error)

GetObjMemo returns the object memo field string.

func (*Client) GetObjTags added in v0.0.7 

func (c *Client) GetObjTags(hnd int) (tags []string, err error)

GetObjTags returns a slice of tag strings for the equipment with the provided handle.

func (*Client) GetSCVoltagePhase added in v0.0.8 

func (c *Client) GetSCVoltagePhase(hnd int) (Va, Vb, Vc Phasor, err error)

GetSCVoltagePhase gets the short circuit phase voltage for the equipment with the provided handle. Returns Va, Vb, Vc Phasor types.

func (*Client) GetSCVoltageSeq added in v0.0.8 

func (c *Client) GetSCVoltageSeq(hnd int) (V0, V1, V2 Phasor, err error)

GetSCVoltageSeq gets the short circuit sequence voltagse for the equipment with the provided handle. Returns V0, V1, V2 Phasor types.

func (*Client) Info 

func (c *Client) Info() string

Info calls the OlxAPIVersionInfo function, returning the string

func (*Client) LoadDataFile 

func (c *Client) LoadDataFile(name string) error

LoadDataFile loads *.olr file from disk

func (*Client) NextBusEquipment added in v0.0.7 

func (c *Client) NextBusEquipment(busHnd, eqType int) HandleIterator

NextBusEquipment returns an EquipmentIterator type. The EquipmentIterator will loop through all equipment handles at the provided bus in the case until it reaches the end. This is done using the Next() and Hnd() methods. See NextEquipment for more details.

func (*Client) NextEquipment 

func (c *Client) NextEquipment(eqType int) HandleIterator

NextEquipment returns an EquipmentIterator type. The EquipmentIterator will loop through all equipment handles in the case until it reaches the end. This is done using the Next() and Hnd() methods. Note: ASPEN equipment handle integers are not unique and are generated on data access. Therefore care should be taken when using handle across functions or applications. It is recommended to use the handle immediately after retrieving to get unique equipment identifiers.

func (*Client) NextEquipmentByTag 

func (c *Client) NextEquipmentByTag(eqType int, tags ...string) HandleIterator

NextEquipmentByTag returns a NextEquipmentTag type which satisfies the HandleIterator interface.

func (*Client) NextRelay added in v0.0.7 

func (c *Client) NextRelay(rlyGroupHnd int) HandleIterator

NextRelay returns an HandleIterator type. The HandleIterator will loop through all relay handles in the provided relay group until it reaches the end. This is done using the Next() and Hnd() methods. Note: ASPEN equipment handle integers are not unique and are generated on data access. Therefore care should be taken when using handle across functions or applications. It is recommended to use the handle immediately after retrieving to get unique equipment identifiers.

func (*Client) ObjMemoContains added in v0.0.8 

func (c *Client) ObjMemoContains(hnd int, substr string) bool

ObjMemoContains reports whether substr is within the objects memo field.

func (*Client) PickFault added in v0.0.8 

func (c *Client) PickFault(indx, tiers int) error

PickFault must be called before accessing short circuit simulation data. The given index and number of tiers to be calculated are provided. See NextFault for an iterator which automatically switches from SFFirst to SFNext after the first fault until the last. 

The index codes are:
	SFLast     = -1
	SFNext     = -2
	SFFirst    = 1
	SFPrevious = -4

func (*Client) ReadChangeFile 

func (c *Client) ReadChangeFile(name string) error

ReadChangeFile reads *.chf file from disk and applies to case

func (*Client) Release 

func (c *Client) Release() error

Release releases the api dll. Must be called when done with use of dll.

func (*Client) ReplaceAllObjMemo added in v0.0.8 

func (c *Client) ReplaceAllObjMemo(hnd int, old, new string) error

ReplaceAllObjMemo replaces all non-overlapping instances of old replaced by new in the object memo field.

func (*Client) ReplaceObjTag added in v0.0.7 

func (c *Client) ReplaceObjTag(hnd int, oldTag, newTag string) error

ReplaceObjTag replaces all occurences of the old tag with the new tag provided.

func (*Client) SaveDataFile 

func (c *Client) SaveDataFile(name string) error

SaveDataFile saves *.olr file to disk

func (*Client) SetObjMemo added in v0.0.8 

func (c *Client) SetObjMemo(hnd int, memo string) error

SetObjMemo sets the object memo field, overwrites existing data.

func (*Client) SetObjTags added in v0.0.7 

func (c *Client) SetObjTags(hnd int, tags ...string) error

SetObjTags replaces the object tag with the provided tags. Will override existing tags, use GetObjTags to retrieve existing tags and append to if the wanting to keep existing tags.

func (*Client) Version 

func (c *Client) Version() (string, error)

Version parses the version number from the olxapi.dll info function.

type Data 

type Data struct {
	// contains filtered or unexported fields
}

Data represents data returned via the GetData method.

func (Data) Scan 

func (d Data) Scan(dest ...interface{}) error

Scan copies the data from the matched parameter token into the values pointed at by dest. The order of the destination pointers should match the parameters queried with GetData. Will return an error if any parameters produced an error during GetData call. Data will not be populated in this case.

Example 
// Create API client.
api := NewClient()

// Load data file, and find bus handle.
api.LoadDataFile(testCase)
busHnd, err := api.FindBusByName("TENNESSEE", 132)
if err != nil {
	return
}

// Get bus name and kv data.
data := api.GetData(busHnd, constants.BUSsName, constants.BUSdKVnominal)

// Scan loads the data into the pointers provided. Types must match the tokens provided.
var name string
var kV float64
data.Scan(&name, &kV)

fmt.Printf("Name: %s\n", name)
fmt.Printf("kV: %0.2f\n", kV)

Output:

Name: TENNESSEE
kV: 132.00

type FaultConfig added in v0.0.3 

type FaultConfig struct {
	// contains filtered or unexported fields
}

FaultConfig represents configuration parameters required to run the Oneliner DoFault procedure. Options are configured by passing one or more of the FaultOption functions provided into the NewFaultConfig function.

func New1LGFaultConfig added in v0.0.3 

func New1LGFaultConfig() *FaultConfig

New1LGFaultConfig is a helper function to return a new 1LG FaultConfig instance. See NewFaultConfig for more specifics.

func New3LGFaultConfig added in v0.0.3 

func New3LGFaultConfig() *FaultConfig

New3LGFaultConfig is a helper function to return a new 3LG FaultConfig instance. See NewFaultConfig for more specifics.

func NewFaultConfig added in v0.0.3 

func NewFaultConfig(options ...FaultOption) *FaultConfig

NewFaultConfig returns a pointer to a new instance of FaultConfig for use with the Oneliner DoFault procedure. Provide FaultOption functions to modify the underlying parameters.

type FaultOption added in v0.0.4 

type FaultOption func(*FaultConfig)

FaultOption represents configuration modification functions to apply to the FaultConfig data.

func FaultClearPrev added in v0.0.3 

func FaultClearPrev(e bool) FaultOption

FaultClearPrev sets the clear previous flag. True will clear the previous fault results.

func FaultCloseIn added in v0.0.3 

func FaultCloseIn() FaultOption

FaultCloseIn applies a close-in fault.

func FaultCloseInEndOpen added in v0.0.4 

func FaultCloseInEndOpen() FaultOption

FaultCloseInEndOpen applies a close-in fault with the end open as determined by the Oneliner algorithm for determining the end of the line.

func FaultCloseInEndOpenOutage added in v0.0.4 

func FaultCloseInEndOpenOutage(outageList []int, otgOpt OutageOption) FaultOption

FaultCloseInEndOpenOutage applies a close-in fault with outages and the end open as determined by the Oneliner algorithm for determining the end of the line. An outage list and options are required.

func FaultCloseInOutage added in v0.0.4 

func FaultCloseInOutage(outageList []int, otgOpt OutageOption) FaultOption

FaultCloseInOutage applies a close-in fault with outages on the system. An outage list and options are required.

func FaultConn added in v0.0.3 

func FaultConn(conn ...FltConn) FaultOption

FaultConn applies the provided fault connections. Overrides the previous fault connections.

func FaultIntermediate added in v0.0.4 

func FaultIntermediate(percent float64) FaultOption

FaultIntermediate applies an intermediate fault at the provided percentage.

func FaultIntermediateAuto added in v0.0.4 

func FaultIntermediateAuto(step, from, to float64) FaultOption

FaultIntermediateAuto applies an auto sequencing intermediate fault between from and to at the specified step.

func FaultIntermediateEndOpen added in v0.0.4 

func FaultIntermediateEndOpen(percent float64) FaultOption

FaultIntermediate applies an intermediate fault with at the provided percentage with the end open.

func FaultIntermediateEndOpenOutage added in v0.0.4 

func FaultIntermediateEndOpenOutage(percent float64, outageList []int, otgOpt OutageOption) FaultOption

FaultIntermediateEndOpenOutage applies an intermediate fault with at the provided percentage with the end open and outages. An outage list and options are required.

func FaultIntermediateOutage added in v0.0.4 

func FaultIntermediateOutage(percent float64, outageList []int, otgOpt OutageOption) FaultOption

FaultIntermediate applies an intermediate fault with outage at the provided percentage. An outage list and options are required.

func FaultLineEnd added in v0.0.4 

func FaultLineEnd() FaultOption

FaultLineEnd applies a line end fault, as determined by Oneliners algorithm for determining line end.

func FaultLineEndOutage added in v0.0.4 

func FaultLineEndOutage(outageList []int, otgOpt OutageOption) FaultOption

FaultLineEndOutage applies a line end fault with outages. Line end is determined by Oneliners algorithm for determining line end. An outage list and options are required.

func FaultOptions added in v0.0.5 

func FaultOptions(options ...FaultOption) FaultOption

FaultOptions consolidates a list of FaultOptions to a single FaultOption.

func FaultRX added in v0.0.3 

func FaultRX(r, x float64) FaultOption

FaultRX sets the fault impedance in Ohms.

func FaultRemoteBus added in v0.0.4 

func FaultRemoteBus() FaultOption

FaultRemoteBus applies a remote bus fault.

func FaultRemoteBusOutage added in v0.0.4 

func FaultRemoteBusOutage(outageList []int, otgOpt OutageOption) FaultOption

FaultRemoteBusOutage applies a remote bus fault with outages. An outage list and options are required.

type FltConn added in v0.0.5 

type FltConn int

FltConn represents a fault connection for use with the DoFault procedure. The codes are applied to FaultConfig and SteppedEventConfig as specified in ASPEN Oneliner documentation. 

const (
	// Three phase fault.
	ABC FltConn = iota
	// Phase-Phase-Ground faults.
	BCG
	CAG
	ABG

	// Phase-Ground faults.
	AG
	BG
	CG

	// Phase-Phase faults.
	BC
	CA
	AB
)

Fault connection codes.

type HandleIterator 

type HandleIterator interface {
	Next() bool
	Hnd() int
}

HandleIterator is a iterator interface for equipment handles.

type NextBusEquipment added in v0.0.7 

type NextBusEquipment struct {
	// contains filtered or unexported fields
}

NextBusEquipment is an equipment handle iterator for getting the next equipment handle of the provided type at the specified bus. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextBusEquipment) Hnd added in v0.0.7 

func (n *NextBusEquipment) Hnd() int

Hnd returns the current equipment handle, Next() must be called first.

func (*NextBusEquipment) Next added in v0.0.7 

func (n *NextBusEquipment) Next() bool

Next retrieves the next equipment handle of type at the specified bus. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.

type NextEquipment 

type NextEquipment struct {
	// contains filtered or unexported fields
}

NextEquipment is an equipment handle iterator for getting the next equipment handle of the provided type. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextEquipment) Hnd 

func (n *NextEquipment) Hnd() int

Hnd returns the current equipment handle, Next() must be called first.

func (*NextEquipment) Next 

func (n *NextEquipment) Next() bool

Next retrieves the next equipment handle of type. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.

type NextEquipmentByTag 

type NextEquipmentByTag struct {
	// contains filtered or unexported fields
}

NextEquipmentByTag is an equipment handle iterator for getting the next equipment handle of the provided type with the listed tags. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextEquipmentByTag) Hnd 

func (n *NextEquipmentByTag) Hnd() int

Hnd returns the current equipment handle, Next() must be called first.

func (*NextEquipmentByTag) Next 

func (n *NextEquipmentByTag) Next() bool

Next retrieves the next equipment handle of type. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.

type NextRelay added in v0.0.7 

type NextRelay struct {
	// contains filtered or unexported fields
}

NextRelay is an handle iterator for getting the next relay handle in the provided relay group. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextRelay) Hnd added in v0.0.7 

func (n *NextRelay) Hnd() int

Hnd returns the current relay handle, Next() must be called first.

func (*NextRelay) Next added in v0.0.7 

func (n *NextRelay) Next() bool

Next retrieves the next relay handle int he relay group. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.

type OutageOption added in v0.0.3 

type OutageOption int

OutageOption represents a the method outages are applied with use in the DoFault procedure. 

const (
	OutageOptionOnePer OutageOption = iota // One at a time
	OutageOptionTwoPer                     // Two at a time
	OutageOptionAll                        // All at once
	OutageOptionBF                         // Breaker failure
)

type Phasor added in v0.0.8 

type Phasor complex128

Phasor represents a phasor value for common power system calculations.

func NewPhasor added in v0.0.8 

func NewPhasor(mag, ang float64) Phasor

NewPhasor returns a new phasor instance.

func PhaseToSeq added in v0.0.8 

func PhaseToSeq(a, b, c Phasor) (seq0, seq1, seq2 Phasor)

PhaseToSeq converts from phase values to sequential components. Three phase only.

func SeqToPhase added in v0.0.8 

func SeqToPhase(seq0, seq1, seq2 Phasor) (a, b, c Phasor)

SeqToPhase converts from sequential compoents to phase values. Three phase only.

func (Phasor) Ang added in v0.0.8 

func (p Phasor) Ang() float64

Ang returns the Phasor angle in degrees.

func (Phasor) Mag added in v0.0.8 

func (p Phasor) Mag() float64

Mag returns the Phasor absolute magnitude.

func (Phasor) Rect added in v0.0.8 

func (p Phasor) Rect() complex128

Rect returns the complex128 representation.

func (Phasor) String added in v0.0.8 

func (p Phasor) String() string

String implements the stringer interface for the Phasor type.

type SteppedEventConfig added in v0.0.4 

type SteppedEventConfig struct {
	// contains filtered or unexported fields
}

SteppedEventConfig represents the configuration options for running stepped event analysis, for use with DoSteppedEvent function.

func NewSteppedEvent added in v0.0.4 

func NewSteppedEvent(options ...SteppedEventOption) *SteppedEventConfig

NewSteppedEvent returns a new SteppedEventConfig instance with the applied options. The default number of tiers is 3, this can be changed using the SteppedEventTiers option.

type SteppedEventOption added in v0.0.4 

type SteppedEventOption func(cfg *SteppedEventConfig)

SteppedEventOption represents a function to modify the SteppedEventConfig options.

func SteppedEventAll added in v0.0.4 

func SteppedEventAll() SteppedEventOption

SteppedEventAll option enabled checking all relay types during stepped event simulation.

func SteppedEventCloseIn added in v0.0.4 

func SteppedEventCloseIn() SteppedEventOption

SteppedEventCloseIn applies a close-in fault by setting the intermediate to 0.

func SteppedEventConn added in v0.0.4 

func SteppedEventConn(conn FltConn) SteppedEventOption

SteppedEventConn sets the fault connection code.

func SteppedEventDSGnd added in v0.0.4 

func SteppedEventDSGnd() SteppedEventOption

SteppedEventDSGnd option enables ground distance relays during stepped event simulation.

func SteppedEventDSPh added in v0.0.4 

func SteppedEventDSPh() SteppedEventOption

SteppedEventDSPh option enables phase distance relays during stepped event simulation.

func SteppedEventDiffRelay added in v0.0.4 

func SteppedEventDiffRelay() SteppedEventOption

SteppedEventDiffRelay option enables differential relays during stepped event simulation.

func SteppedEventIntermediate added in v0.0.4 

func SteppedEventIntermediate(percent float64) SteppedEventOption

SteppedEventIntermediate applies an intermediate fault at the given percentage.

func SteppedEventLogicScheme added in v0.0.4 

func SteppedEventLogicScheme() SteppedEventOption

SteppedEventLogicScheme option enables protection schemes during stepped event simulation.

func SteppedEventLogicVoltRelay added in v0.0.4 

func SteppedEventLogicVoltRelay() SteppedEventOption

SteppedEventLogicVoltRelay option enables voltage relays during stepped event simulation.

func SteppedEventOCGnd added in v0.0.4 

func SteppedEventOCGnd() SteppedEventOption

SteppedEventOCGnd option enables ground overcurrent relays during stepped event simulation.

func SteppedEventOCPh added in v0.0.4 

func SteppedEventOCPh() SteppedEventOption

SteppedEventOCPh option enables phase overcurrent relays during stepped event simulation.

func SteppedEventOptions added in v0.0.4 

func SteppedEventOptions(options ...SteppedEventOption) SteppedEventOption

SteppedEventOptions consolidates a list of SteppedEventOption's into a single SteppedEventOption.

func SteppedEventRX added in v0.0.4 

func SteppedEventRX(r, x float64) SteppedEventOption

SteppedEventRX sets the stepped event fault impedance.

func SteppedEventTiers added in v0.0.4 

func SteppedEventTiers(n int) SteppedEventOption

SteppedEventTiers option sets the number of tiers from the initiating equipment to be evaluated.

Source Files

View all Source files

Directories

Path Synopsis
internal
olxapi
Package model provides data structures and helper functions for loading common Oneliner equipment models.
 Package model provides data structures and helper functions for loading common Oneliner equipment models.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.