OPLEM API Reference

Assets

Asset module

Asset objects define distributed energy resources (DERs) and loads. Attributes include network location, phase connection and real and reactive output power profiles over the simulation time-series. Flexible Asset classes have an update control method, which is called by EnergySystem simulation methods with control references to update the output power profiles and state variables. The update control method also implements constraints which limit the implementation of references.

OPLEM includes the following Asset subclasses: NondispatchableAsset for uncontrollable loads and generation sources, StorageAsset for storage systems and BuildingAsset for buildings with flexible heating, ventilation and air conditioning (HVAC).

class Assets.Asset(bus_id, dt, T, dt_ems, T_ems, phases=[0, 1, 2])

An energy resource located at a particular bus in the network :param bus_id: id number of the bus in the network :type bus_id: float :param dt: simulation time interval duration (h) :type dt: float :param T: number of simulation time intervals :type T: int :param dt_ems: optimisation time interval duration (h) :type dt_ems: float :param T_ems: number of optimisation time intervals :type T_ems: int :param phases: [0, 1, 2] indicates 3 phase connection

Wye: [0, 1] indicates an a,b connection

Delta: [0] indicates a-b, [1] b-c, [2] c-a

Return type:

Asset

class Assets.BuildingAsset(Tmax, Tmin, Hmax, Cmax, T0, C, R, CoP_heating, CoP_cooling, Ta, bus_id, dt, T, dt_ems, T_ems, phases=[0, 1, 2])

A building asset (use for flexibility from building HVAC)

Parameters:

• Tmax (float) – Maximum temperature inside the building (Degree C) optimisation time scale

• Tmin (float) – Minimum temperature inside the building (Degree C) optimisation time scale

• Hmax (float) – Maximum power consumed by electrical heating (kW)

• Cmax (float) – Maximum power consumed by electrical cooling (kW)

• T0 (float) – Initial temperature inside the buidling (Degree C)

• C (float) – Thermal capacitance of building (kWh/Degree C)

• R (float) – Thermal resistance of building to outside environment(Degree C/kW)

• CoP_heating (float) – Coefficient of performance of the heat pump (N/A)

• CoP_cooling (float) – Coefficient of performance of the chiller (N/A)

• Ta (numpy.ndarray (T_ems,)) – Ambient temperature (Degree C) in the optimisation time scale

• bus_id (float) – id number of the bus in the network

• dt (float) – simulation time interval duration (h)

• T (int) – number of simulation time intervals

• dt_ems (float) – time interval duration (optimisation time scale) (h)

• T_ems (int) – number of time intervals (optimisation time scale)

• phases (list, default [0,1,2]) –

  [0, 1, 2] indicates 3 phase connection

  Wye: [0, 1] indicates an a,b connection

  Delta: [0] indicates a-b, [1] b-c, [2] c-a

• delta (float) – deadband (Degree C)

• alpha (float) – Coefficient of previous temperature in the temperature dynamics equation (N/A)

• beta (float) – Coefficient of power consumed to heat/cool the building in the temperature dynamics equation (Degree C/kW)

• gamma (float) – Coefficient of ambient temperature in the temperature dynamics equation (N/A)

• Pnet (numpy.ndarray (T,)) – Input real power over the simulation time series (kW)

• Pnet_ems (numpy.ndarray (T_ems,)) – Input real power over the optimisation time series (kW)

• Qnet (numpy.ndarray (T,)) – Input reactive power over the simulation time series(kVAR)

• Qnet_ems (numpy.ndarray (T_ems,)) – Input reactive power over the optimisation time series(kVAR)

• Tin (numpy.ndarray (T,)) – indoor temperature in the building over the simulation time series (Degree C)

• Tin_ems (numpy.ndarray (T_ems,)) – indoor temperature in the building over the optimisation time series (Degree C)

Return type:

Building Asset

flexibility(T_flex, flex_min=None, flex_type='up')

Compute the flexibility that can be provided by the HVAC for the flexibility period T_flex

Parameters:

• T_flex (numpy.ndarray) – period of flexibility [t_start, t_end]

• flex_type ({'down', 'up'}, default 'up') –

  the type of flexibility to provide

  ’up’ : to decrease consumption of the HVAC in flexibility period

  ’down’: to increase consumption of the HVAC in flexibility period

Returns:

Flex – the flexibility

Return type:

float

maxdemand_baseline()

Compute the baseline consumption of the building by minimizing the peak demand

Returns:

• P_th (numpy.ndarray (T_ems,)) – thermal energy schedule

• P_el (numpy.ndarray (T_ems,)) – daily electrical schedule

polytope(t0=0)

Computes the polytope representation of the asset operational constraints in the optimisation time scale Ax <= b,

with x=[P_h, P_c] and P_h/c is the heating/cooling power over the optimisation horizon T_ems

Following [1]

Parameters:

t0 (int, default 0) – starting time slot for the polytope model in optimisation time scale

Returns:

A, b – slope and intercept

Return type:

(6 (T_ems-t_ahead_0), 2 (T_ems-t_ahead_0)), numpy.ndarray (6 (T_ems-t_ahead_0,)

toup_baseline(toup)

Compute the baseline consumption of the building

Parameters:

toup (numpy.ndarray (T_ems,)) – time of use price

Returns:

• P_th (numpy.ndarray (T_ems,)) – thermal energy schedule

• P_el (numpy.ndarray (T_ems,)) – daily electrical schedule

update_control(Pnet, t0=0, enforce_const=True)

Update the indoor temperature and the hvac power (if enforce_const is set to True)

Parameters:

• Pnet (numpy.ndarray (T,)) – input powers over the simulation time series (kW)

• enforce_const (bool, default True) – enforce indoor temperature limits constraints or not

• t0 (int, default=0) – starting time interval (over simulation time scale T) for the update

update_discrete(action, t, enforce_const=True)

Update the power schedule with a discrete EMS signal

Parameters:

• action ({-1,0,1}) – 1=heating ON, -1=cooling ON, 0=OFF

• t (int) – time interval for the update

• enforce_const (bool, default True) – enforce operational constraints on Tin ([Tmin, Tmax]) or not

update_ems(Pnet_ems, t0=0, enforce_const=True)

update the power schedule according to the EMS signal

Parameters:

• Pnet_ems (numpy.ndarray (T_ems,)) – the EMS schedule

• t0 (int) – the time start of the update, default=0

• enforce_const (bool, default True) – enforce indoor temperature limits constraints or not

class Assets.NondispatchableAsset(Pnet, Qnet, bus_id, dt, T, dt_ems, T_ems, phases=[0, 1, 2], Pnet_pred=None, Qnet_pred=None, curt=False, LoG='load')

A 3 phase nondispatchable asset class (use for inflexible loads, PVsources etc)

Parameters:

• Pnet (numpy.ndarray (T,)) – uncontrolled real input powers over the simulation time series

• Qnet (numpy.ndarray (T,)) – uncontrolled reactive input powers over the simulation time series (kVar)

• Pnet_pred (numpy.ndarray (T,), default None) – predicted real input powers over the simulation time series (kW)

• Qnet_pred (numpy.ndarray (T,), default None) – predicted reactive input powers over the simulation time series (kVar)

• curt (bool, default False) – if the power can be curtailed or not

Return type:

Non-dispachable Asset

mpc_demand(t0=0, q_val=False)

a power vector composed of the actual realisation of the current time step and the predicted values for the future time steps

Parameters:

• t0 (int, default=0) – first time slot of observation

• q_val (bool, default false) – returns reactive power values or not

Returns:

• demand (numpy.ndarray (T_ems,)) – power vector

• qdemand (numpy.ndarray (T_ems,)) – reactive power vector

polytope(t0)

Computes the polytope representation of the asset operational constraints following the optimisation time scale Ax <= b,

with x=[P_in, P_out] and P_in (P_out) is the absorbed (injected) power over the optimisation horizon T_ems

Following [1]

Parameters:

t0 (int, default=0) – starting time slot for the polytope model in optimisation time scale

Returns:

A, b – slope and intercept

Return type:

(6 (T_ems-t_ahead_0), 2 (T_ems-t_ahead_0)), numpy.ndarray (6 (T_ems-t_ahead_0,)

update_ems(curt, t0=0)

Update the schedule of the asset based on the curt signal from the EMS

Parameters:

• curt (numpy.ndarray) – curtailed amount over the optimisation time series (kW)

• t0 (int, default=0) – start time interval for the update

class Assets.StorageAsset(Emax, Emin, Pmax, Pmin, E0, ET, bus_id, dt, T, dt_ems, T_ems, phases=[0, 1, 2], Pmax_abs=None, c_deg_lin=None, eff_ch=1, eff_opt_ch=1, eff_dis=1, eff_opt_dis=1, self_dis=1)

A storage asset (use for batteries, EVs etc.)

Parameters:

• Emax (numpy.ndarray (T_ems,)) – maximum energy levels over the time series (kWh)

• Emin (numpy.ndarray (T_ems,)) – minimum energy levels over the time series (kWh)

• Pmax (numpy.ndarray (T_ems,)) – maximum input powers over the time series (kW)

• Pmin (numpy.ndarray (T_ems,)) – minimum input powers over the time series (kW)

• E0 (float) – initial energy level (kWh)

• ET (float) – required terminal energy level (kWh)

• bus_id (float) – id number of the bus in the network

• dt (float) – simulation time interval duration (h)

• T (int) – number of simulation time intervals

• dt_ems (float) – optimisation time interval duration (h)

• T_ems (int) – number of optimisation time intervals

• phases (list, optional, default [0,1,2]) –

  [0, 1, 2] indicates 3 phase connection

  Wye: [0, 1] indicates an a,b connection

  Delta: [0] indicates a-b, [1] b-c, [2] c-a

• Pmax_abs (float) – max power level (kW)

• c_deg_lin (float) – battery degradation rate with energy throughput (£/kWh)

• eff_ch (float, default 1) – charging efficiency (between 0 and 1)

• eff_opt_ch (float, default 1) – charging efficiency to be used in optimiser (between 0 and 1).

• eff_dis (float, default 1) – discharging efficiency (between 0 and 1)

• eff_opt_dis (float, default 1) – discharging efficiency to be used in optimiser (between 0 and 1).

• self_dis (float, default 1) – self discharging rate

• E (numpy.ndarray (T,)) – Energy profile over the simulation time series (kWh)

• E_ems (numpy.ndarray (T_ems,)) – Energy profile over the optimisarion time series (kWh)

• Pnet (numpy.ndarray (T,)) – Input real power over the simulation time series (kW)

• Pnet_ems (numpy.ndarray (T_ems,)) – Input real power over the optimisation time series (kW)

• Qnet (numpy.ndarray (T,)) – Input reactive power over the simulation time series(kVAR)

• Qnet_ems (numpy.ndarray (T_ems,)) – Input reactive power over the optimisation time series(kVAR)

Return type:

Storage Asset

EV_baseline(t_arr, T_avail, SOC_arr)

Compute the baseline consumption of an EV in the absence of flexibility

Parameters:

• t_arr (int) – index of time slot correspnding to the plug-in of the EV

• T_avail (int) – number of time slots the EV remained plugged-in

• SOC_arr (float [0,1]) – SOC of EV at arrival

Returns:

P_ch – daily charging schedule of EV

Return type:

numpy.ndarray (T_ems,)

EV_flexibility(t_arr, T_avail, SOC_arr, SOC_dep, T_flex, flex_type='up')

Compute the flexibility that can be provided by the EV for the period T_flex

Parameters:

• t_arr (int) – index of time slot correspnding to the plug-in of the EV

• T_avail (int) – number of time slots the EV remained plugged-in

• SOC_arr (float [0,1]) – SOC of EV at arrival

• SOC_dep (float [0,1]) – desired SOC of EV at departure

• T_flex (1d array) – period of flexibility [t_start, t_end]

• flex_type ({'down', 'up'}, default 'up') –

  the type of flexibility to provide ‘up’ : to decrease consumption of the HVAC in flexibility period

  ’down’ : to increase consumption of the HVAC in flexibility period

Returns:

Flex – available flexibility

Return type:

float

EV_toup_baseline(t_arr, T_avail, SOC_arr, SOC_dep, toup)

Compute the baseline consumption of an EV in the absence of flexibility, response to TOUP signal

Parameters:

• t_arr (int) – index of time slot correspnding to the plug-in of the EV

• T_avail (int) – number of time slots the EV remained plugged-in

• SOC_arr (float [0,1]) – SOC of EV at arrival

• SOC_dep (float [0,1]) – desired SOC of EV at departure

• toup (numpy.ndarray (T_ems,)) – time of use price

Returns:

P_ch – daily charging schedule of EV

Return type:

numpy.ndarray (T_ems,)

polytope(t0=0)

Computes the polytope representation of the asset operational constraints in optimisation time scale Ax <= b,

with x=[P_ch, P_dis] and P_(dis)ch is the (dis)charging power over the optimisation horizon T_ems, P_ch>=0 and P_dis<0

Following [1]

Parameters:

t0 (int, default=0) – starting time slot for the polytpe model in optimisation time scale

Returns:

A, b – slope and intercept

Return type:

numpy.ndarray (6 (T_ems-t_ahead_0), 2 (T_ems-t_ahead_0)), numpy.ndarray (6 (T_ems-t_ahead_0,)

update_control(Pnet, t0=0, enforce_const=True)

Update the energy profile and the storage system power based on the ‘Pnet’ signal

Parameters:

• Pnet (float or numpy.ndarray) – input powers over the simulation time series (kW)

• enforce_const (bool, default True) –

  True: enforce the operational constraints on E [Emin, Emax]

  False: update the energy profile based on Pnet

• t0 (int, default=0) – time interval (over simulation time scale T) for the update

update_discrete(action, t0, enforce_const=True)

Update the storage system energy at time interval t

Parameters:

• action ({-1,0,1}) – 1=charging, -1=discharging, 0=idle

• t (int) – time interval (over optimisation time scale T_ems) for the update

• enforce_const (bool, default True) – enforce the operational constraints on E ([Emin, Emax]) or not

update_ems(Pnet_ems, t0=0, enforce_const=True)

Update the storage system energy at time interval t

Parameters:

• Pnet_ems (float or numpy.ndarray) – input powers over the time series (kW)

• t (int, default=0) – first time interval for the update (in optimisation time scale)

• enforce_const (bool, default True) –

  True: enforce the operational constraints on E [Emin, Emax]

  False: update the energy profile based on Pnet

Networks

3-phase networks module

OPLEM offers two options for network modelling.

(1)The PandapowerNet class from the open-source python package pandapower can be used for balanced power flow analysis.

(2)For unbalanced multi-phase power flow analysis, OPLEM offers the Network_3ph class.

class Network_3ph_pf.Network_3ph

A 3-phase electric power network. Default to an unloaded IEEE 13 Bus Test Feeder.

Parameters:

• bus_df (pandas.DataFrame) – bus information, columns: [‘name’,’number’,’load_type’,’connect’, ‘Pa’,’Pb’,’Pc’,’Qa’,’Qb’,’Qc’], load_type: ‘S’ (slack),’PQ’,’Z’ or ‘I’ (only S and PQ are currently implemented), connect: ‘Y’ (wye) or ‘D’ (delta), ‘Px’ in (kW), ‘Qx’ in (kVAr)

• capacitor_df (pandas.DataFrame) – capacitor information, columns [‘name’,’number’,’bus’,’kVln’, ‘connect’,’Qa’,’Qb’,’Qc’], connect: ‘Y’ (wye) or ‘D’ (delta), ‘kVln’: line-to-line base voltage, ‘Qx’ in (kVAr)

• di_iter (np.ndarray) – change in the sum of abs phase currents at each Z-Bus iteration

• dv_iter (np.ndarray) – change in the sum of abs phsae voltages at each Z-Bus iteration

• i_abs_max (numpy.ndarray) – max abs line phase currents [line, phase] (|A|)

• i_PQ_iter (numpy.ndarray) – current injected at each phase at each Z-Bus iteration [iter,phase] (A)

• i_PQ_res (numpy.ndarray) – power flow result, current injected at each phase (excl. slack) (A)

• i_net_res (numpy.ndarray) – power flow result, current injected at each phase (A)

• i_slack_res (numpy.ndarray) – power flow result, current injected at slack bus phases (A)

• Jabs_dPQdel_list (list of numpy.ndarray) – linear line abs current model, [P_delta,Q_delta] coeff. matrix list

• Jabs_dPQwye_list (list of numpy.ndarray) – linear line abs current model, [P_wye,Q_wye] coeff. matrix list

• Jabs_I0_list (list of numpy.ndarray) – linear line abs current model, constant vector list

• J_dPQdel_list (list of numpy.ndarray) – linear line current model, [P_delta,Q_delta] coeff. matrix list

• J_dPQwye_list (list of numpy.ndarray) – linear line current model, [P_wye,Q_wye] coeff. matrix list

• J_I0_list (list of numpy.ndarray) – linear line current model, constant vector list

• K_del (numpy.ndarray) – linear abs voltage model, [P_delta,Q_delta] coeff. matrix

• K_wye (numpy.ndarray) – linear abs voltage model, [P_wye,Q_wye] coeff. matrix

• K0 (numpy.ndarray) – linear abs voltage model, constant vector

• line_config_df (pandas.DataFrame) – information on line configurations, columns: [‘name’,’Zaa’, ‘Zbb’,’Zcc’,’Zab’,’Zac’,’Zbc’,’Baa’,’Bbb’,’Bcc’,’Bab’,’Bac’,’Bbc’], ‘Zxx’ in (Ohms/length unit), ‘Bxx’ in (S/length unit) [base voltage of Vslack]

• line_df (pandas.DataFrame) – line information: [‘busA’,’busB’,’Zaa’,’Zbb’,’Zcc’,’Zab’,’Zac’,’Zbc’, ‘Baa’,’Bbb’,’Bcc’,’Bab’,’Bac’,’Bbc’], ‘Zxx’ in (Ohms) ‘Bxx’ in (S) [base voltage of Vslack]

• line_info_df – matches lines to their configurations: [‘busA’,’busB’,’config’, ‘length’,’Z_conv_factor’,’B_conv_factor’], Z,B_conv_factors used to match ‘lenth’ units to line_config_df ‘Zxx’ and ‘Bxx’ values

• list_Yseries (list of numpy.ndarray) – list of series admittance matrices for the lines

• list_Yshunt (list of numpy.ndarray) – list of shunt admittance matrices for the lines

• M_del (numpy.ndarray) – linear voltage model, [P_delta,Q_delta] coeff. matrix

• M_wye (numpy.ndarray) – linear voltage model, [P_wye,Q_wye] coeff. matrix

• M0 (numpy.ndarray) – linear abs voltage model, constant vector

• N_buses (int) – number of buses

• N_capacitors (int) – number of capacitors

• N_iter (int) – number of Z-Bus power flow solver iterations

• N_phases (int) – number of phases

• N_lines (int) – number of lines

• N_transformers (int) – number of transformers

• res_bus_df (pandas.DataFrame) – power flow result, bus information, columns: [‘name’,’number’, ‘load_type’,’connect’,’Sa’,’Sb’,’Sc’,’Va’,’Vb’,’Vc’,’Ia’,’Ib’,’Ic’] load_type: ‘S’ (slack),’PQ’,’Z’ or ‘I’ (only S and PQ are currently implemented), connect: ‘Y’ (wye) or ‘D’ (delta), ‘Sx’ in (kVA), ‘Vx’ in (V), ‘Ix’ in (A)

• res_lines_df (pandas.DataFrame) – power flow result, line information, columns: [‘busA’,’busB’,’Sa’,’Sb’, ‘Sc’,’Ia’,’Ib’,’Ic’,’VAa’,’VAb’,’VAc’,’VBa’,’VBb’,’VBc’], ‘Sx’ in (VA), ‘Ix’ in (A), bus A voltages ‘VAx’ in (V), bus B voltages ‘VBx’ in (V).

• S_del_lin0 (numpy.ndarray) – linear model, delta apparent power load (kVA)

• S_PQloads_del_res (numpy.ndarray) – power flow result, delta apparent power load (kVA)

• S_PQloads_wye_res (numpy.ndarray) – power flow result, wye apparent power load (kVA)

• S_net_res (pandas.DataFrame) – power flow result, apparent power load at each phase (VA)

• S_wye_lin0 – linear model, delta apparent power load (kVA) Y :

• transformer_df (pandas.DataFrame) – transformer information, columns: [‘busA’,’busB’,’typeA’,’typeB’, ‘Zseries’,’Zshunt’], typex: ‘wye-g’, ‘wye’ or ‘delta’

• v_abs_min (numpy.ndarray) – min abs bus voltages [bus, phase] (|V|)

• v_abs_max (numpy.ndarray) – max abs bus voltages [bus, phase] (|V|)

• v_iter (numpy.ndarray) – bus phase voltages at each Z-Bus iteration [iteration, phase]

• v_lin_abs_res (numpy.ndarray) – linear model result, bus phase abs voltage (excl. slack) (|V|)

• v_lin_res (numpy.ndarray) – linear model result, bus phase voltage (excl. slack) (V)

• v_net_lin_abs_res (numpy.ndarray) – linear model result, bus phase abs voltage (|V|)

• v_net_lin_res (numpy.ndarray) – linear model result, bus phase voltage (V)

• v_net_lin0 (numpy.ndarray) – linear model, nominal bus phase voltages (V)

• v_net_res (numpy.ndarray) – power flow result, bus phase voltages (V)

• vs (numpy.ndarray) – slack bus phase voltages (V)

• Vslack (float) – slack bus line-to-line voltage magnitude (|V|)

• Vslack_ph (float) – slack bus line-to-phase voltage magnitude (|V|)

• v_res (numpy.ndarray) – power flow result, bus phase voltages (excl. slack) (V)

• Y (numpy.ndarray) – admittance matrix (excl. slack) (S)

• Ynet (numpy.ndarray) – admittance matrix (S)

• Y_non_singular – admittance matrix with 1e-20*I added (excl. slack) (S) [base voltage of Vslack]

• Yns (numpy.ndarray) – admittance matrix partition [Yss, Ysn; Yns, Y] (S) [base voltage of Vslack] voltage of Vslack

• Ysn (numpy.ndarray) – admittance matrix partition [Yss, Ysn; Yns, Y] (S) [base voltage of Vslack]

• Yss (numpy.ndarray) – admittance matrix partition [Yss, Ysn; Yns, Y] (S) [base voltage of Vslack]

• Z – impedance matrix (Ohm) [base voltage of Vslack]

• Znet – impedance matrix (excl. slack) (Ohm) [base voltage of Vslack]

Return type:

Network_3ph

clear_loads()

Removes all real and reactive power loads from the network by clearing bus_df.

get_Gs(assets)

Set up matrices G_wye and G_del linking a group of assets to their bus and phase

Parameters:

assets (list) – list of assets

Returns:

• G_wye (numpy.ndarray (no unit)) – size (3*(N_buses-1),nbr of connected buses)

• G_del (numpy.ndarray (no unit)) – size (3*(N_buses-1),nbr of connected buses)

get_linear_parameters(assets, t, t0)

Get linear parameters for linear optimisation

Parameters:

• assets (list) – list of the non_dispatchable assets in the network

• t (int) – time

• t0 (int) – first slot of observation

Returns:

• A_Pslack (numpy.ndarray (2*Nbr of connected buses, )) – submatrix(G) for which the rows correspond to the connected buses

• b_Pslack (float) – g_0

• A_vlim (numpy.ndarray (N_buses*N_phases, 2*Nbr of connected buses)*) – submatrix(K) for which the rows correspond to the connected buses

• b_vlim (float) – k_0

• v_abs_min_vec (numpy.ndarray (N_buses*N_phases, )) – vector of minimum voltage limit

• v_abs_max_vec (numpy.ndarray) – vector of maximum voltage limit (N_buses*N_phases, )

• A_lines (list of numpy.ndarray, len=N_lines, (N_phases, 2*Nbr of connected buses)) – list of submatrices(J) over lines connected

• i_lim (list, len=N_lines) – j0

• i_abs_max (numpy.ndarray (N_lines,)) – vector of maximum thermal limit

linear_model_setup(v_net_lin0, S_wye_lin0, S_del_lin0)

Set up a linear model based on A. Bernstein, et al., [3]

Parameters:

• v_net_lin0 (numpy.ndarray) – nominal operating point, bus phase voltages (V)

• S_wye_lin0 (numpy.ndarray) – nominal operating point, apparent wye power loads (kVA)

• S_del_lin0 (numpy.ndarray) – nominal operating point, apparent delta power loads (kVA)

linear_pf()

Solves the linear model based on A. Bernstein, et al. [3]

Requires running linear_model_setup() first.

set_load(bus_id, ph_i, Pph, Qph)

Sets the P and Q load on a particular bus and phase

Parameters:

• bus_id (int) – the load bus id

• ph_i (int) – the load phase (either 0, 1 or 2)

• Pph (float) – nominal operating point, apparent wye load (kVA)

• Qph (float) – nominal operating point, apparent delta load (kVA)

set_pf_limits(v_abs_min_val, v_abs_max_val, i_abs_max_val)

Sets the abs bus phase voltage limits and abs line phase current limits

Parameters:

• v_abs_min_val (float) – minimum abs voltage bus phase voltage limit

• v_abs_max_val (float) – maximum abs voltage bus phase voltage limit

• i_abs_max_val (float) – maximum abs line phase current limit

setup_network_ieee13()

Set up the network as the unloaded IEEE 13 Bus Test Feeder

update_YandZ()

Update the network admittance and impedance matrices

update_line_pf_results()

Updates the line power flow results dataframe res_lines_df, based on the results of zbus_pf().

v_flat()

Get the vector of 1 p.u. balanced bus phase voltages

Return type:

numpy.ndarray

zbus_pf()

Solves the nonlinear power flow problem using the Z-bus method from M. Bazrafshan, N. Gatsis [4]

Participant

This module presents a participant. A participant can be either a prosumer, an aggregator or an energy provider

class Participant.Participant(p_id, assets)

Parameters:

• p_id (int) – unique identifier for a participant

• assets (a list of assets' objects) –

  assets managed by the participant

  assets located in the same bus => prosumer

  assets in different buses => aggregator

Return type:

Participant

EMS(price_imp, P_import, P_export, price_exp, t_ahead_0=0)

runs an energy management program to optimise schedules of the participant’ assets

Parameters:

• price_imp (1d array) – import prices per bus (£/kW)

• P_import (1d array) – limit of import (kW)

• P_export (1d array) – limit of export per bus (kW)

• price_exp (1d array) – export prices per bus (£/KW)

• t_ahead_0 (int, default=0) – starting time of the optimisation (<T_ems)

Returns:

schedules – list of assets’ schedules

Return type:

list of arrays

nd_demand(t0=0)

a power vector composed of the actual realisation of the current time step and the predicted values for the future time steps for all the non dispatchale assets of the participant

Parameters:

t0 (int default=0) – first time slot of observation

Returns:

P_demand – power vector

Return type:

numpy.ndarray

polytope(assets, t0=0)

Computes an outer approximation of the aggregated polytope representation of the assets operational constraints Ax <= b,

with x=[P_in, P_out] and P_in/out is the power into and out of the assets over the optimisation horizon T_ems P_ch>=0 P_dis<0

From [1]

Parameters:

• assets (list) – list of assets objects

• t0 (int, default=0) – first time slot of aggregation in an optimisation time scale

Returns:

(A_agg, b_agg) – Aggregated slope, aggregated intercept

Return type:

numpy.ndarray (6 (T_ems-t_ahead_0), 2 (T_ems-t_ahead_0)), numpy.ndarray (6 (T_ems-t_ahead_0,)

power_disaggregation(p_agg, assets, t_ahead_0=0)

produces a feasible power vector for each asset in the list from the aggregated power schedule p_agg.

From [1]

Parameters:

• p_agg (numpy.ndarray) – a vector containing the aggregated power injection or absorption for each time period over the optimisation horizon [t_ahead_0, T_ems]

• assets (list) – list of assets objects in the aggregation

• t_ahead_0 (int, default =0) – first time slot of aggregation in an optimisation time scale

Returns:

p_disagg – 2 dimension array of the disaggregated power schedules: 1st dim: time, 2nd dim: assets

Return type:

numpy.ndarray

Market

OPLEM Market module has two types of markets:

1. Energy markets, and

2. Flexibility markets

1. The energy market comes with subclasses of the common types of energy markets:

1. central market

2. time of use market

3. P2P market

4. auction market

2. The flexibility markets comes with one market

1. Capacity limits market

class Market.Auction_market(participants, offers, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None)

Auction Market Class

The Auction market matches buyers and sellers

Parameters:

• participants (list of objects) – Containing details of each participant

• T_market (int) – Market horizon

• dt_market (float) – time interval duration (hours)

• price_imp (numpy.ndarray) – import prices from the grid (£/kWh)

• t_ahead_0 (int) – starting time slot of market clearing

• P_import (numpy.ndarray) – max import from the grid (kW)

• P_export (numpy.ndarray) – max export to the grid (kW)

• price_exp (numpy.ndarray) – export prices to the grid (£/kWh)

• network (object, default=None) –

  the network infrastructure of the market

  useful for market clearings that account for network constraints,

  required to run simulate_network_3ph

• offers (pandas Dataframe) –

  id_participant, quantity of energy, price

  id_participant	time	energy		price

Return type:

Market object

Auction_matching(priority='price')

Returns the outcome of an auction matching highest bid with lowest ask matching

Parameters:

priority ({'price', 'demand'}, default=price) –

‘price’: the buyer with the highest bid price is matched to the seller with the lowest offer price

’demand’: the buyer with the highest bid demand is matched to the seller with the highest offer surplus

Returns:

market_clearing_outcome – the resulting energy exchange

id	time	seller	buyer	energy	price

Return type:

pandas Dataframe

class Market.Capacity_limits(participants, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None)

Returns the maximum capacity to absorb and inject per node per time step following the paper [put ref here]

capacity_limits(Cfirm, Sigma)

Returns the max capacities to absorb/inject per each node for each time step

Parameters:

• epsilon (float ]0.5, 1]) –

  the probabilistic error, probabilistic guarantee = 1-epsilon

  for a deterministic solution (with no probabilistic guarantee, take epsilon=0.5)

• Cfirm (float generally [15, 18]*1e3 kW) – firm capacity of the transfomer upstream

• Sigma (list of numpy.ndarray) – each element of the list stores the variance of the inflexible loads at time step t

Returns:

• Cmax (numpy.ndarray (T_market-t_ahead_0, Nbr of nodes)) – max capacity to absorb:

• Cmin (numpy.ndarray (T_market-t_ahead_0, Nbr of nodes)) – max capacity to inject (<=0)

class Market.Central_market(participants, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None, nw_const=True)

Central Market Class

Central market runs a central optimisation market clearing

Parameters:

• participants (list of objects) – Containing details of each participant

• T_market (int) – Market horizon

• dt_market (float) – time interval duration (hours)

• price_imp (numpy.ndarray) – import prices from the grid (£/kWh)

• t_ahead_0 (int) – starting time slot of market clearing

• P_import (numpy.ndarray) – max import from the grid (kW)

• P_export (numpy.ndarray) – max export to the grid (kW)

• price_exp (numpy.ndarray) – export prices to the grid (£/kWh)

• network (object, default=None) –

  the network infrastructure of the market

  useful for market clearings that account for network constraints,

  required to run simulate_network_3ph

Return type:

Market object

market_clearing(v_unconstrained_buses=[], i_unconstrained_lines=[])

computes assets schedules based on central optimisation

Parameters:

• v_unconstained_buses (list, default =[]) – the list of unconstained buses in the network

• i_unconstained_lines (list, default =[]) – the list of unconstained lines in the network

Returns:

• market_clearing_outcome (pandas Dataframe) – the resulting energy exchange

  id	time	seller	buyer	energy	price

• schedules (list of numpy.ndarrays) – each array contains an asset’s schedule

• P_imp (numpy.ndarray (T_market-t_ahead_0,)) – imported power upstream

• P_exp (numpy.ndarray (T_market-t_ahead_0,)) – exported power upstream

class Market.Market(participants, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None)

Base Market Class

Parameters:

• participants (list of objects) –

• participant (Containing details of each) –

• T_market (int) – Market horizon

• dt_market (float) – time interval duration (hours)

• price_imp (numpy.ndarray (T_market,)) – import prices from the grid (£/kWh)

• t_ahead_0 (int) – starting time slot of market clearing

• P_import (numpy.ndarray (T_market,)) – max import from the grid (kW)

• P_export (numpy.ndarray (T_market,)) – max export to the grid (kW)

• price_exp (numpy.ndarray (T_market,)) – export prices to the grid (£/kWh)

• network (object, default=None) –

  the network infrastructure of the market

  useful for market clearings that account for network constraints,

  required to run simulate_network_3ph

Return type:

Market object

simulate_network_3ph(single_iter=False)

simulate the power flow of the network if the network is created using Network_3ph() class

Parameters:

single_iter (bool, default False) –

False: simulate network power flow for the remaining time steps of the horizon [t_ahead_0, T_market]

True: simulate network power flow for a single optimisation time step t_ahead_0

Returns:

network_pf – the resulting network object for [t_ahead_0, T_market] time steps

Return type:

list

simulate_network_pp(single_iter=False)

simulate the power flow of the network if the network is created using pandaspower

Parameters:

single_iter (bool, default: False) –

False: simulate network power flow for the remaining time steps of the horizon [t_ahead_0, T_market]

True: simulate network power flow for a single optimisation time step t_ahead_0

Returns:

output – the resulting network output for the simulation time steps:

buses_Vpu : Voltage magnitude at bus (V)

buses_Vang : Voltage angle at bus (rad)

buses_Pnet : Real power at bus (kW)

buses_Qnet : Reactive power at bus (kVAR)

Pnet_market : Real power seen by the market (kW)

Qnet_market : Reactive power seen by the market (kVAR)

Return type:

dict

class Market.P2P_market(participants, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None, fees=None)

P2P market returns the bilateral contracts between peers following the algorithm proposed by Morstyn et. Al, in [2]

Parameters:

• participants (list of participant instances) – Containing details of each participant

• T_market (int) – Market horizon

• dt_market (float) – time interval duration (hours)

• price_imp (numpy.ndarray) – import prices from the grid (£/kWh)

• t_ahead_0 (int) – starting time slot of market clearing

• P_import (numpy.ndarray) – max import from the grid (kW)

• P_export (numpy.ndarray) – max export to the grid (kW)

• price_exp (numpy.ndarray) – export prices to the grid (£/kWh)

• network (object, default=None) –

  the network infrastructure of the market

  useful for market clearings that account for network constraints,

  required to run simulate_network_3ph

• fees (numpy.ndarray (T_market-t_ahead_0, N, N)) –

  the fees the peers have to pay to the DNO for using the physical infrastructure

  fees[t,i,j]: the fees of transferring energy between participant i and participant j at time t

P2P_negotiation(trade_energy, price_inc, N_p2p_ahead_max, stopping_criterion=None)

Returns the outcome of a P2P negotiation procedure

Parameters:

• trade_energy (float) – the unit amount of energy to trade (kWh)

• price_inc (float) – the incremental step of the peers prices

• N_p2p_ahead_max (int) – maximum number of contracts between 2 peers

• stopping_criterion (int) – number of iterations that the negotiation will make before stopping

Returns:

• market_clearing_outcome (pandas Dataframe) – the resulting energy exchange

  id	time	seller	buyer	energy	price

• schedules (list of numpy.ndarrays) – list of assets schedules

class Market.ToU_market(participants, dt_market, T_market, price_imp, t_ahead_0=0, P_import=None, P_export=None, price_exp=None, network=None)

Time of Use Market Class

ToU market runs a decentralised optimisation in which every participant optimises its resources in response to a ToU price signal

Parameters:

• participants (list of objects) – Containing details of each participant

• T_market (int) – Market horizon

• dt_market (float) – time interval duration (hours)

• price_imp (numpy.ndarray) – import prices from the grid (£/kWh)

• t_ahead_0 (int) – starting time slot of market clearing

• P_import (numpy.ndarray) – max import from the grid (kW)

• P_export (numpy.ndarray) – max export to the grid (kW)

• price_exp (numpy.ndarray) – export prices to the grid (£/kWh)

• network (object, default=None) –

  the network infrastructure of the market

  useful for market clearings that account for network constraints,

  required to run simulate_network_3ph

Return type:

Market object

market_clearing()

computes the energy exchange of each participant with the grid

Returns:

• market_clearing_outcome (pandas Dataframe) – the resulting energy exchange

  id	time	seller	buyer	energy	price

• schedules (list of numpy.ndarrays) – list of assets schedules

References

[1] (1,2,3,4,5)

Suhail Barot, Josh A. Taylor, A concise, approximate representation of a collection of loads described by polytopes, International Journal of Electrical Power & Energy Systems, Volume 84, 2017, Pages 55-63, ISSN 0142-0615.

[2]

T. Morstyn, A. Teytelboym and M. D. Mcculloch, “Bilateral Contract Networks for Peer-to-Peer Energy Trading,” in IEEE Transactions on Smart Grid, vol. 10, no. 2, pp. 2026-2035, March 2019.

[3] (1,2)

Load Flow in Multiphase Distribution Networks: Existence, Uniqueness, Non-Singularity and Linear Models, IEEE Transactions on Power Systems, 2018.

[4]

Comprehensive Modeling of Three-Phase Distribution Systems via the Bus Admittance Matrix,” IEEE Transactions on Power Systems, 2018.