2.2.1. Building a scenario and loading data
A description of the simulation scenario must be provided to the simulator before execution.
2.2.1.1. Initializing
Import pyramses and create an instance of pyramses.cfg:
import pyramses
case = pyramses.cfg()
The available methods of pyramses.cfg are fully documented in Full list of functions. The most important are described below.
2.2.1.2. Loading and saving a test case from a configuration file
If a previously saved configuration file exists, it can be used to initialise the descriptor:
import pyramses
case = pyramses.cfg("cmd.txt")
Similarly, a test case can be saved to a configuration file:
case.writeCmdFile('cmd.txt')
Multiple cases can be loaded or saved in a loop:
import pyramses
list_of_cases = []
for i in range(12):
list_of_cases.append(pyramses.cfg('cmd' + str(i) + '.txt'))
for i in range(12):
list_of_cases[i].writeCmdFile('cmd' + str(i) + '.txt')
2.2.1.3. Parameters
The following parameters define the test case scenario.
2.2.1.3.1. Data files
Data files describe the network topology, dynamic models, and solver settings. At least one must be provided:
case.addData('dyn_A.dat')
case.addData('settings1.dat')
case.delData('dyn_A.dat') # Remove a specific data file
case.getData() # Return list of data files
case.clearData() # Remove all data files
Warning
At least one data file must be provided, otherwise the simulator will raise an exception.
2.2.1.3.2. Initialization file
Specifies where the simulator writes the initialisation procedure output:
case.addInit('init.trace')
case.getInit()
Note
This is optional. If omitted, the simulator skips writing initialisation output.
2.2.1.3.3. Disturbance file
Describes the disturbances to be simulated (generator trips, faults, parameter changes, etc.):
case.addDst('events.dst')
case.getDst()
case.clearDst()
Warning
A disturbance file must be provided, otherwise the simulator will raise an exception.
2.2.1.3.4. Trajectory file (results)
Specifies the file where time-series simulation results (trajectories) are saved for post-processing:
case.addTrj('output.trj')
case.getTrj()
This file is used by pyramses.extractor to access results after the simulation completes.
Note
This is optional. If omitted, no trajectory file is written and result extraction via pyramses.extractor will not be possible.
2.2.1.3.5. Observables file
Defines which components and quantities are recorded in the trajectory file:
case.addObs('obs.dat')
case.getObs()
Note
Required when a trajectory file is specified. Defines what data is stored.
2.2.1.3.6. Output trace file
Specifies the main output trace file for simulation progress logging:
case.addOut('output.trace')
case.getOut()
Note
This is optional.
2.2.1.3.7. Continuous trace file
Records information about Newton solver convergence at each step. Useful for debugging but can slow down simulation:
case.addCont('cont.trace')
case.getCont()
Note
This is optional.
2.2.1.3.8. Discrete trace file
Records discrete events: switching actions from disturbance files, discrete controllers, or discrete variables in injector/torque/exciter/two-port models:
case.addDisc('disc.trace')
case.getDisc()
case.clearDisc()
Note
This is optional.
2.2.1.3.9. Runtime observables
Runtime observables are displayed live during simulation using Gnuplot. The following observable types are available:
BV BUSNAME— Voltage magnitude of a bus:case.addRunObs('BV 1041')
MS MACHINE_NAME— Rotor speed of a synchronous machine:case.addRunObs('MS g1')
BPE/BQE/BPO/BQO BRANCH_NAME— Active (P) or reactive (Q) power at the origin (O) or extremity (E) of a branch:case.addRunObs('BPE 1041-01') # Active power at origin of branch 1041-01
ON INJECTOR_NAME OBSERVABLE_NAME— Named observable from an injector model:case.addRunObs('ON WT1a Pw') # Observable Pw from injector WT1a
RT RT— Real-time versus simulated-time plot (useful to gauge simulation speed):case.addRunObs('RT RT') case.clearRunObs() # Remove all runtime observables
Warning
Gnuplot must be installed and available in the system PATH. See Installing Gnuplot (optional).
2.2.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!
- 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.