fuzzy_dl_owl2.fuzzydl.feature_function

A class representing mathematical expressions over features that supports arithmetic operations and converts them into linear programming constraints.

Description

Software components representing mathematical expressions over features are defined here, supporting atomic variables, constants, and arithmetic operations such as summation, subtraction, and scalar multiplication. The design utilizes a polymorphic initialization strategy where the specific structure of the expression is determined by the types of arguments provided, allowing the creation of complex hierarchical trees from simple building blocks. This intermediate representation serves as a bridge between high-level feature definitions and low-level optimization constraints. To facilitate integration with optimization solvers, the logic includes functionality to recursively traverse the expression tree and extract all dependent feature names. Furthermore, the core capability involves converting these abstract definitions into concrete linear programming expressions by resolving atomic features to specific variables within the context of a given individual. This transformation relies on external helpers to map relationships between individuals to solver variables, ensuring that the mathematical model accurately reflects the semantic structure of the defined features.

Classes

FeatureFunction

This class encapsulates a mathematical expression defined over features, supporting atomic variables, constants, and arithmetic operations such as summation, subtraction, and scalar multiplication. The specific type of function is determined polymorphically at initialization based on the provided arguments—for instance, passing a string defines an atomic feature, a float defines a constant, and a list of functions defines a sum. It serves as an intermediate representation that can be traversed to extract dependencies or converted into a concrete linear programming expression via the to_expression method, which resolves atomic features to variables based on an individual's relations.

Module Contents

UML Class Diagram for FeatureFunction

class FeatureFunction(feature: Self)

class FeatureFunction(feature: str)

class FeatureFunction(n: float)

class FeatureFunction(feature: list[Self])

class FeatureFunction(feature1: Self, feature2: Self)

class FeatureFunction(n: float, feature: Self)

This class encapsulates a mathematical expression defined over features, supporting atomic variables, constants, and arithmetic operations such as summation, subtraction, and scalar multiplication. The specific type of function is determined polymorphically at initialization based on the provided arguments—for instance, passing a string defines an atomic feature, a float defines a constant, and a list of functions defines a sum. It serves as an intermediate representation that can be traversed to extract dependencies or converted into a concrete linear programming expression via the to_expression method, which resolves atomic features to variables based on an individual’s relations.

Raises:

ValueError – Raised if the arguments passed to the constructor do not match any of the valid signatures for defining a feature function, such as having an incorrect number of arguments or incompatible type combinations.

__feature_function_init_1(feature: str) → None

Initializes the object to represent an atomic feature function identified by the provided string. This configuration sets the instance’s type to ATOMIC, prepares an empty list for potential child functions, assigns the specific feature name, and resets the internal counter to zero. The method directly mutates the instance’s state to establish a base-level feature representation, assuming the input string is a valid identifier.

Parameters:

feature (str) – The name of the atomic feature.

__feature_function_init_2(n: float) → None

Initializes the feature function instance to represent a constant numeric value. It sets the type attribute to NUMBER, assigns the provided float argument to the n attribute, and explicitly clears the list of child functions and the feature name string to ensure a clean state.

Parameters:

n (float) – The numeric value associated with the feature function.

__feature_function_init_3(feature: list[Self]) → None

Configures the instance to represent a summation operation over a provided list of subordinate feature functions. It sets the internal type to SUM and stores the input list within the instance for later aggregation. Additionally, this method resets the feature name identifier and the numeric coefficient to their default states of an empty string and 0.0, respectively, ensuring the composite function is initialized without residual values from other potential configurations.

Parameters:

feature (list[Self]) – A list of feature functions to be summed.

__feature_function_init_4(feature1: Self, feature2: Self) → None

Initializes the instance to represent a subtraction operation between two feature functions. It configures the internal type to SUBTRACTION and stores the provided feature1 and feature2 as the operands for the calculation. As a side effect, this method explicitly clears the feature string attribute and resets the n numeric attribute to zero, ensuring the object state is consistent with a binary operation rather than a leaf node.

Parameters:

• feature1 (Self) – The first operand in the subtraction operation, representing the value from which the second operand is subtracted.

• feature2 (Self) – The feature to subtract from the first feature.

__feature_function_init_5(n: float, feature: Self) → None

Initializes the instance to represent a product feature function defined by a scalar coefficient and a nested feature. It sets the function type to PRODUCT, assigns the scalar value n, and stores the provided feature object in a list of sub-features. This operation overwrites existing attributes, specifically resetting the string-based feature identifier to an empty string.

Parameters:

• n (float) – The numeric coefficient or scalar value associated with the feature function.

• feature (Self) – The feature function instance to be used as a factor in the product operation.

__feature_function_init_6(feature: Self) → None

Copies the core attributes from an existing FeatureFunction instance to the current object. Specifically, it assigns the type, f, feature, and n attributes from the provided feature argument to self. This method performs a shallow copy, meaning mutable attributes like the list f will be shared between the two instances rather than deep-copied.

Parameters:

feature (Self) – An existing instance of the same class from which to copy attributes to initialize the current instance.

__repr__() → str

Returns the official string representation of the object by delegating to the __str__ method. This ensures that the output is identical to the informal string representation, providing a consistent textual format for debugging and logging. The specific content of the returned string depends entirely on the implementation of the string conversion logic within the class.

Returns:

Returns the string representation of the object, identical to the output of str().

Return type:

str

__str__() → str

Returns a human-readable string representation of the feature function, formatted according to its specific type. For atomic features, it returns the feature name, while numeric types return the string value of the number. Composite operations are represented as mathematical expressions: products display a scalar multiplied by a sub-feature, subtractions show the difference between two sub-features, and sums join multiple sub-features with plus signs. If the feature function type does not match any known category, an empty string is returned.

Returns:

A string representation of the feature function, formatted as a mathematical expression or feature name based on its type.

Return type:

str

get_features() → set[str]

Recursively collects and returns a set of feature names that are utilized within the feature function’s definition. The method handles different function types by traversing the internal structure: it returns the direct feature name for atomic types, aggregates features from all sub-functions for sums, combines features from the first two sub-functions for subtractions, and extracts features only from the first sub-function for products. This operation is read-only and does not alter the state of the object.

Returns:

A set containing the unique names of all features involved in the function.

Return type:

set[str]

get_number() → float

Retrieves the numeric value stored within the instance. This method acts as a getter for the internal attribute n, returning its current value as a float. The operation is read-only and does not modify the state of the object or any external entities.

Returns:

The floating-point number associated with the instance.

Return type:

float

get_type() → fuzzy_dl_owl2.fuzzydl.util.constants.FeatureFunctionType

Retrieves the type classification of the feature function instance. This method returns the value stored in the internal type attribute, which typically defines the category or operational nature of the feature function within the broader system. As a simple accessor, this method performs no modifications to the object’s state and has no side effects.

Returns:

The type of the feature function.

Return type:

FeatureFunctionType

to_expression(

a: fuzzy_dl_owl2.fuzzydl.individual.individual.Individual,

milp: fuzzy_dl_owl2.fuzzydl.milp.milp_helper.MILPHelper,

) → fuzzy_dl_owl2.fuzzydl.milp.expression.Expression | None

Converts the abstract definition of the feature function into a concrete mathematical expression suitable for a MILP solver, evaluated in the context of a specific individual a. Depending on the function’s type, this involves retrieving the solver variable associated with a related individual for atomic features, generating constant terms for numbers, or recursively combining the expressions of child functions using arithmetic operations such as summation, subtraction, or scalar multiplication. The method relies on the provided MILPHelper to resolve individuals to variables and includes assertions to ensure the structural integrity of the function definition, such as the presence of required relations or a valid number of sub-functions. It returns the resulting Expression object, or None if the function type is unrecognized.

Parameters:

• a (Individual) – The individual entity serving as the context for resolving feature relations and constructing the expression.

• milp (MILPHelper) – Helper object used to look up variables associated with individuals in the MILP model.

Returns:

Returns an Expression object representing the mathematical formulation of the feature function for the given individual, or None if the function type is unsupported.

Return type:

Optional[Expression]