cstool parameter file format

Parameters for cstool are provided in the YAML text format. An example paramter file is:

name:           alumina
density:        3.98 g/cm³

    Al: { count: 2, Z: 13, M: 26.982 g/mol }
    O:  { count: 3, Z:  8, M: 15.999 g/mol }

    model:      insulator
    valence:    3.64 eV
    band_gap:   7.0 eV
    affinity:   3.71 eV

    df_file:   elf/df_Al2O3.dat

    lattice:    4.76 Å

        ac_def: 13.0 eV

        c_s:    11003 m/s

        c_s:    6512 m/s

Generic parameters

The following generic parameters are required:

  • Name
  • Density

These parameters speak for themselves.

Element list

Next in the example file is the list of elements in the material. Each element should have its own entry; each entry should look like this:

    Al: { count: 2, Z: 13, M: 26.982 g/mol }
  • Al is the name of the element. This is not used by cstool, but you should use a reasonable name for the benefit of other humans.
  • count is the number of atoms per unit cell
  • Z is the atomic number
  • M is the average atomic mass

Band structure

We use a very simplistic band structure model. Metals have a single band, the conduction band. Semiconductors and insulators have two bands, the valence and conduction bands, with a band gap in between.

The parameter you need to provide is model, which can be metal, semiconductor or insulator. The semiconductor and insulator models are actually equivalent.

If the model is metal, the following parameters are required:

  • fermi: The position of the Fermi energy, with respect to the bottom of the conduction band
  • work_function: The work function

If the model is semiconductor or insulator, we need the following parameters:

  • valence: the width of the valence band
  • band_gap: the band gap
  • affinity: the electron affinity


Only one parameter is possible here, df_file. This is the file name with optical parameters. The exact file format of that file is described here.


These are parameters for the electron-acoustic phonon scattering model of Schreiber and Fitting.

The phonon section may look as follows (parameters are for silicon):

    lattice:    5.43071 Å
    m_dos:      1.08 m_e
    m_eff:      0.26 m_e

        alpha:  2.00e-7 m²/s
        c_s:    9130 m/s
        ac_def: 9.2 eV

        alpha:  2.26e-7 m²/s
        c_s:    5842 m/s
        ac_def: 5.0 eV

One parameter is always required:

  • lattice, which is the material's lattice constant.

Two parameters are optional:

  • m_eff: the effective mass of the electron
  • m_dos: the density-of-states mass of the electron

If these are not provided, they are set to the electron rest mass in vacuum.

There are three phonon modes: two transverse and a longitudinal one. Per mode, two parameters are required:

  • c_s: the speed of sound
  • ac_def: the acoustic deformation potential

Another parameter is optional:

  • alpha, with units of m²/s, describes the band bending of the phonon dispersion relation near the Brillouin zone edge. This is zero by default.

In practice, it is very difficult to find the acoustic deformation potential in literature. If it is available, it is often an effective value combining the longitudinal and transverse modes. If that happens, you can provide the ac_def, c_s and alpha parameters in an isotropic branch instead of the longitudinal and transverse branches separately. If you do have separate longitudinal and transverse speeds of sounds, you can provide these in their respective branches, and cstool will automatically combine them with the isotropic acoustic deformation potential. This has happened in the parameter file all the way at the top of this page.

Finally, for metals, there is a way to estimate the acoustic deformation potential using the resistivity (which is much easier to find). Instead of providing ac_def in the isotropic branch, you may provide a resistivity parameter. The phonon section may then look as follows (parameters are for gold):

    lattice:         4.0782 Å

        resistivity: 2.44e-8 Ω m

        c_s:         3240 m/s

        c_s:         1200 m/s