Grouping

A grouping is a loose collection of gates, nets, and modules. The elements within a grouping do not need to stand in any kind of relationship to each other and do not have to be connected. In contrast to modules, groupings do not allow for any kind of hierarchization and each element of the netlist can be in at most one grouping at the same time. Each grouping comes with a unique ID and a name.

GUI

Within the GUI, groupings can be managed using the Groupings Widget. The user can create, manipulate, and remove groupings from within the GUI using either GUI functionalities or the provided Python bindings.

TODO: widget and context menus, coloring

Code

A grouping can be created by calling create_grouping on the current netlist. The ID cannot be changed by the user and may only be read by calling the get_id function from C++ or Python. Read and write access to the name is provided by the get_name and set_name functions respectively. Some example Python code is given below:

g = netlist.create_grouping("example_grouping")   # create a new grouping
print(g.get_name())                               # print the name of the grouping
print(g.get_id())                                 # print the ID of the grouping

To retrieve a grouping from the netlist that corresponds to a known ID, the get_grouping_by_id command can be executed on the netlist. Furthermore, a grouping may be deleted using delete_grouping as shown below:

g = netlist.get_grouping_by_id(3)                 # get the grouping with ID 3 from the netlist
netlist.delete_grouping(g)                        # delete the grouping

Elements can be added to a grouping by calling assign_gate, assign_net, or assign_module and removed by using remove_gate, remove_net, or remove_module. Furthermore, the user can check whether an element is part of a grouping by resorting to contains_gate, contains_net, and contains_module. Finally, a list of contained elements is returned by the functions get_gates, get_nets, and get_modules. All these functions also exist in a variant that takes or returns the ID of the respective element(s) instead of the object itself. A short example is given below:

g = netlist.create_grouping("example_grouping")   # create a new grouping
g.assign_gate(netlist.get_gate_by_id(1))          # assign gate with ID 1 to grouping
g.assign_module(netlist.get_module_by_id(2))      # assign module with ID 2 to grouping
g.contains_gate(netlist.get_gate_by_id(4))        # return 'false'
gates = g.get_gates()                             # return a list containing only the gate with ID 1
g.remove_gate(gates[0])                           # remove gate with ID 1 from grouping

Each gate, net, and module always known what grouping it resides in. Hence, by calling get_grouping on one of these elements, one retrieves the containing grouping. If an element is not part of a grouping, this will simply return None.

TODO: add reference to Python Doc