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 Full list of functions. 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 Installing Gnuplot (optional).

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.