Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
64 commits
Select commit Hold shift + click to select a range
387f8ee
Bug: Illegal import of plot artifacts from bf.mt
detlefarend Sep 28, 2026
a287585
Redesign bf.mt for maximum performance and resource efficiency
detlefarend Sep 29, 2026
95fc748
Redesign event management
detlefarend Oct 5, 2026
4c75587
Redesign event management
detlefarend Oct 5, 2026
021b645
Complete event management docstrings
detlefarend Oct 5, 2026
000944d
Move constructor parameter docs to class docstrings
detlefarend Oct 5, 2026
63f9e86
Redesign event management
detlefarend Oct 5, 2026
b8d432a
Validate event configuration consistency
detlefarend Oct 5, 2026
28de8f9
Include event config type in implementation error
detlefarend Oct 5, 2026
bacf7d0
Redesign event management
detlefarend Oct 5, 2026
6df7d7b
Refine event management docstrings
detlefarend Oct 5, 2026
148a48c
Complete task event docstrings
detlefarend Oct 5, 2026
d71fd6a
Complete ML event management docstrings
detlefarend Oct 5, 2026
21c98e5
Document stream task event configuration
detlefarend Oct 5, 2026
221bced
Complete OA stream event docstrings
detlefarend Oct 5, 2026
5a7634d
Use shared ImplementationError in event management
detlefarend Oct 5, 2026
0dcfe1e
Fix event documentation references
detlefarend Oct 5, 2026
3a24810
Fix OA event documentation references
detlefarend Oct 5, 2026
1fa47b5
Release v2.3.0
detlefarend Oct 5, 2026
ce34dc8
Update event handling documentation
detlefarend Oct 5, 2026
e007332
Document task event configuration
detlefarend Oct 5, 2026
dc69ee5
Document event configuration in multitasking
detlefarend Oct 5, 2026
363734f
Document configurable ML events
detlefarend Oct 5, 2026
9c97122
Document event configuration for stream tasks
detlefarend Oct 5, 2026
d0dc477
Extend stream processing event documentation
detlefarend Oct 5, 2026
1d1e484
Document event configuration in OA streams
detlefarend Oct 5, 2026
a6e4792
Redesign event management
detlefarend Oct 6, 2026
f266ff7
Refact: Extended cluster model
detlefarend Oct 6, 2026
e70dea9
Refact: Extended cluster model
detlefarend Oct 6, 2026
8633fff
Refact: Extended cluster model
detlefarend Oct 6, 2026
4b49d23
Docs: Update cluster analyzer docstrings
detlefarend Oct 6, 2026
791f0d5
Docs: Update centroid cluster docstrings
detlefarend Oct 6, 2026
21cdb82
Docs: Update cluster base docstrings
detlefarend Oct 6, 2026
75c81c5
Docs: Update cluster body docstrings
detlefarend Oct 6, 2026
44ade54
Docs: Update cluster analysis architecture
detlefarend Oct 6, 2026
d4694a6
Docs: Update cluster analysis API overview
detlefarend Oct 6, 2026
ba5f237
Refact: Extended cluster model
detlefarend Oct 6, 2026
a707964
Refact: Extended cluster model
detlefarend Oct 8, 2026
0703619
Refact: Extended cluster model
detlefarend Nov 2, 2026
6651695
Update clustering docs for ClusterAPI rename
detlefarend Nov 2, 2026
893c4f3
Update clustering docs for ClusterAPI rename
detlefarend Nov 2, 2026
54e474c
Update clustering docs for ClusterAPI rename
detlefarend Nov 2, 2026
f6b8fbc
Merge remote-tracking branch 'origin/main' into v2.3.0
detlefarend Nov 4, 2026
7a4680e
Refact: Extended cluster model
detlefarend Nov 10, 2026
f987a88
Refact: Extended cluster model
detlefarend Nov 10, 2026
7fc4819
BF.MATH: New class NormalizerAPI
detlefarend Nov 11, 2026
8eba3cc
docs(bf.math): describe NormalizerAPI and its abstract operations
detlefarend Nov 11, 2026
89589b5
BF.MATH: New class NormalizerAPI
detlefarend Nov 11, 2026
a022ab2
BF.MATH: Optimize Normalizer.renormalize()
detlefarend Nov 11, 2026
cf43800
perf(bf.math): combine affine parameters in Normalizer.renormalize
detlefarend Nov 11, 2026
c89a19a
test(bf.math): cover combined normalizer renormalization
detlefarend Nov 11, 2026
349e9d7
test(bf.math): validate renormalization in existing normalizer howto
detlefarend Nov 11, 2026
608229a
test(bf.math): retain howto-based normalizer coverage
detlefarend Nov 11, 2026
a154be3
BF.MATH: Optimize Normalizer.renormalize()
detlefarend Nov 11, 2026
a1820e7
fix(bf.math): restore resolved normalization parameters after renorma…
detlefarend Nov 11, 2026
f9fff75
fix(bf.math): use dimension-specific coefficients in ndarray mappings
detlefarend Nov 11, 2026
05e67e7
feat(bf.math): support optional precomputed parameters for Scaler.res…
detlefarend Nov 11, 2026
c213a4c
BF.MATH: Optimize Normalizer.renormalize()
detlefarend Nov 11, 2026
fe13ee7
refactor(bf.math): compute renormalization parameters on update and d…
detlefarend Nov 11, 2026
723021e
Release v2.3.0
detlefarend Nov 12, 2026
a4d5417
BF.MATH: Optimize Normalizer.renormalize()
detlefarend Nov 12, 2026
cbd6d79
Refact: Extended cluster model
detlefarend Nov 15, 2026
981cbfe
Refact: Extended cluster model
detlefarend Nov 16, 2026
822ea6f
BF.MATH: Optimize Normalizer.renormalize()
detlefarend Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/rtd/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
author = "blueAIC"

# The full version, including alpha/beta/rc tags
release = "2.2.1"
release = "2.3.0"


# -- General configuration ---------------------------------------------------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,138 @@
Event handling
==============

Event handling is a widely used standard technique in software development. And that's how it found its way into MLPro.
The mechanism is inherited by higher classes in the form of the property class **EventHandler**. This class allows
event handler methods to be registered and events to be triggered, which in turn call registered handlers. An object of
type **Event** is passed to each handler. This contains further information about the context of the event.
Event handling is a fundamental mechanism in MLPro. It decouples the object that detects a state
transition from the objects that react to it. The generic implementation is provided by
``mlpro.bf.events`` and is reused by higher layers such as multitasking, stream processing, and
machine learning.

The event handling functionality is used extensively in MLPro. A large number of higher classes use this mechanism.
Based on this, even an event-oriented adaptation mechanism is cultivated in
:ref:`Layer 4 - Machine Learning <target_bf_ml>`.
The central classes are ``Event``, ``EventManager``, ``EventConfig``, and ``EventMode``.
Event identifiers use the type alias ``EventId`` and are represented by strings.

Event ids and handlers
----------------------

An event-capable class derives from ``EventManager`` and raises events under a unique event id.
Handlers can register for a particular id and are called whenever the event is dispatched.

.. code-block:: python

from mlpro.bf.events import Event, EventId, EventManager


class Producer(EventManager):

C_EVENT_CHANGED: EventId = 'CHANGED'

def change(self):
event = Event(p_raising_object=self)
self._raise_event(
p_event_id=self.C_EVENT_CHANGED,
p_event_object=event,
)


def handler(p_event_id, p_event_object):
print(p_event_id, p_event_object.get_raising_object())


producer = Producer()
producer.register_event_handler(
p_event_id=Producer.C_EVENT_CHANGED,
p_event_handler=handler,
)
producer.change()

The ``Event`` object transports the raising object, a time stamp, and optional event-specific
keyword data to all registered handlers.

Configurable events
-------------------

Event generation can be configured with ``EventConfig``. Concrete event-capable implementations
define their own child class and add one attribute per configurable event.

By convention, event ids and their corresponding configuration attributes are written in **upper
case** and are **identical**. This keeps the relationship transparent and allows an implementation
to query a mode directly by event id.

.. code-block:: python

from dataclasses import dataclass

from mlpro.bf.events import EventConfig, EventMode


@dataclass
class ProducerEvents(EventConfig):

CHANGED: EventMode = EventMode.EVENT


config = ProducerEvents(
CHANGED=EventMode.OFF,
)

The generic modes are:

``EventMode.OFF``
The event is disabled.

``EventMode.EVENT``
The event is enabled and may be raised.

The configuration is optional. If no ``EventConfig`` object is supplied, MLPro preserves the
historic behavior and ``_get_event_mode()`` returns ``EventMode.EVENT`` for every queried event id.

If a configuration object is supplied, every queried event id must have a matching attribute.
A mismatch indicates an implementation error and raises ``ImplementationError``. The concrete
event-capable implementation is responsible for maintaining the convention between event ids and
configuration attributes.

Efficient event creation
------------------------

The event mode should be queried **before** creating the ``Event`` object. This is important for
events that may occur at high frequency: a disabled event should cause virtually no runtime overhead.

.. code-block:: python

class Producer(EventManager):

C_EVENT_CHANGED: EventId = 'CHANGED'

def change(self):

if self._get_event_mode(self.C_EVENT_CHANGED) == EventMode.OFF:
return

self._raise_event(
p_event_id=self.C_EVENT_CHANGED,
p_event_object=Event(p_raising_object=self),
)

``_raise_event()`` deliberately does not evaluate the event configuration. At that point the event
object already exists. Its task is only to look up the registered handlers and dispatch the event.

The dispatcher is intentionally lightweight and silent. Event handling itself does not perform
routine logging.

Higher-level event modes
------------------------

Higher MLPro layers may extend the event-mode semantics without changing the generic event
infrastructure. In :ref:`Layer 4 - Machine Learning <target_bf_ml>`, for example,
``EventModeML`` adds the mode ``ADAPTATION``. This allows a concrete ML implementation to
distinguish between a normal event and an event that shall additionally count as a model adaptation.

The interpretation of such higher-level modes remains the responsibility of the concrete
implementation. ``EventManager`` itself only provides the generic event configuration, handler
registration, and event dispatch mechanisms.


**Cross reference**

- :ref:`Howto BF-EH-001: Event handling <Howto BF EH 001>`
- :ref:`BF-MT - Multitasking <target_bf_mt>`
- :ref:`Layer 4 - Machine Learning <target_bf_ml>`
- :ref:`API reference BF-EVENTS - Event handling <target_api_bf_event>`

Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ relationships. Successor tasks are informed about the termination of their prede
consistently reused in higher functions through inheritance. Some examples are :ref:`Stream Processing <target_bf_streams_processing>`
and the :ref:`Adaptive Workflows <target_bf_ml_workflows>`.

``Task`` integrates ``EventManager`` and therefore accepts the optional parameter ``p_event_config``. This provides a common configuration channel for event-capable task subclasses. Such subclasses can query ``_get_event_mode()`` before constructing an event object and thereby suppress disabled events without unnecessary object creation. The built-in ``C_EVENT_FINISHED`` event continues to coordinate predecessor/successor execution in workflows.


**Gap under MacOS**

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,21 @@ Why normalization?

Many algorithms become easier to combine and numerically more stable when their input features live on comparable scales. A temperature in degrees, a position in meters, and a probability may all describe the same sample, but their numerical ranges can differ by orders of magnitude.

MLPro treats normalization as a reversible mapping rather than as a one-way preprocessing step. The common abstraction is **Normalizer**, which builds on :class:`Scaler` and therefore supports normalization, denormalization, and renormalization with a consistent parameter model.
MLPro treats normalization as a reversible mapping rather than as a one-way preprocessing step. The abstract **NormalizerAPI** defines the common interface for normalization, denormalization, and renormalization. The base class **Normalizer** implements this interface and extends :class:`Scaler` with a consistent linear parameter model.

**NormalizerAPI** declares three abstract operations:

* ``normalize(p_data, p_dim=None, p_param=None)`` maps data into normalized coordinates,
* ``denormalize(p_data, p_dim=None, p_param=None)`` maps normalized data back to their original coordinates,
* ``renormalize(p_data, p_dim=None, p_param_old=None, p_param_new=None)`` transforms normalized data from one parameter set to another.

The interface is independent of the normalization strategy. Concrete implementations provide the normalization behavior and parameter management. The optional ``p_dim`` argument selects a single dimension; parameter arguments allow explicit parameter sets where supported.

The basic lifecycle is:

``raw data -> determine parameters -> normalize -> parameters change -> renormalize``

All normalizers use linear parameters per dimension. Internally, each dimension has a scale factor and an offset. This common representation enables the same operations for different normalization strategies:
The supplied MLPro normalizers use linear parameters per dimension. Internally, each dimension has a scale factor and an offset. This common representation enables the same operations for different normalization strategies:

* ``normalize()`` maps original data into normalized coordinates,
* ``denormalize()`` reconstructs data in the original coordinates,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ The instance dictionary carried through a workflow does not only contain data ob

A StreamWorkflow builds on MLPro's multitasking layer. Independent branches can therefore be executed according to their predecessor dependencies and configured range of asynchronicity, while the shared object provides task-specific results and instance sets.

``StreamTask`` also inherits MLPro's event-management infrastructure and forwards the optional ``p_event_config`` parameter to its underlying ``Task``. Stream-processing implementations can therefore expose their own configurable events without introducing a separate callback mechanism. As elsewhere in MLPro, the event mode should be queried before creating the corresponding event object.

The detailed page shows how to implement own StreamTasks, connect them to workflows, and orchestrate them with StreamScenario.


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ A custom task usually only needs to specialize ``_run()``:

``StreamTask.run()`` handles integration with the shared workflow state. If ``p_duplicate_data=True`` is configured, the incoming instances are copied before processing; otherwise a task works on the objects forwarded by its predecessors.

**Event configuration.** ``StreamTask`` inherits ``EventManager`` through ``Task`` and accepts an optional ``p_event_config``. A concrete stream task can therefore define implementation-specific events using an ``EventConfig`` child class. The task should call ``_get_event_mode()`` before constructing an ``Event`` object. This is especially useful for stream events that may occur once per instance, because disabled events can then be skipped without object-creation overhead.

**Shared processing state.** After a task has run, its resulting instance dictionary is stored in the workflow's **StreamShared** object under the task id. A dependent task retrieves the instance sets of its predecessor tasks from this shared object. This gives every task a well-defined input while still allowing the workflow to coordinate parallel branches.

Stream workflows
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,17 @@ Core capabilities
distinguishes regular forward adaptation from event-triggered adaptation. Other ML objects can register handlers and react
to these events, enabling adaptation chains between cooperating models.

**Configurable model events**
``Model`` accepts the optional ``p_event_config`` parameter inherited from ``EventManager``. Concrete model implementations
can define their own ``EventConfig`` child classes and use ``EventModeML`` for the individual switches. ``EventModeML``
extends the generic modes ``OFF`` and ``EVENT`` by ``ADAPTATION``. The latter expresses that the concrete event shall be
emitted and shall additionally count as a model adaptation. The concrete model is responsible for evaluating this mode and
integrating it into its adaptation logic; the generic ``EventManager`` does not interpret ML-specific modes.

As in the generic event layer, event ids and their matching configuration attributes are written in upper case and are
expected to be identical. The mode should be queried before an ``Event`` object is created, so that disabled high-frequency
events do not cause avoidable runtime overhead.

**Execution and multitasking**
Because ``Model`` is a ``Task``, a model can execute synchronously or within MLPro's asynchronous task infrastructure. Range,
autorun, shared-object, and visualization concepts therefore apply to ML models as they do to other BF tasks.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,10 @@ may change the observed data range, an adaptive normalizer can react to the new
renormalize buffered state. Adaptation therefore becomes a property of the complete processing chain rather than an isolated
method call inside one algorithm.

``OAStreamTask`` also receives the optional ``p_event_config`` parameter through its ``Model`` and ``StreamTask`` parents. Concrete online-adaptive algorithms can therefore expose implementation-specific events and configure them with ``EventModeML``. The modes ``OFF`` and ``EVENT`` control event emission, while ``ADAPTATION`` allows an implementation to treat a specific event additionally as a model adaptation. MLPro deliberately leaves the interpretation of this third mode to the concrete algorithm.

For efficient online processing, an implementation should query the configured mode before creating the event object. This makes it practical to offer even high-frequency events, such as per-instance state transitions, without imposing the same overhead when the event is disabled.

OA workflows are intentionally hybrid. A workflow may contain adaptive OA tasks and ordinary BF stream tasks side by side. This
is useful because not every processing step needs to learn. Rearranging dimensions, buffering a window, deriving features, or
other deterministic processing can remain in BF-Streams while only selected stages adapt online.
Expand Down
Loading
Loading