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.