4. User interface
4.1. Starting DEVSIM
Refer to Supported platforms for instructions on how to install DEVSIM. Once installed, DEVSIM may be invoked using the following command
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
4.2. Directory structure
A DEVSIM directory is created with the following sub directories listed in Directory structure for DEVSIM.
|
contains project documentation files |
|
product documentation |
|
example scripts |
|
additional examples used for testing |
This may be found using the virtual environment path specified in Table 3.2.
4.3. Python language
4.3.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 [5].
4.3.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 *
4.3.3. Unicode support
Internally, DEVSIM uses UTF-8 encoding, and expects model equations and saved mesh files to be written using this encoding. Care should be taken when using non-ASCII characters in names for visualization using the tools in Visualization and post processing, as this character set may not be supported in these third-party tools.
4.4. Error handling
4.4.1. Exceptions
When a syntax error occurs in a Python script an exception may be thrown. If it is uncaught, then DEVSIM will terminate. An exception that is thrown by DEVSIM is of the type devsim.error. It may be caught, and a message may be extracted to determine the issue.
4.4.2. Fatal errors
When DEVSIM enters a state in which it may not recover. The interpreter will throw a devsim.error 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.
4.4.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.
4.4.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.
4.4.5. Example
More helpful exception information returned to Python if the error is considered fatal. This can be used to decide if the simulation can be restarted. Note that if this occurs during a solve, it is necessary for the user to restore the previous circuit and device solutions if a restart is desired. In addition, model evaluation is reset so that no false cyclic dependencies are reported after an error.
In this example code below, the previously DEVSIM FATAL error string will now provide the context that a floating point exception occurred and be handled in Python.
try:
self.solve()
except error as msg:
m = str(msg)
if 'Convergence failure' in m:
self.set_vapp(last_bias)
elif'floating point exception' in m:
self.set_vapp(last_bias)
self.restore_callback(self.is_circuit)
else:
raise
4.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")
4.6. Command help
It is now possible to see the full list of DEVSIM commands by typing
help(devsim.solve)
4.7. Parallelization
4.7.1. Model evaluation
Routines for the evaluating of models are 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.
4.7.2. Long operations
While running long operations, DEVSIM, will yield to the Python to allow it to perform other operations.
4.7.3. External math libraries
Please see the documentation for external solvers, such as BLAS/LAPACK or the Intel MKL Pardiso, on how to control their threading behavior.
4.8. Reset simulator
The devsim.reset_devsim() command will clear all simulator data, so that a program restart is not necessary.
4.9. Array type input and output
In most circumstances, the software now returns numerical data using the Python array class. This is more efficient than using standard lists, as it encapsulates a contiguous block of memory. More information about this class can be found at https://docs.python.org/3/library/array.html. The representation can be easily converted to lists and numpy arrays for efficient manipulation.
When accepting user input involving lists of homogenous data, such as devsim.set_node_values() the user may enter data using either a list, string of bytes, or the array class. It may also be used to input numpy arrays or any other class with a tobytes method.