The Builder Console¶
The Builder Console is an expert tool in the Nanolab Builder, where you can manipulate the Builder configurations using QuantumATK scripting.
Also, Builder Plugins can expose QuantumATK commands in the console. When plugins write to the console, a visual counter is shown over the console icon.
Unfold the console by clicking the console icon in the bottom left corner of the Builder.
You can execute any valid QuantumATK command through the console. In addition the console also exposes four magic variables, which allow you to interact with the configurations in the Builder.
configuration variable always refers to the active configuration in the 3D window. If the current configuration is methane or \(CH_4\), you can use QuantumATK to perform operaitons such as querying the elements list:
In [-]: configuration.symbols() Out[-]: ['C', 'H', 'H', 'H']
You can also manipulate the current configuration, using the exposed methods:
In [-]: configuration.deleteAtoms([1, 2]) In [-]: configuration.shiftAtoms([0, 0, 1] * Angstrom, indices=[0, 1, 2, 3]) In [-]: configuration.findBonds()
You can also replace the current configuration by assigning to the
In [-]: configuration = repeat(configuration, 2, 2, 2) In [-]: configuration = MoleculeConfiguration([Oxygen, Oxygen], [[0, 0, 0] * Angstrom, [0, 0, 1.208] * Angstrom])
In the Builder Console the configurations also expose their title. This is special for the Builder Console, and cannot be used in other QuantumATK scripts.
In [-]: configuration.title() Out[-]: 'Methane'
selection variable contains a list of the selected indices of the active configuration.
In [-]: selection Out[-]: array([1, 2])
You can change the current selection by setting the selection like this:
In [-]: selection = [0, 1, 2, 3]
Note that the first element is numbered “0”, the second “1” and so on. You can also select “All” or “None” of the atoms.
In [-]: selection = All In [-]: selection = None
camera variable allows for the manipulation of the current 3D window camera. Center the camera on the configuration, by calling:
In [-]: camera.center()
The list of configurations in the left side of the Builder is called the Builder Stash, and the console has a special
stash variable that refers to this list of configurations.
Simply retrieve configurations in the stash by referring to their index or title:
In [-]: stash In [-]: stash['GaAs']
The latter only works if there is only one configuration titled ‘GaAs’. Note that the first element is numbered “0”, the second “1” and so on.
Configurations in the stash can be overwritten by assigning different configuration, for example:
In [-]: stash['GaAs'] = MoleculeConfiguration([Oxygen, Oxygen], [[0, 0, 0 ], [0, 0, 1.208]] * Angstrom)
In the stash you can also query both for title and index:
In [-]: stash.title(0): Out[-]: 'GaAs' In [-]: stash.index('GaAs') Out[-]: 0
The titles of the stash items can also be changed:
In [-]: stash.setTitle('GaAs', 'GalliumArsenide')
Configurations can be added to and deleted from
stash by using the methods
In [-]: stash.insert(2, new_configuration) # Or using the title stash.insert('GaAs', new_configuration) In [-]: stash.append(new_configuration) In [-]: stash.duplicate(2) # Or using the title stash.duplicate('GaAs') In [-]: stash.delete(2) # Or using the title stash.delete('GaAs')
You can also switch to another active configuration. This will also update the special
In [-]: stash.activate(index)
The stash also supports iteration,
In [-]: for c in stash: : print(c.title()) Out[-]: Methane : SiC : SiC 
You can also access the currently selected entries in the stash. Select multiple items by clicking on configurations in the Builder Stash with your mouse. Then call the
stash.selected() method to retrieve a list of the selected configurations.
In [-]: stash.selected() Out[-]: [Configuration(), ..., Configuration()]
An iterating over the selected titles and e.g. centering their camera.
In [-]: for item in stash.selected(): : stash.activate(item.title()) : camera.center()
Sometimes you may wish to execute same set of commands in the Builder Console several times over. The Console snippets help you do just that without having to bother with copy-pasting preformatted commands.
Unfold the console and access the snippets by clicking on the button to the top-right of the console. The first time you do this, the following menu opens:
- New snippet
- Open snippets folder
The first two entries are example snippets that ship with QuantumATK. Each snippet show a simple example that uses the
configuration and the
stash variable respectively.
Click a snippet to insert it into the console. You can also insert and execute the snippet by clicking the running man icon, or open the snippet in the snippet editor by clicking the pencil icon.
New snippets are created by clicking the
New snippet menu entry. This opens the Snippet editor, where you can rename, edit, delete and execute (run) the snippet in the Builder Console.
Since snippets are just python scripts, they are saved in the ~/.vnl/buillder/console subfolder. You can open the folder by clicking
Open snippets folder.
This section discusses the development of BuilderToolBarPlugins or BuilderPanelPlugins, and only relevant if you wish to develop your own plugins.
Builder plugin developers can insert and execute commands in the Builder console.
Several native plugins already expose their QuantumATK commands in the Console. Try using either the Repeat, Center or Passivate Builder plugins to see how it works.
Builder plugins (
BuilderPanelPlugin) are passed a reference to the Console object in their constructor, and can access it through the
The Console object exposes the following API:
This writes the script to the console and executes it afterwards.
For advanced users it is also possible to append a script to the console history, and insert additional parameters into the console scope.
parameters keyword must contain a dictionary with the defined variables and their values. Note that it is not possible to overwrite the special variables,
It is also possible to simply insert a script into the console without executing it. This can be done by invoking the
write method on the console object.