3.1. Building a scenario and loading data

A description of the simulation needs to be provided to the simulator.

3.1.1. Initializing

We can initialize an instance of the test-case decriptor by importing pyramses and invoking the pyramses.cfg class of pyramses:

import pyramses
case = pyramses.cfg()

The available calls to the pyramses.cfg class are fully documented in code_cases_doc. The most important are detailed below.

3.1.2. Loading and saving test-case to configuration file

If a previously saved configuration file exists, it can be used to initialize the descriptor:

import pyramses
case = pyramses.cfg("cmd.txt") # where cmd.txt is the file with the test-case description

Similarly, a test-case can be saved into a configuration file:

case.writeCmdFile('cmd.txt') # where cmd.txt is the file with the test-case description

Many files can be loaded as follows:

import pyramses
list_of_cases = []
for i in range(12):
   list_of_cases.append(pyramses.cfg('cmd'+str(i)+'.txt')) # loads 12 test-cases from files named 'cmd0.txt', ..., 'cmd11.txt'

Or saved:

for i in range(12):
   list_of_cases[i].writeCmdFile('cmd'+str(i)+'.txt') # saves 12 test-cases to files named 'cmd0.txt', ..., 'cmd11.txt'

3.1.3. Parameters

These are the different parameters that can be defined in the test-case description.

3.1.3.1. Data files

The data files provide a description of the system to be simulated, along with the solver parameters. These files have to be defined in the pyramses.cfg class:

case.addData('data1.dat')
case.addData('data2.dat')

A data file can be removed:

case.delData('data1.dat')

The list of data can be retrieved:

case.getData()

Or all the data files can be removed:

case.clearData()

Warning

At least one data file has to be provided, otherwise the simulator will give an exeption.

3.1.3.2. Initialization file

The initialization file is where the simulator will write the initialization procedure output:

case.addInit('init.trace')

Note

This is optional. It can remain empty and the simulator will skip this step.

3.1.3.3. Disturbance file

The disturbance file is where the disturbance to be simulated is described:

case.addDst('events.dst')

The disturbance file name can be retrieved:

case.getDst()

Or can be cleared:

case.clearDst()

Warning

A disturbance file has to be provided, otherwise the simulator will give an exception.

3.1.3.4. Continuous trace file

The continuous trace file saves information about the convergence of the solution algorithm used inside RAMSES. This is mainly used for debugging reasons and it can slow down the execution of the simulation:

case.addCont('cont.trace')

Note

This is optional. It can remain empty and the simulator will skip this step.

3.1.3.5. Discrete trace file

The discrete trace file saves information about the discrete events in the system, these may be from the discrete controllers, events in the disturbance file, or from discrete variables inside the injector, twoport, torque, or exciter models. It’s defined as:

case.addDisc('disc.trace')

Note

This is optional. It can remain empty and the simulator will skip this step.

3.1.3.6. Runtime observables

This defines some states that will be displayed during the simulation using gnuplot. The available commands are:

  • BV BUSNAME: Voltage magnitude of bus:

    case.addRunObs('BV 1041')
    
  • MS SYNHRONOUS_MACHINE: Synchronous speed of machine:

    case.addRunObs('MS g1')
    
  • RT RT: Real-time vs simulated time plot:

    case.addRunObs('RT RT')
    
  • BPE/BQE/BPO/BQO BRANCH_NAME: Branch active (P), reactive (Q) power at the origin (O) or extremity (E) of a branch:

    case.addRunObs('BPE 1041-01') # active power at the origin of branch 1041-01
    
  • ON INJECTOR_NAME OBSERVABLE_NAME: Monitor a named observable from an injector

    case.addRunObs('ON WT1a Pw') # observable Pw from injector WT1a
    

Warning

Gnuplot should be installed and the executable in the OS Path. Please see start_install_gnuplot.

3.1.4. Full list of functions

class pyramses.cfg(cmd=None)[source]

Test case description class.

addCont(afile)[source]

Add contrinuous trace file

The continuous trace file saves information about the convergence of the solution algorithm used inside RAMSES. This is mainly used for debugging reasons and it can slow down the execution of the simulation.

Parameters

afile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addCont("cont.trace")

Warning

If the file already exists, it will be ovewritten without warning!

addData(datafile)[source]

Add datafile in the dataset.

The data files provide a description of the system to be simulated, along with the solver parameters.

Parameters

datafile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addData("dyn_A.dat")

Warning

At least one file needs to be added.

addDisc(afile)[source]

Add discrete trace file.

The discrete trace file saves information about the discrete events in the system, these may be from the discrete controllers, events in the disturbance file, or from discrete variables inside the injector, twoport, torque, or exciter models.

Parameters

afile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addDisc("disc.trace")

Warning

If the file already exists, it will be ovewritten without warning!

addDst(dstfile)[source]

Add dstfile in the dstset

The disturbance file is where the disturbance to be simulated is described

Parameters

dstfile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addDst("short.dst")

Warning

A file needs to be provided for the simulation to start.

addInit(afile)[source]

Define the file where the simulation initialization will be saved.

The initialization file is where the simulator will write the initialization procedure output.

Parameters

afile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addInit("init.trace")

Warning

If the file already exists, it will be ovewritten without warning!

addObs(ofile)[source]

Add observables file

Parameters

ofile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addObs("obs.dat")
addOut(afile)[source]

Define the file where the simulation output will be saved.

Parameters

afile (str) – the filename. The complete path must be given.

Example

>>> import pyramses
>>> import os
>>> case1 = pyramses.cfg()
>>> case1.addOut(os.path.join(os.getcwd(),'output.trace'))

Note

If the file already exists, the output will be appended to that file.

addRunObs(runobs)[source]

Add runtime observable.

This defines some states that will be displayed during the simulation using gnuplot.

Parameters

runobs (str) – Description of runtime observable as defined in the RAMSES userguide

Example

  • BV BUSNAME: Voltage magnitude of bus:

    >>> case.addRunObs('BV 1041') # observe the bus voltage of bus 1041
    
  • MS SYNHRONOUS_MACHINE: Synchronous speed of machine:

    >>> case.addRunObs('MS g1')
    
  • RT RT: Real-time vs simulated time plot:

    >>> case.addRunObs('RT RT')
    
  • BPE/BQE/BPO/BQO BRANCH_NAME: Branch active (P), reactive (Q) power at the origin (O) or extremity (E) of a branch:

    >>> case.addRunObs('BPE 1041-01') # active power at the origin of branch 1041-01
    
  • ON INJECTOR_NAME OBSERVABLE_NAME: Monitor a named observable from an injector

    >>> case.addRunObs('ON WT1a Pw') # observable Pw from injector WT1a
    
addTrj(afile)[source]

Add trajectory file

Parameters

afile (str) – the filename. The complete path can be given or a the path relative to the working directory (os.getcwd())

Example

>>> import pyramses
>>> case1 = pyramses.cfg()
>>> case1.addTrj("output.trj")

Warning

If the file already exists, it will be ovewritten without warning!

clearData()[source]

Empty the dataset

clearDisc()[source]

Clear discrete trace file

clearDst()[source]

Empty the dstset

clearRunObs()[source]

Clear runtime observables

delData(datafile)[source]

Remove a specific datafile from dataset

getCont()[source]

Return contrinuous trace file

Returns

name of file

Return type

str

getData()[source]

Get datafile list

Returns

list of data file names

Return type

list

getDisc()[source]

Return discrete trace file

Returns

name of discrete trace file

Return type

str

getDst()[source]

Get disturbance

Returns

name of disturbance file

Return type

str

getInit()[source]

Return initialization trace file

Returns

name of file

Return type

str

getObs()[source]

Get observables file name

Returns

name of observables file

Return type

str

getOut()[source]

Return output trace file

Returns

name of file

Return type

str

getTrj()[source]

Return trajectory file

Returns

name of file

Return type

str

writeCmdFile(userFile=None)[source]

Write command file.

Parameters

userFile (str) – The filename to write to (Optional). The complete path can be given or a the path relative to the working directory (os.getcwd()). If a file is not given, then a temporary is created and deleted when the object is destroyed.