core.dispatcher

Central operation dispatcher for AxisFuzzy.

This module provides a central, intelligent dispatcher for all mathematical and logical operations involving AxisFuzzy data types. It acts as the primary routing mechanism that enables seamless interaction between Fuzznum, Fuzzarray, and standard Python/NumPy types.

Overview

The dispatcher is the core component that powers Python’s operator overloading (e.g., +, *, >) for fuzzy objects. Its main responsibility is to inspect the types of the operands involved in an operation and route the request to the most efficient implementation path available in the framework.

Dispatch Logic:

  • `Fuzznum` vs `Fuzznum`: Operations are delegated directly to the execute_operation method of the underlying FuzznumStrategy, performing element-wise computation.

  • `Fuzzarray` vs `Fuzzarray`: Operations are dispatched to the Fuzzarray’s execute_vectorized_op method, which leverages the high-performance SoA backend for efficient, vectorized calculations.

  • Mixed `Fuzzarray` and `Fuzznum`: The Fuzznum is automatically broadcast into a Fuzzarray of a compatible shape, and the operation is then handled as a Fuzzarray-Fuzzarray operation.

  • Fuzzy vs Scalar/`ndarray`: Similar to mixed fuzzy types, scalars or NumPy arrays are handled by broadcasting them to operate against the Fuzzarray’s backend, ensuring maximum performance.

  • Reverse Operations: It correctly handles commutative operations where the fuzzy object is the right-hand operand (e.g., 2 * my_fuzznum).

axisfuzzy.core.dispatcher.operate(op_name, operand1, operand2)[source]

Perform a named operation between two operands using intelligent, type-based dispatch.

This function is the single entry point for all binary and unary operations invoked on Fuzznum and Fuzzarray objects. It determines the most efficient execution path by analyzing the types of the operands.

Parameters:

  • op_name (str) – The name of the operation to perform (e.g., ‘add’, ‘mul’, ‘gt’, ‘complement’). This name corresponds to an operation registered in the OperationScheduler.

  • operand1 (object) – The first (left-hand) operand. Supported types include Fuzznum, Fuzzarray, int, float, and numpy.ndarray.

  • operand2 (object or None) – The second (right-hand) operand. Supported types mirror operand1. For pure unary operations like ‘complement’, this should be None.

Returns:

The result of the dispatched operation. The return type is dynamic and depends on the operation and operand types (e.g., Fuzznum, Fuzzarray, bool).

Return type:

Any

Raises:

TypeError – If the combination of operand types is not supported for the given operation.

Notes

  • Lazy Imports: Fuzznum and Fuzzarray are imported inside the function to prevent circular dependencies that can occur during module initialization.

  • Performance: The dispatcher prioritizes vectorized Fuzzarray operations. When an operation involves a Fuzzarray, it will always attempt to use the backend-accelerated path, broadcasting other operands if necessary.

  • Broadcasting: When a Fuzznum operates with a Fuzzarray or ndarray, it is implicitly converted into a Fuzzarray of the correct shape before the operation proceeds.

  • Operation Aliases: For convenience, some common operation names are mapped to their internal strategy equivalents. For example, mul and div with a scalar are mapped to the tim (times) operation.

Examples

from axisfuzzy.core.fuzznums import fuzznum
from axisfuzzy.core.fuzzarray import fuzzarray

# Assume qrofn is the default mtype
a = fuzznum(md=0.5, nmd=0.3)
b = fuzznum(md=0.6, nmd=0.2)
arr1 = fuzzarray([a, b])
arr2 = fuzzarray([b, a])

# Fuzznum + Fuzznum -> returns Fuzznum
result_fn = operate('add', a, b)

# Fuzznum * scalar -> returns Fuzznum
result_fn_scalar = operate('mul', a, 2.0)

# Fuzzarray + Fuzzarray -> returns Fuzzarray
result_arr = operate('add', arr1, arr2)

# Fuzzarray + Fuzznum (broadcasting) -> returns Fuzzarray
result_arr_fn = operate('add', arr1, a)

# scalar + Fuzzarray (reverse operation) -> returns Fuzzarray
# Note: 'mul' is commutative and supported for reverse ops
result_rev_arr = operate('mul', 2.0, arr1)

# Fuzznum complement (unary op) -> returns Fuzznum
result_unary = operate('complement', a, None)