mixin.factory

Implementation factory for AxisFuzzy mixin system structural operations.

This module provides the core implementation functions for mtype-agnostic structural and container operations on Fuzznum and Fuzzarray objects. These functions work directly with the SoA (Struct-of-Arrays) backend architecture to provide efficient NumPy-like functionality across all fuzzy number types.

Architecture

The factory follows a direct implementation approach where each function:

  1. Input Validation: Checks input types and converts Fuzznum to Fuzzarray when necessary for consistent processing.

  2. Backend Interaction: Extracts component arrays from the SoA backend, performs NumPy operations on each component, then reconstructs the backend.

  3. Result Construction: Creates new Fuzzarray instances with the modified backend, preserving mtype and fuzzy-specific metadata.

  4. Type Consistency: Maintains proper return types (Fuzznum vs Fuzzarray) based on the mathematical properties of each operation.

Core Implementation Functions

This module implements the following categories of structural operations:

Shape Manipulation Functions:

  • _reshape_factory: Changes array shape without modifying data, supports automatic dimension inference (-1)

  • _flatten_factory: Collapses multi-dimensional arrays into 1D while preserving element order

  • _squeeze_factory: Removes dimensions of size 1, with optional axis specification

  • _ravel_factory: Returns contiguous flattened view (currently implemented as copy, future optimization possible)

Transformation Functions:

  • _transpose_factory: Permutes array dimensions according to specified axes order, supports back-reference optimization

  • _broadcast_to_factory: Broadcasts arrays to specified shapes following NumPy broadcasting rules

Data Access Functions:

  • _copy_factory: Creates deep independent copies of fuzzy objects with full data duplication

  • _item_factory: Extracts scalar Fuzznum elements from arrays, supports multi-dimensional indexing

Container Operations:

  • _concat_factory: Joins multiple arrays along existing axes with shape and type compatibility checking

  • _stack_factory: Combines arrays along new axes with strict shape matching requirements

  • _append_factory: Flexible append operation supporting various input types and in-place modification

  • _pop_factory: Removes and returns elements from 1D arrays with optional in-place operation

Boolean Testing Functions:

  • _any_factory: Tests if arrays contain any elements (always True for non-empty valid fuzzy arrays)

  • _all_factory: Tests if all elements are truthy (always True for valid fuzzy arrays)

Future Implementation Placeholders:

  • _sort_factory: Sorting operations (not yet implemented)

  • _argsort_factory: Argument sorting (not yet implemented)

  • _argmax_factory: Argument maximum (not yet implemented)

  • _argmix_factory: Argument minimum (not yet implemented)

Backend Integration

All functions work with the SoA backend architecture:

  1. Component Extraction: Uses backend.get_component_arrays() to access individual fuzzy number components (e.g., membership, non-membership values).

  2. Parallel Processing: Applies the same NumPy operation to all components simultaneously, maintaining data alignment and type consistency.

  3. Backend Reconstruction: Uses backend_cls.from_arrays() to create new backends from modified components, preserving mtype-specific parameters.

  4. Metadata Preservation: Maintains q-values, mtype information, and other fuzzy-specific metadata through the transformation process.

Error Handling

Functions provide comprehensive error handling for:

  • Type Validation: Ensures inputs are valid Fuzznum or Fuzzarray objects

  • Shape Compatibility: Validates shapes for operations like concatenation, broadcasting, and stacking

  • Index Bounds: Checks array bounds for element access and removal operations

  • Mathematical Constraints: Enforces fuzzy number constraints and backend limitations

  • Empty Array Handling: Special cases for zero-size arrays and edge conditions

Performance Considerations

The factory functions are optimized for:

  • Vectorized Operations: Leverages NumPy’s optimized C implementations through component arrays

  • Memory Efficiency: Minimizes object creation and copying where possible

  • Backend Reuse: Reuses backend classes and metadata to avoid unnecessary allocations

  • Lazy Evaluation: Some operations (like transpose) include optimizations for repeated use

Type Safety

Functions maintain strict type consistency:

  • Input Promotion: Fuzznum inputs are promoted to single-element Fuzzarray when needed

  • Return Type Logic: Operations that may result in scalars return Fuzznum, others return Fuzzarray

  • Metadata Consistency: All type-specific metadata (mtype, q-values) is preserved through operations

  • Backend Compatibility: Ensures all operations preserve backend-specific constraints and properties

Notes

  • Functions are designed to be called from registration wrappers in axisfuzzy.mixin.register

  • All operations preserve the original object when creating copies or views

  • Backend-specific optimizations may be added in future versions without changing the API

  • Thread safety depends on the underlying NumPy operations and backend implementations

See also

axisfuzzy.mixin.register

Registration layer that exposes these functions as methods

axisfuzzy.mixin.registry

Infrastructure for dynamic injection and registration

axisfuzzy.core.backend

SoA backend architecture used by all operations

axisfuzzy.core.fuzzarray

Primary data structure for array operations

axisfuzzy.core.fuzznums

Scalar fuzzy number data structure

Examples

Factory functions are typically not called directly, but through registered methods:

from axisfuzzy.mixin.factory import _reshape_factory
from axisfuzzy.core import fuzzarray, fuzznum

# Direct factory call (not typical usage)
a = fuzznum((0.6, 0.3), mtype='qrofn')
arr = fuzzarray([a, a, a, a])
reshaped = _reshape_factory(arr, 2, 2)

# Normal usage through registered methods
reshaped = arr.reshape(2, 2)  # Calls _reshape_factory internally

Backend Compatibility

All factory functions work with any backend that implements:

  • get_component_arrays(): Returns list of NumPy arrays for each fuzzy component

  • from_arrays(cls, *arrays, q, **kwargs): Class method to reconstruct from component arrays

  • Proper mtype and parameter preservation through the reconstruction process

References

  • NumPy documentation for array manipulation functions

  • AxisFuzzy backend architecture documentation

  • SoA (Struct-of-Arrays) design patterns for high-performance computing