x_step module
Helper modules for extraction steps
General extraction steps
Implemented extraction steps
XStep Module Documentation
Extraction step super class and some decorators for the extraction and its GUI
Author: Mario Krattenmacher | Mario.Krattenmacher@semimod.de Author: Markus Müller | Markus.Mueller3@tu-dresden.de
- class DMT.extraction.x_step.XStep(name, mcard: ~DMT.core.mcard.MCard, lib: ~DMT.core.dut_lib.DutLib, op_definition: dict, model=None, deembed_method=None, key=None, use_exact_key=False, use_regex_key=False, to_optimize=None, to_optimize_per_line=None, op_selector=None, op_selector_para=None, initial_guess=True, relevant_duts=None, DutCircuitClass=None, circuit_sim_dir=None, circuit_database_dir=None, get_circuit_arguments=None, technology=None, write_table_model=False, n_step_max=100, fit_method='trf', f_tol=2.220446049250313e-16, bounds_class=<class 'DMT.extraction.ixbounds.XBounds'>, t_max=60, n_core=4, normalize=True, sort_by=None, legend_off=False, document_step=True, specifier_paras=None, **kwargs)[source]
Bases:
QObject
Template class for all parameter extraction classes that inherit from this class. XStep subclasses need to implement all methods with the decorator @abc.abstractclass. This class implements logic to fit data, from either a “Model” or “Circuit SImulation” to reference data. For fitting, a “modelcard” is used, that is a named list of parameters with attributes.
- Parameters:
- name
str
This string specifies the name of the XStep object. The name should be unique when XStep objects are added to an Xtraction object, a container-like object for XSteps.
- mcard
MCard
orMcParameterCollection
The mcard holds all relevant model parameters for the model evaluation. Unknown parameters are added to the mcard, and initialized as 0.
- lib
DutLib
This DutLib object contains DutView objects with data that are relevant for this XStep.
- op_definition{
DMT.specifier
float
,tuple
orlist
}or
iterableof
{DMT.specifier
float
,tuple
orlist
} - This dictionary defines how to filter the relevant data for this XStep from the DutView objets in the DutLib by setting either a:
single value (float): Use only the data, where the column with a name equal to the specifier equals the single value
2-element tuple: Use only the data, where the column with name equal to the specifier is bigger than the first element of the tuple and smaller than the second element of the tuple-
3-element tuple: same as 2-element tuple, but take only columns in the data that have more than tuple[2] unique elements.
4-element tuple: same as 3-element tuple, but take only tuple[3] equally spaced values from the column.
list: Use only the data, where the column with name equal to the specifier equals one of the values in the list
More than one dictionary can be passed.
- model
Model
,optional
Model object with all model equations used for this extraction step.
- deembed_method
method
,optional
If given, the data found in the DutViews by this XStep is pre-processed with the method deembed_method. This argument can be used to de-embed the internal or intrinsic transistor data “on the fly”.
- key
str
or
[str
],optional
This key is used to find the reference data in relevant_duts.data. See
DMT.extraction.x_step.XStep.collect_data()
for the usage.- use_exact_key{True,False},False
If this argument is set to True, only those keys in DutView data are considered, that correspond exactly to “key”. Else, only those keys are considered that contain “key” in them.
- to_optimize[
str
] This list contains the names of all parameters that shall be optimized by this XStep.
- to_optimize_per_line[
str
] This list contains the names of all parameters that shall be optimized for each line, separately. The parameters in this list MUST be a subset of “to_optimize”.
- op_selector{
None
,Specifier
},optional
If given, an operating point selector plot will be created that can be displayed in the DMT Gui.
- op_selector_para{
None
,Specifier
},optional
If given, the operating point selector will use this parameter for viewing the optimization for different operating points. Else self.to_optimize_per_line[0] will be used.
- initial_guess{
True
,False
},optional
If True, the set_initial_guess method is called. Turn this off, if the parameters are already good with good boundaries in the given modelcard.
- relevant_duts[
DutView
],None
List of DutViews, that are relevant for the current step. If none is give, only the DutLib.dut_ref DutView is considered to be relevant.
- DutCircuitClass
DutCircuit
,optional
The DutCircuitClass is used for simulation of DutView objects.
- circuit_sim_dir, circuit_database_dir
str
,optional
Paths where the circuit simulations and also the simulated and read duts are saved.
- get_circuit_arguments
None
TODO
- technology
technology
,optional
Technology for the created DutCircuit objects. A technology specifies additional methods for example to scale modelcards.
- write_table_modelbool,
optional
Flag to turn on copying the reference dataframes into the simulation folder, for example as table model.
- n_step_max
int
,optional
Maximum number of optimization algorithm steps. Default = 100
- fit_method{‘lm’,’trf’}
The fit method that shall be used. ‘lm’ -> Levenberg Marquardt and ‘trf’ Trust-Region-Reflective (?)
- f_tol
float
,optional
The target function tolerance. Default = np.finfo(float).eps so machine tolerance.
- bounds_class
Bounds
Class to choose which bound type is used for this step, either x, y or both.
- t_max
float
,optional
The maximum time in seconds that simulations may run. Is passed on to the object of
DMT
. Default = 60- n_core
int
,optional
The number of cores the object of
DMT
is allowed to use in parallel. Default = 4- normalize{
True
,False
},optional
If True, the model parameters that need to be extracted, are normalized to the range [0,1], if possible.
- sort_by
SpecifierStr
,optional
By default (None), data is sorted by x/y depending on the bounds. Change this if for example the plot is versus I_C but the measurement is over V_BE.
- legend_off{
False
,True
},optional
Turns off the legend in the main plot.
- document_step{
True
,False
},optional
If False, this step is not added to the documentation.
- specifier_paras
None
This dict with keys corresponding to arguments and values corresponding to default values for the arguments is given to __init__. Can be used to define which arguments must be supplied to the __init__ function.
- name
- add_plot_method(func)[source]
Binds the function to self. Func has the method signature func(self) and needs to return a DMT.Plot object
- Parameters:
- func
callable()
A callable object with signature func(self) that returns a Plot object. Will be binded to self.
- func
- add_to_xtraction(xtraction)[source]
Sets the duts from xtraction to the given step
- Parameters:
- xstep
XTraction
]
- xstep
- apply_interpolation(spline_order=None, points_out_of_bounds=None, nr_points=None, smoothing_factor=None, weights=None)[source]
Interpolates each line of the self.data_model[‘y_ref’] using scipy.interpolate.UnivariateSpline.
Can also be used to smooth the data using the smoothing_factor and the weights can be used to weight the spline. This is only possible if in data_model only ‘x’, ‘y’, ‘y_ref’ and scalar values are present. All given parameters which are not None will be saved to the local correspondants. If they are None, they are replaced by the local correspondants.
- Parameters:
- spline_order
int
,optional
scipy: Degree of the smoothing spline. Must be <= 5. Default is k=3, a cubic spline.
- points_out_of_bounds
int
,optional
Defines how many points of each line outside of the boundaries should be included. Default is 1
- nr_points
int
,optional
Number of points to interpolate using numpy.linspace. Default is 50.
- smoothing_factor
float
,optional
scipy: If None (default), s = len(w) which should be a good value if 1/w[i] is an estimate of the standard deviation of y[i]. If 0, spline will interpolate through all data points.
- weightsarray_like,
optional
scipy: Weights for spline fitting. Must be positive. If None (default), weights are all equal.
- spline_order
- calc_all(xdata, paras_model, jac=True, reinit=True, n_optimize=None)[source]
This method needs to start the calculation of the function to be optimized self.f_0 and its jacobian self.jac .
Calculating the jacobian here allows to use DMT’s parallel computing features, which might be relevant for circuit or TCAD simulations.
This function is called inside fit_function.
- Parameters:
- xdata
np.ndarray
The argument of the fit_function, scipy.curve_fit wants to calculate.
- paras_model
McParameterCollection
Parameters of the model to calculate. Can bei either a full modelcard or only a McParameterCollection.
- jac{
True
,False
},optional
This boolean controls wheather or not the jacobian is computed.
- reinit
Boolean
What is this?
- n_optimize
integer
The number of parameters to optimize. Not really needed but for memoization in XVerify.
- xdata
- Returns:
- self.data_model
dict
{} This is only returned in order to enable memoization. It is actually not really needed for anything else.
- self.data_model
- collect_data()[source]
This method looks for all data in duts in self.relevant_duts and then applies the filter specified by self.op_definition. If data remains, it is considered relevant for this step.
The function check_key checks the dut key versus self.key, if the data should be part of the current extraction step. The check depends on what type is self.key. Possible is:
str : Checks if self.key is part of key
[str] : Checks if any element of self.key is part of key
- ensure_input_correct()[source]
Ensures that the user-supplied dut views hold the correct column names in their data.
Overwrite this method, if you need access to all duts in your method!
- extract()[source]
Perform a parameter extraction. This algorithm should be valid for ALL smallest common XSteps. Compositional XSteps will get another algorithm.
- abstract fit(data_model: Dict, paras_model: McParameterCollection, dut=None)[source]
This function needs to return y-data that corresponds to the reference y-data.
This function is called several times at each iteration.
If a DutView is used as a reference device, it is recommended to not to perform the actual simulation inside this function. Then this function should only read out the simulation results and postprocess them to create the y-data. The actual computation is performed in parallel by simulation the DutView with the user-supplied Sweep object. See the calc_all() function. This saves simulation time, since it allows parallel computing. To access the data of the simulated dut, it is given as a additional parameter.
If a ModelEquation is used for the extraction, the computation of the y-parameters should be inside this function. In this case the simulation speed is not critical. The parameters are then given inside of the parameters dictionary.
- Parameters:
- data_model{‘x’
ndarray
, ‘y’ndarray
, ‘y_ref’ndarray
} Data for the model to calculate.
- paras_model
McParameterCollection
Parameters of the model to calculate. Can bei either a full modelcard or only a McParameterCollection.
- data_model{‘x’
- Returns:
- y[
np.ndarray
()] y-data that corresponds the the reference-lines in self.reference_data[‘y’]
- y[
- fit_function(xdata, *args)[source]
This function is passed to curve_fit and is a little abused here, see text below.
The curve_fit function is passed to scipy alongside with the jacobian function. Scipy will call these functions in an alternating way, in order to get the current function value and the jacobian. However this would prevent the usage of parallel computing, hence all calculations are performed inside fit_function. self.jacobian just returns calculation results that have already been calculated in fit_function.
This approach also allows easy implementation of multi-dimensional fits.
- Parameters:
- xdata
np.ndarray
The argument of the fit_function, scipy.curve_fit wants to calculate.
- *argslist-like
These represent the current parameter values that curve_fit is interested in. They are expanded by the full local modelcard.
- xdata
- Returns:
- f_0
np.ndarray
The current value of the model function, possibly normalized.
- f_0
- fit_wrapper(data_model, paras_model, duts=None)[source]
Dummy function to wrap the user supplied fit function. This allows a more easy to get interface.
- Parameters:
- data_model{‘x’:np.ndarray,’y’:np.ndarray,’y_ref’:np.ndarray}
Data for the model to calculate.
- paras_model
McParameterCollection
Parameters of the model to calculate. Can bei either a full modelcard or only a McParameterCollection.
- Returns:
np.ndarray
The return on the fit function.
- get_bibtex_entry()[source]
Return a valid bibtex entry that may be used in the get_tex command. Optional.
- get_bool_array(line_ref, bounds)[source]
Return a boolean array, where True means that the value in line_ref is inside the bounds.
- Parameters:
- line_ref{}
A dictionarray of a line that has at least the keys “x” and “y”
- bounds
DMT.extraction.XBounds
,YBounds
orXYBounds
The boundaries that shall be used to determine which values in bool_array are true
- Returns:
np.array
()An array that has “True” where the value in “x” or “y”, depending on the type of bounds, is inside the bounds.
- get_description()[source]
Return a tex description of this XStep. Used for generating the documentation. If not implemented, there is no description for this XStep in the documentation.
- get_normalized_parameters()[source]
Get the (normalized) parameters for the optimiziation and the corresponding boundaries.
If normalize is true, all parameters are tried to be normalized either linear or logarithmic. The boundaries are given accordingly.
- Returns:
- p_0, p_min, p_max
np.array
Values, minimal bounds and maximal bounds of the parameters in correct order.
- p_0, p_min, p_max
- abstract get_tex()[source]
Return a tex Representation of the Model that is beeing fitted. This can then be displayed in the UI.
- get_tex_docu()[source]
Returns the tex equation from get_tex a little better suited for the documentation. hmhmhm
- init_data_model()[source]
This method inits the data_model[‘x’] values according to the self.x_bounds and the data_reference. If the self.x_bounds do not match with available x-data, they are adjusted to lie on the nearest availabel x-point.
- init_data_reference()[source]
This function needs to init self.reference_data = [{‘x’:x_values, ‘y’:y_values}] from duts present in self.lib
Overwrite this method, if you need access to all duts in your method!
The attributes self.reference_data is a list of dicts. Each element of the list represents one line with its x_values and y_values. Additional keys can be added, see the x_step_cjc example, where the temperature T of each line has been added.
- init_data_reference_per_dataframe(dataframe, t_meas, dut=None, key=None)[source]
This function needs to append lines to self.reference_data = [{‘x’:x_values, ‘y’:y_values}] from each dataframe in a dut.
Per default overwrite this method since, generally the extraction steps create one or multiple lines from one dataframe independent of other frames.
The attributes self.reference_data is a list of dicts. Each element of the list represents one line with its x_values and y_values. Additional keys can be added, see the x_step_cjc example, where the temperature T of each line has been added.
- init_parameters_per_line()[source]
Initialize a McParameterCollection for each line with paras_to_optimize_per_line.
- jacobian(xdata, *args)[source]
This function returns the jacobian self.jac and possibly normalizes it. This function is only a helper to work with the curve_fit interface.
- main_plot(plot_name, style='xtraction_color', x_specifier=None, y_specifier=None, x_label=None, y_label=None, x_scale=None, y_scale=None, x_log=False, y_log=False, legend_location='upper left')[source]
Creates the main plot that is also displayed in the GUI and printed to the documentation.
The parameters are not used in the method here, but in the decorator
plot()
- Parameters:
- paras_model
McParameterCollection
,optional
If given, it is set to this XStep before plotting.
- calc_all{
False
,True
} If True, the method
calc_all()
is called before plotting.
- paras_model
- op_selection_plot()[source]
Creates the main plot that is also displayed in the GUI and printed to the documentation.
The parameters are not used in the method here, but in the decorator
plot()
- Parameters:
- paras_model
McParameterCollection
,optional
If given, it is set to this XStep before plotting.
- calc_all{
False
,True
} If True, the method
calc_all()
is called before plotting.
- paras_model
- set_guess_bounds()[source]
Overwrite this method to set bounds of parameters dependent on the extraction region bounds. Make sure to only overwrite the min and max of each parameter and no the value to preserve already extracted values.
- abstract set_initial_guess(reference_data)[source]
This methods should set an initial guess for the optimization parameters from the available reference_data array. If no initial guess is set for a parameter, the value for the initial guess is taken form the modelcard. For steps which use a simulation of a DutCircuit, here the sweep should be defined, too.
- set_normalized_parameters(values_normalized)[source]
Saves the parameters from the optimize to self.paras_to_optimize, self.paras_to_optimize_per_line and self.mcard.
If necessary it denormalizes the parameters before doing so.
- Parameters:
- values_normalized
np.array
- values_normalized
- sort_line(line)[source]
Sort all values in line with increasing “x” or “y” or self.sort_by and cast everything to numpy.
- Returns:
line
:{str:[]}The sorted line.
- staticMetaObject = PySide6.QtCore.QMetaObject("XStep" inherits "QObject": Methods: #4 type=Signal, signature=process() #5 type=Signal, signature=finished() #6 type=Signal, signature=mcardChanged() )[source]
- switch_plots(plots_to_switch: dict)[source]
Switch on or off additional plots for the GUI
- Parameters:
- plots_to_switch
dict
Names and states to switch to. For example: {“plot_ib”:True} switches on the extra base current plot for the XVerify-Step.
- plots_to_switch
- switch_prints(plots_to_switch: dict)[source]
Switch on or off additional plots to print into the automatic documentation
- Parameters:
- plots_to_switch
dict
Names and states to switch to. For example: {“plot_ib”:True} switches on the extra base current plot for the XVerify-Step.
- plots_to_switch
- validate_key(key)[source]
Checks if the given key belongs to the x_step by checking if the class name AND the object name is part of the key.
- variate_parameter(parameter)[source]
Changes the parameter by a small delta value.
First tries to add the value, if a ValueTooLargeError is risen, the delta is subtracted from the value.
- Parameters:
- parameter
McParameter
- parameter
- Returns:
- parameter
McParameter
parameter with new, variated value.
- delta_value
float
Change of the parameter value.
- parameter