Fitting#

elecboltz.fit_model(x_data: ~collections.abc.Mapping[str, ~collections.abc.Sequence | ~collections.abc.Sequence[~collections.abc.Sequence]], y_data: ~collections.abc.Mapping[str, ~collections.abc.Sequence | ~collections.abc.Sequence[~collections.abc.Sequence]], init_params: ~collections.abc.Mapping, bounds: ~collections.abc.Mapping, multi_params: ~collections.abc.Collection[str] = [], x_shift: ~collections.abc.Mapping = None, x_normalize: ~collections.abc.Mapping = None, y_shift: ~collections.abc.Mapping = None, y_normalize: ~collections.abc.Mapping = None, loss: ~typing.Callable = <function _mean_absolute_error>, postprocess: ~typing.Callable = <function _dummy_postprocess>, save_path: str = None, save_label: str = None, **kwargs)#

Convenience function to set up and run a fitting routine.

This uses scipy.optimize.differential_evolution to perform a global fit. The optimizer is hard-coded, because the callback functions are highly specific to each optimizer. Saves the results to the specified path.

Parameters:

  • x_data (Mapping[str, Union[Sequence, Sequence[Sequence]]]) – The independent variable data (e.g. field). The name of the variable is mapped to the data, e.g. {'field': [[0.5, 1.5, 2.5], [0.6, 1.6, 2.6]]}. In case of nonempty multi_params, the value must be a collection of sequences, where each sequence corresponds to a different parameter to be fitted, e.g. {'field': [[0, 1, 2], [0, 1, 2]]}.

  • y_data (Mapping[str, Union[Sequence, Sequence[Sequence]]]) – The dependent variable data (e.g. conductivity). The name of the variable is mapped to the data, e.g. {'sigma_xx': [1.1, 2.4, 3.8]}. The name of each variable must start with “sigma” or “rho” (for conductivity or resistivity, respectively), and you can add a suffix to specify the component (e.g. "sigma_xx", "rho_xy"). In case of nonempty multi_params, the value must be a collection of sequences, where each sequence corresponds to a different parameter to be fitted, e.g. {'rho_zz': [[1.1, 2.4, 3.8], [1.2, 2.5, 3.9]]}.

  • init_params (Mapping) – Initial parameters for the fitting routine, and also other parameters for initiallizing the classes. This is passed through easy_params to the BandStructure and Conductivity.

  • bounds (Mapping) – Bounds for the fitting parameters. This mapping has the same structure as init_params, but only containing the variables that are to be fitted, and their values in the mapping must be a collection of the form (min, max).

  • multi_params (Collection, optional) – A collection of parameters that are to be fitted differently for the different datasets in x_data and y_data, if there is more than one. To make it precise, each label must be a dot-separated string, showing the “path” to the value in the parameters dictionary, e.g. "band_params.mu" or "scattering_params.nu.0". These parameters must themselves be collections in the parameters dictionary, showing the value for every dataset e.g. {'band_params': {'mu': [0.1, 0.2, 0.3]}} in init_params or {'band_params': {'mu': [(0.1, 0.9), (0.2, 0.8), (0.3, 0.7)]}} in bounds.

  • x_shift (Mapping, optional) – If provided, the y values will be shifted by the y value at this x point. The mapping must have the same structure as x_data, but with single values instead of arrays as the values.

  • x_normalize (Mapping, optional) – If provided, the y values will be normalized by the y value at this x point. Note that shifting will always be done before normalization. The mapping must have the same structure as x_data, but with single values instead of arrays as the values. Note that shifts are applied before normalization.

  • y_shift (Mapping, optional) – The y values will be normalized to this value (if x_normalize is provided). The mapping must have the same structure as y_data, but with single values instead of arrays as the values.

  • y_normalize (Mapping, optional) – The y values will be shifted to this value (if x_shift is provided). The mapping must have the same structure as y_data, but with single values instead of arrays as the values.

  • loss (Callable, optional) – A function that takes the fit and data y values, and returns a scalar loss value. By default, the mean absolute error is used.

  • postprocess (Callable, optional) – This callable is applied to the data and fit y values before calculating the loss. It takes x_data and a y with a format similar to y_data, and returns the processed y, again with a format similar to y_data. By default, no postprocessing is applied. An example use case is filtering out parts of the values where the data can be unreliable.

  • save_path (str, optional) – The directory where the fitting results will be saved. If not provided, results will not be saved.

  • save_label (str, optional) – Label of the results. If not provided, will be set to f"y_label_x_label". If y_label` or ``x_label are collections of string, they will be joined with an underscore.

  • **kwargs (dict, optional) – Additional keyword arguments passed to scipy.optimize.differential_evolution.

class elecboltz.fit.FittingRoutine(init_params: Mapping, save_path: str = None, save_label: str = 'fit', update_keys: Collection[str] = None, print_log: bool = True)#

This convenience class automatically sets up a fitting routine.

Stores the necessary data and generates the functions used in This includes handling the residual computation, parameter update, logging the fitting progress, and saving the results to a file.

Parameters:

  • init_params (Mapping) – Initial parameters for the fitting routine, and also other parameters for initiallizing the classes. This is passed through easy_params to the BandStructure and Conductivity.

  • save_path (str, optional) – The directory where the fitting logs will be saved. If not provided, logs will not be saved.

  • save_label (str, optional) – Label of the results.

  • update_keys (Collection[str], optional) – The “flattened” keys of the parameters that will be updated during the fitting. See extract_keys for more information. Used for updating the params attribute and logging. If not provided, params will not be updated and the parameter names will not be mentioned in the log.

  • print_log (bool, optional) – If True, the fitting progress will be printed to the console.

params#

The current parameters dictionary.

Type:

Mapping

save_path#

The directory where the fitting logs will be saved.

Type:

Path

save_label#

The label of the results.

Type:

Path

update_keys#

The “flattened” keys of the parameters that will be updated during the fitting. This is used for updating the params attribute and logging.

Type:

Collection[str]

iteration#

The current iteration number.

Type:

int

last_time#

The timestamp of the last fitting iteration.

Type:

float

total_time#

The total time spent on the fitting routine.

Type:

float

log(param_values, convergence: float = None)#

Log the current fitting iteration and parameters.

Parameters:

  • param_values (Sequence) – The current values of the parameters.

  • convergence (float, optional) – The convergence value of the fitting routine. 0.0 means no convergence, 1.0 means perfect convergence. If not provided, it will not be logged.

residual(param_values: ~collections.abc.Sequence, param_keys: ~collections.abc.Sequence[str], x_data: ~collections.abc.Mapping[str, ~collections.abc.Sequence | ~collections.abc.Sequence[~collections.abc.Sequence]], y_data: ~collections.abc.Mapping[str, ~collections.abc.Sequence | ~collections.abc.Sequence[~collections.abc.Sequence]], multi_params: ~collections.abc.Collection = [], x_shift: ~collections.abc.Mapping = None, x_normalize: ~collections.abc.Mapping = None, y_shift: ~collections.abc.Mapping = None, y_normalize: ~collections.abc.Mapping = None, cond_obj: ~elecboltz.conductivity.Conductivity = None, loss: ~typing.Callable = <function FittingRoutine.<lambda>>, postprocess: ~typing.Callable = <function FittingRoutine.<lambda>>)#

Compute the residual for the given parameters and data.

Parameters:

  • param_values (Sequence) – The values of the parameters to update.

  • param_keys (Sequence[str]) – The “flat keys of the parameters to update.

  • x_data (Mapping[str, Union[Sequence, Sequence[Sequence]]]) – The independent variable data (e.g. field). The name of the variable is mapped to the data, e.g. {'field': [0.5, 1.5, 2.5]}. In case of a nonempty multi_params, the value must be a collection of sequences, where each sequence corresponds to a different parameter to be fitted, e.g. {'field': [[0.5, 1.5, 2.5], [0.6, 1.6, 2.6]]}.

  • y_data (Mapping[str, Union[Sequence, Sequence[Sequence]]]) – The dependent variable data (e.g. conductivity). The name of the variable is mapped to the data, e.g. {'sigma_xx': [1.1, 2.4, 3.8]}. The name of each variable must start with “sigma” or “rho” (for conductivity or resistivity, respectively), and you can add a suffix to specify the component (e.g. "sigma_xx", "rho_xy"). In case of nonempty multi_params, the value must be a collection of sequences, where each sequence corresponds to a different parameter to be fitted, e.g. {'rho_zz': [[1.1, 2.4, 3.8], [1.2, 2.5, 3.9]]}.

  • multi_params (Collection, optional) – A collection of parameters that are to be fitted differently for the different datasets in x_data and y_data, if there is more than one. To make it precise, each label must be a dot-separated string, showing the “path” to the value in the parameters dictionary, e.g. "band_params.mu" or "scattering_params.nu.0". These parameters must themselves be collections in the parameters dictionary, showing the value for every dataset e.g. {'band_params': {'mu': [0.1, 0.2, 0.3]}} in init_params or {'band_params': {'mu': [(0.1, 0.9), (0.2, 0.8), (0.3, 0.7)]}} in bounds.

  • x_shift (Mapping, optional) – If provided, the y values will be shifted by the y value at this x point.

  • x_normalize (Mapping, optional) – If provided, the y values will be normalized by the y value at this x point. Note that shifts are applied before normalization.

  • y_shift (float, optional) – The y values will be normalized to this value (if x_normalize is provided).

  • y_normalize (float, optional) – The y values will be shifted to this value (if x_shift is provided).

  • cond_obj (Conductivity, optional) – If provided, the fitter will try to salvage the calculations already done from that object.

  • loss (Callable, optional) – A function that takes the fit and data y values, and returns a scalar loss value. By default, the mean absolute error is used.

  • postprocess (Callable, optional) – This callable is applied to the data and fit y values before calculating the loss. It takes x_data and a y with a format similar to y_data, and returns the processed y, again with a format similar to y_data. By default, no postprocessing is applied. An example use case is filtering out parts of the values where the data can be unreliable.