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.

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')


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]

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()


Warning

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

addData(datafile)[source]

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()


Warning

At least one file needs to be added.

addDisc(afile)[source]

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()


Warning

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

addDst(dstfile)[source]

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()


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()


Warning

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

addObs(ofile)[source]

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()

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()


Note

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

addRunObs(runobs)[source]

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]

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()


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.