BF-ML - Machine Learning

../../../../../../../_images/MLPro-BF-ML_class_diagram.drawio.png

Ver. 2.3.0 (2023-07-24)

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_id=None, p_name: str = None, p_range_max: int = 2, p_autorun=0, p_class_shared=None, p_visualize: bool = False, p_logging=True, **p_par)

Bases: Task, 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_id – Optional external id

  • 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_EVENT_OBJECTIVE_REACHED = False
C_BUFFER_CLS

alias of Buffer

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

  1. Create hyperparameter tuple and bind to self._hyperparam_tuple

  2. 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.

_hyperparam_handler(p_event_id, p_event_object: Event)

This is an event handler method for managing the updates of hyperparameters in the HPTuple. Set’s the flag hp_latest to false, as the hpt of the model are not latest to the tuple.

_update_hyperparameters() → bool

Custom method to update the hyperparameters of a system with the latest value in the Hyperparameter Tuple. This may be due to Hyperparameter Tuning. Please return True if the hyperparameters are updated successfully.

Returns:

True if the hyperparameters are updated successfully.

Return type:

bool

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).

add_objective(**p_kwargs)

Determines the objective of the model.

_add_objective(**p_kwargs)

This method is called in add_objective(). PLease redefine this method.

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

_get_accuracy() → float

This method is called in get_accuracy(). PLease redefine this method.

Returns:

accuracy – Accuracy of the model as a scalar value in interval [0,1]

Return type:

float

class mlpro.bf.ml.basics.AWorkflow(p_name: str = 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)

Bases: Model, Workflow

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)

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

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:

Model

init_plot(p_figure: Figure = None, p_plot_settings: PlotSettings = 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.

get_model() → Model

Returns the adaptive model object inside the scenario.

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

_reduce_state(p_state: dict, p_path: str, p_os_sep: str, p_filename_stub: str)

Custom method to reduce the given object state by components that can not be pickled. Further data files can be created in the given path and should use the given filename stub.

Parameters:

  • p_state (dict) – Object state dictionary to be reduced by components that can not be pickled.

  • p_path (str) – Path to store further optional custom data files

  • p_os_sep (str) – OS-specific path separator.

  • p_filename_stub (str) – Filename stub to be used for further optional custom data files

_complete_state(p_path: str, p_os_sep: str, p_filename_stub: str)

Custom method to complete the object state (=self) from external data sources. This method is called by standard method __setstate__() during unpickling the object from an external file.

Parameters:

  • p_path (str) – Path of the object pickle file (and further optional related files)

  • p_os_sep (str) – OS-specific path separator.

  • p_filename_stub (str) – Filename stub to be used for further optional custom data files

class mlpro.bf.ml.basics.TrainingResults(p_scenario: Scenario, p_run, p_cycle_id, p_logging='W')

Bases: Persistent

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()
classmethod load(p_path: str, p_filename: str)

Loading training results is explicitely disabled.

_save_line(p_file, p_name, p_value)
save(p_path: str, p_filename: str = '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_id=None, p_logging=True)

Bases: Persistent

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:

TrainingResults

_maximize() → TrainingResults
classmethod load(p_path: str, p_filename: str)

Loading training results is explicitely disabled.

_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 = '------------------------------------------------------------------------------'
get_scenario() → Scenario
_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:

TrainingResults

_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, p_range_max: int = 2, p_autorun=0, p_class_shared=None, p_visualize: bool = False, p_logging=True, **p_par)

Bases: Function, Model

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).

C_TYPE = 'Adaptive Function'
C_NAME = '????'