Games / Command flash cards / TCL for physical design / Dictionaries and arrays

Dictionaries and arrays

Each card shows a command to explain. A missed card returns later in the round and starts the schedule over. A card answered correctly moves up the schedule and next appears after 1, 3, 7, then 21 days. Keys 1 to 4 choose an option, h shows a hint, and Enter moves on. A hint keeps the card where it is on the schedule. An ordering card is answered by clicking its items in order, and one wrong click ends it. Time values are in nanoseconds. Progress is stored in this browser.

SourceTCL (Tool Command Language) is the scripting language every place-and-route and timing tool embeds, so the same skills carry between them. These cards follow the official Tcl manual pages, and each answer links to the page for that command. The examples are in the style the OpenROAD-flow-scripts scripts use, since that is Tcl written for a real flow. Reference: the Tcl manual (Tcl on GitHub).

All 6 cards in this section, with answers

dict set metrics wns -0.06 dict set metrics tns -2.18 puts [dict get $metrics wns]

A dictionary, which is a value held in an ordinary variable.

Hint: Ask what the value of the variable metrics actually is.

A dictionary is a list of alternating keys and values. Because it is a value, it can be passed to a procedure, returned, and stored in a list, which an array cannot. dict for iterates it, and dict exists tests a key without the error that dict get would raise. Tcl reference
set area(nand2) 0.798 foreach cell [array names area] { puts "$cell $area($cell)" }

An array, which stays in the interpreter and cannot be passed by value.

Hint: Compare it with a dictionary: ask what you cannot do with this one.

Arrays predate dictionaries and are still everywhere in tool scripts. Passing one to a procedure needs upvar on its name. array names lists the keys, in no defined order, and array get flattens it into a list that a dictionary can be built from. Tcl reference
dict for {key value} $metrics { puts [format "%-12s %s" $key $value] } dict exists $metrics wns dict keys $metrics

Walks every pair in insertion order, with the keys available separately.

Hint: Ask what order the pairs come out in.

Insertion order is guaranteed, which is what makes a dictionary good for a report whose rows should stay in the order they were built. Testing with dict exists avoids the error that fetching a missing key raises. Tcl reference
set metrics [dict create wns -0.06] set area(nand2) 0.798

A dictionary is a value; an array is a variable.

Hint: Ask which of the two can be returned from a procedure.

Because an array is a collection of variables, a procedure has to reach it with upvar or pass it as array get. A dictionary is an ordinary string, so it can be passed, returned, and nested. Arrays remain useful for very large tables that are updated in place. Tcl reference
dict set runs base place wns -0.06 dict get $runs base place wns

A path of keys into a dictionary of dictionaries.

Hint: Count the words between the command and the value.

Intermediate levels are created as needed on a set, which makes this a tidy way to collect results per run and per stage. Reading a path that does not exist raises an error, so dict exists takes a path too. Tcl reference
dict incr counts $type dict lappend byType $type $violation

Count into a key, and collect a list under a key.

Hint: Both work on a key that may not be there yet.

This is the whole of a violation summary: walk the report, increment by type, and keep the instances under the same key. Neither needs the key to exist first, which removes the usual test before each update. Tcl reference