pySIMsalabim.utils package

Submodules

pySIMsalabim.utils.clean_up module

Cleaning output files

pySIMsalabim.utils.clean_up.clean_all_output(path, filename_starts=['JV', 'Var', 'tj', 'tVG', 'scPars', 'Str4Parallel', 'log'], exts=['.png'])

Delete all files in the current directory

Parameters:

• path (string) – path to the directory where we clean the output

• filename_starts (list of string) – list of string containing the beginning of the filename to delete, default is [‘JV’,’Var’,’tj’,’tVG’,’scPars’,’Str4Parallel’,’log’]

• exts (list of string) – list of string containing the extension of the files to delete, default is [‘.png’]

pySIMsalabim.utils.clean_up.clean_file_type(ext, path)

Delete files of a given type in the current directory

Parameters:

• ext (string) – extension of the files to delete

• path (string) – path to the directory where we clean the output

pySIMsalabim.utils.clean_up.clean_up_output(filename_start, path)

Delete output files from the simulation

Parameters:

• filename_start (string) – string containing the beginning of the filename to delete

• path (string) – path to the directory where we clean the output

pySIMsalabim.utils.clean_up.delete_folders(folder_name_start, path)

Delete all folders starting with a given name in the current directory, even if they are not empty

Parameters:

• folder_name (string) – name of the folder to delete

• path (string) – path to the directory where we delete the folder

pySIMsalabim.utils.clean_up.store_output_in_folder(filenames, folder_name, path)

Move output files from the simulation into new folder

Parameters:

• filenames (list of string) – list of string containing the name of the files to move

• folder_name (string) – name of the folder where we store the output files

• path (string) – directory of the folder_name (creates one if it does not already exist)

pySIMsalabim.utils.device_parameters module

Functions for processing the device parameters

pySIMsalabim.utils.device_parameters.ReadParameterFile(path2file)

Get all the parameters from the ‘Device_parameters.txt’ file for SIMsalabim and ZimT :param path2file: Path to the ‘Device_parameters.txt’ :type path2file: str

Returns:

Contains the parameters and values from the ‘Device_parameters.txt’

Return type:

dict

pySIMsalabim.utils.device_parameters.calc_new_W_F(dev_pars, simulation_setup)

Calculate the new work function for a contactless device based on the conduction and valence band energies of the available layers. We take the smallest difference between E_c and E_v (assumption: this is the PVK) and set the work function to half the gap above E_c.

Parameters:

• dev_pars (dict) – Dictionary with the device parameters

• simulation_setup (str) – Name of the simulation setup file

Returns:

Work function for the contactless device (equal for both sides)

Return type:

float

pySIMsalabim.utils.device_parameters.create_block_layer(session_path, dev_pars, layers, block_layer_file='Block.txt', block_layer_mat='Air')

Create a new layer file for the blocking layer, which is a copy of the first layer to use as a template. The parameters of the blocking layer are set to values that make it a blocking layer, like a very thin (1nm) layer with a large band offsets and low effective density of states. The nkLayer parameter is set to the block_layer_mat file.

Parameters:

• session_path (str) – Path to the session folder

• dev_pars (dict) – Dictionary with the device parameters

• layers (list) – List with the layers in the device

• block_layer_file (str, optional) – Name of the blocking layer file, by default ‘Block.txt’

• block_layer_mat (str, optional) – Name of the blocking layer material, by default ‘Air’

Return type:

None

pySIMsalabim.utils.device_parameters.create_contactless_device(session_path, simulation_setup, block_layer_file='Block.txt', block_layer_mat='Air', force_last_interface=True, cmd_pars=None)

Create a contactless device by adding a blocking layer on either side of the device. This will change the input files! Depending on the flag in the output function, these files are kept or returned to their original state.

Parameters:

• session_path (str) – Path to the session folder

• simulation_setup (str) – Name of the simulation setup file

• block_layer_file (str, optional) – Name of the blocking layer file, by default ‘Block.txt’

• block_layer_mat (str, optional) – Name of the blocking layer material, by default ‘Air’

• force_last_interface (bool, optional) – If True, the interface traps at the last interface are set to 0, by default True

• cmd_pars (list, optional) – List of dict with the command line parameters, by default None

Returns:

• int – 0 if the contactless device was created successfully, 1 if there was an error

• dict – Updated dictionary with the command line parameters

• str – Name of the blocking layer file

pySIMsalabim.utils.device_parameters.devpar_read_from_txt(fp)

Read the opened .txt file line by line and store all in a List.

Parameters:

fp (TextIOWrapper) – filepointer to the opened .txt file.

Returns:

List with nested lists for all parameters in all sections.

Return type:

List

pySIMsalabim.utils.device_parameters.devpar_write_to_txt(dev_par_object)

Convert the List object into a single string. Formatted to the device_parameter definition

Parameters:

dev_par_object (List) – List object with all parameters and comments.

Returns:

Formatted string for the txt file

Return type:

string

pySIMsalabim.utils.device_parameters.format_output_files(session_path, simulation_type, num_layers, JV_file='JV.dat', tJ_file='tJ.dat', Var_file='Var.dat')

Format the output files (JV, tJ, Var) to remove the columns for the blocking layers and update the layer indices back to their original values. In the Var file, the rows for the blocking layers are removed and the x values are shifted to start at 0. Cleaned the leftover interface values for those layers as well

Parameters:

• session_path (str) – Path to the session folder

• simulation_type (str) – Type of simulation: ‘simss’ or ‘zimt’

• num_layers (int) – Number of layers in the device after reverting the simulation setup file

• JV_file (str) – Name of the JV file

• tJ_file (str) – Name of the tJ file

• Var_file (str) – Name of the Var file

Return type:

None

pySIMsalabim.utils.device_parameters.get_inputFile_from_cmd_pars(sim_type, cmd_pars)

Get the input file name from the command line parameters except the layer files

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars (List) – List with the command line parameters

• except_layers (bool, optional) – If True, the layer files are excluded from the list, by default True

Returns:

The name of the input file

Return type:

string

pySIMsalabim.utils.device_parameters.get_inputFile_from_layer(layer, session_path)

Get the input file name from the layer parameters

Parameters:

• layer (List) – List with the layer parameters

• session_path (string) – Folder path of the current simulation session

Returns:

The name of the input file

Return type:

string

pySIMsalabim.utils.device_parameters.get_par_from_dev_par(dev_par, par_name)

Get the parameter from the device parameters

Parameters:

• dev_par (List) – List with the device parameters

• par_name (string) – Name of the parameter

Returns:

List with the parameter

Return type:

List

pySIMsalabim.utils.device_parameters.load_device_parameters(session_path, dev_par_file_name, default_path='SIMsalabim/ZimT', reset=False, availLayers=[], run_mode=False)

Load the device_parameters file and create a List object. Check if a session specific file already exists. If True, use this one, else return to the default device_parameters

Parameters:

• session_path (string) – Folder path of the current simulation session

• dev_par_file_name (string) – Name of the device parameters file

• default_path (string) – Path name where the default/standard device parameters file is located

• reset (boolean) – If True, the default device parameters are copied to the session folder

• availLayers (List) – List with all the available layer files

• run_mode (bool, optional) – indicate whether the script is in ‘web’ mode (True) or standalone mode (False). Used to control the console output, by default True

Returns:

• List – List with nested lists for all parameters in all sections.

• List – List with all the layers

pySIMsalabim.utils.device_parameters.make_basename_file_cmd_pars(cmd_pars, except_output_files=True)

Update the command line parameters with the basename of the input files

Parameters:

• cmd_pars (List) – List with the command line parameters

• except_output_files (bool, optional) – If True, the output files names are not updated, by default True

Returns:

List with the updated command line parameters

Return type:

List

pySIMsalabim.utils.device_parameters.make_basename_input_files(filename, updateFile=True)

Update the layer file with the basename of the input files

Parameters:

• filename (string) – path to the layer file

• updateFile (bool, optional) – if True, the layer file is updated with the new file names, else the updated layer file list is returned, by default True

Returns:

List with the updated layer parameters

Return type:

List

pySIMsalabim.utils.device_parameters.process_output_contactless(session_path, simulation_setup, simulation_type, format_output=True, clean_simulation_setup=True, JV_file='JV.dat', tJ_file='tJ.dat', Var_file='Var.dat', block_layer_file='Block.txt')

Process the output files for a contactless device simulation. The log file is always updated.

If format_output = True, the simulation setup is reverted to its original state, and the output files are formatted to remove any data related to the blocking layers.

Parameters:

• session_path (str) – Path to the session folder

• simulation_setup (str) – Name of the simulation setup file

• simulation_type (str) – Type of simulation: ‘simss’ or ‘zimt’

• format_output (bool) – If True, the simulation setup is reverted to its original state and the output files are formatted

• JV_file (str) – Name of the JV file

• tJ_file (str) – Name of the tJ file

• Var_file (str) – Name of the Var file

• block_layer_file (str) – Name of the blocking layer file

Return type:

None

pySIMsalabim.utils.device_parameters.revert_simulation_setup(dev_pars, session_path, simulation_setup)

Revert the simulation setup file to its original state by removing the blocking layers and updating the layer indices back to their original values.

Parameters:

• dev_pars (dict) – Dictionary with the device parameters

• session_path (str) – Path to the session folder

• simulation_setup (str) – Name of the simulation setup file

Returns:

Number of layers in the device after reverting the simulation setup file

Return type:

int

pySIMsalabim.utils.device_parameters.store_file_names(dev_par, sim_type, dev_par_name, layers, run_mode=False)

Read the relevant file names from the device parameters and store the file name in a session state.

This way the correct and relevant files can be retrieved and used in the results. Make a distinction between simss and zimt.

Parameters:

• dev_par (List) – Nested List object containing all device parameters

• sim_type (string) – Which type of simulation to run: simss or zimt

• dev_par_name (string) – Name of the device parameter file

• layers (List) – List with all the layers in the device

• run_mode (bool, optional) – indicate whether the script is in ‘web’ mode (True) or standalone mode (False). Used to control the console output, by default True

pySIMsalabim.utils.device_parameters.update_cmd_pars_contactless(cmd_pars)

Update the command line parameters with new layer indices, which are now shifted by 1 for a contactless device.

Parameters:

cmd_pars (List) – List of dict with the command line parameters

Returns:

List of dict with the updated command line parameters

Return type:

List

pySIMsalabim.utils.device_parameters.update_logFile(session_path, logFile='log.txt')

Update the log file to add a line after the line ‘Reading in of parameters:’ to indicate that a contactless device has been simulated and that the indices of the layers have been shifted by 1 for the set command line parameters.

Parameters:

• session_path (str) – Path to the session folder

• logFile (str, optional) – Name of the log file, by default ‘log.txt’

Returns:

0 if the log file was updated successfully, 1 if the log file does not exist

Return type:

int

pySIMsalabim.utils.device_parameters.update_simulation_setup(session_path, simulation_setup, dev_pars, block_layer_file='Block.txt')

Update the simulation setup file to add a layer on either side and change the layer indices.

Parameters:

• session_path (str) – Path to the session folder

• simulation_setup (str) – Name of the simulation setup file

• dev_pars (dict) – Dictionary with the device parameters

• block_layer_file (str, optional) – Name of the blocking layer file, by default ‘Block.txt’

Returns:

Updated dictionary with the device parameters

Return type:

dict

pySIMsalabim.utils.general module

Functions for general use

pySIMsalabim.utils.general.construct_cmd(sim_type, cmd_pars)

Construct a single string to use as command to run a SIMsalabim executable

Parameters:

• sim_type (string) – Which program to run: simss or zimt

• cmd_pars (List) – List with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

Returns:

Constructed string to run as cmd

Return type:

string

pySIMsalabim.utils.general.error_message(errorcode)

When a ‘standard Pascal’ fatal error occurs, add the standard error message to be used with parallel which does not read the

Parameters:

errorcode (int) – the error code

Returns:

the error message

Return type:

str

pySIMsalabim.utils.general.fatal_error_message(errorcode)

When a ‘standard Pascal’ fatal error occurs, add the standard error message

Parameters:

errorcode (int) – the error code

pySIMsalabim.utils.general.make_thread_safe_file_copy(file, destination)

Copy a file to a temp folder, and wait until the file is not in use anymore.

Parameters:

• file (string) – File path of the file to copy

• destination (string) – File path of the destination folder

pySIMsalabim.utils.general.run_simulation(sim_type, cmd_pars, session_path, run_mode=False, verbose=False)

Run the SIMsalabim simulation executable with the chosen device parameters.

Return the complete result object of the process accompanied by a message with information, in case of both success and failure.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars (List) – List with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• run_mode (boolean) – True if function is called as part of The Shell, False when called directly. Prevents using streamlit components outside of The Shell.

• verbose (boolean) – True if the console output of the simulation should be printed to the console

Returns:

• int – Return code of the simulation process, 0 for success, other values for errors.

• string – Return message to display on the UI, for both success and failed

pySIMsalabim.utils.general.run_simulation_filesafe(sim_type, cmd_pars, session_path, run_mode=False, verbose=False, **kwargs)

Run the SIMsalabim simulation executable with the chosen device parameters.

Return the complete result object of the process accompanied by a message with information, in case of both success and failure.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars (List) – List with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• run_mode (boolean) – True if function is called as part of The Shell, False when called directly. Prevents using streamlit components outside of The Shell.

• verbose (boolean) – True if the console output of the simulation should be printed to the console

• **kwargs (dict) – Additional keyword arguments, not used in this function but can be used to pass additional parameters to the function.

Returns:

• result (int) – Return code of the simulation process, 0 for success, other values for errors.

• string – Return message to display on the UI, for both success and failed

pySIMsalabim.utils.parallel_sim module

Functions for general use

class pySIMsalabim.utils.parallel_sim.CustomThread(group=None, target=None, name=None, args=(), kwargs={}, Verbose=None)

Bases: Thread

join(*args)

Wait until the thread terminates.

This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating-point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

When the timeout argument is not present or None, the operation will block until the thread terminates.

A thread can be join()ed many times.

join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

pySIMsalabim.utils.parallel_sim.parallel_error_message(errorcode)

When a ‘standard Pascal’ fatal error occurs, add the standard error message to be used with parallel which does not read the

Parameters:

errorcode (int) – the error code

Returns:

the error message

Return type:

str

pySIMsalabim.utils.parallel_sim.run_simulation_GNU_parallel(sim_type, cmd_pars_list, session_path, max_jobs=3, verbose=False)

Run the SIMsalabim simulation executable with the chosen device parameters.

The simulation is run in parallel using the GNU Parallel program. (https://www.gnu.org/software/parallel/). If this command is used please cite: Tange, O. (2021, August 22). GNU Parallel 20210822 (‘Kabul’). Zenodo. https://doi.org/10.5281/zenodo.5233953

To Install GNU Parallel on linux: (not available on Windows) sudo apt-get update sudo apt-get install parallel

or try to run the install_GNU_parallel_Linux() function from the install module. import pySIMsalabim.install as install install.install_GNU_parallel_Linux()

Return the complete result object of the process accompanied by a message with information, in case of both success and failure.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars_list (List) – List of list with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• max_jobs (int) – Maximum number of parallel jobs to run. Default is the number of CPU cores - 1

Returns:

• CompletedProcess – Output object of with returncode and console output of the simulation

• List – Return list of messages for each simulation

• List – Return list of return codes for each simulation

pySIMsalabim.utils.parallel_sim.run_simulation_multithreaded_linux(sim_type, cmd_pars_list, session_path, max_jobs=3, verbose=False)

Runs simulations in parallel on max_jobs number of threads. This procedure should work on Windows and Linux but it is not as efficient as run_parallel_simu on Linux. Yet, it is the only way to run simulations in parallel on Windows in a thread safe way and making sure that two thread do not try to write to the same file at the same time. This is achieved by running the simulation in a temporary folder with a copy of all the necessary input files and then moving the output files to the original folder.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars_list (List) – List of list with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• max_jobs (int) – Maximum number of parallel jobs to run. Default is the number of CPU cores - 1

• verbose (bool) – If True, print the output of the simulation to the console

Returns:

List of CompletedProcess objects with returncode and console output of the simulation

Return type:

List

pySIMsalabim.utils.parallel_sim.run_simulation_multithreaded_windows(sim_type, cmd_pars_list, session_path, max_jobs=3, verbose=False)

Runs simulations in parallel on max_jobs number of threads. This procedure should work on Windows and Linux but it is not as efficient as run_parallel_simu on Linux. Yet, it is the only way to run simulations in parallel on Windows in a thread safe way and making sure that two thread do not try to write to the same file at the same time. This is achieved by running the simulation in a temporary folder with a copy of all the necessary input files and then moving the output files to the original folder.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars_list (List) – List of list with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• max_jobs (int) – Maximum number of parallel jobs to run. Default is the number of CPU cores - 1

• verbose (bool) – If True, print the output of the simulation to the console

Returns:

List of CompletedProcess objects with returncode and console output of the simulation

Return type:

List

pySIMsalabim.utils.parallel_sim.run_simulation_parallel(sim_type, cmd_pars_list, session_path, max_jobs=3, verbose=False, **kwargs)

Run the SIMsalabim simulation executable with the chosen device parameters. Select the correct function to run the simulation in parallel based on the operating system.

Parameters:

• sim_type (string) – Which type of simulation to run: simss or zimt

• cmd_pars_list (List) – List of list with parameters to add to the simss/zimt cmd line. Each parameter is a dict with par,val keys. Note: when relevant the first entry must be the deviceparameters file with a key: dev_par_file

• session_path (string) – File path of the simss or zimt executable

• max_jobs (int) – Maximum number of parallel jobs to run. Default is the number of CPU cores - 1

• verbose (bool) – If True, print the output of the simulation to the console

• **kwargs (dict) – Additional keyword arguments to pass to the function

Returns:

Output object of with returncode and console output of the simulation

Return type:

CompletedProcess

pySIMsalabim.utils.parallel_sim.worker_linux(q, lock, semaphore, verbose=False)

Worker function that runs the simulation in a temporary folder and moves the output files to the original folder.

Parameters:

• q (queue) – Queue to communicate with the main thread

• lock (threading.Lock) – Lock to prevent multiple threads from writing to the same file at the same time

• semaphore (threading.Semaphore) – Semaphore to limit the number of parallel jobs

• verbose (bool) – If True, print the output of the simulation to the console

pySIMsalabim.utils.parallel_sim.worker_windows(q, lock, tmp_folder, semaphore, verbose=False)

Worker function that runs the simulation in a temporary folder and moves the output files to the original folder.

Parameters:

• q (queue) – Queue to communicate with the main thread

• lock (threading.Lock) – Lock to prevent multiple threads from writing to the same file at the same time

• tmp_folder (string) – Temporary folder to run the simulation in

• semaphore (threading.Semaphore) – Semaphore to limit the number of parallel jobs

• verbose (bool) – If True, print the output of the simulation to the console

pySIMsalabim.utils.utils module

pySIMsalabim.utils.utils.get_integral_bounds(data, f_min=0.01, f_max=1000000.0, f_steps=20)

Determine integral bounds in the time domain, used to compute the conductance and capacitance

Parameters:

• data (dataFrame) – Pandas dataFrame containing the time, voltage, current density and numerical error in the current density of the tj_file

• f_min (float) – Minimum frequency

• f_max (float) – Maximum frequency

• f_steps (float) – Frequency steps

Returns:

List of array indices that will be used in the plotting

Return type:

list

pySIMsalabim.utils.utils.read_tj_file(session_path, tj_file_name='tj.dat')

Read relevant parameters for impedance of the tj file

Parameters:

• session_path (string) – Path of the simulation folder for this session

• data_tj (dataFrame) – Pandas dataFrame containing the tj output file from ZimT

Returns:

Pandas dataFrame containing the time, voltage, current density and numerical error in the current density of the tj_file

Return type:

DataFrame

pySIMsalabim.utils.utils.update_cmd_pars(main_pars, cmd_pars)

Merges main parameters with command line parameters.

Parameters:

• main_pars (list of dict) – A list containing dictionaries of the main parameters of the application. These parameters serve as the default values.

• cmd_pars (list of dict) – A list containing dictionaries of parameters passed through the command line interface. These parameters have higher precedence and override the main parameters in case of a conflict within any dictionary.

Returns:

A list of dictionaries containing the combined set of parameters, with command line parameters overriding main parameters in case of conflicts within any dictionary.

Return type:

list of dict

Raises:

ValueError – If duplicate parameters are found in the command line parameters.

Module contents