BF-ML - Machine Learning
Ver. 2.1.3 (2023-03-10)
This module provides the fundamental templates and processes for machine learning in MLPro.
- class mlpro.bf.ml.basics.HyperParam(p_name_short, p_base_set='R', p_name_long='', p_name_latex='', p_unit='', p_unit_latex='', p_boundaries: list = [], p_description='', p_symmetrical: bool = False, p_logging=False, **p_kwargs)
Bases:
Dimension
Hyperparameter definition class. See class Dimension for further descriptions.
- C_EVENT_VALUE_CHANGED = 'VALUE_CHANGED'
- class mlpro.bf.ml.basics.HyperParamSpace
Bases:
ESpace
Hyperparameter space, which is just an Euclidian space.
- class mlpro.bf.ml.basics.HyperParamTuple(p_set: Set)
Bases:
Element
Tuple of hyperparameters, which is an element of a hyperparameter space
- set_value(p_dim_id, p_value)
- class mlpro.bf.ml.basics.HyperParamDispatcher(p_set: Set)
Bases:
HyperParamTuple
To dispatch multiple hp tuples into one tuple
- add_hp_tuple(p_hpt: HyperParamTuple)
- get_value(p_dim_id)
- set_value(p_dim_id, p_value)
- get_values()
- set_values(p_values)
Overwrites the values of all components of the element.
- Parameters:
dimensions. (p_values Something iterable with same length as number of element) –
- class mlpro.bf.ml.basics.Model(p_ada: bool = True, p_buffer_size: int = 0, p_name: str | None = None, p_range_max: int = 2, p_autorun=0, p_class_shared=None, p_visualize: bool = False, p_logging=True, **p_par)
Bases:
Task
,LoadSave
,ScientificObject
- Fundamental template class for adaptive ML models. Supports in particular
Adaptivity (explicit and/or event based)
Hyperparameter management
Data buffering
Multitasking
Plotting
Scientific referencing on source code level
- Parameters:
p_ada (bool) – Boolean switch for adaptivitiy. Default = True.
p_buffer_size (int) – Initial size of internal data buffer. Defaut = 0 (no buffering).
p_name (str) – Optional name of the model. Default is None.
p_range_max (int) – Maximum range of asynchonicity. See class Range. Default is Range.C_RANGE_PROCESS.
p_autorun (int) – On value C_AUTORUN_RUN method run() is called imediately during instantiation. On vaule C_AUTORUN_LOOP method run_loop() is called. Value C_AUTORUN_NONE (default) causes an object instantiation without starting further actions.
p_class_shared – Optional class for a shared object (class Shared or a child class of it)
p_visualize (bool) – Boolean switch for visualisation. Default = False.
p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL
p_par (Dict) – Further model specific hyperparameters (to be defined in child class).
- C_TYPE = 'Model'
- C_NAME = '????'
- C_EVENT_ADAPTED = 'ADAPTED'
- C_SCIREF_TYPE = None
- _init_hyperparam(**p_par)
Implementation specific hyperparameters can be added here. Please follow these steps: a) Add each hyperparameter as an object of type HyperParam to the internal hyperparameter
space object self._hyperparam_space
Create hyperparameter tuple and bind to self._hyperparam_tuple
Set default value for each hyperparameter
- Parameters:
p_par (Dict) – Further model specific hyperparameters, that are passed through constructor.
- get_hyperparam() HyperParamTuple
Returns the internal hyperparameter tuple to get access to single values.
- switch_adaptivity(p_ada: bool)
Switches adaption functionality on/off.
- Parameters:
p_ada (bool) – Boolean switch for adaptivity
- set_random_seed(p_seed=None)
Resets the internal random generator using the given seed.
- get_adapted() bool
Returns True, if the model was adapted at least once. False otherwise.
- _set_adapted(p_adapted: bool)
Sets the adapted flag. Internal use only.
- adapt(**p_kwargs) bool
Adapts the model by calling the custom method _adapt().
- Parameters:
p_kwargs (dict) – All parameters that are needed for the adaption. Depends on the specific higher context.
- Returns:
adapted – True, if something has been adapted. False otherwise.
- Return type:
bool
- _adapt(**p_kwargs) bool
Custom implementation of the adaptation algorithm. Please specify the parameters needed by your implementation. This method will be called by public method adapt() if adaptivity is switched on.
- Parameters:
p_kwargs (dict) – All parameters that are needed for the adaption. Please replace by concrete parameter definitions that meet the needs of your algorithm.
- Returns:
adapted – True, if something has been adapted. False otherwise.
- Return type:
bool
- adapt_on_event(p_event_id: str, p_event_object: Event)
Method to be used as event handler for event-based adaptations. Calls custom method _adapt_on_event() and updates the internal adaptation state.
- Parameters:
p_event_id (str) – Event id.
p_event_object (Event) – Object with further context informations about the event.
- _adapt_on_event(p_event_id: str, p_event_object: Event) bool
Custom method to be used for event-based adaptation. See method adapt_on_event().
- Parameters:
p_event_id (str) – Event id.
p_event_object (Event) – Object with further context informations about the event.
- Returns:
adapted – True, if something was adapted. False otherwise.
- Return type:
bool
- clear_buffer()
Clears internal buffer (if buffering is active).
- get_accuracy() float
Determines the accuracy of the model.
- Returns:
accuracy – Accuracy of the model as a scalar value in interval [0,1]
- Return type:
float
- _range: int
- _plot_settings: PlotSettings
- class mlpro.bf.ml.basics.AWorkflow(p_name: str | None = None, p_range_max=1, p_class_shared=<class 'mlpro.bf.mt.Shared'>, p_ada: bool = True, p_visualize: bool = False, p_logging=True, **p_kwargs)
-
Adaptive workflow based on a workflow and an adaptive ml model.
- Parameters:
p_name (str) – Optional name of the workflow. Default is None.
p_range_max (int) – Maximum range of asynchonicity. See class Range. Default is Range.C_RANGE_PROCESS.
p_class_shared – Optional class for a shared object (class OAShared or a child class of OAShared)
p_ada (bool) – Boolean switch for adaptivitiy. Default = True.
p_visualize (bool) – Boolean switch for visualisation. Default = False.
p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL
p_kwargs (dict) – Further optional named parameters.
- C_TYPE = 'Adaptive Workflow'
- add_task(p_task: Task, p_pred_tasks: list | None = None)
Adds a task to the workflow.
- Parameters:
p_task (Task) – Task object to be added.
p_pred_tasks (list) – Optional list of predecessor task objects
- switch_adaptivity(p_ada: bool)
Switches adaption functionality on/off.
- Parameters:
p_ada (bool) – Boolean switch for adaptivity
- set_random_seed(p_seed=None)
Resets the internal random generator using the given seed.
- get_adapted() bool
Returns True, if the model was adapted at least once. False otherwise.
- clear_buffer()
Clears internal buffer (if buffering is active).
- get_accuracy()
Determines the accuracy of the model.
- Returns:
accuracy – Accuracy of the model as a scalar value in interval [0,1]
- Return type:
float
- _range: int
- _plot_settings: PlotSettings
- class mlpro.bf.ml.basics.Scenario(p_mode=0, p_ada: bool = True, p_cycle_limit: int = 0, p_auto_setup: bool = True, p_visualize: bool = True, p_logging=True)
Bases:
ScenarioBase
Template class for a common ML scenario with an adaptive model inside. To be inherited and specialized in higher ML subtopic layers. See class bf.ops.ScenarioBase for further details and custom methods.
- The following key features are included:
Operation mode
Cycle management
Timer
Latency
Explicit handling of an adaptive ML model inside
- Parameters:
p_mode – Operation mode. See bf.ops.Mode.C_VALID_MODES for valid values. Default = Mode.C_MODE_SIM.
p_ada (bool) – Boolean switch for adaptivity. Default = True.
p_cycle_limit (int) – Maximum number of cycles. Default = 0 (no limit).
p_visualize (bool) – Boolean switch for visualisation. Default = True.
p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL.
- C_TYPE = 'ML-Scenario'
- C_NAME = '????'
- switch_logging(p_logging)
Sets new log level.
- Parameters:
p_logging – Log level (constant C_LOG_LEVELS contains valid values)
- setup()
Custom method to set up all components of the scenario.
- _setup(p_mode, p_ada: bool, p_visualize: bool, p_logging) Model
Custom setup of ML scenario.
- Parameters:
p_mode – Operation mode. See Mode.C_VALID_MODES for valid values. Default = Mode.C_MODE_SIM
p_ada (bool) – Boolean switch for adaptivity.
p_visualize (bool) – Boolean switch for visualisation.
p_logging – Log level (see constants of class Log).
- Returns:
model – Adaptive model inside the ML scenario
- Return type:
- init_plot(p_figure: Figure | None = None, p_plot_settings: PlotSettings | None = None)
Initializes the plot functionalities of the class.
- Parameters:
p_figure (Matplotlib.figure.Figure, optional) – Optional MatPlotLib host figure, where the plot shall be embedded. The default is None.
p_plot_settings (PlotSettings) – Optional plot settings. If None, the default view is plotted (see attribute C_PLOT_DEFAULT_VIEW).
- update_plot(**p_kwargs)
Updates the plot.
- Parameters:
**p_kwargs – Implementation-specific plot data and/or parameters.
- reset(p_seed=1)
Resets the scenario and especially the ML model inside. Internal random generators are seed with the given value. Custom reset actions can be implemented in method _reset().
- Parameters:
p_seed (int) – Seed value for internal random generator
- _plot_settings: PlotSettings
- class mlpro.bf.ml.basics.TrainingResults(p_scenario: Scenario, p_run, p_cycle_id, p_logging='W')
-
Results of a training (see class Training).
- Parameters:
p_scenario (Scenario) – Related scenario.
p_run (int) – Run id.
p_cycle_id (int) – Id of first cycle of this run.
p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL
- C_TYPE = 'Results '
- add_custom_result(p_name, p_value)
- close()
- log_results()
- _log_results()
- _save_line(p_file, p_name, p_value)
- save(p_path, p_filename='summary.csv') bool
Saves a training summary in the given path.
- Parameters:
p_path (str) – Destination folder
p_filename (string) – Name of summary file. Default = ‘summary.csv’
- Returns:
success – True, if summary file was created successfully. False otherwise.
- Return type:
bool
- class mlpro.bf.ml.basics.HyperParamTuner(p_logging=True)
-
Template class for hyperparameter tuning (HPT).
- C_TYPE = 'HyperParam Tuner'
- C_NAME = '????'
- C_VAR_TRIAL = 'Trial'
- C_VAR_SCORE = 'Highscore'
- maximize(p_training_cls, p_num_trials, p_root_path, **p_training_param) TrainingResults
…
- Parameters:
p_training_cls – Training class to be instantiated/executed
p_num_trials (str) – Number of trials
p_num_trials – Root path of the training class
p_training_param (dictionary) – Training parameters
- Returns:
results – Training results of the best tuned model (see class TrainingResults).
- Return type:
- _maximize() TrainingResults
- _save_line(p_file, p_name, p_value)
- save(p_param, p_result, p_filename='best_parameters.csv') bool
Saves the best result of the hyperparameter tuning in the root path.
- Parameters:
p_param (dict) – A dictionary that consists of list of best parameters
p_result (float) – Highest score
p_filename (str) – Name of summary file. Default = ‘best_parameters.csv’
- Returns:
success – True, if summary file was created successfully. False otherwise.
- Return type:
bool
- class mlpro.bf.ml.basics.Training(**p_kwargs)
Bases:
Log
Template class for a ML training and hyperparameter tuning.
- Parameters:
p_scenario_cls – Name of ML scenario class, compatible to/inherited from class Scenario.
p_cycle_limit (int) – Maximum number of training cycles (0=no limit). Default = 0.
p_adaptation_limit (int) – Maximum number of adaptations (0=no limit). Default = 0.
p_hpt (HyperParamTuner) – Optional hyperparameter tuner (see class HyperParamTuner). Default = None.
p_hpt_trials (int) – Optional number of hyperparameter tuning trials. Default = 0.
p_path (str) – Optional destination path to store training data. Default = None.
p_visualize (bool) – Boolean switch for visualisation. Default = False.
p_logging – Log level (see constants of class Log). Default = Log.C_LOG_WE.
- C_TYPE = 'Training'
- C_NAME = '????'
- C_CLS_RESULTS
alias of
TrainingResults
- C_MODE_TRAIN = 0
- C_MODE_EVAL = 1
- C_LOG_SEPARATOR = '------------------------------------------------------------------------------'
- _gen_root_path(p_path) str
- _gen_current_path(p_root_path, p_run) str
- _init_results() TrainingResults
- _close_results(p_results: TrainingResults)
- run_cycle() bool
Runs a single training cycle.
- Returns:
termination_event – True, if training run has finished. False otherwise.
- Return type:
bool
- _run_cycle() bool
Single custom trainig cycle to be redefined. Custom training results can be added to using self._results.add_custom_result(p_name, p_value).
- Returns:
True, if training has finished. False otherwise.
- Return type:
bool
- run() TrainingResults
Runs a training and returns the results of the best trained/tuned agent.
- Returns:
Object with training results.
- Return type:
- _run() TrainingResults
- get_results() TrainingResults
- get_training_path() str
- class mlpro.bf.ml.basics.AdaptiveFunction(p_input_space: ~mlpro.bf.math.basics.MSpace, p_output_space: ~mlpro.bf.math.basics.MSpace, p_output_elem_cls=<class 'mlpro.bf.math.basics.Element'>, p_ada: bool = True, p_buffer_size: int = 0, p_name: str | None = None, p_range_max: int = 2, p_autorun=0, p_class_shared=None, p_visualize: bool = False, p_logging=True, **p_par)
-
Template class for an adaptive bi-multivariate mathematical function. The kind of adaptation (learning paradigm) is to be specified in child classes.
- Parameters:
p_input_space (MSpace) – Input space of function
p_output_space (MSpace) – Output space of function
p_output_elem_cls – Output element class (compatible to/inherited from class Element)
p_ada (bool) – Boolean switch for adaptivitiy. Default = True.
p_buffer_size (int) – Initial size of internal data buffer. Defaut = 0 (no buffering).
p_name (str) – Optional name of the model. Default is None.
p_range_max (int) – Maximum range of asynchonicity. See class Range. Default is Range.C_RANGE_PROCESS.
p_autorun (int) – On value C_AUTORUN_RUN method run() is called imediately during instantiation. On vaule C_AUTORUN_LOOP method run_loop() is called. Value C_AUTORUN_NONE (default) causes an object instantiation without starting further actions.
p_class_shared – Optional class for a shared object (class Shared or a child class of it)
p_visualize (bool) – Boolean switch for visualisation. Default = False.
p_logging – Log level (see constants of class Log). Default: Log.C_LOG_ALL
p_par (Dict) – Further model specific hyperparameters (to be defined in chhild class).
- _range: int
- _plot_settings: PlotSettings
- C_TYPE = 'Adaptive Function'
- C_NAME = '????'