GridCal.Engine.Core package¶

Submodules¶

GridCal.Engine.Core.calculation_inputs module¶

class GridCal.Engine.Core.calculation_inputs.CalculationInputs(nbus, nbr, ntime, nbat, nctrlgen)¶

Bases: object

nbus (int): Number of buses nbr (int): Number of branches ntime (int): Number of time steps nbat (int): Number of batteries nctrlgen (int): Number of voltage controlled generators

build_linear_ac_sys_mat()¶: Get the AC linear approximation matrices :return:

compile_types(types_new=None)¶: Compile the types :param types_new: new array of types to consider :return: Nothing

compute_branch_results(V)¶: Compute the branch magnitudes from the voltages :param V: Voltage vector solution in p.u. :return: CalculationResults instance with all the grid magnitudes

consolidate()¶: Compute the magnitudes that cannot be computed vector-wise

get_island(bus_idx, branch_idx, gen_idx, bat_idx)¶: Get a sub-island :param bus_idx: bus indices of the island :param branch_idx: branch indices of the island :return: CalculationInputs instance

get_structure(structure_type)¶

Get a DataFrame with the input.

Arguments:

structure_type (str): ‘Vbus’, ‘Sbus’, ‘Ibus’, ‘Ybus’, ‘Yshunt’, ‘Yseries’ or ‘Types’

Returns:

pandas DataFrame

print(bus_names)¶: print in console :return:

re_calc_admittance_matrices(tap_mod)¶: Recalculate the admittance matrices as the tap changes :param tap_mod: tap modules per bus :return: Nothing, the matrices are changed in-place

trim_profiles(time_idx)¶: Trims the profiles with the passed time indices and stores those time indices for later :param time_idx: array of time indices

GridCal.Engine.Core.csc_graph module¶

class GridCal.Engine.Core.csc_graph.Graph(adj)¶

Bases: object

find_islands()¶: Method to get the islands of a graph This is the non-recursive version :return: islands list where each element is a list of the node indices of the island

GridCal.Engine.Core.multi_circuit module¶

class GridCal.Engine.Core.multi_circuit.MultiCircuit(name='')¶

Bases: object

The concept of circuit should be easy enough to understand. It represents a set of nodes (buses) and branches (lines, transformers or other impedances).

The MultiCircuit class is the main object in GridCal. It represents a circuit that may contain islands. It is important to understand that a circuit split in two or more islands cannot be simulated as is, because the admittance matrix would be singular. The solution to this is to split the circuit in island-circuits. Therefore MultiCircuit identifies the islands and creates individual Circuit objects for each of them.

GridCal uses an object oriented approach for the data management. This allows to group the data in a smart way. In GridCal there are only two types of object directly declared in a Circuit or MultiCircuit object. These are the Bus and the Branch. The branches connect the buses and the buses contain all the other possible devices like loads, generators, batteries, etc. This simplifies enormously the management of element when adding, associating and deleting.

from GridCal.Engine.Core.multi_circuit import MultiCircuit
grid = MultiCircuit(name="My grid")

add_battery(bus: GridCal.Engine.Devices.bus.Bus, api_obj=None)¶

Add a Battery object to a Bus.

Arguments:

bus (Bus): Bus object

api_obj (Battery): Battery object

add_branch(obj: GridCal.Engine.Devices.branch.Branch)¶

Add a Branch object to the grid.

Arguments:

obj (Branch): Branch object

add_bus(obj: GridCal.Engine.Devices.bus.Bus)¶

Add a Bus object to the grid.

Arguments:

obj (Bus): Bus object

add_generator(bus: GridCal.Engine.Devices.bus.Bus, api_obj=None)¶

Add a (controlled) Generator object to a Bus.

Arguments:

bus (Bus): Bus object

api_obj (Generator): Generator object

add_load(bus: GridCal.Engine.Devices.bus.Bus, api_obj=None)¶

Add a Load object to a Bus.

Arguments:

bus (Bus): Bus object

api_obj (Load): Load object

add_overhead_line(obj: GridCal.Engine.Devices.tower.Tower)¶: Add overhead line (tower) template to the collection :param obj: Tower instance

add_sequence_line(obj: GridCal.Engine.Devices.sequence_line.SequenceLineType)¶: Add sequence line to the collection :param obj: SequenceLineType instance

add_shunt(bus: GridCal.Engine.Devices.bus.Bus, api_obj=None)¶

Add a Shunt object to a Bus.

Arguments:

bus (Bus): Bus object

api_obj (Shunt): Shunt object

add_static_generator(bus: GridCal.Engine.Devices.bus.Bus, api_obj=None)¶

Add a StaticGenerator object to a Bus.

Arguments:

bus (Bus): Bus object

api_obj (StaticGenerator): StaticGenerator object

add_transformer_type(obj: GridCal.Engine.Devices.transformer.TransformerType)¶: Add transformer template :param obj: TransformerType instance

add_underground_line(obj: GridCal.Engine.Devices.underground_line.UndergroundLineType)¶: Add underground line :param obj: UndergroundLineType instance

add_wire(obj: GridCal.Engine.Devices.wire.Wire)¶: Add Wire to the collection :param obj: Wire instance

apply_all_branch_types()¶: Apply all the branch types

apply_lp_profiles()¶: Apply the LP results as device profiles.

assign_circuit(circ)¶

Assign a circuit object to this object.

Arguments:

circ (MultiCircuit): MultiCircuit object

build_graph()¶: Returns a networkx DiGraph object of the grid.

clear()¶: Clear the multi-circuit (remove the bus and branch objects)

compile(use_opf_vals=False, opf_time_series_results=None, logger=[]) → GridCal.Engine.Core.numerical_circuit.NumericalCircuit¶

Compile the circuit assets into an equivalent circuit that only contains matrices and vectors for calculation. This method returns the numerical circuit, but it also assigns it to self.numerical_circuit, which is used when the MultiCircuit object is passed onto a simulation driver, for example:

from GridCal.Engine import *

grid = MultiCircuit()
grid.load_file("grid.xlsx")
grid.compile()

options = PowerFlowOptions()

power_flow = PowerFlowMP(grid, options)
power_flow.run()

Arguments:

use_opf_vals (bool, False): Use OPF results as inputs

opf_time_series_results (list, None): OPF results to be used as inputs

logger (list, []): Message log

Returns:

self.numerical_circuit (NumericalCircuit): Compiled numerical circuit of the grid

copy()¶: Returns a deep (true) copy of this circuit.

create_profiles(steps, step_length, step_unit, time_base: datetime.datetime = datetime.datetime(2019, 7, 1, 16, 36, 15, 51052))¶

Set the default profiles in all the objects enabled to have profiles.

Arguments:

steps (int): Number of time steps

step_length (int): Time length (1, 2, 15, …)

step_unit (str): Unit of the time step (“h”, “m” or “s”)

time_base (datetime, datetime.now()): Date to start from

delete_branch(obj: GridCal.Engine.Devices.branch.Branch)¶

Delete a Branch object from the grid.

Arguments:

obj (Branch): Branch object

delete_bus(obj: GridCal.Engine.Devices.bus.Bus)¶

Delete a Bus object from the grid.

Arguments:

obj (Bus): Bus object

delete_overhead_line(i)¶: Delete tower from the collection :param i: index

delete_sequence_line(i)¶: Delete sequence line from the collection :param i: index

delete_transformer_type(i)¶: Delete transformer type from the colection :param i: index

delete_underground_line(i)¶: Delete underground line :param i: index

delete_wire(i)¶: Delete wire from the collection :param i: index

device_type_name_dict = None¶

self.type_name = ‘Shunt’

self.properties_with_profile = [‘Y’]

dispatch()¶: Dispatch either load or generation using a simple equalised share rule of the shedding to be done.

export_pf(file_name, power_flow_results)¶

Export power flow results to file.

Arguments:

file_name (str): Excel file name

export_profiles(file_name)¶

Export object profiles to file.

Arguments:

file_name (str): Excel file name

format_profiles(index)¶

Format the pandas profiles in place using a time index.

Arguments:

index: Time profile

get_Jacobian(sparse=False)¶

Returns the grid Jacobian matrix.

Arguments:

sparse (bool, False): Return the matrix in CSR sparse format (True) or as full matrix (False)

get_batteries()¶: Returns a list of Battery objects in the grid.

get_battery_capacities()¶: Returns a list of Battery capacities.

get_battery_names()¶: Returns a list of Battery names.

get_catalogue_dict(branches_only=False)¶

Returns a dictionary with the catalogue types and the associated list of objects.

Arguments:

branches_only (bool, False): Only branch types

get_catalogue_dict_by_name(type_class=None)¶

get_controlled_generator_names()¶: Returns a list of Generator names.

get_elements_by_type(element_type: GridCal.Engine.Devices.meta_devices.DeviceType)¶: Get set of elements and their parent nodes :param element_type: DeviceTYpe instance :return: List of elements, it raises an exception if the elements are unknown

get_generators()¶: Returns a list of Generator objects in the grid.

get_json_dict(id)¶

Returns a JSON dictionary of the MultiCircuit instance with the following values: id, type, phases, name, Sbase, comments.

Arguments:

id: Arbitrary identifier

get_load_names()¶: Returns a list of Load names.

get_loads()¶: Returns a list of Load objects in the grid.

get_node_elements_by_type(element_type: GridCal.Engine.Devices.meta_devices.DeviceType)¶

Get set of elements and their parent nodes.

Arguments:

element_type (str): Element type, either “Load”, “StaticGenerator”, “Generator”, “Battery” or “Shunt”

Returns:

List of elements, list of matching parent buses

get_shunt_names()¶: Returns a list of Shunt names.

get_shunts()¶: Returns a list of Shunt objects in the grid.

get_static_generators()¶: Returns a list of StaticGenerator objects in the grid.

get_static_generators_names()¶: Returns a list of StaticGenerator names.

plot_graph(ax=None)¶: Plot the grid. :param ax: Matplotlib axis object :return:

save_calculation_objects(file_path)¶

Save all the calculation objects of all the grids.

Arguments:

file_path (str): Path to file

set_power(S)¶

Set the power array in the circuits.

Arguments:

S (list): Array of power values in MVA for all the nodes in all the islands

set_state(t)¶: Set the profiles state at the index t as the default values.

GridCal.Engine.Core.numerical_circuit module¶

class GridCal.Engine.Core.numerical_circuit.NumericalCircuit(n_bus, n_br, n_ld, n_gen, n_sta_gen, n_batt, n_sh, n_time, Sbase)¶

Bases: object

R_corrected(t=None)¶: Returns temperature corrected resistances (numpy array) based on a formula provided by: NFPA 70-2005, National Electrical Code, Table 8, footnote #2; and https://en.wikipedia.org/wiki/Electrical_resistivity_and_conductivity#Linear_approximation (version of 2019-01-03 at 15:20 EST).

compute(add_storage=True, add_generation=True, apply_temperature=False, branch_tolerance_mode=<BranchImpedanceMode.Specified: 0>) → List[GridCal.Engine.Core.calculation_inputs.CalculationInputs]¶: Compute the cross connectivity matrices to determine the circuit connectivity towards the calculation. Additionally, compute the calculation matrices. :param add_storage: :param add_generation: :param apply_temperature: :param branch_tolerance_mode: :return: list of CalculationInputs instances where each one is a circuit island

compute_ts(add_storage=True, add_generation=True, apply_temperature=False, branch_tolerance_mode=<BranchImpedanceMode.Specified: 0>) → Dict[int, List[GridCal.Engine.Core.calculation_inputs.CalculationInputs]]¶: Compute the cross connectivity matrices to determine the circuit connectivity towards the calculation. Additionally, compute the calculation matrices. :param add_storage: :param add_generation: :param apply_temperature: :param branch_tolerance_mode: :return: dictionary of lists of CalculationInputs instances where each one is a circuit island

get_B(apply_temperature=False)¶

Parameters:	apply_temperature –
Returns:

get_different_states()¶: Get a dictionary of different connectivity states :return: dictionary of states {master state index -> list of states associated}

get_raw_circuit(add_generation, add_storage) → GridCal.Engine.Core.calculation_inputs.CalculationInputs¶

Parameters:	add_generation – add_storage –
Returns:

plot(stop=True)¶: Plot the grid as a graph :param stop: stop the execution while displaying

power_flow_post_process(V, only_power=False, t=0)¶: Compute the power flows trough the branches for the complete circuit taking into account the islands @param V: Voltage solution array for the circuit buses @param only_power: compute only the power injection @return: Sbranch (MVA), Ibranch (p.u.), loading (p.u.), losses (MVA), Sbus(MVA)

print(islands_only=False)¶: print the connectivity matrices :return:

GridCal.Engine.Core.numerical_circuit.calc_connectivity(branch_active, C_branch_bus_f, C_branch_bus_t, apply_temperature, R_corrected, R, X, G, B, branch_tolerance_mode: GridCal.Engine.basic_structures.BranchImpedanceMode, impedance_tolerance, tap_mod, tap_ang, tap_t, tap_f, Ysh)¶: Build all the admittance related objects :param branch_active: array of branch active :param C_branch_bus_f: branch-bus from connectivity matrix :param C_branch_bus_t: branch-bus to connectivity matrix :param apply_temperature: apply temperature correction? :param R_corrected: Use the corrected resistance? :param R: array of resistance :param X: array of reactance :param G: array of conductance :param B: array of susceptance :param branch_tolerance_mode: branch tolerance mode (enum: BranchImpedanceMode) :param impedance_tolerance: impedance tolerance :param tap_mod: tap modules array :param tap_ang: tap angles array :param tap_t: virtual tap to array :param tap_f: virtual tap from array :param Ysh: shunt admittance injections :return: Ybus: Admittance matrix

Yf: Admittance matrix of the from buses Yt: Admittance matrix of the to buses B1: Fast decoupled B’ matrix B2: Fast decoupled B’’ matrix Yseries: Admittance matrix of the series elements Ys: array of series admittances GBc: array of shunt conductances Cf: Branch-bus from connectivity matrix Ct: Branch-to from connectivity matrix C_bus_bus: Adjacency matrix C_branch_bus: branch-bus connectivity matrix islands: List of islands bus indices (each list element is a list of bus indices of the island)

GridCal.Engine.Core.numerical_circuit.calc_islands(circuit: GridCal.Engine.Core.calculation_inputs.CalculationInputs, C_bus_bus, C_branch_bus, C_gen_bus, C_batt_bus, nbus, nbr, time_idx=None) → List[GridCal.Engine.Core.calculation_inputs.CalculationInputs]¶

Partition the circuit in islands for the designated time intervals :param circuit: CalculationInputs instance with all the data regardless of the islands and the branch states :param C_bus_bus: bus-bus connectivity matrix :param C_branch_bus: branch-bus connectivity matrix :param C_gen_bus: gen-bus connectivity matrix :param C_batt_bus: battery-bus connectivity matrix :param nbus: number of buses :param nbr: number of branches :param time_idx: array with the time indices where this set of islands belongs to

(if None all the time series are kept)

Returns:	list of CalculationInputs instances

GridCal.Engine.Core.numerical_circuit.get_branches_of_the_island(island, C_branch_bus)¶: Get the branch indices of the island :param island: array of bus indices of the island :param C_branch_bus: connectivity matrix of the branches and the buses :return: array of indices of the branches