DutView

A Device Unter Test (DUT) can be single devices or full circuits and range from atomic TCAD simulations to full circuit simulations and also measurements. This range of different DUTs is represented in DMT as a view on a DUT. The name view is chosen, because sometimes the same device is measured and simulated in different simulators. So this “view-axis” can change, always the same are the DUT properties and also the data handling.

Submodules of DutView

Relation of the Submodules

digraph "classes_dut" {
rankdir=BT
charset="utf-8"
"DMT.core.circuit.Circuit" [color="black", fontcolor="black", label="Circuit", shape="record", style="solid"];
"DMT.core.circuit.CircuitElement" [color="black", fontcolor="black", label="CircuitElement", shape="record", style="solid"];
"DMT.Hdev.DutHdev" [color="black", fontcolor="black", label="DutHdev", shape="record", style="solid"];
"DMT.core.DutCircuit" [color="black", fontcolor="black", label="DutCircuit", shape="record", style="solid"];
"DMT.core.DutMeas" [color="black", fontcolor="black", label="DutMeas", shape="record", style="solid"];
"DMT.ngspice.DutNgspice" [color="black", fontcolor="black", label="DutNgspice", shape="record", style="solid"];
"DMT.core.DutTcad" [color="black", fontcolor="black", label="DutTcad", shape="record", style="solid"];
"DMT.core.DutType" [color="black", fontcolor="black", label="DutType", shape="record", style="solid"];
"DMT.core.dut_type.DutTypeInt" [color="black", fontcolor="black", label="DutTypeInt", shape="record", style="solid"];
"DMT.core.DutView" [color="black", fontcolor="black", label="DutView", shape="record", style="solid"];
"DMT.xyce.DutXyce" [color="black", fontcolor="black", label="DutXyce", shape="record", style="solid"];
"enum.Enum" [color="black", fontcolor="black", label="Enum", shape="record", style="solid"];
"enum.Flag" [color="black", fontcolor="black", label="Flag", shape="record", style="solid"];
"DMT.core.MCard" [color="black", fontcolor="black", label="MCard", shape="record", style="solid"];
"DMT.core.mc_parameter.McParameterComposition" [color="black", fontcolor="black", label="McParameterComposition", shape="record", style="solid"];
"DMT.core.mc_parameter.McParameter" [color="black", fontcolor="black", label="McParameter", shape="record", style="solid"];
"DMT.Hdev.DutHdev" -> "DMT.core.DutTcad" [arrowhead="empty", arrowtail="none"];
"DMT.core.DutMeas" -> "DMT.core.DutView" [arrowhead="empty", arrowtail="none"];
"DMT.core.DutType" -> "enum.Flag" [arrowhead="empty", arrowtail="none"];
"DMT.core.MCard" -> "DMT.core.mc_parameter.McParameterComposition" [arrowhead="empty", arrowtail="none"];
"DMT.ngspice.DutNgspice" -> "DMT.core.DutCircuit" [arrowhead="empty", arrowtail="none"];
"DMT.xyce.DutXyce" -> "DMT.core.DutCircuit" [arrowhead="empty", arrowtail="none"];
"DMT.core.DutCircuit" -> "DMT.core.DutView" [arrowhead="empty", arrowtail="none"];
"DMT.core.DutTcad" -> "DMT.core.DutView" [arrowhead="empty", arrowtail="none"];
"enum.Flag" -> "enum.Enum" [arrowhead="empty", arrowtail="none"];
"DMT.core.dut_type.DutTypeInt"  -> "DMT.core.DutType" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", style="solid"];
"DMT.core.MCard"  -> "DMT.core.circuit.CircuitElement" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="parameters", style="solid"];
"DMT.core.mc_parameter.McParameterComposition"  -> "DMT.core.circuit.CircuitElement" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="parameters", style="solid"];
"DMT.core.mc_parameter.McParameter"  -> "DMT.core.mc_parameter.McParameterComposition" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="_paras", style="solid", taillabel="0..*"];
"DMT.core.circuit.CircuitElement"  -> "DMT.core.circuit.Circuit" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="netlist", style="solid", taillabel="0..*"];
"DMT.core.DutType"  -> "DMT.core.DutView" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="dut_type", style="solid"];
"DMT.core.circuit.Circuit"  -> "DMT.core.DutCircuit" [arrowhead="diamond", arrowtail="none", fontcolor="darkgreen", label="_inp_circuit", style="solid"];
}

DutView class

class DMT.core.dut_view.DutView(database_dir, name, dut_type, *, reference_node, copy_va_files=True, force=False, loading=False, separate_databases=False, list_copy=None, t_max=None, sim_dir=PosixPath('/root/.DMT/simulation_results'), simulate_on_server=None, simulator_command='', simulator_arguments=None, technology: Technology | None = None, width=None, length=None, nfinger=None, contact_config=None, flavor=None, ac_ports=None, nodes=None, inp_name=None, va_code_filter=None)[source]

Bases: object

DutView is the parent class of all DUTs in DMT.

All simulation back-end classes must inherit from this class and overwrite the methods that raise NotImplemented errors. This ensures that all classes in DMT work independent of the concrete simulation back-end.

Parameters:
database_dirstr or None

The directory where all the databases of this project are saved. If None, DMT.config.DATA_CONFIG[“directories”][“database”] is used.

namestr

The name of the DutView object, which is used as a prefix for saving the database and the pickled object.

dut_typeDutType

Type of the DutView object, represented by a DutType object (basically an Enumeration).

nodes[str], optional

List of names of the nodes of the DutView object. Only nodes that shall be present in the DutView’s database are relevant. They are past in the given order to all df methods which need the small-signal parameters.

copy_va_files{False, True}, optional
force{False, True}, optional

If True, all data found in the duts database are deleted.

separate_databases{False, True}, optional

If True, each simulation is saved in a separate database file and only the needed files are loaded. Usefull for large simulation files, like transient simulations. For small files, the lookup in the hard drive takes to long.

list_copy[], optional

List of files or file contents to copy to the simulation directory as additional files.

t_maxint, optional

Maximum simulation duration for this dut. This value and the simulation controller value have to be exceeded.

simulate_on_server{False, True, None}, optional

If not set, the config value is used.

simulator_commandstr

Command to start the correct circuit simulator

simulator_argumentslist[str]

List of arguments for the simulator command, will be added one by one before the input file.

technologyTechnology, optional
widthfloat64, optional

Width in m.

lengthfloat64, optional

Length in m.

nfingerint, optional

Number of parallel emitter fingers

contact_configstr, optional

String describing the physical contact config for this device. The possible value depends on the technology, example: ‘CBEBC’.

inp_namestr

The name of the input file to be generated.

Attributes:
database_dirstr

The directory where all the databases of this project are saved.

namestr

The name of the DutView object, which is used as a prefix for saving the database and the pickled object.

managerDatabaseManager

The DatabaseManager object of the DutView, used to interact with its database.

sim_folderstr

Path to the simulation folder

inp_namestr

The name of the input file to be generated.

save_dirstr

This is the directory were the DutView object will save its object and database.

dut_dirstr

This is the directory were the DutView object will create its pickle file. This equals save_dir+’.h5’

database_dirstr

This is the directory were the DutView object will create its database. This equals save_dir+’.h5’

dut_typeDutType

Type of the DutView object, represented by a DutType object (basically an Enumeration).

nodes[str]

List of names of the nodes of the DutView object. Only nodes that shall be present in the DutView’s database are relevant. They are past in the given order to all df methods which need the small-signal parameters.

ac_ports[str]

List of ports for AC simulations. At each port mentioned here a AC source is applied. Defaults to the first 2 nodes.

list_copy[data]

List of path or data to save to the simlation folder. If it is a path, the file is copied. If it is data, a file is created.

Methods

run_simulation(sweep)

Start the simulation of this DutView object.

prepare_simulation(sweep)

Prepare a simulation folder and run make_input().

make_input(sweep)

Create the correct simulation input file from this Dut_view together with a Sweep object.

get_hash()

Return a unique hash for this Dut without considering the Sweep.

save()

Save this DutView as a pickled .p file to save_dir.

__getstate__()

This helper methods helps in the pickling process.

__setstate__(state)

This helper methods helps in the pickling process.

load_dut(save_dir)

Static class method. Loads a DutView object from a pickle file with full path save_dir.

add_data(df, key, force=True)

Add data into the DutView’s database.

get_data(key)

Get the data stored in key from the DutView’s database.

check_existence_sweep(self, sweep)

Returns True if the simulation corresponding to this DutView object in combination with Sweep object sweep has already been run.

del_db()

Delete the DutView’s database.

clean_all_data()

Iterate through all keys in the DutView’s database and try to clean the column names according to the internal DMT format.

add_data(data: DataFrame | Sweep | str | os.Pathlike, key: str | None = None, force: bool = True, validate: bool = True, **kwargs)[source]

Add a measurement or simulation data to the DutView’s data.

Parameters:
dataDataFrame, sweep or str

If DataFrame: Directly added to the data using the given key. If str: Full path to the file that shall be added to the database if sweep: Simulated sweep to import.

keystr, optional

Key that shall be used in the database to save the data.

forcebool, optional

Default=True. If = True, the data is added even if it already exists.

kwargskeyword arguments, optional

Passed on to read_data in case of str as a data argment.

check_existence_sweep(sweep: Sweep)[source]

Return true, if the combination dut+sweep has already been simulated.

If self.data is None, the database is loaded first.

Parameters:
sweepDMT.core.sweep.Sweep

Sweep object that can return a hash.

Returns:
existencebool

Is True if the combination dut+sweep has already been simulated.

clean_data(fallback=None, **kwargs)[source]

Clean the dataframe columns of the DataFrame objects in this DutMeas objects database.

Parameters:
fallbackdict, optional

Is used to update self.nodes_fallback for this special key to clean.

property data[source]

data is a property to ensure loading before usage.

As _data is a dict, the getter is also called before setting. So the separate setter is not necessary. If someone tries to set dut.data an attribute error occurs, but setting dict entries is possible directly.

property database_dir[source]
del_db()[source]

Delete the DutView’s complete database.

del_dut()[source]

Delete the DutView’s pickled file.

delete_sim_results(sweep: Sweep, ignore_errors=False)[source]

Deletes the simulation results of the given sweep.

Parameters:
sweepSweep

Sweep object that corresponds to the folder.

ignore_errors{False, True}, optional

Passed through to shutil.rmtree(). If ignore_errors is true, errors resulting from failed removals will be ignored.

property dut_dir[source]
classmethod from_json(json_content: Dict, classes_technology: List[Type[Technology]], subclass_kwargs: Dict | None = None) DutView[source]

Static class method. Loads a DutView object from a pickle file with full path save_dir.

Parameters:
json_contentdict

Readed dictionary from a saved json DutView.

classes_technologyList[Type[Technology]]

All possible technologies this loaded DutView can have. One will be choosen according to the serialized technology loaded from the file.

subclass_args: List = None,

Positional arguments needed

subclass_kwargs: Dict = None,
Returns:
DutView

Loaded object.

get_data(key: str = 'iv', sweep: Sweep | None = None) DataFrame[source]

Return data stored in the DutView’s data.

One needs to specify either:

  • key : The data stored under the path key in the dut’s database is returned.

  • sweep : Get the data from this sweep. If none, key must be a valid key for the database.

  • sweep+key: Return the data stored as self.get_sweep_key(sweep)+’/’+key from the dut’s database.

Parameters:
keystr, optional, {‘iv’}

The key of the data in the DutView’s database that shall be retrieved.

sweepDMT.core.sweep.Sweep, optional

The sweep whose data shall be looked for.

get_db_dir(name='db') Path[source]

Returns the name for a db, either use ‘db’ for regular behavior or use ‘sweep.get_hash()’ for a db per sweep.

get_hash()[source]

Return a unique hash for this Dut without (!) considering the Sweep.

Returns:
hashfloat64

Hash that corresponds to this DUT.

get_key_temperature(key)[source]

Function that returns the temperature of a given data key. Overwrite this if the measurements differ from the default DMT naming.

Default naming is:

  • Single temperature: “Txxx.xxK”

  • List of temperatures: “T(xxx.xx,yyy.yy,…)K”

  • Range of temperatures: “T[xxx.xx-sss.ss-yyy.yy]K”, s is the step

Parameters:
keystr

Key that shall be evaluated.

Returns:
tempfloat

The temperature at which the measurement “key” has been conducted in Kelvin.

get_sim_folder(sweep: Sweep) Path[source]

Returns the simulation folder of the given sweep

Parameters:
sweepSweep

Sweep object that corresponds to the folder.

Returns:
str

Path to the simulationfolder

get_start_sim_command()[source]

Returns the command to start the simulation

Returns:
str
get_sweep_key(sweep: Sweep)[source]

Key for the dict in dut.data.

Parameters:
sweepSweep or str

Either the key for the given sweep or if it is a string, directly the string

Returns:
keystr
import_output_data(sweep, delete_sim_results=False)[source]

Read the output files that have been produced while simulating sweep and attach them to self.db.

Parameters:
sweepDMT.core.sweep.Sweep

Sweep that has been simulated for the desired output files.

delete_sim_results{False, True}, optional

If True, the simulation folder is deleted after reading.

Raises:
NotImplementedError

If the Dut is not a simulatable dut.

IOError

If the given sweep can not be read.

info_json(**_kwargs) Dict[source]

Returns a dict with serializeable content for the json file to create.

Add the info about the concrete subclass to create here! See :py:method::DMT.core.dut_meas.DutMeas.info_json() for an example implementation.

Returns:
dict

serialized dictionary ready to be dumped to json.

join_key(*parts_key)[source]

Joins the parts of the key into one key for self.dict

Parameters:
parts_keyiterable
Returns:
str

parts_key[0]/parts_key[1]/…/parts_key[-1]

load_db(sweep=None)[source]

Load saved data from the database into the object.

If the complete dictionary is reloaded, here it is set directly to self._data. if separate databases is activated it loads only the given sweep (and it has to be given then!)

Parameters:
sweepSweep or str, optional

In case of separate databases, the sweep must be given either directly or as string name

Returns:
bool

Is True if the database was loaded successfully

static load_dut(file_dut, classes_technology: List[Type[Technology]] | None = None, classes_dut_view: List[Type[DutView]] | None = None) DutView[source]

Static class method. Loads a DutView object from a pickle file with full path save_dir.

Parameters:
file_dutstr or os.Pathlike

Path to the json or pickle DutView file that shall be loaded.

classes_technologyList[Type[Technology]]

All possible technologies this loaded DutView can have. One will be choosen according to the serialized technology loaded from the file.

classes_dut_viewList[Type[DutView]]

All possible DutViews this loaded DutView can be. One will be choosen according to the serialized dutview class name loaded from the file.

Returns:
DutView

Loaded object.

make_input(sweep: Sweep)[source]

Joins simulation header with a given Sweep object and returns it.

Parameters:
sweepDMT.core.sweep.Sweep

Sweep specification according to the Sweep class.

make_pbs(sweep)[source]

Create a PBS script for the PBS job system. (See: https://albertsk.files.wordpress.com/2011/12/pbs.pdf)

prepare_simulation(sweep: Sweep)[source]

Creates a simulation folder, appends the sweep to the structure definition and creates a input file in the simulation folder.

Parameters:
sweepSweep
remove_data(key: str)[source]

Remove a measurement or simulation dataframe from the DutView’s data.

Parameters:
keystr

Key that shall be removed from the database.

save(**kwargs)[source]

Save this DutView as a json file and the also the data into the database on the hard drive. The kwargs are passed on to :py:method::DMT.core.dut_view.DutView.info_json() or the overwritten method.

save_db(sweep_keys=None, sweeps=None)[source]

Write a database for this dut. If it already exists it is overwritten. Does NOT save all keys starting with ‘_’

Parameters:
sweep_keyslist[str], optional

List of sweeps to save to database. Usefull if a lot of data is loaded but only a part should be saved to the hard drive database.

property save_dir: Path[source]
split_key(key)[source]

Splits the key up in its parts.

Parameters:
keystr
Returns:
list[str]

key splitted at ‘/’

validate_simulation_successful(sweep: Sweep)[source]

Checks if the simulation of the given sweep was successful.

Parameters:
sweepDMT.core.sweep.Sweep

Sweep that has been simulated.

Raises:
NotImplementedError

If the Dut is not a simulatable dut.

SimulationUnsuccessful

If the simulation output is not valid.

FileNotFoundError

If the sim log file does not exist.