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