Study objects¶

In QuantumATK version 2018, a new type of calculation object has been introduced: the study object. Study objects have been designed to facilitate both long-running calculations and complex studies of a particular type of system. The defining feature of a study object is that it is made up of a number of smaller interdependent tasks. The number and nature of the tasks (e.g., whether they are homogeneous or heterogeneous), and the dependencies between them, will depend on the particular type of study.

The study object can execute its tasks either in serial or in parallel. If the program is terminated before the calculation finishes (e.g., the requested wall time given to a job scheduler was insufficient) then it can be automatically resumed from the already completed tasks by running the same script again.

In order to support this resuming, the study object takes care of writing its results to disk on-the-fly. This means that all study objects require a filename and object_id (see nlread for more details). Since all the results are saved automatically, it is not necessary (or allowed) to call nlsave on a study object. Saved study objects can then be read normally with nlread.

In addition to providing support for resuming execution, study objects also allow for the user to modify and update existing calculations. When any existing study object is modified the previously calculated data is reused (when appropriate), which greatly improves performance. For example, the IVCharacteristics study object allows for additional voltage points to be added to a pre-existing calculation. This means that an initial rough calculation can be quickly refined.

Note

In contrast to Analysis objects, study objects do not perform any calculation when the object is constructed; instead, the object’s update method must be called first. Similarly, when adding or modifying data points in a study object, update must be called before the new points will be calculated and the changes will be available for any post-processing methods.

For a full list of study objects see the Study section of the reference manual.

Restart example¶

As an example, consider this simple script carbon-chain-ivcharacteristics.py, which applies the IVCharacteristics study object to the model system of a carbon chain. It runs in a few minutes, but to show the restart capability of study objects, we purposefully interrupted it. The first log file therefore show the first 3 tasks being executed, as it was interrupted during the third task:

+------------------------------------------------------------------------------+
| Executing task 1 / 22:                                                       |
|   Update configuration                                                       |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.0 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.0_Volt.log                    |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| Executing task 2 / 22:                                                       |
|   Calculate TransmissionSpectrum                                             |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.0 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.0_Volt.log                    |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| Executing task 3 / 22:                                                       |
|   Update configuration                                                       |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.1 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.1_Volt.log                    |
+------------------------------------------------------------------------------+


To continue the calculations, we simply execute the same script in the same directory, giving this information in the log-file:

+------------------------------------------------------------------------------+
| Executing task 1 / 20:                                                       |
|   Update configuration                                                       |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.1 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.1_Volt.log                    |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| Executing task 2 / 20:                                                       |
|   Calculate TransmissionSpectrum                                             |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.1 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.1_Volt.log                    |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| Executing task 3 / 20:                                                       |
|   Update configuration                                                       |
|   Gate voltage: 0.0 V                                                        |
|   Left electrode voltage: 0.2 V                                              |
|   Right electrode voltage: 0.0 V                                             |
|   Log to: ivcharacteristics_Vgs_0.0_Volt_Vds_0.2_Volt.log                    |
+------------------------------------------------------------------------------+


Note how the total number of tasks has decreased by two, as the first two tasks were successfully completed in the first run, and QuantumATK simply starts from the task that was interrupted. In this case, we chose to interrupt it and restart it a second time, while letting the third run finish. The full log-files can be found here: