9. User Interface¶

9.1. Starting DEVSIM¶

Refer to Installation for instructions on how to install DEVSIM. Once installed, DEVSIM may be invoked using the following command

It is necessary to first PYTHONPATH variable to the lib directory in the DEVSIM distribution. As an alternative, an experimental installation script is available to make the process easier. Please see Installation Script for more information.

devsim is loaded by calling

import devsim

from Python.

Many of the examples in the distribution rely on the python_packages module, which is available by using:

import devsim.python_packages

The supported versions of Python for use in scripts is 3.6 or higher.

9.2. Python Language¶

9.2.1. Introduction¶

Python is the scripting language employed as the text interface to DEVSIM. Documentation and tutorials for the language are available from [1]. A paper discussing the general benefits of using scripting languages may be found in [6].

9.2.2. DEVSIM commands¶

All of commands are in the devsim namespace. In order to invoke a command, the command should be prefixed with devsim., or the following may be placed at the beginning of the script:

from devsim import *

For details concerning error handling, please see Error handling.

9.2.3. Advanced usage¶

In this manual, more advanced usage of the Python language may be used. The reader is encouraged to use a suitable reference to clarify the proper use of the scripting language constructs, such as control structures.

9.2.4. Unicode Support¶

Internally, DEVSIM uses UTF-8 encoding, and expects model equations and saved mesh files to be written using this encoding. Users are encouraged to use the standard ASCII character set if they do not wish to use this feature. Python 3 interpreters handle UTF-8 encoding well.

On some systems, such as Microsoft Windows, it may be necessary to set the following environment variable before running a script containing UTF-8 characters.

SET PYTHONIOENCODING=utf-8

Care should be taken when using UTF-8 characters in names for visualization using the tools in Visualization, as this character set may not be supported.

9.3. Error handling¶

9.3.1. Python errors¶

When a syntax error occurs in a Python script an exception may be thrown. If it is uncaught, then DEVSIM will terminate. More details may be found in an appropriate reference. An exception that is thrown by DEVSIM is of the type devsim.error. It may be caught.

9.3.2. Fatal errors¶

When DEVSIM enters a state in which it may not recover. The interpreter should throw a Python exception with a message DEVSIM FATAL. At this point DEVSIM may enter an inconsistent state, so it is suggested not to attempt to continue script execution if this occurs.

In rare situations, the program may behave in an erratic manner, print a message, such as UNEXPECTED or terminate abruptly. Please report this using the contact information in Contact.

9.3.3. Floating point exceptions¶

During model evaluation, DEVSIM will attempt to detect floating point issues and return an error with some diagnostic information printed to the screen, such as the symbolic expression being evaluated. Floating point errors may be characterized as invalid, division by zero, and numerical overflow. This is considered to be a fatal error.

9.3.4. Solver errors¶

When using the devsim.solve(), the solver may not converge and a message will be printed and an exception may be thrown. The solution will be restored to its previous value before the simulation began. This exception may be caught and the bias conditions may be changed so the simulation may be continued. For example:

try:
  solve(type="dc", absolute_error=abs_error,
    relative_error=rel_error, maximum_iterations=max_iter)
except devsim.error as msg:
  if msg[0].find("Convergence failure") != 0:
    raise
  #### put code to modify step here.

9.3.5. Verbosity¶

The set_parameter() may be used to set the verbosity globally, per device, or per region. Setting the debug_level parameter to info results in the default level of information to the screen. Setting this option to verbose or any other name results in more information to the screen which may be useful for debugging.

The following example sets the default level of debugging for the entire simulation, except that the gate region will have additional debugging information.

devsim.set_parameter(name="debug_level", value="info")
devsim.set_parameter(device="device" region="gate",
  name="debug_level", value="verbose")

9.3.6. Parallelization¶

Routines for the evaluating of models have been parallelized. In order to select the number of threads to use

devsim.set_parameter(name="threads_available", value=2)

where the value specified is the number of threads to be used. By default, DEVSIM does not use threading. For regions with a small number of elements, the time for switching threads is more than the time to evaluate in a single thread. To set the minimum number of elements for a calculation, set the following parameter.

devsim.set_parameter(name="threads_task_size", value=1024)

The Intel Math Kernel Library is parallelized, the number of thread may be controlled by setting the MKL_NUM_THREADS environment variable.