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. 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.

Groupings are the scratch space of a HAL analysis. Reverse engineering proceeds by hypothesis: you notice a set of gates that might belong together, mark them, look at them, and often discard the idea. Committing every such guess to a module would be premature — modules carry a boundary, pins, and hierarchy, and restructuring them is disruptive. A grouping lets you mark things now and decide later.

The practical difference:

	Grouping	Module
Contains	gates, nets, and modules	gates (and submodules)
Hierarchy	none	nested
Has an interface (pins)	no	yes
Affects the netlist structure	no	yes
Typical use	hypotheses, temporary marks, highlighting	recovered structure you are confident about

Groupings are also a GUI feature: each one is assigned a color and its elements are highlighted accordingly in the graph view, which makes them the standard way to make something visible while you work on it. See the Groupings Widget for the interactive side of this. Because groupings are stored in the project, marks you make survive saving and reloading.

Grouping information and management

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 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

Managing gates, nets, and modules

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, named with a _by_id suffix for the assign, remove, and contains functions (assign_gate_by_id, remove_net_by_id, contains_module_by_id, ...) and as get_gate_ids, get_net_ids, and get_module_ids for retrieval. 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.

gate = netlist.get_gate_by_id(1)                  # get the gate with ID 1
g = gate.get_grouping()                           # get the grouping of that gate

A typical use

Groupings pair naturally with a filter over the netlist: select a candidate set programmatically, then look at it in the GUI.

g = netlist.create_grouping("high_fanout_nets")
for net in netlist.get_nets(lambda n: n.get_num_of_destinations() > 50):
    g.assign_net(net)

Since each element can be in at most one grouping, assigning an element that already belongs to another grouping fails and returns False. Pass force=True to move it out of its previous grouping instead:

g.assign_gate(gate, True)   # reassign even if the gate is already in another grouping

Once a hypothesis holds up, promote it: create a module and assign the grouping's gates to it, so the structure becomes a permanent part of the netlist.

See also

• Module — permanent structure with pins and hierarchy, for when a collection turns out to be a unit
• Groupings Widget — creating and managing groupings in the GUI
• Selection — assigning the current selection to a grouping
• Data Container — the other way to record what you found out about an element