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.
Special variables¶
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.
The active configuration¶
The special 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()
Read more about the exposed methods by consulting MoleculeConfiguration
, BulkConfiguration
, SurfaceConfiguration
, DeviceConfiguration
, NudgedElasticBand
in the reference manual.
You can also replace the current configuration by assigning to the configuration
variable:
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'
The selected atoms¶
The special 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
The active camera¶
The special camera
variable allows for the manipulation of the current 3D window camera. Center the camera on the configuration, by calling:
In [-]: camera.center()
The Builder Stash¶
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[0]
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 insert
, append
, duplicate
and delete
:
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 configuration
variable.
In [-]: stash.activate(index)
The stash also supports iteration,
In [-]: for c in stash:
: print(c.title())
Out[-]: Methane
: SiC
: SiC [111]
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()
Console Snippets¶
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:
configuration_info
stash_info
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
.
The console in Builder plugin development¶
Note
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 (BuilderToolBarPlugin
and BuilderPanelPlugin
) are passed a reference to the Console object in their constructor, and can access it through the plugin.console()
method.
The Console object exposes the following API:
console.execute(script)
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.
console.append(script, parameters=None)
The parameters
keyword must contain a dictionary with the defined variables and their values. Note that it is not possible to overwrite the special variables, configuration
, selection
, camera
and stash
.
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.
console.write(script)
Questions¶
Do not hesitate to write questions or comments about the Builder console in the QuantumATK User Forum