Logical Predicates¶

class jlnn.nn.predicates.FixedPredicate(*args: Any, **kwargs: Any)[source]¶

Bases: Module

Stateless non-trainable identity predicate that preserves input truth intervals.

This module acts as a rigid, static pass-through transformation layer for pre-computed truth intervals. It is primarily applied in hybrid neuro-symbolic systems, crisp Boolean boundary injections, or deterministic logic anchoring pipelines where structural parameters must remain completely shielded from gradient descent variations.

None¶

__call__(x: Array) → Array[source]¶

Routes the truth interval tensor forward without altering internal value matrices.

Parameters:: x (jnp.ndarray) – Presettled input truth interval tensor structured as (…, 2) representing explicit [Lower, Upper] bounds.
Returns:: The identical, unaltered truth interval tensor structured as (…, 2).
Return type:: jnp.ndarray

__init__()[source]¶: Initializes the stateless FixedPredicate structural identity layer.

class jlnn.nn.predicates.LearnedPredicate(*args: Any, **kwargs: Any)[source]¶

Bases: Module

Stateful parametric grounding layer that transforms real-valued input data into bounded truth intervals [L, U].

In Logical Neural Networks (LNN), predicates function as the foundational semantic interface mapping raw empirical data streams into strict logical propositions. This class models parametric grounding profiles by independently optimizing the slopes and offsets of monotonic activation functions, thereby refining fuzzy boundaries via backpropagation while preserving structural valid intervals.

slope_l¶

Trainable sensitivity vector scaling the lower truth bound activation.

Type:: nnx.Param

offset_l¶

Trainable horizontal threshold vector shifting the lower truth bound.

Type:: nnx.Param

slope_u¶

Trainable sensitivity vector scaling the upper truth bound activation.

Type:: nnx.Param

offset_u¶

Trainable horizontal threshold vector shifting the upper truth bound.

Type:: nnx.Param

__call__(x: Array) → Array[source]¶

Maps standard numerical arrays into multi-dimensional fuzzy truth intervals.

Parameters:

x (jnp.ndarray) – Numerical observation tensor structured as (…, in_features).

Returns:

Evaluated truth interval tensor structured as (…, in_features, 2),: where the trailing dimension defines the [Lower, Upper] truth limits.

Return type:

jnp.ndarray

__init__(in_features: int, rngs: Rngs)[source]¶

Initializes trainable slope and offset tracking parameters for each feature sub-space.

Parameters:

in_features (int) – Total dimensionality of the incoming numerical feature vector.
rngs (nnx.Rngs) – Flax NNX random number generator collection for parameter states.

class jlnn.nn.predicates.PhysicalPredicate(*args: Any, **kwargs: Any)[source]¶

Bases: Module

Stateful non-Euclidean grounding layer utilizing Space-Curved Physical Fuzzy Logic (PFL).

Transforms real-valued external arrays into coherent logical truth intervals [L, U] by routing numerical potentials through an artificial gravitational space deformation field. Under this paradigm, highly unstable or contradictory information matrices are naturally drawn towards the entropic singularity core (0.5), while highly deterministic inputs converge safely into saturated axiomatic boundaries.

gamma¶

Coupling constant governing the intensity of the gravitational restoring force pulling states towards absolute maximum entropy (0.5).

Type:: float

mode¶

Baseline structural activation compression kernel (‘sigmoid’ or ‘ramp’).

Type:: str

slope_l¶

Trainable directional landscape steepness for lower bound potential.

Type:: nnx.Param

offset_l¶

Trainable landscape origin shift for lower bound potential.

Type:: nnx.Param

slope_u¶

Trainable directional landscape steepness for upper bound potential.

Type:: nnx.Param

offset_u¶

Trainable landscape origin shift for upper bound potential.

Type:: nnx.Param

__call__(x: Array) → Array[source]¶

Maps numeric input arrays to curved physical truth intervals via gravitational warping.

Parameters:: x (jnp.ndarray) – Numerical observation tensor structured as (…, in_features).
Returns:: Consistency-verified physical truth interval tensor shaped as (…, in_features, 2).
Return type:: jnp.ndarray

__init__(in_features: int, rngs: Rngs, gamma: float = 0.2, mode: str = 'sigmoid')[source]¶

Initializes trainable metric mapping landscapes alongside space curvature fields.

Parameters:

in_features (int) – Total dimensionality of the incoming numerical feature vector.
rngs (nnx.Rngs) – Flax NNX random number generator collection.
gamma (float, optional) – Space bending elasticity coefficient. Defaults to 0.2.
mode (str, optional) – Underlying kernel geometry selector. Defaults to ‘sigmoid’.

This module implements the so-called Grounding Layers, which form a semantic interface between the real empirical world (continuous numerical data) and the world of interval fuzzy logic. The task of the predicates is to transform raw features into valid truth intervals \([L, U]\), where \(0.0 \le L \le U \le 1.0\).

All predicates inherit from the flax.nnx.Module base class and are fully compatible with JAX transformations and automatic derivation.

1. Trainable parametric predicate (LearnedPredicate)¶

This predicate independently models and optimizes the lower and upper truth limits for each input feature. Using gradient descent, the network automatically discovers the ideal decision boundaries.

Architecture: Encapsulates four independent learning parameter vectors nnx.Param: slope_l, offset_l (for the lower bound) and slope_u, offset_u (for the upper bound).
Activation mechanism: Uses the ramp_sigmoid function to transform potentials into truth values.
Axiomatic fuse: The resulting tensors are normalized before wrapping using intervals.ensure_interval, which guarantees that the lower bound never exceeds the upper bound, even if the gradients behave chaotically during learning.

\[ \begin{align}\begin{aligned}L = \text{ramp\_sigmoid}(x \cdot \text{slope}_l - \text{offset}_l)\\U = \text{ramp\_sigmoid}(x \cdot \text{slope}_u - \text{offset}_u)\end{aligned}\end{align} \]

2. Space-time curved physical predicate (PhysicalPredicate)¶

An advanced grounding layer that does not use traditional linear displacements but maps real data through a physical fuzzy logic (PFL) topology.

Semantics: Evaluates inputs as physical potentials and decomposes them into a curved space where the mean value \(0.5\) represents maximum entropy (uncertainty singularity).
Configuration:
- gamma: Coefficient of the gravitational field intensity of the center of uncertainty.
- mode: Field compression selection – sigmoid (continuous field) or ramp (clipped field).
Stabilization: Excellent at suppressing outliers and anomalies in data by pulling unstable states towards the center of uncertainty proportional to the local Shannon entropy.

3. Static Identity (FixedPredicate)¶

A stateless and completely untrainable predicate that serves as a rigid data channel.

Function: Takes a ready-made truth interval as input and returns it unchanged to the network (Identity Mapping).
Usage: Used for direct injection of pure Boolean facts, expert constants, or deterministic logical anchors into the knowledge graph, which are strictly required to remain completely immune to changes caused by gradient backpropagation.