2.6.13. run{}

Specifications for the program execution (program flow)

Note

There are two syntaxes for run{}.

New syntax

recommended syntax for versions newer than 2020-05-01. We specify new syntax in this documentation.

Deprecated syntax

used in versions older than 2020-04-30. Nevertheless, it will still work in later versions. Deprecated syntax is specified here.

General

run{ structure_only{} } (optional)

If present, calculation is aborted after structure setup, similarly to when the command line flag -s or --structure is set. But differently from the command line flag, if last_region is present, partial structure initialization is performed. This is useful for debugging your structure definition, e.g. if you have a 2D or 3D simulation with many material regions, contact regions, doping regions and generation regions overlapping each other in a complicated way. The files in the output directory Structure/ will then reflect this partial initialization. (Note that in case not all regions are used here, some initialization and output steps related to strain, poisson, current, quantum, cbr, optics, etc. will be omitted in order to avoid inconsistencies.)

last_region{ <integer> }
value:

any integer >= 1

default:

1000000

Example:

run{
    structure_only{
        last_region = 5
    }
}

The simulation prints out the structure up to the (last) region index 5.

run{ strain{} } (optional)

It solves the strain equation

Semi-Classical Run

run{ poisson{} } (optional)

It solves the Poisson equation

run{ current_poisson{} } (optional)

It solves the coupled current and Poisson equations self-consistently.

fermi_limit (optional)
value:

any float between 0.0 and 10.0

default:

2.0

Defines how far the quasi-Fermi levels can move above the highest / below the lowest contact. Except in case of huge band gaps and extreme photogeneration, the defaults should not require any change. At the same time, in the absence of any externally induced photogeneration, these values could be set to zero in order to stabilize the iteration.

multi_stage_solve (optional)
value:

yes or no

default:

no

Flag in order to solve classical current equation first with recombination/generation switched off in order to get a good starting point, and then with recombination/generation switched on (if any recombination models are switched on). Can be used to improve convergence in some situations but may increase runtime in others.

fast_poisson (optional)
value:

yes or no

default:

no

If enabled, Newton iterations for Poisson in the middle of the classical current-Poisson iteration will be limited to 1. Note that enabling this setting may also influence stability of convergence or change the optimal value for alpha_fermi. Typically, yes increases the number of iterations but significantly reduces the overall execution time.

system_solve (optional)
value:

yes or no

default:

no

Alternative new iteration method for classical current-Poisson. This Newton method may provide better convergence for some systems (but may require different values of convergence parameters). Setting system_solve = yes results in Fermi levels and potential being simultaneously updated as a system of unknowns during the iteration. Irrespective of its value, system_solve always takes the value of current_repetitions into account.

iterations (optional)
value:

any integer >= 1

default:

100

Maximum number of iterations for current-Poisson solver

current_repetitions (optional)
value:

any integer >= 1

default:

1

Number of current-density iterations. The current equations are repeatedly solved for the quasi-Fermi levels with the densities fixed. The current equation for the electrons and for the holes are solved independently with a common and fixed recombination term. For each iteration, the densities are adjusted according to the new quasi-Fermi levels of the previous iteration. current_repetitions defines number of these repetitions. If generation/recombination is present, using a value > 1 (e.g. 5) may stabilize the iteration and sometimes enable faster convergence (larger alpha_fermi may also be possible then).

limit_repetitions (optional)
value:

yes or no

default:

no

If enabled, the current-density loop is exited early as soon as residual_fermi is reached by the quasi-Fermi levels.

residual (optional)
value:

any float > 0.0

default:

1e5 cm-2 (1D)

1e3 cm-1 (2D)

1e-3 [dimensionless] (3D)

Residual occupation changes.

residual_fermi (optional)
value:

any float > 0.0

default:

1e-5 # [eV]

Residual Fermi level changes, see Residuals for more details. This value is also used during quantum_current_poisson{ }

alpha_fermi (optional)
value:

any float between 1e-5 and 1.0

default:

1.0

Dimensionless under-relaxation parameter for Fermi level. The final quasi-Fermi level for electrons after each iteration is calculated as follows:

\(E_{F,n}\) = ( \(E_{F,n}\) of previous iteration ) * ( 1 - alpha_fermi) + ( \(E_{F,n}\) of actual iteration ) * alpha_fermi

This Fermi level is then input to the next iteration. The same holds for the Fermi level \(E_{F,p}\) for holes. The value of alpha_fermi will change due to alpha_scale during the iterations. The actually used alpha_fermi is now included in iteration_current_poisson.dat and iteration_quantum_current_poisson_details.dat.

alpha_iterations (optional)
value:

any integer >= 1

default:

1000

Iteration at which alpha_fermi begins to be rescaled by alpha_scale at each following iteration.

alpha_scale (optional)
value:

any float between 0.1 and 1.0

default:

0.998

A factor rescaling alpha_fermi starting at the iteration alpha_iterations, both for classical and quantum stages of simulation. The alpha_fermi is overwritten by: max( alpha_fermi * alpha_scale , 1e-5) at each iteration step once the number of iterations exceeds alpha_iterations.

Use this feature to improve convergence (particularly convergence of Fermi levels) towards the end of the iteration.

Attention

Decreasing alpha_fermi too fast (a problem with older versions) will result in the iteration stalling (only the residuals of the densities but none of the Fermi levels decrease). The total current equation may then not be properly conserved.

output_log (optional)
type:

choice

values:

yes or no

default:

yes

output_local_residuals (optional)

Outputs residuals as functions of position when output_local_residuals = yes. In case the attribute is enabled for both classical and quantum iterations, the quantum iteration overwrites the respective files of the classical iteration.

type:

choice

values:

yes or no

default:

no

Attention

Both conditions specified by residual and residual_fermi must hold in order to consider a calculation as converged.

Quantum Run

run{ quantum{} } (optional)

It solves the Schrödinger equation. Exchange–correlation effects (optional) can be included and are calculated from the quantum density. Then the Schrödinger equation is solved again but this time including the exchange-correlation potential energy.

run{ quantum_density{} } (optional)

Includes exchange correlation effects into solutions of Schrödinger equation in a self-consistent manner.

residual (optional)

residual of the integrated total charge carrier density changes. Note that this is dimension dependent and default is: 1e5/cm2 (1D), 1e3/cm (2D), 1e-3[dimensionless] (3D). This applies to exact Schrödinger equation, not to subspace Schrödinger equation

type:

real number

constrain:

residual >= 0

default:

1e5 cm-2 (1D), 1e3 cm-1 (2D), 1e-3 [dimensionless] (3D)

Note

If you do not include enough eigenstates, the convergence behavior might be affected as the occupation of the eigenstates is not considered in a useful way.

iterations (optional)

Maximum number of iterations, i.e. self-consistency cycles

type:

integer number

constrains:

iterations >= 0

default:

30

use_subspace (optional)

solve Schrödinger equation within subspace of eigenvectors of previous iteration as long as achieved residual is larger than desired residual * residual_factor and at least in every second iteration

type:

choice

values:

yes or no

default:

yes

subspace_iterations (optional)
type:

integer number

constrains:

1 <= subspace_residual_factor <= 1000

default:

1

subspace_residual_factor (optional)
type:

real numbers

constrains:

subspace_residual_factor >= 2.0

default:

1e12

output_log (optional)

Output of convergence of Schrödinger-Poisson equation (residuals for quantum_poisson) into the logfile iteration_quantum_poisson.dat

type:

choice

values:

yes or no

default:

yes

output_local_residuals (optional)

Outputs residuals as functions of position when output_local_residuals = yes. In case the attribute is enabled for both classical and quantum iterations, the quantum iteration overwrites the respective files of the classical iteration.

type:

choice

values:

yes or no

default:

no

run{ quantum_poisson{} } (optional)

It solves the Schrödinger-Poisson equations self-consistently. When quantum_poisson{} is desired, note that additionally either poisson{} or current_poisson{} is required.

residual (optional)

residual of the integrated total charge carrier density changes. Note that this is dimension dependent and default is: 1e5/cm2 (1D), 1e3/cm (2D), 1e-3[dimensionless] (3D). This applies to exact Schrödinger equation, not to subspace Schrödinger equation

type:

real number

constrain:

residual >= 0

default:

1e5 cm-2 (1D), 1e3 cm-1 (2D), 1e-3 [dimensionless] (3D)

Note

If you do not include enough eigenstates, the convergence behavior might be affected as the occupation of the eigenstates is not considered in a useful way.

iterations (optional)

Maximum number of iterations, i.e. self-consistency cycles

type:

integer number

constrains:

iterations >= 0

default:

30

use_subspace (optional)

solve Schrödinger equation within subspace of eigenvectors of previous iteration as long as achieved residual is larger than desired residual * residual_factor and at least in every second iteration

type:

choice

values:

yes or no

default:

yes

subspace_iterations (optional)
type:

integer number

constrains:

1 <= subspace_residual_factor <= 1000

default:

1

subspace_residual_factor (optional)
type:

real numbers

constrains:

subspace_residual_factor >= 2.0

default:

1e12

alpha_potential (optional)
value:

any float between 0.001 and 1

default:

1.0

In case of stubborn convergence problems which do not appear to have any root cause such as not enough eigenvalues and which appear not to respond to any change in other parameters, try using a mildly smaller value than 1.0 such as 0.5.

Using values smaller than 1.0 per default is not recommended, as the run time is expected to increase as 1/ alpha_potential for normally converging input files.

output_log (optional)

Output of convergence of Schrödinger-Poisson equation (residuals for quantum_poisson) into the logfile iteration_quantum_poisson.dat

type:

choice

values:

yes or no

default:

yes

output_local_residuals (optional)

Outputs residuals as functions of position when output_local_residuals = yes. In case the attribute is enabled for both a classical and quantum iterations, the quantum iteration overwrites the respective files of the classical iteration.

type:

choice

values:

yes or no

default:

no

run{ quantum_current_poisson{} } (optional)

It solves the Schrödinger-Current-Poisson equations self-consistently. When quantum_current_poisson{} is desired, note that additionally either poisson{} or current_poisson{} is required and current_poisson must be defined in the input file..

residual (optional)
default:

1e5 (1D) / 1e3 (2D) / 1e-3 (3D)

see quantum_poisson{}

iterations (optional)
value:

integer

default:

30

see quantum_poisson{}

use_subspace (optional)
value:

yes or no

default:

yes

see quantum_poisson{}

subspace_iterations (optional)
value:

any integer between 1 and 1000

see quantum_poisson{}

subspace_residual_factor (optional)
value:

any float >= 2.0

default:

1e12

see quantum_poisson{}

fermi_limit (optional)
value:

any float between 0.0 and 10.0

default:

2.0

see quantum_poisson{}

current_repetitions (optional)
default:

2

number of current-density iterations. The current equation is repeatedly solved for the quasi-Fermi levels. For each iteration, the densities are adjusted according to the new quasi-Fermi levels of the previous iteration. current_repetitions defines number of these repetitions. If generation/recombination is present, using a value > 1 (e.g. 5) may stabilize the iteration and sometimes enable faster convergence (larger alpha_fermi may also be possible then).

limit_repetitions (optional)
value:

yes or no

default:

yes

If enabled, the current-density loop is exited early as soon as residual_fermi is reached by the quasi-Fermi levels.

residual_fermi (optional)
value:

any float > 0.0

default:

1e-5 [eV]

alpha_fermi (optional)
value:

any float between 1e-5 and 1.0

default:

1.0

The Fermi level is under-relaxed between repetitions using an under-relaxation parameter for the Fermi levels. It should be used once an oscillation of residuals is observed while self-consistently solving the Poisson and Schrödinger (and current) equations to improve convergence. For further information, please read comments on alpha_fermi parameter above

alpha_iterations (optional)
value:

any integer >= 1

default:

1000

number of alpha iterations

alpha_scale (optional)
value:

any float between 0.1 and 1.0

default:

0.998

Both for classical and for quantum iterations, alpha_fermi will be reduced further as alpha_fermi <- max( alpha_fermi * alpha_scale , 1e-5) at each iteration step once the number of iterations exceeds alpha_iterations. Use this feature to improve convergence (particularly convergence of Fermi levels) towards the end of the iteration. Note that decreasing alpha_fermi too fast (a problem with older versions) will result in the iteration stalling (only the residuals of the densities but none of the Fermi levels decrease). The total current equation may then not be properly conserved.

alpha_potential (optional)
value:

any float between 0.001 and 1

default:

1.0

In case of stubborn convergence problems which do not appear to have any root cause such as not enough eigenvalues and which appear not to respond to any change in other parameters, try using a mildly smaller value than 1.0 such as 0.5.

Using values smaller than 1.0 per default is not recommended, as the run time is expected to increase as 1/ alpha_potential for normally converging input files.

output_log (optional)

Output of convergence of (quantum) current-Poisson equation (residuals for quantum_current_poisson) into the logfile iteration_quantum_current_poisson.dat

type:

choice

values:

yes or no

default:

yes

output_local_residuals (optional)

Outputs residuals as functions of position when output_local_residuals = yes. In case the attribute is enabled for both classical and quantum iterations, the quantum iteration overwrites the respective files of the classical iteration.

type:

choice

values:

yes or no

default:

no

Note

Both conditions specified by residual and residual_fermi are only checked between iterations but not between repetitions.

run{ quantum_optics{} } (optional)

calculate optical properties using results of quantum{}, see optics{}

Examples

run{
    structure_only{}             # If present, calculation is aborted after structure setup.
}

run{}                         # just sets up the device geometry

run{
    strain{}                   # solves the strain equation
}

run{
    strain{}                   # solves the strain equation
    quantum{}                  # and then the Schrödinger equation
}

run{
    strain{}                   # solves the strain equation
    poisson{}
    quantum_poisson{}          #
}                              # solves the Schrödinger and Poisson equations self-consistently

run{
    strain{}                   # solves the strain equation
    current_poisson{}          # solves the coupled current and Poisson equations self-consistently
    quantum_current_poisson{}  # solves the Schrödinger,  Poisson and current equations self-consistently
}

run{
    quantum{}                  # solves the Schrödinger equation
    quantum_optics{}                   # calculates optical properties using quantum solutions
}

Using the new syntax (quantum_poisson{}, quantum_current_poisson{}), the classical computations (poisson{} or current_poisson{}) can be specified independent of the quantum calculation to be performed, e.g. it is now possible to combine poisson{} with quantum_current_poisson{} to bypass the classical current calculations.

Restrictions

  • Poisson: Only maximally one of poisson{} and current_poisson{} can be defined, which defines the classical equation to be solved (also as first stage before possibly solving any quantum mechanics). If neither is set, only fixed potentials will be used.

  • Quantum: If quantum mechanics is desired, one of quantum{}, quantum_density{}, quantum_poisson{}, and quantum_current_poisson{} must be set.

  • The quantum equations to be solved - only quantum, quantum with self-consistent density/exchange, self-consistent quantum-Poisson, and self-consistent quantum-current-Poisson - are only defined by the choice of quantum{}, quantum_density{}, quantum_poisson{}, and quantum_current_poisson{}, irrespective of the choice of the classical solution method. Note that one of poisson{} and current_poisson{} must be set when quantum_poisson{} or quantum_current_poisson{} is desired. Use poisson{} in conjunction with quantum_current_poisson{} to skip classical current calculations.

  • Quantum with self-consistent density/exchange is solved by selection of quantum_density{} (users can change parameters in there as needed).

Further remarks

2019-01-24: At the end of current_poisson{}, Poisson is now solved once to make the band structure consistent with the Fermi levels. In case of incomplete convergence, the partly converged output is then more in line with physical intuition.

Input residuals and tolerances are rescaled to various internal units (often in a dimension-dependent manner, i.e. they are different for 1D, 2D and 3D simulations) before being passed to low-level numerical routines like ARPACK, LAPACK, BLAS, nonlinear solvers, etc. Therefore, diagnostic output from low-level numerical solvers usually contains values which are completely different from those which are output by the high-level physics routines or output into files.

There are log files that track the convergence behavior of the iterations during the simulation. The convergence information for the respective self-consistent equations can be plotted. It is best to use a logarithmic scale.

  • iteration_quantum_density.dat

    quantum_density{}
    Convergence of Schrödinger equation with self-consistent density/exchange

  • iteration_quantum_poisson.dat

    quantum_poisson{}
    Convergence of outer iteration loop for Schrödinger-Poisson

  • iteration_quantum_current_poisson.dat

    quantum_current_poisson{}
    Convergence of outer iteration loop, i.e. for Current-Poisson-Schrödinger with quantum

  • iteration_quantum_current_poisson_details.dat

    quantum_current_poisson{}
    Convergence of current equation, i.e. for Current-Poisson with quantum densities