OLED workflows¶

Basic input¶

The minimal input to the deposition workflow just specifies what to deposit:

#!/bin/sh

DEPOSITION_JOBNAME=myDeposition $AMSBIN/oled-deposition << EOF

Molecule
   SystemName myMol
End

System myMol
   ...
End

EOF

The Molecule block is only really used when depositing mixed molecule materials, e.g. host-guest systems. This will be explained in a separate section below. For a single molecule deposition there should just be one Molecule block that references the only System block by name via the SystemName keyword, as shown in the example above.

The System block used by the OLED deposition script closely follows the System block in the input for the AMS driver, but supports only a subset of the keywords:

System

Type

Block

Recurring

True

Description

Specification of the chemical system. For some applications more than one system may be present in the input. In this case, all systems except one must have a non-empty string ID specified after the System keyword. The system without an ID is considered the main one.

Atoms

Type

Non-standard block

Description

The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.

GeometryFile

Type

String

Description

Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz

BondOrders

Type

Non-standard block

Description

Defined bond orders. Each line should contain two atom indices, followed by the bond order (1, 1.5, 2, 3 for single, aromatic, double and triple bonds) and (optionally) the cell shifts for periodic systems. May be used by MM engines and for defining constraints. If the system is periodic and none of the bonds have the cell shift defined then AMS will attempt to determine them following the minimum image convention.

Just like in the AMS driver, as an alternative to the System block, you an also use the LoadSystem block to load a system directly from a .rkf file of a previous calculation.

The deposition workflow uses the ForceField engine for the molecular dynamics simulation of the physical vapor deposition. In order to also support the deposition of metal containing compounds, we use the UFF force field with the UFF4MOF-II parametrization for the deposition. As with any calculation with the ForceField engine you may manually provide (UFF4MOF-II) atom-types, atomic charges and bond orders in the input file:

System
  Atoms
     C  [...]  ForceField.Type=C_R  ForceField.Charge=-0.1186
     N  [...]  ForceField.Type=N_R  ForceField.Charge=-0.2563
     H  [...]  ForceField.Type=H_   ForceField.Charge=+0.1021
     [...]
  End
  BondOrders
     1 2 1.0
     1 5 1.5
     1 6 1.5
     [...]
  End
End

Whatever is not specified in the input will automatically be determined: the input system is optimized with ADF using the S12g exchange-correlation functional with a TZP basis set. At the optimized geometry, the Charge Model 5 is used to calculate the atomic charges, while the rounded Nalewajski-Mrozek bond orders determine the topology. See the ADF manual for details on the calculation of charges and bond orders. Finally, using the topology determined by the calculated bond orders, the automatic UFF atom-typing that is built into the ForceField engine is used to determine the atom-types.

If you want to make sure the correct atom-types and bonds are used in your calculation, we recommend building the system in AMSinput, where you can visually check the bond orders and atom-types to make sure they are correct. The result can then be exported into a file as a System block via File → Export coordinates → .in. For the atomic charges we recommend relying on the automatic calculation with ADF. (Just make sure the ForceField.Charge suffixes are not included in the atom block. Their absence will trigger the automatic charge calculation with ADF.)

By default a box of 60 x 60 x 120 Å is deposited. The first two dimensions give the surface area of the deposited layer, while the third dimension is the thickness of the layer. The size of the deposited box can be changed using the Size keyword in the Box block:

Box
   Size 60 60 120
End

Box

Type

Block

Description

Specifications of the box into which the material is deposited.

Size

Type

Float List

Default value

[60.0, 60.0, 120.0]

Unit

Angstrom

GUI name

Box size

Description

Specify the desired size of the box. The final deposited box may have a different size. The x- and y-axis are perpendicular to the direction of deposition, so these may be regarded as the width of the growing layer. The z-axis is the direction along which the deposition happens, so this determines the thickness of the deposited layer. Note that the x- and y-axis will be ignored if a custom substrate is used: the are of the box is then determined by the lattice of the substrate. The z-axis can still be freely chosen, but should be large enough that there is enough space for the substrate itself and to deposit more molecules on top of it.

With sizes typical for molecules used in OLED devices, the default box size results in a deposition of ~500 molecules. Note that the computational time of a deposition scales linearly with the thickness of the layer, but quadratically with the surface area. This is because a larger area requires both the deposition of more molecules to fill the box, but also makes each MD step more expensive as more molecules have to be simulated at the same time. When increasing the thickness of the layer, molecules at the bottom are first frozen, and later removed from the simulation altogether, giving an overall linear scaling.

The temperature at which the deposition is performed can be configured in the Deposition section.

Deposition
   Temperature float
End

Deposition

Type

Block

Description

Specifies the details of how molecules are deposited.

Temperature

Type

Float

Default value

600.0

Description

The temperature at which the deposition happens.

Finally, there are a couple more technical options in the Deposition section, that we suggest to leave at their default values.

Deposition
   Frequency integer
   TimeStep float
   ConstrainHXBonds Yes/No
   NumMolecules integer
End

Deposition

Type

Block

Description

Specifies the details of how molecules are deposited.

Frequency

Type

Integer

Default value

10000

Description

The frequency in MD steps at which new molecules will be added to the system.

TimeStep

Type

Float

Default value

1.0

Unit

Femtoseconds

Description

The time difference per step.

ConstrainHXBonds

Type

Bool

Default value

Yes

GUI name

Constrain H-* bonds

Description

Constrain the bond length for all H-* bonds (i.e. any bond to a hydrogen atom). Doing this allows choosing a larger time step. If this option is disabled, the TimeStep needs to be reduced manually.

NumMolecules

Type

Integer

Description

The number of molecules that we will try to deposit. If not specified the number will be determined automatically such that the box becomes approximately full.

Output¶

Running the oled-deposition workflow script creates a single directory in which you can find all results of a deposition. By default this directory is named oled-deposition.results, but in order to avoid name clashes, that location can be changed with the AMS_JOBNAME environment variable. The example below will collect all results in the directory myLayer.results:

#!/bin/sh

AMS_JOBNAME=myLayer $AMSBIN/oled-deposition << EOF
...
EOF

Let us go through all files and folders in the working directory in the order in which they are created.

Firstly, the working directory contains a oled-deposition.log logfile. The contents of the logfile are identical to what you see on standard output when running the oled-deposition workflow.

The deposition workflow starts with a couple of calculations on single molecules in vacuum. Each of them runs in a separate folder, in which you can find the usual AMS output files (such as ams.rkf):

myMol.dft_opt/
myMol.ff_opt/
myMol.equilibrate_ff_input_molecule/

Here myMol corresponds to the name of the molecule that was used in the input file. The myMol.dft_opt directory contains the results of the initial geometry optimization with ADF, which is used to determine the atomic charges and bond orders if these were not specified in the input. The myMol.ff_opt directory contains the results of a subsequent geometry optimization using the ForceField engine with the UFF4MOF-II forcefield. Finally in the myMol.equilibrate_ff_input_molecule directory a short MD simulation at the deposition temperature is performed to equilibrate the molecule to the desired temperature. We suggest visualizing the trajectory of this equilibration in AMSmovie to make sure the molecule does not undergo unexpected conformational changes that could be caused by wrong atom-types or bonds. If the molecule behaves strangely (or falls apart) at this point, one may need to go back and assign atom-types and bonds manually in the input.

When depositing mixtures you will see multiple instances of the three directories above: one for each deposited species.

Once all the preparatory work is done, the actual deposition cycles each write a folder and (upon completion of the cycle) two files:

depo_cycle_1/
depo_box.1.in
depo_box.1.xyz

You can follow the progress of your deposition by opening the ams.rkf in the last depo_cycle_*/ directory. The depo_box.*.in and depo_box.*.xyz files contain the entire morphology deposited so far: by visualizing them in order you can watch your material grow!

Once all molecules have been deposited the entire box is annealed from the deposition temperature down to room temperature. This creates one directory and (upon completion) a .in and .xyz file containing the annealed morphologies:

equilibrate_box/
equil_box.in
equil_box.xyz

The last step is to take the room temperature morphology and perform a geometry optimization on it. This essentially removes all thermal vibrations and results in a geometry that is relaxed at the force field level. As you might expect, the last step also produces a folder and (upon completion) a .in and .xyz file:

optimize_box/
morphology.in
morphology.xyz

It is up to the user to decide whether to continue to the OLED properties workflow with the morphology from equil_box.in (equilibrated to 300K) or morphology.in file (fully relaxed). We recommend using the fully relaxed morphology though. We also used fully relaxed morphologies for the generation of the OLED material database.

Deposition of host-guest materials¶

A deposition of host-guest materials can easily be done by specifying multiple Molecule and System blocks in the input. The following runscript generates a 95% to 5% mixture (by number of molecules) of two compounds:

#!/bin/sh

AMS_JOBNAME=host_guest $AMSBIN/oled-deposition << EOF

Molecule
   SystemName myHost
   MoleFraction 0.95
End
Molecule
   SystemName myGuest
   MoleFraction 0.05
End

System myHost
   ...
End
System myGuest
   ...
End

EOF

Molecule
   MoleFraction float
   SystemName string
End

Molecule

Type

Block

Recurring

True

GUI name

Molecules

Description

Specification of the molecule to be deposited.

MoleFraction

Type

Float

Default value

1.0

GUI name

Molar fraction

Description

The relative occurrence of the molecule with regard to other deposited species. Only relevant for mixed molecule depositions.

SystemName

Type

String

GUI name

Molecule

Description

String ID of a named [System] to be inserted. The lattice specified with this System, if any, is ignored and the main system’s lattice is used instead.

You can have an arbitrary number of Molecule blocks in your input to deposit multi-component mixtures. Obviously, the box your are depositing must be large enough that it still contains at least a few molecules of the rarest component.

Note that multiple Molecule and System blocks can also be used to deposit different conformers of the same compound. While conformational changes can in principle happen over the course of the MD simulation, it may be a good idea to deposit a mixture of conformers directly if their geometries are very different.

Deposition of interfaces¶

By default the deposition will use a single graphene layer as a substrate. The graphene layer is removed after the first deposition cycle and will not be included in the output morphologies, i.e. the .in files in the working directory. Note that the graphene layer is not present in the annealing of the entire morphology from deposition temperature to 300K, which is performed at the end of the workflow. The result of this is that both the bottom and top of the deposited thin-film by default represents an interface between the material and a vacuum.

Instead of depositing on a clean graphene sheet, the deposition workflow also supports custom substrates. This is intended to be used for depositing a thin film of one material on top of another material and allows users to study the interface between the two. A custom substrate is set up using the Substrate and SubstrateSystem keys in the Box block.

Box
   Substrate [Graphene | Custom]
   SubstrateSystem string
End

Box

Type

Block

Description

Specifications of the box into which the material is deposited.

Substrate

Type

Multiple Choice

Default value

Graphene

Options

[Graphene, Custom]

Description

The substrate on which to grow the layer.

SubstrateSystem

Type

String

GUI name

Custom substrate

Description

String ID of a named [System] to be used as a substrate. (This is only used when the Substrate key is set to Custom.)

Here the value of the SubstrateSystem refers to a named System block in the input, representing the geometry of the substrate. The following example shows how to deposit a molecule B on top of a substrate of molecule A:

#!/bin/sh

AMS_JOBNAME=molB_on_molA $AMSBIN/oled-deposition << EOF

Molecule
   SystemName molB
End
System molB
   ...
End

Box
   Size 0 0 240
   Substrate Custom
   SubstrateSystem molA_substrate
End

System molA_substrate
   Atoms
      ...
   End
   BondOrders
      ...
   End
   Lattice
      ...
   End
End

EOF

The contents of the block System molA_substrate should be obtained by first running a deposition of molecule A: just use the System block found in e.g. the equil_box.in file of that deposition as the custom substrate for the next job. (Note that no attempt will be made to automatically determine atomic charges, bond orders, or force-field atom types for the molecules in the substrate. Taking the System block from the results of an earlier deposition is the easiest way ensure you are using exactly the same bonds, atom types and charges for the substrate molecules in the new calculation.)

Note that the Box%Size in the x- and y-direction is ignored when using a custom substrate: the size of the custom substrate is used instead. The thickness of the layer can be set manually when using a custom substrate, but it needs to accommodate both the already existing substrate as well as the newly grown film on top. Assume that the thickness of the substrate film is 120 Å in the example above. By setting the the z-value of the Box%Size to 240 Å, we will have space to accommodate the substrate and then grow another layer of 120 Å thickness on top of it. Note that while the default graphene layer is removed from the morphology, a custom substrate will be included in the morphology.

Restarting¶

The OLED workflow scripts are based on the PLAMS scripting framework. As such it can rely on the PLAMS rerun prevention to implement restarting of interrupted depositions.

The easiest way to restart a deposition is to include the --restart (or short: -r) command line flag:

#!/bin/sh

AMS_JOBNAME=myDeposition $AMSBIN/oled-deposition --restart << EOF
...
EOF

This first (interrupted) run will have created the myDeposition.results directory. Running the above script again will move that directory to myDeposition.results.bak and reuse all successful jobs from the first run. (People already familiar with PLAMS will recognize that this works just like the -r flag on the PLAMS launch script.) Note that this does not restart the previous deposition precisely at the point where it was interrupted. Instead it restarts from the beginning of the last deposition cycle.

When running a deposition workflow on a batch system such as SLURM, you may want to consider always including the --restart flag in your runscript. It is not a problem if there are no previous results to restart from, but in case your job gets interrupted and automatically rescheduled, the --restart flag will make sure that it continues (approximately) where it stopped.

There is also the --load (or short: -l) command line flag:

#!/bin/sh

AMS_JOBNAME=newDepo $AMSBIN/oled-deposition -l oldDepo.results << EOF
...
EOF

While this can be used to accomplish the same thing the --restart flag would do, its best use is to specify a directory of a previous deposition of the same molecules. This can save you the initial step of doing the DFT calculations in order to determine the atomic charges and bonds. A perfect use it when you have already deposited a mixture, and later decide to change the ratio between the compounds: by specifying the results directory of the first deposition the initial DFT calculations can be skipped entirely. (Again, people already familiar with PLAMS will recognize that this works just like the -l flag on the PLAMS launch script.)

LAMMPS offload¶

The OLED deposition workflow supports offloading the calculation of the force to a local LAMMPS installation. If a GPU accelerated LAMMPS is available, this can easily speed up the deposition by a factor of 5.

If a local LAMMPS installation is available, it can easily be used through the following keywords in the OLED deposition input file.

LAMMPSOffload
   Enabled Yes/No
   UseGPU Yes/No
   UseOpenMP Yes/No
End

LAMMPSOffload

Type

Block

Description

Offload the calculation to LAMMPS via AMSPipe.

Enabled

Type

Bool

Default value

No

Description

Enable offloading the force field evaluation to LAMMPS instead of handling it internally in AMS.

UseGPU

Type

Bool

Default value

No

GUI name

Use GPU

Description

Accelerate LAMMPS calculations using a GPU. Requires a LAMMPS library built with the GPU package.

UseOpenMP

Type

Bool

Default value

No

GUI name

Use OpenMP

Description

Parallelize LAMMPS calculations using OpenMP threading. Requires a LAMMPS library built with the OMP package.

Basic input¶

The simplest possible input for the oled-properties workflow script is just a single System block.

#!/bin/sh

$AMSBIN/oled-properties << EOF

System
   Atoms
      ...
   End
   Lattice
      ...
   End
  [BondOrders
      ...
   End]
End

EOF

Obviously, the Atoms and Lattice blocks are required, while the BondOrders block is optional. If the bond orders are present, they will be used to determine which parts of the system are connected, which ultimately determines which sets of atoms are considered distinct molecules. If the BondOrders block is not present, the bonds will be guessed. Since we only care about which atoms are bonded at all, and not on details such as the bond order, this should work quite reliably.

Nevertheless, if the morphology was obtained with the AMS deposition workflow, we can use the fact that it writes out the morphology as a .in file containing exactly the System block we need. Basically, we use the morphology.in output file of the deposition as the input for the properties script.

#!/bin/sh

$AMSBIN/oled-deposition << EOF
   ... see oled-deposition manual page ...
EOF

$AMSBIN/oled-properties < oled-deposition.results/morphology.in

This has the advantage that the bonds are guaranteed to be transferred without change between the two workflows.

By default the properties are calculated for all molecules in the morphology, but this can be limited with the SelectedMolecules keyword:

SelectedMolecules integer_list

SelectedMolecules

Type

Integer List

Description

Indices of the molecules to calculate properties for. If not present, all molecules will be used. Note that indexing starts at 0.

Output¶

#!/bin/sh

AMS_JOBNAME=myMaterial $AMSBIN/oled-properties << EOF
...
EOF

myMaterial.results/
├── oled-properties.log
├── oled-properties.rkf
└── properties.hdf5

import h5py

with h5py.File("properties.hdf5", "r") as f:
   IPs = f['energies']['IP'][:]
   print("IP = ", IPs.mean(), "±" , IPs.std())

import h5py
import numpy as np

with h5py.File("properties.hdf5", "r") as f:
   IPs        = f['energies']['IP'][:]
   speciesIDs = f['molecules']['species'][:]

   for specID, specName in enumerate(f['species']['name']):
         mask = (speciesIDs==specID) & (~np.isnan(IPs))
         print(specName)
         print("IP = ", IPs[mask].mean(), "±" , IPs[mask].std())

Additional settings¶

The OLED properties workflow script has a few options that determine what properties will be calculated and/or written to the HDF5 file file:

NumAdditionalOrbitalEnergies integer
NumExcitations integer
TransferIntegrals
   Include
      Cutoff float
      Metric [CoM | Atoms | Atoms_noH]
   End
   Exclude
      Cutoff float
      Metric [CoM | Atoms | Atoms_noH]
   End
   Type [None | Fast | Full]
End

NumAdditionalOrbitalEnergies

Type

Integer

Default value

1

Description

The number of additional orbital energies to write to the HDF5 file. A value of N means to write everything up to HOMO-N and LUMO+N.

NumExcitations

Type

Integer

Default value

1

Description

The number of exited states to calculate. By default the S_1 and T_1 states will be calculated. The calculation of excited states is currently only supported for systems with a closed-shell ground state.

TransferIntegrals

Type

Block

Description

Configures the details of the calculation of electron and hole transfer integrals.

Exclude

Type

Block

Description

Configures which dimers NOT to calculate transfer integrals for.

Cutoff

Type

Float

Default value

4.0

Unit

Angstrom

GUI name

Exclude beyond

Description

Exclude dimers for which the distance is larger than this threshold. Acts as a quick pre-screening to reduce the number of dimers to calculate transfer integrals for.

Metric

Type

Multiple Choice

Default value

Atoms

Options

[CoM, Atoms, Atoms_noH]

Description

The metric used to calculate the distance between two molecules. • CoM: use the distance between the centers of mass of the two molecules. • Atoms: Use the distance between the two closest atoms of two molecules. • Atoms_noH: Use the distance between the closest non-hydrogen atoms of the two molecules.

Include

Type

Block

Description

Configures which dimers transfer integrals are calculated for.

Cutoff

Type

Float

Default value

4.0

Unit

Angstrom

GUI name

Include within

Description

Transfer integrals will be calculated for all molecule pairs within a cutoff distance from each other. This distance can be measured using different metrics, see the corresponding Metric keyword.

Metric

Type

Multiple Choice

Default value

Atoms

Options

[CoM, Atoms, Atoms_noH]

Description

The metric used to calculate the distance between two molecules. • CoM: use the distance between the centers of mass of the two molecules. • Atoms: Use the distance between the two closest atoms of two molecules. • Atoms_noH: Use the distance between the closest non-hydrogen atoms of the two molecules.

Type

Type

Multiple Choice

Default value

Fast

Options

[None, Fast, Full]

Description

The method used for the calculation of the transfer integrals.

There are also a few options to tweak some aspects of the workflow. We have not properly tested their effect on the results. When changing these options, verify your results against calculations using all default settings.

Embedding
   Charges [DFTB | DFT]
   Cutoff float
   Metric [CoM | Atoms | Atoms_noH]
   Type [None | DRF]
End
Relax [None | Neutral | All]
OccupationSmearing [None | Ions | All]

Embedding

Type

Block

Description

Configures details of how the environment is taken into account.

Charges

Type

Multiple Choice

Default value

DFT

Options

[DFTB, DFT]

Description

Which atomic charges to use for the DRF embedding. • DFTB: Use the self-consistent Mulliken charges from a quick DFTB calculation with the GFN1-xTB model. • DFT: Use the MDC-D charges from a relatively quick DFT calculation using LDA and a DZP basis set.

Cutoff

Type

Float

Default value

15.0

Unit

Angstrom

Description

The cutoff distance determining which molecules will be considered the environment of the central molecule. The maximum possible cutoff distance is half the length of the smallest lattice vector. The distance can be measured using different metrics, see the Metric keyword.

Metric

Type

Multiple Choice

Default value

Atoms

Options

[CoM, Atoms, Atoms_noH]

Description

The metric used to calculate the distance between two molecules. • CoM: use the distance between the centers of mass of the two molecules. • Atoms: Use the distance between the two closest atoms of two molecules. • Atoms_noH: Use the distance between the closest non-hydrogen atoms of the two molecules.

Type

Type

Multiple Choice

Default value

DRF

Options

[None, DRF]

Description

The type of embedding used to simulate the molecular environment.

Relax

Type

Multiple Choice

Default value

All

Options

[None, Neutral, All]

Description

Which geometries to relax prior to taking the energy differences for the calculation of ionization potential and electron affinity. The relaxation is done at the DFTB level using the GFN1-xTB model Hamiltonian with electrostatic embedding in a UFF environment. • None: Use the geometries directly from the input. • Neutral: Relax the uncharged molecule and use its optimized geometry for the neutral as well as the ionic systems. This gives (approximately) the vertial ionization potential and electron affinity. • All: Individually relax the neutral systems and the ions before calculating the total energies. This gives (approximately) the adiabatic ionization potential and electron affinity.

OccupationSmearing

Type

Multiple Choice

Default value

Ions

Options

[None, Ions, All]

Description

Determines for which systems the electron smearing feature in ADF will be used. If enabled, the molecular orbital occupations will be smeared out with a 300K Fermi-Dirac distribution. This makes SCF convergence easier, as the occupation of energetically close orbitals does not jump when their energetic order flips. See the ADF manual for details. It is recommended to keep this option enabled for the ionic systems, which are more likely to suffer from difficult SCF convergence.

Parallelization¶

The OLED properties workflow consists of independent chains of calculations for the individual molecules, and therefore scales very well when running on parallel machines. The OLED properties workflow is computationally very expensive. While could theoretically run it on your local machine, you will need HPC facilities to do these calculations within any reasonable time frame.

Luckily, running the OLED workflow via a batch system has become much easier in the 2023 version, thanks to improvements in the underlying PLAMS library. Basically the .run script for the oled-properties workflow script can just be submitted to the batch system like any other AMS job.

The workflow script will then internally take care of scheduling the individual jobs within the allocation that was made for it. All available CPUs are divided into groups, and each group of codes works together on one molecule before moving on to the next. By default 8 CPUs work together, so the oled-properties script submitted to a 128 core cluster allocation, would internally do calculations for 16 molecules at the same time, each one using 8 cores. The size of the groups can be configured with the CoresPerJob keyword:

CoresPerJob integer

CoresPerJob

Type

Integer

Default value

8

Description

The number of CPU cores used for each job in the workflow. Combined with the total number of cores used (set by the NSCM environment variable or the -n command line argument), this indirectly determines the number of simultaneously running jobs. The default value should usually be a good choice. When changing this value, make sure you are using all allocated cores by setting a value that divides the total number of cores, as well as the number of cores on each node.

Restarting¶

Results are continuously written to the HDF5 file as they are calculated. If a job is interrupted, it will therefore leave an incomplete HDF5 file on disk, which can be use to restart the workflow by passing it to the Restart keyword:

Restart string

Restart

Type

String

Description

The HDF5 file from a previous calculation on the same morphology. Data already calculated on the restart file will just be copied over and not be recalculated.

Calculations are then only done for molecules (and dimers) for which not all results have been found on the restart HDF5 file.

This can be combined with the --load (or short: -l) flag, which uses the PLAMS rerun prevention and may prevent rerunning jobs for which the full result files are still available in the results directory of the failed job.

$AMSBIN/oled-properties -l "failed.results" << EOF

Restart failed.results/properties.hdf5

System
   ...
End

EOF

Pure materials¶

1

For the calculation of the mean and standard deviation of IP and EA, data points with a modified Z score > 16 were discarded as outliers. This only affects a few systems that had isolated outliers, e.g. due to SCF convergence problems.

2

T2T and TMBT are actually just two different names for the same compound. We did not realize this until after running the calculations. Both sets of results are included in the database.

Host-guest systems¶