From a Foundation Model

This tutorial describes how to evaluate the optical lineshape using a mace foundation model.

Step 0: Identify and Calculate a Transition

The first step is to identify a defect candidate and a potential optical transition. For a transition, there will be a ground state and an excited state, and we perform an atomic relaxation in each state to determine the respective equilibrium geometries.

This step occurs indepedent of lineshape_tools and is left as an exercise for the reader.

Step 1: Compute the Dynamical Matrix

To compute the dynamical matrix, we must specify an atomic geometry as a starting point. The atomic geometry should correspond to the “final state” of the transition: for luminescence, this is the ground state, and for absorption, this is the excited state. This geometry is just a starting point, as we will perform an atomic relaxation to determine the foundation model’s prediction for the equilibrium geometry. (The relaxation can be skipped with the --no-relax-struct tag, but we recommend against this.) Ultimately, since the current foundation models have no notion of electronic structure, they will predict the same geometry for the ground and excited states.

To obtain the dynamical matrix, run

lineshape_tools compute-dynmat /path/to/structure

Note that the structure is read using the ase.io.read function, so a wide variety of first-principles codes are supported. The default assumes you are running on a GPU. If you are limited to CPUs, append --device cpu to the command.

If the above command fails with the error

RuntimeError: Model download failed and no local model found

then you will need to download a foundation model manually. Navigate to the foundation model release page and download one of the *.model files. For example,

wget https://github.com/ACEsuit/mace-foundations/releases/download/mace_omat_0/mace-omat-0-medium.model

The dynamical matrix can be obtained by specifying the path to the model, for example,

lineshape_tools compute-dynmat /path/to/structure --mace-model ./mace-omat-0-medium.model

If the above suceeded, you should have produced a file dynmat.npz in the current directory.

Step 2: Evaluate the Optical Lineshape

Finally, we evalute the luminescence intensity by issuing the following command

lineshape_tools compute-lineshape /path/to/ground/structure /path/to/excited/structure dynmat.npz

This should produce a file lineshape.txt that contains the frequency grid in the first column, the phonon density of states in the second, the spectral density in the third, and the luminescence intensity in the fourth. We can then plot the results with the plotting program of our choice. Alternatively, we can append the --plot subplots tag to produce plots of these three quantities. We note that broadening parameters are highly system specific, and the default values will likely need to be tuned. This can be accomplished using the various tags listed in the lineshape_tools compute-lineshape --help text. If the absorption lineshape is desired instead, append the --absorption tag.

Tip

If your structure files contain total energies (e.g., vasprun.xml files), then the energy difference can be determined automatically. However, this will not include corrections for charge or other effects. Alternatively, the energy difference can be provided with the --de tag.