The global parameters database¶

Where are the parameters?¶

Parameter sets and configurations available throughout PyNitride are stored as .txt files in the PyNitride/parameters directory.

Files that begin with an underscore (eg _meta.txt) are for configuration and all others are (intended) for material parameters and the like. The first line of a file describes its syntax.

_system.txt begins with a line # Pint, implying that it is a units definition file for the Pint library.
Currently, all other files supplied in the distribution begin with PyNitride v2, indicating compatibility with version 2 of PyNitride.

Accessing parameters¶

Parameters can be accessed from a ParamDB object. They will be returned in the internal unit system of PyNitride. For example, if the relative dielectric constant of GaN is \(\epsilon_r=10.4\), then

>>> from pynitride import *
>>> pmdb=ParamDB()
>>> epsilon=pmdb['GaN.dielectric.eps']
>>> print("{:.3g} eps_0".format(to_unit(epsilon,"epsilon_0")))
10.4 eps_0
>>> print("{:.2g} F/cm".format(to_unit(epsilon,"F/cm")))
9.2e-13 F/cm

The above example shows how to print the permittivity of GaN in two ways. The details of the units system are discussed in the Units section, so here we will just discuss the syntax for accessing the parameters.

[ FILL IN A LOT MORE HERE. ]

Parameters file format¶

Parameter files have a broadly adaptable, generic, nested structure to suit the different sorts of information that different solvers or analyses will require. The overall syntax is described below, but the content, ie what information is used and how it should be structured, is left to the individual solvers and utilities. (For example, if you want the Schrodinger solver to work out-of-the-box with a parameter file you add, check the documentation of the Schrodinger solver to see what parameters it requires.)

Overall structure¶

Here’s an sample chunk of a parameter file:

PyNitride v2

...

material=GaN
    material type=binary
    conditions=strained to AlN
        Eg: 3.605 eV
        surface=GenericMetal
            electronbarrier: 1 eV
        carrier=electron
            DEc: 0 eV
            band=
                g: 2
                mdos: .2 m_e
        carrier=hole
            DEv: 0 eV
            band=HH
                g: 2
                mdos: 1.5 m_e
        polarization
            Ptot: 2e-6 e/cm**2    # don't trust this value
    conditions=
        dielectric
            eps: 10.4 epsilon_0

...

Now let’s break it down. First, some general conventions:

The first line of the file is PyNitride v2
Any content after # on a line is ignored (as a comment)
Blank lines (including lines which begin with #) are ignored
The characters =, ., :, and [] are special and their uses are described below.

There are three types of lines:

Unnamed lines, eg polarization: are simply a string Y. This indicates that the subsequent parameters belong to Y. For this example polarization might be followed by lines describing coefficients of spontaneous and piezoelectric polarization.
Named lines, eg material=GaN: are of the form X=Y where X and Y are any strings. Y has the same role as above: in this example, lines would follow describing the material GaN. The X= is provided as a convenience which will allow more flexible forms of access as described in Accessing parameters. Also Y can be empty: this typically indicates a default value. For example, there are often lines like conditions=relaxed which indicate parameters for a relaxed material, as well as lines like conditions= to indicate fallback parameters which apply when conditions are not specified.
Value lines, eg eps: 10.4 epsilon_0: are of the form X:Y, where X is any string (with no quotes, not containing periods or equals signs) and Y is a value as described below in Values specification. When following the below-specified formats Y can contain any of the mentioned special characters as needed.

Lines are related by nesting space-indentation. Note that lines of different types all intermix, but also that it is important to align indents (eg. Eg, surface=..., carrier=... are all the same number of spaces from the start of line.

Array special syntax¶

The structure outlined above essentially maps onto nested dictionaries, but sometimes, it may not make sense to “name” the subitem keys. Sometimes, you really just want a list. For instance, _meta.txt contains a list of parameter files to read in:

...
meta
    default parameter files:
        .:'VM2003.txt'
        .:'chemistry.txt'
        .:'fake.txt'
...

The : at the end of default parameter files indicates that the subsequent elements form an array, not a dictionary. The subsequent value lines begin with a . rather than a proper key. This is entirely equivalent to

...
meta
    default parameter files: ['VM2003.txt','chemistry.txt','fake.txt']
...

This syntax generalizes to allow the elements of the list to be more than just values. For instance, chemistry.txt contains the following:

crystal=wurtzite
    unitcell=conventional
        basis:
            .
                element: 'Nitrogen'
                position: `lambda u=3/8: r_[0,0,0]`
            .
                element: 'Gallium'
                position: `lambda u=3/8: r_[0,0,u]`
            .
                element: 'Nitrogen'
                position: `lambda u=3/8: r_[1/3,1/3,1/2]`
            .
                element: 'Gallium'
                position: `lambda u=3/8: r_[1/3,1/3,1/2+u]`

where it’s clear that the elements of the array are allowed to continue containing the entire nested syntax of the parameter files.

Values specification¶

Values for Value lines may be of any of following forms

A number with or without units. For example, g: 2 describes a unitless degeneracy. And mdos: .2 m_e describes the density-of-states mass in units of the electron mass. Such expressions will be parsed by Pint, and a full list of allowed values (including units such as meter, prefixed units such as meV, more complex units like cm**-2 and constants such as hbar) is provided in the Pint docs. Numbers with units are all converted to pure numbers in the internal units system of PyNitride.
A string enclosed by quotes, eg type: "Acceptor"
An arbitrary single-line Python expression enclosed in backticks, eg `Eg: lambda T: 3.510 - (.909)*T**2/(T+830)`. Currently, such expressions do not have access to other parameter values, but that is an obvious direction for future development.