:py:mod:`simcats.ideal_csd.geometric` ===================================== .. py:module:: simcats.ideal_csd.geometric .. autoapi-nested-parse:: SimCATS subpackage containing all functionalities related to the geometric approach for the simulation of ideal CSDs. Package Contents ---------------- Functions ~~~~~~~~~ .. autoapisummary:: :nosignatures: simcats.ideal_csd.geometric.tct_bezier simcats.ideal_csd.geometric.initialize_tct_functions simcats.ideal_csd.geometric.calculate_all_bezier_anchors simcats.ideal_csd.geometric.generate_lead_transition_mask_1d simcats.ideal_csd.geometric.generate_lead_transition_mask_2d simcats.ideal_csd.geometric.get_electron_occupation simcats.ideal_csd.geometric.ideal_csd_geometric Package Implementation Details ------------------------------ .. py:function:: tct_bezier(tct_params, x_eval, lut_entries = None, max_peaks = None) Evaluates a total charge transition (TCT) with bezier curves and linear parts. A TCT separates the region with n electrons and the region with n+1 electrons in the system. The TCTs (series of connected lead-to-dot transitions) are represented by linear parts and bezier curves for the round triple-points. :param tct_params: Numpy array containing all required parameters to describe the TCT form. The parameters for a TCT are: [0] = length left (in x-/voltage-space, not number of points) [1] = length right (in x-/voltage-space, not number of points) [2] = gradient left (in voltages) [3] = gradient right (in voltages) [4] = start position x (bezier curve leftmost point) (in x-/voltage-space, not number of points) [5] = start position y (bezier curve leftmost point) (in x-/voltage-space, not number of points) [6] = end position x (bezier curve rightmost point) (in x-/voltage-space, not number of points) [7] = end position y (bezier curve rightmost point) (in x-/voltage-space, not number of points) :type tct_params: np.ndarray :param x_eval: X-values for which the function is evaluated or a single x-value. :type x_eval: Union[np.ndarray, numbers.Number] :param lut_entries: Number of samples for the lookup-table. If this is not None, a lookup-table will be used to evaluate the points on the bezier curve, else it is solved explicitly. Default is None. :type lut_entries: Optional[int] :param max_peaks: Limit for the number of peaks of the TCT. If multiple TCTs are supplied, max_peaks is increased by 1 for every further wavefront. If None, all TCTs have an unlimited number of peaks and no outer linear part. Default is None. :type max_peaks: Optional[int] :returns: Y-values for the supplied x-values (if an array of values was supplied) or a single y-value. :rtype: Union[np.ndarray, numbers.Number] .. py:function:: initialize_tct_functions(tct_params, max_peaks = 1) Initializes total charge transition (TCT) functions. It is also possible to directly initialize multiple functions. The total charge transitions (TCTs) (series of connected lead-to-dot transitions), separating regions with different numbers of electrons in the system, are represented by linear parts and bezier curves for the round triple-points. :param tct_params: Numpy array containing all required parameters to describe the TCT form, or a list of such arrays. The parameters for a TCT are: [0] = length left (in x-/voltage-space, not number of points) [1] = length right (in x-/voltage-space, not number of points) [2] = gradient left (in voltages) [3] = gradient right (in voltages) [4] = start position x (bezier curve leftmost point) (in x-/voltage-space, not number of points) [5] = start position y (bezier curve leftmost point) (in x-/voltage-space, not number of points) [6] = end position x (bezier curve rightmost point) (in x-/voltage-space, not number of points) [7] = end position y (bezier curve rightmost point) (in x-/voltage-space, not number of points) :type tct_params: Union[np.ndarray, List[np.ndarray]] :param max_peaks: Limit for the number of peaks of the TCT. If multiple TCTs are supplied, max_peaks is increased by 1 for every further wavefront. Default is 1. :type max_peaks: int :returns: Partially initialized function(s) of the TCT(s) (tct_bezier). The TCT(s) is/are not rotated into the actual voltage space. The keys of the dictionary refer to the corresponding TCT ID. :rtype: Dict[int, Callable] .. py:function:: calculate_all_bezier_anchors(tct_params, max_peaks = 1, rotation = -np.pi / 4) Function used to calculate all bezier-curve anchors for a given total-charge-transition (TCT) or for multiple TCTs. :param tct_params: Array with required parameters to describe the TCT form, or a list of such arrays. The parameters for a TCT are: [0] = length left (in x-/voltage-space, not number of points) [1] = length right (in x-/voltage-space, not number of points) [2] = gradient left (in voltages) [3] = gradient right (in voltages) [4] = start position x (bezier curve leftmost point) (in x-/voltage-space, not number of points) [5] = start position y (bezier curve leftmost point) (in x-/voltage-space, not number of points) [6] = end position x (bezier curve rightmost point) (in x-/voltage-space, not number of points) [7] = end position y (bezier curve rightmost point) (in x-/voltage-space, not number of points) :type tct_params: Union[np.ndarray, List[np.ndarray]] :param max_peaks: Limit for the number of peaks. If multiple TCTs are supplied, then max_peaks is increased for every next TCT. Default is 1. :type max_peaks: int :param rotation: The rotation to be applied to the TCT(s) (which is/are usually represented rotated by 45 degrees). Default is -np.pi/4 :type rotation: float :returns: Dictionary with keys representing the maximum number of peaks (TCT ID) and values containing a numpy array with the coordinates of the corresponding bezier-curve anchors for each TCT. The dimensions of the array are mapped as follows: - first dimension = peak / valley identifier, - second dimension =anchor position (0 = left, 1 = center, 2 = right), - third dimension = coordinate axis identifier (0 = x-value, 1 = y-value). :rtype: Dict[int, np.ndarray] .. py:function:: generate_lead_transition_mask_1d(csd_occ) Generates the ground truth label mask for the lead transitions of 1D scans. The labels are numbers indicating which total charge number is separated by the corresponding total charge transition (TCT). Label with value n is the TCT (consisting of a series of connected lead transitions) between n-1 and n electrons in the system. The pixels with the labels are always part of the region with the higher number of electrons. :param csd_occ: The 1D-CSD occupation data. :type csd_occ: np.ndarray :returns: The label mask for the lead transitions (aka total charge transitions). :rtype: np.ndarray .. py:function:: generate_lead_transition_mask_2d(csd, volt_limits_g1, volt_limits_g2, tct_functions, rotation = -np.pi / 4, lut_entries = None) Generates the ground truth label mask for the lead transitions of 2D scans. The labels are numbers indicating which total charge number is separated by the corresponding total charge transition (TCT). Label with value n is the TCT (consisting of a series of connected lead transitions) between n-1 and n electrons in the system. The pixels with the labels are always part of the region with the higher number of electrons. A TCT is described using a bezier-curve for the round triple-points and linear parts in between two bezier-curves. :param csd: Numpy array of the same shape as the corresponding 2D-CSD data. :type csd: np.ndarray :param volt_limits_g1: Voltage limits of (plunger) gate 1 (second-/x-axis). Example: [min_V1, max_V1] :type volt_limits_g1: np.ndarray :param volt_limits_g2: Voltage limits of (plunger) gate 2 (first-/y-axis). Example: [min_V2, max_V2] :type volt_limits_g2: np.ndarray :param tct_functions: Dictionary containing the functions of the TCTs in the CSD. The keys must specify the id of the TCT (starting with 1 for the TCT between 0 and 1 electrons in the system) and the items should be partially initialized versions of the function "tct_bezier". :type tct_functions: Dict[int, Callable] :param rotation: The rotation to be applied to the TCT(s) (which is/are usually represented rotated by 45 degrees). Default is -np.pi/4. :type rotation: float :param lut_entries: Number of samples for the lookup-table. If this is not None, a lookup-table will be used to evaluate the points on the bezier curve. Default is None. :type lut_entries: Optional[int] :returns: The label mask for the lead transitions (in our case: total charge transitions). :rtype: np.ndarray .. py:function:: get_electron_occupation(csd, volt_limits_g1, volt_limits_g2, bezier_coords, tct_functions, rotation = -np.pi / 4, lut_entries = None, cdf_type = 'sigmoid', cdf_gamma_factor = None) Calculates the electron occupations for a given CSD represented by a numpy array. The total charge transitions (TCTs) in the CSD are expected to be labeled by their pixel values (all pixels with value 1 belong to TCT 1, etc.). :param csd: The CSD transition line mask (for 2D scans) or only zeros (for 1D scans). :type csd: np.ndarray :param volt_limits_g1: Voltage limits of (plunger) gate 1 (second-/x-axis). Example: [min_V1, max_V1] :type volt_limits_g1: np.ndarray :param volt_limits_g2: Voltage limits of (plunger) gate 2 (first-/y-axis). Example: [min_V2, max_V2] :type volt_limits_g2: np.ndarray :param bezier_coords: Bezier anchor coordinates for all used total charge transitions (TCTs). The keys of the dictionary must specify the id of the TCT (starting with 1 for the TCT between 0 and 1 electrons in the system). Each item is an array that corresponds to one TCT and has the shape (n, 3, 2). The first dimension refers to the id of the bezier curve, the second dimension to the position of the anchor point (0 = left, 1 = center, 2 = right), and the third dimension to the axis (0 = x-values, 1 = y-value). :type bezier_coords: Dict[int, np.ndarray] :param tct_functions: Dictionary containing the functions of the TCTs in the CSD. The keys must specify the id of the TCT (starting with 1 for the TCT between 0 and 1 electrons in the system) and the items should be partially initialized versions of the function "tct_bezier". :type tct_functions: Dict[int, Callable] :param rotation: The rotation that has been applied to the TCT (which is usually represented with the tct_params rotated by 45 degrees). Default: is -np.pi/4. :type rotation: float :param lut_entries: Number of samples for the lookup-table for the bezier curves. If this is not None, a lookup-table will be used to evaluate the points on the bezier curve. Default is None. :type lut_entries: Optional[int] :param cdf_type: Name of the type of cumulative distribution function (CDF) to be used for interdot transitions. Can be either "cauchy" or "sigmoid. Default is "sigmoid". :type cdf_type: str :param cdf_gamma_factor: The factor used for the calculation of the gamma values of the CDF. If set to None, the default values for the selected cdf_type are used (2.2 for sigmoid, 6.15 for cauchy). Gamma is calculated as follows: gamma = width_bezier_curve / cdf_gamma_factor. Default is None. :type cdf_gamma_factor: Optional[float] :returns: The electron occupations for the CSD. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. :rtype: np.ndarray .. py:function:: ideal_csd_geometric(tct_params, volt_limits_g1, volt_limits_g2, resolution = np.array([100, 100]), rotation = -np.pi / 4, lut_entries = None, cdf_type = 'sigmoid', cdf_gamma_factor = None) Generate an ideal Charge Stability Diagram (CSD) based on the supplied parameters. The CSD is stored in a numpy array. The two axis refer to gate voltages, with axis 0 (y-axis) representing the voltage on gate 2 and axis 1 (x-axis) representing the voltage of gate 1. The total charge transitions (TCTs) (series of connected lead-to-dot transitions) separating regions with different numbers of electrons in the system are represented by linear parts and bezier curves. :param tct_params: List containing a numpy array with parameters for every TCT in the CSD. Each array contains all required parameters to describe the TCT form. The parameters for a TCT are: [0] = length left (in x-/voltage-space, not number of points) [1] = length right (in x-/voltage-space, not number of points) [2] = gradient left (in voltages) [3] = gradient right (in voltages) [4] = start position x (bezier curve leftmost point) (in x-/voltage-space, not number of points) [5] = start position y (bezier curve leftmost point) (in x-/voltage-space, not number of points) [6] = end position x (bezier curve rightmost point) (in x-/voltage-space, not number of points) [7] = end position y (bezier curve rightmost point) (in x-/voltage-space, not number of points) :type tct_params: List[np.ndarray] :param volt_limits_g1: Voltage sweep range of (plunger) gate 1 (second-/x-axis). Example: [min_V1, max_V1] :type volt_limits_g1: np.ndarray :param volt_limits_g2: Voltage sweep range of (plunger) gate 2 (first-/y-axis). Example: [min_V2, max_V2] :type volt_limits_g2: np.ndarray :param resolution: Desired resolution (in pixels) for the gates. If only one value is supplied, a 1D sweep is performed. Then, both gates are swept simultaneously. Default is np.array([100, 100]). Example: [res_g1, res_g2] :type resolution: np.ndarray :param rotation: Float value defining the rotation to be applied to the TCT (which is usually represented with the tct_params rotated by 45 degrees). Default is -np.pi/4. :type rotation: float :param lut_entries: Number of samples for the lookup-table for bezier curves. If this is not None, a lookup-table will be used to evaluate the points on the bezier curves, else they are solved explicitly. Using a lookup-table speeds up the calculation at the possible cost of accuracy. Default is None. :type lut_entries: Optional[int] :param cdf_type: Name of the type of cumulative distribution function (CDF) to be used. Can be either "cauchy" or "sigmoid". Default is "sigmoid". :type cdf_type: str :param cdf_gamma_factor: The factor used for the calculation of the gamma values of the CDF. If set to None (=default) the default values for the selected cdf_type are used. Gamma is calculated as follows: gamma = width_bezier_curve / cdf_gamma_factor Default is None. :type cdf_gamma_factor: Optional[float] :returns: Occupation numbers and lead transition mask (in our case: total charge transitions). The occupation numbers are stored in a 3-dimensional numpy array. The first two dimensions map to the axis of the CSD, while the third dimension indicates the dot of the corresponding occupation value. The label mask for the lead-to-dot transitions is stored in a 2-dimensional numpy array with the axis mapping to the CSD axis. :rtype: Tuple[np.ndarray, np.ndarray]