aixcalibuha.calibration package

Package containing modules and classes to perform calibration tasks.

Submodules

aixcalibuha.calibration.calibrator module

Module containing the basic class to calibrate a dynamic model, e.g. a modelica model.

class aixcalibuha.calibration.calibrator.Calibrator(cd: str, sim_api: SimulationAPI, calibration_class: CalibrationClass, **kwargs)[source]

Bases: Optimizer

This class can Calibrator be used for single time-intervals of calibration.

Parameters:

  • cd (str,os.path.normpath) – Working directory

  • sim_api (ebcpy.simulationapi.SimulationAPI) – Simulation-API for running the models

  • calibration_class (CalibrationClass) – Class with information on Goals and tuner-parameters for calibration

  • result_path (str) – If given, then the resulting parameter values will be stored in a JSON file at the given path.

  • timedelta (float) – If you use this class for calibrating a single time-interval, you can set the timedelta to instantiate the simulation before actually evaluating it for the objective. The given float (default is 0) is subtracted from the start_time of your calibration_class. You can find a visualisation of said timedelta in the img folder of the project.

  • save_files (boolean) – If true, all simulation files for each iteration will be saved!

  • verbose_logging (boolean) – Default is True. If False, the standard Logger without Visualization in Form of plots is used. If you use this, the following keyword arguments below will help to further adjust the logging.

  • show_plot (boolean) – Default is True. If False, all created plots are not shown during calibration but only stored at the end of the process.

  • create_tsd_plot (boolean) – Default is True. If False, the plot of the time series data (goals) is not created and thus shown in during calibration. It therefore is also not stored, even if you set the save_tsd_plot keyword-argument to true.

  • save_tsd_plot (boolean) – Default is False. If True, at each iteration the created plot of the time-series is saved. This may make the process much slower

  • fail_on_error (boolean) – Default is False. If True, the calibration will stop with an error if the simulation fails. See also: ret_val_on_error

  • ret_val_on_error (float,np.NAN) – Default is np.NAN. If fail_on_error is false, you can specify here which value to return in the case of a failed simulation. Possible options are np.NaN, np.inf or some other high numbers. be aware that this max influence the solver.

  • fixed_parameters (dict) – Default is an empty dict. This dict may be used to add certain parameters to the simulation which are not tuned / variable during calibration. Such parameters may be used if the default values in the model don’t represent the parameter values you want to use.

  • apply_penalty (boolean) – Default is true. Specifies if a penalty function should be applied or not.

  • penalty_factor (boolean) – Default is 0. Quantifies the impact of the penalty term on the objective function. The penalty factor is added to the objective function.

  • recalibration_count (boolean) – Default is 0. Works as a counter and specifies the current cycle of recalibration.

  • perform_square_deviation (boolean) – Default is false. If true the penalty function will evaluate the penalty factor with a quadratic approach.

  • max_itercount (int) – Default is Infinity. Maximum number of iterations of calibration. This may be useful to explicitly limit the calibration time.

  • plot_file_type (str) – File ending of created plots. Any supported option in matplotlib, e.g. svg, png, pdf … Default is png

calibrate(framework, method=None, **kwargs) → dict[source]

Start the calibration process of the calibration classes, visualize and save the results.

The arguments of this function are equal to the arguments in Optimizer.optimize(). Look at the docstring in ebcpy to know which options are available.

property calibration_class: CalibrationClass

Get the current calibration class

property fixed_parameters: dict

Get the currently fixed parameters during calibration

get_penalty(current_tuners, current_tuners_scaled)[source]

Get penalty factor for evaluation of current objective. The penaltyfactor considers deviations of the tuner parameters in the objective function. First the relative deviation between the current best values of the tuner parameters from the recalibration steps and the tuner parameters obtained in the current iteration step is determined. Then the penaltyfactor is being increased according to the relative deviation.

Parameters:

current_tuner_values (pd.series) – To add

Returns:

float penalty Penaltyfactor for evaluation.

property goals: Goals

Get the current goals of the calibration class

mp_obj(x, *args)[source]

Objective function for Multiprocessing.

Parameters:

  • x (np.array) – Array with parameters for optimization. Shape of the array is (number_of_evaluations x number_of_variables). For instance, optimizating 10 variables and evaluating 900 objectives in parallel, the shape would be 900 x 10.

  • n_cpu (int) – Number of logical Processors to run optimization on.

obj(xk, *args)[source]

Default objective function. The usual function will be implemented here:

  1. Convert the set to modelica-units

  2. Simulate the converted-set

  3. Get data as a dataFrame

  4. Get penalty factor for the penalty function

  5. Calculate the objective based on statistical values

Parameters:

  • xk (np.array) – Array with normalized values for the minimizer

  • work_id (int) – id for worker in Multiprocessing

Returns:

Objective value based on the used quality measurement

Return type:

float

save_results(parameter_values: dict, filename: str)[source]

Saves the given dict into a file with path self.result_path and name filename.

property tuner_paras: TunerParas

Get the current tuner parameters of the calibration class

validate(validation_class: CalibrationClass, calibration_result: Dict, verbose=False)[source]

Validate the given calibration class based on the given values for tuner_parameters.

Parameters:

  • validation_class (CalibrationClass) – The class to validate on

  • calibration_result (dict) – The calibration result to apply to the validation class on.

aixcalibuha.calibration.multi_class_calibrator module

Module containing a class for calibrating multiple calibration classes at once.

class aixcalibuha.calibration.multi_class_calibrator.MultipleClassCalibrator(cd: str, sim_api, calibration_classes: List[CalibrationClass], start_time_method: str = 'fixstart', calibration_strategy: str = 'parallel', **kwargs)[source]

Bases: Calibrator

Class for calibration of multiple calibration classes. When passing multiple classes of the same name, all names are merged into one class with so called relevant time intervals. These time intervals are used for the evaluation of the objective function. Please have a look at the file in docsimgtypeOfContinouusCalibration.pdf for a better understanding on how this class works.

Parameters:

  • start_time_method (str) – Default is ‘fixstart’. Method you want to use to specify the start time of your simulation. If ‘fixstart’ is selected, the keyword argument fixstart is used for all classes (Default is 0). If ‘timedelta’ is used, the keyword argument timedelta specifies the time being subtracted from each start time of each calibration class. Please have a look at the file in docsimgtypeOfContinouusCalibration.pdf for a better visualization.

  • calibration_strategy (str) – Default is ‘parallel’. Strategy you want to use for multi-class calibration. If ‘parallel’ is used, parameters will be calibrated on the respective time intervals independently. If ‘sequential’ is used, the order of the calibration classes matters: The resulting parameter values of one class will be used as starting values for calibration on the next class.

  • fix_start_time (float) – Value for the fix start time if start_time_method=”fixstart”. Default is zero.

  • timedelta (float) – Value for timedelta if start_time_method=”timedelta”. Default is zero.

  • merge_multiple_classes (str) – Default True. If False, the given list of calibration-classes is handeled as-is. This means if you pass two CalibrationClass objects with the same name (e.g. “device on”), the calibration process will run for both these classes stand-alone. This will automatically yield an intersection of tuner-parameters, however may have advantages in some cases.

calibrate(framework, method=None, **kwargs) → dict[source]

Start the calibration process.

Return dict self.res_tuner:

Dictionary of the optimized tuner parameter names and values.

Return dict self._current_best_iterate:

Dictionary of the current best results of tuner parameter, iteration step, objective value, information about the goals object and the penaltyfactor.

check_intersection_of_tuner_parameters()[source]

Checks intersections between tuner parameters.

Return dict res_tuner:

Dictionary of the optimized tuner parameter names and values.

fix_start_time = 0
merge_multiple_classes = True