hynet.data package

Submodules

hynet.data.connection module

Manage hynet’s database connections.

class hynet.data.connection.DBConnection(database_uri)

Bases: object

Manager for a hynet grid database connection.

See also

hynet.data.connection.DBTransaction

description

Return the description of this database.

Before the text is returned, the description retrieved from the database is wrapped to an appropriate column width to improve readability.

empty

Return True if the database does not contain grid information.

get_setting(key)

Return the database setting for the specified key.

Parameters:key (DBInfoKey) – The key for which the value shall be retrieved. Returns:value – The value associated with the provided key. Return type:str Raises:ValueError – If the setting was not found.

grid_name

Return the name of the grid in this database.

set_setting(key, value)

Set the database setting for the specified key.

Parameters:

• key (DBInfoKey) – The key for which the value shall be set.
• value (str) – Value to be set.

Raises:

ValueError – If the value is not a string.

start_session()

Return a new database session as an SQLAlchemy Session object.

Remark: This function is for internal use.

version

Return the hynet grid database format version of this database.

class hynet.data.connection.DBTransaction(database)

Bases: object

Database transaction that is automatically committed at the exit block.

add(object_)

Add an object to the session.

add_all(collection)

Add a collection of objects to the session.

delete(object_)

Mark the object as deleted in the session.

delete_all(collection)

Mark a collection of objects as deleted

execute(query)

Execute the SQL expression construct or string statement.

query(object_type)

Return a new SQLAlchemy Query object for this session.

update(object_)

Update the state of the object in the session.

hynet.data.connection.connect(database_uri)

Return a connection to the specified hynet grid database.

Parameters:database_uri (str) – URI or file name of the hynet grid database. Returns:database – Connection to the hynet grid database. Return type:DBConnection

hynet.data.example_days module

Support for the generation of scenarios of exemplary days.

hynet.data.example_days.add_example_days(database, base_case)

Add the exemplary day scenarios to the database.

hynet.data.example_days.initialize_database_with_example_days(database, base_case)

Initialize the database with the base case and add exemplary day scenarios.

The added day scenarios are exemplary winter and summer weekdays/weekends obtained by scaling the base case load according to the data provided in [1], Table 4.

Parameters:

• database (DBConnection) – Connection to the destination database. This database must be empty.
• base_case (Scenario) – Base case scenario for the new database.

Raises:

ValueError – In case that the destination database is not empty or the provided scenario data exhibits integrity or validity issues.

References

[1]	C. Grigg et al., “The IEEE Reliability Test System - 1996. A report prepared by the Reliability Test System Task Force of the Application of Probability Methods Subcommittee,” in IEEE Trans. Power Systems, vol. 14, no. 3, pp. 1010-1020, Aug. 1999.

hynet.data.import_ module

Import of model data into the hynet data format.

class hynet.data.import_.BranchConstants

Bases: object

Constants for the MATPOWER branch data, see the MATPOWER manual.

ANGMAX = 12

ANGMIN = 11

BR_B = 4

BR_R = 2

BR_STATUS = 10

BR_X = 3

F_BUS = 0

MU_ANGMAX = 20

MU_ANGMIN = 19

MU_SF = 17

MU_ST = 18

PF = 13

PT = 15

QF = 14

QT = 16

RATE_A = 5

RATE_B = 6

RATE_C = 7

SHIFT = 9

TAP = 8

T_BUS = 1

class hynet.data.import_.BusConstants

Bases: object

Constants for the MATPOWER bus data, see the MATPOWER manual.

BASE_KV = 9

BS = 5

BUS_AREA = 6

BUS_I = 0

BUS_TYPE = 1

GS = 4

LAM_P = 13

LAM_Q = 14

MU_VMAX = 15

MU_VMIN = 16

NONE = 4

PD = 2

PQ = 1

PV = 2

QD = 3

REF = 3

VA = 8

VM = 7

VMAX = 11

VMIN = 12

ZONE = 10

class hynet.data.import_.DCLineConstants

Bases: object

Constants for the MATPOWER DC line data, see the MATPOWER manual.

BR_STATUS = 2

F_BUS = 0

LOSS0 = 15

LOSS1 = 16

MU_PMAX = 18

MU_PMIN = 17

MU_QMAXF = 20

MU_QMAXT = 22

MU_QMINF = 19

MU_QMINT = 21

PF = 3

PMAX = 10

PMIN = 9

PT = 4

QF = 5

QMAXF = 12

QMAXT = 14

QMINF = 11

QMINT = 13

QT = 6

T_BUS = 1

VF = 7

VT = 8

class hynet.data.import_.GeneratorConstants

Bases: object

Constants for the MATPOWER generator data, see the MATPOWER manual.

APF = 20

COST = 4

GEN_BUS = 0

GEN_STATUS = 7

MBASE = 6

MODEL = 0

MU_PMAX = 21

MU_PMIN = 22

MU_QMAX = 23

MU_QMIN = 24

NCOST = 3

PC1 = 10

PC2 = 11

PG = 1

PMAX = 8

PMIN = 9

POLYNOMIAL = 2

PW_LINEAR = 1

QC1MAX = 13

QC1MIN = 12

QC2MAX = 15

QC2MIN = 14

QG = 2

QMAX = 3

QMIN = 4

RAMP_10 = 17

RAMP_30 = 18

RAMP_AGC = 16

RAMP_Q = 19

SHUTDOWN = 2

STARTUP = 1

VG = 5

hynet.data.import_.import_matpower_test_case(input_file, output_file=None, grid_name=None, description='', num_sample_points=10, res_detection=False)

Import a MATPOWER test case file into hynet’s database format.

This function imports a MATPOWER test case, which is stored as a MATPOWER test case struct mpc in a MATLAB MAT-file, to a hynet’s database. To prepare the import, start MATLAB and perform the following two steps:

1. Load the MATPOWER test case into the variable mpc:

   mpc = loadcase('your_matpower_test_case_file.m');
   

2. Save the MATPOWER test case struct mpc to a MATLAB MAT file:

   save('your_matpower_test_case_file.mat', 'mpc');
   

Call this function with the MAT-file as the input.

Parameters:

• input_file (str) – MATLAB MAT-file (.mat) with the MATPOWER test case struct mpc.
• output_file (str, optional) – Destination hynet grid database file. By default (None), the file name is set to the input file name with a .db extension.
• grid_name (str, optional) – Name of the grid. By default (None), the grid name is set to the input file name excluding the extension.
• description (str, optional) – Description of the grid model and, if applicable, copyright and licensing information.
• num_sample_points (int, optional) – Number of sample points that shall be used for the conversion of polynomial to piecewise linear cost functions (on the interval from minimum to maximum output). This setting is a trade-off between an accurate representation of the original cost function and the number of additional constraints in the OPF problem.
• res_detection (bool, optional) – Detection of the injector type for renewable energy sources (RES), which is inactive by default. This scheme is motivated by the German grid data, which contains PV- and wind-based injectors with zero marginal cost that are arranged in a specific pattern: The injectors that connect to the same bus are stored consecutively in the generator matrix. If two or more injectors connect to the same bus, then the last one is wind-based and the second to the last is PV-based generation if their marginal cost is zero. If this parameter is set to True, this RES detection scheme is enabled.

Returns:

output_file – Destination hynet grid database file name.

Return type:

str

Raises:

• ValueError –
• NotImplementedError –

hynet.data.interface module

Interface to access the model data in a hynet grid database.

hynet.data.interface.copy_scenarios(source_database, destination_database, scenario_ids=None, bus_id_map=None)

Copy the scenarios from the source to the destination hynet grid database.

Caution: Note that this function does not verify that the grid infrastructure of the source and destination database is compatible, it only copies the content of the scenario information tables for the requested scenarios. In case a scenario with a specified ID already exists in the destination database, it is skipped.

Parameters:

• source_database (DBConnection) – Connection to the source hynet grid database.
• destination_database (DBConnection) – Connection to the destination hynet grid database.
• scenario_ids (list[hynet_id_], optional) – List of scenario identifiers that shall be copied. By default, all scenarios are copied.
• bus_id_map (pandas.Series, optional) – If provided, this series, indexed by the bus IDs in the source database, specifies the mapping of a bus ID in the source database to a bus ID in the destination database. This is necessary, e.g., after a network reduction, where certain buses are combined and the load shall be accumulated at the aggregated bus. By default, a one-to-one mapping is considered.

hynet.data.interface.fix_hynet_id(series)

Fix the data type of the given nullable integer pandas series.

When reading integer columns that contain NULL values using pandas.read_sql_table, they are converted to float [1]. This may lead to errors, e.g. the PWL function foreign keys cause key errors during indexing. This function fixes the type.

References

[1]	https://github.com/pandas-dev/pandas/issues/13049

hynet.data.interface.get_max_bus_id(database)

Determine the highest bus ID in the specified hynet grid database.

Parameters:database (DBConnection) – Connection to the hynet grid database. Returns:result – The highest bus ID in the database or None if there are no buses. Return type:hynet_id_ or None

hynet.data.interface.get_max_scenario_id(database)

Determine the highest scenario ID in the specified hynet grid database.

Parameters:database (DBConnection) – Connection to the hynet grid database. Returns:result – The highest scenario ID in the database or None if there are no scenarios. Return type:hynet_id_ or None

hynet.data.interface.get_scenario_info(database)

Load a list of all scenarios from the specified hynet grid database.

Parameters:database (DBConnection) – Connection to the hynet grid database. Returns:Data frame with a list of all scenarios, indexed by the scenario ID, which comprises the following columns:

name: (str)

Name of the scenario.

time: (hynet_float_)

Relative time in hours of the scenario (w.r.t. the scenario group start time).

annotation: (str)

Annotation string for supplementary information.

Return type:pandas.DataFrame Raises:ValueError – In case that the database is empty.

hynet.data.interface.initialize_database(database, scenario)

Initialize an empty hynet grid database with the data of the scenario.

The database is populated with the grid infrastructure and scenario data of the given scenario object. In the given scenario object, the scenario ID is reset to 0 and the database URI is updated.

Parameters:

• database (DBConnection) – Connection to the hynet grid database.
• scenario (hynet.scenario.representation.Scenario) – Scenario object with the grid infrastructure and scenario data.

Raises:

ValueError – In case the database is not empty or any kind of data integrity or validity violation is detected.

hynet.data.interface.load_scenario(database, scenario_id=0)

Load the specified scenario from the hynet grid database.

Parameters:

• database (DBConnection) – Connection to the hynet grid database.
• scenario_id (hynet_id_, optional) – Identifier of the scenario; default is 0.

Returns:

scenario – Scenario object with the loaded data.

Return type:

hynet.scenario.representation.Scenario

Raises:

ValueError – In case that the database is empty or the scenario with the specified ID was not found.

hynet.data.interface.remove_scenarios(database, scenario_ids)

Remove the specified scenarios from the hynet grid database file.

Parameters:

• database (DBConnection) – Connection to the hynet grid database.
• scenario_ids (list[hynet_id_]) – List of identifiers for the scenarios that shall be removed.

Raises:

ValueError – In case that a scenario with the specified ID was not found.

hynet.data.interface.save_scenario(database, scenario, auto_id=True)

Save the provided scenario to the specified hynet grid database.

The scenario information in the provided scenario object is extracted and saved to the specified hynet grid database. Note that a scenario can only capture the following changes:

• Changes of the load (scenario.bus['load'])

• Selected changes of injectors:

  • Scaling of the cost function for active and reactive power (scenario.injector[['cost_p', 'cost_q']]). The scaling must be the same for both cost functions of an injector.
  • Changes of the box constraints of the capability region (p_min, p_max, q_min, and q_max of the objects in scenario.injector['cap']). Note that changes of the parameters of the half-spaces are not supported.)

• Inactivity of buses, branches, converters, injectors, and shunts. For example, to deactivate (decommit) an injector, remove (drop) the respective row in the injector data frame of the scenario.

Any other changes are considered as a modification of the grid infrastructure and cannot be captured as a scenario.

Parameters:

• database (DBConnection) – Connection to the hynet grid database.
• scenario (Scenario) – Scenario object that represents the new scenario.
• auto_id (bool, optional) – If True (default), the scenario ID is set to the lowest available scenario ID in the database. Otherwise, the scenario ID of the Scenario object is applied.

Raises:

ValueError – In case the database is empty or any kind of data integrity or validity violation is detected.

See also

hynet.data.interface.initialize_database()

hynet.data.structure module

Schema and SQLAlchemy declaratives for hynet grid databases.

class hynet.data.structure.DBBranch(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a branch.

angle_max

angle_min

annotation

b_dst

b_src

drop_max

drop_min

dst

dst_id

id

length

phase_dst

phase_src

r

rating

ratio_dst

ratio_src

src

src_id

type

x

class hynet.data.structure.DBBus(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a bus.

annotation

base_kv

id

ref

type

v_max

v_min

zone

class hynet.data.structure.DBCapabilityRegion(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a capability region.

annotation

id

lb_ofs

lb_slp

lt_ofs

lt_slp

p_max

p_min

q_max

q_min

rb_ofs

rb_slp

rt_ofs

rt_slp

class hynet.data.structure.DBConverter(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a converter.

annotation

cap_dst

cap_dst_id

cap_src

cap_src_id

dst

dst_id

id

loss_bwd

loss_fix

loss_fwd

src

src_id

class hynet.data.structure.DBInfo(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a hynet grid database setting.

key

value

class hynet.data.structure.DBInjector(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for an injector.

annotation

bus

bus_id

cap

cap_id

cost_p

cost_p_id

cost_q

cost_q_id

cost_start

cost_stop

energy_max

energy_min

id

min_down

min_up

ramp_down

ramp_up

type

class hynet.data.structure.DBSamplePoint(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a cost function sample point.

id

x

y

class hynet.data.structure.DBScenario(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a scenario.

annotation

id

loss_price

name

time

class hynet.data.structure.DBScenarioInactivity(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for the inactivity specification in a scenario.

entity_id

entity_type

scenario

scenario_id

class hynet.data.structure.DBScenarioInjector(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for the injector adaptation in a scenario.

cost_scaling

injector

injector_id

p_max

p_min

q_max

q_min

scenario

scenario_id

class hynet.data.structure.DBScenarioLoad(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a load in a scenario.

bus

bus_id

p

q

scenario

scenario_id

class hynet.data.structure.DBShunt(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base

Dataset for a shunt.

annotation

bus

bus_id

id

p

q

Module contents