2.2.3. Simulation result processing and visualisation

The pyramses.extractor class provides methods to extract and visualise time-series results from a trajectory file produced during simulation.

2.2.3.1. Initializing

Pass the trajectory file path to the extractor:

import pyramses
case = pyramses.cfg('cmd.txt')
# ... run simulation ...
ext = pyramses.extractor(case.getTrj())

Alternatively, provide the file path directly:

ext = pyramses.extractor('output.trj')

All data objects returned by the extractor carry a time array (seconds), a value array, and a msg description string. They also expose a .plot() method for quick visualisation.

2.2.3.2. Extracting bus data

Retrieve voltage magnitude and phase angle time series for a bus:

bus = ext.getBus('4044')
bus.mag.plot()   # voltage magnitude (pu)
bus.pha.plot()   # voltage phase angle (rad)

2.2.3.3. Extracting synchronous machine data

Retrieve the full set of synchronous machine observables:

gen = ext.getSync('g1')
gen.P.plot()    # active power (MW)
gen.Q.plot()    # reactive power (Mvar)
gen.S.plot()    # rotor speed (pu)
gen.A.plot()    # rotor angle w.r.t. COI (deg)
gen.FV.plot()   # field voltage (pu)
gen.FC.plot()   # field current (pu)
gen.T.plot()    # mechanical torque (pu)
gen.ET.plot()   # electromagnetic torque (pu)

Available observables: P, Q, A (rotor angle), S (speed), FW (field winding flux), DD (d1 damper flux), QD (q1 damper flux), QW (q2 winding flux), FC (field current), FV (field voltage), T (mechanical torque), ET (electromagnetic torque), SC (COI speed).

2.2.3.4. Extracting exciter data

exc = ext.getExc('g1')
exc.obsdict              # dict of observable name → description
exc.vf.plot()            # field voltage (model-dependent observable name)

Available observables depend on the exciter model. Use exc.obsdict to list what is available.

2.2.3.5. Extracting governor/torque data

gov = ext.getTor('g1')
gov.Pm.plot()    # mechanical power (pu)

Available observables depend on the governor model. Use gov.obsdict to list what is available.

2.2.3.6. Extracting injector data

inj = ext.getInj('WT1a')
inj.Pw.plot()    # wind power (model-dependent)
inj.obsdict      # dict of available observables

Injectors include renewable energy sources (wind, PV, BESS), loads, and other single-bus components.

2.2.3.7. Extracting two-port data

twop = ext.getTwop('hvdc1')
twop.P1.plot()   # active power at terminal 1
twop.P2.plot()   # active power at terminal 2
twop.obsdict     # dict of available observables

Two-port models include HVDC links (LCC and VSC), SVCs, and DC systems.

2.2.3.8. Extracting discrete controller data

dctl = ext.getDctl('1-1041')
dctl.obsdict     # dict of available observables

Discrete controllers include LTC transformers, under-voltage load shedding, phase shifters, etc.

2.2.3.9. Extracting branch data

branch = ext.getBranch('1041-01')
branch.PF.plot()   # active power at FROM end (MW)
branch.QF.plot()   # reactive power at FROM end (Mvar)
branch.PT.plot()   # active power at TO end (MW)
branch.QT.plot()   # reactive power at TO end (Mvar)
branch.RM.plot()   # transformer ratio magnitude
branch.RA.plot()   # transformer phase angle (deg)

2.2.3.10. Plotting multiple curves

Use pyramses.curplot() to display multiple curves on the same axes:

import pyramses
ext = pyramses.extractor(case.getTrj())

curves = [
    ext.getSync('g1').S,
    ext.getSync('g2').S,
    ext.getSync('g3').S,
]
pyramses.curplot(curves)

Each curve object has a msg field used as the legend label.

2.2.3.11. Individual curve objects

All extraction methods return curve objects (pyramses.cur named tuples) with the following attributes:

time — NumPy array of time values (seconds)
value — NumPy array of data values
msg — Description string used as plot label
plot() — Display the curve using Matplotlib

2.2.3.12. Full list of functions

class pyramses.extractor(traj)[source]

The extractor class is used to extract the timeseries data after the simulation and process them.

Parameters: rtraj (str) – the path to the ramses trajectory file. This should be the same file that was set in the case with case.addTrj(‘filenm.rtrj’).
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getBus('1041').mag.plot() # will plot the timeseries simulated for the voltage magnitude on bus '1041'

getBranch(braname)[source]

Returns an object that allows to extract or plot branch related variables.

Parameters: braname (str) – the name of the branch
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getBranch('1041-4041').PF.plot() # will plot the timeseries simulated for the active power of line'1041-4041' 

Note

Available data are obsnames = [‘PF’,’QF’,’PT’,’QT’,’RM’,’RA’] obsdesc = [‘P (MW) entering at FROM end’, ‘Q (Mvar) entering at FROM end’,

‘P (MW) entering at TO end’, ‘Q (Mvar) entering at TO end’, ‘magnitude of transformer ratio’,’phase angle of transformer ratio (deg)’]

getBus(busname)[source]

Returns an object that allows to extract or plot bus related variables.

Parameters: busname (str) – the name of the bus
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getBus('1041').mag.plot() # will plot the timeseries simulated for the voltage magnitude on bus '1041' 

Note

Available data are obsnames = [‘mag’,’pha’] obsdesc = [‘Voltage magnitude (pu)’,’Voltage phase angle (deg)’]

getDctl(dctlname)[source]

Returns an object that allows to extract or plot dctl related variables.

Parameters: dctlname (str) – the name of the dctl
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getDctl('agc').g5.plot() # will plot the timeseries simulated for the power of 'g5' 

getExc(syncname)[source]

Returns an object that allows to extract or plot exciter related variables.

Parameters: syncname (str) – the name of the generator that we want to check the exciter
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getExc('g1').vf.plot() # will plot the timeseries simulated for the field voltage of 'g1' 

getInj(injname)[source]

Returns an object that allows to extract or plot injector related variables.

Parameters: injname (str) – the name of the injector
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getInj('pv1').P.plot() # will plot the timeseries simulated for the active power of 'pv1' 

getLoad(ldname)[source]

Returns an object that allows to extract or plot load related variables.

Parameters: ldname (str) – the name of the load
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getLoad('L_1').P.plot() # will plot the timeseries simulated for the active power of 'L_1' 

Note

Available data are obsnames = [‘P’,’Q’] obsdesc = [‘Active power consumed (MW)’,’Reactive power consumed (Mvar)’]

getShunt(shuname)[source]

Returns an object that allows to extract or plot shunt related variables.

Parameters: shuname (str) – the name of the shunt
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getShunt('sh1').Q.plot() # will plot the timeseries simulated for the reactive power of shunt 'sh1' 

Note

Available data are obsnames = [‘Q’] obsdesc = [‘Reactive power produced (Mvar)’]

getSync(syncname)[source]

Returns an object that allows to extract or plot synchronous machine related variables.

Parameters: syncname (str) – the name of the sync machine
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getSync('g1').P.plot() # will plot the timeseries simulated for the active power of 'g1' 

Note

Available data are * obsnames = [‘P’,’Q’,’A’,’S’,’FW’,’DD’,’QD’,’QW’,’FC’,’FV’,’T’,’ET’,’SC’] * obsdesc = [‘active power produced (MW)’,

‘reactive power produced (Mvar)’, ‘rotor angle wrt COI (deg)’, ‘rotor speed (pu)’, ‘flux in field winding (pu mach. base) ‘, ‘flux in d1 damper (pu mach. base) ‘, ‘flux in q1 damper (pu mach. base) ‘, ‘flux in q2 winding (pu mach. base) ‘, ‘field current (pu) ‘, ‘field voltage (pu) ‘, ‘mechanical torque (pu) ‘, ‘electromagnetic torque (pu mach. base) ‘, ‘speed of COI reference (pu) ‘]

getTor(syncname)[source]

Returns an object that allows to extract or plot governor related variables.

Parameters: syncname (str) – the name of the generator that we want to check the governor
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getTor('g1').Tm.plot() # will plot the timeseries simulated for the torque of 'g1' 

getTwop(twopname)[source]

Returns an object that allows to extract or plot twoport related variables.

Parameters: twopname (str) – the name of the twoport
Example

>>> import pyramses
>>> case = pyramses.cfg("case.rcfg") # load case from a configuration file
>>> ram = pyramses.sim()
>>> ram.execSim(case) # run the simulation
>>> ext = pyramses.extractor(case.getTrj())
>>> ext.getTwop('lcc1').P1.plot() # will plot the timeseries simulated for the power of 'lcc1' 