ltntorch 0.1.0

data/sig/ltn.rbs

@@ -0,0 +1,207 @@
+module LTN
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  # The device on which LTN places the groundings of its variables.
+  def self.device: () -> untyped
+  def self.device=: (untyped device) -> untyped
+
+  # A grounding together with the labels of its free variables.
+  class LTNObject
+    attr_accessor value: untyped
+    attr_accessor free_vars: Array[String]
+
+    def initialize: (untyped value, Array[String] var_labels) -> void
+    def shape: () -> Array[Integer]
+  end
+
+  module FuzzyOps
+    EPS: Float
+
+    def self.pi_0: (untyped x) -> untyped
+    def self.pi_1: (untyped x) -> untyped
+    def self.check_values: (*untyped values) -> void
+    def self.check_mask: (untyped mask, untyped xs) -> void
+    def self.reduction_dims: (Integer | Array[Integer] | nil dim) -> Array[Integer]
+    def self.where: (untyped condition, untyped input, untyped other) -> untyped
+
+    module Stable
+      attr_accessor stable: bool
+      def initialize: (?stable: bool) -> void
+    end
+
+    class ConnectiveOperator
+      def call: (*untyped args, **untyped kwargs) -> untyped
+    end
+
+    class UnaryConnectiveOperator < ConnectiveOperator
+    end
+
+    class BinaryConnectiveOperator < ConnectiveOperator
+    end
+
+    class NotStandard < UnaryConnectiveOperator
+      def call: (untyped x) -> untyped
+    end
+
+    class NotGodel < UnaryConnectiveOperator
+      def call: (untyped x) -> untyped
+    end
+
+    class AndMin < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class AndProd < BinaryConnectiveOperator
+      include Stable
+      def call: (untyped x, untyped y, ?stable: bool?) -> untyped
+    end
+
+    class AndLuk < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class OrMax < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class OrProbSum < BinaryConnectiveOperator
+      include Stable
+      def call: (untyped x, untyped y, ?stable: bool?) -> untyped
+    end
+
+    class OrLuk < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class ImpliesKleeneDienes < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class ImpliesGodel < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class ImpliesReichenbach < BinaryConnectiveOperator
+      include Stable
+      def call: (untyped x, untyped y, ?stable: bool?) -> untyped
+    end
+
+    class ImpliesGoguen < BinaryConnectiveOperator
+      include Stable
+      def call: (untyped x, untyped y, ?stable: bool?) -> untyped
+    end
+
+    class ImpliesLuk < BinaryConnectiveOperator
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    class Equiv < BinaryConnectiveOperator
+      attr_reader and_op: BinaryConnectiveOperator
+      attr_reader implies_op: BinaryConnectiveOperator
+
+      def initialize: (BinaryConnectiveOperator and_op, BinaryConnectiveOperator implies_op) -> void
+      def call: (untyped x, untyped y) -> untyped
+    end
+
+    type dim = Integer | Array[Integer] | nil
+
+    class AggregationOperator
+      def call: (*untyped args, **untyped kwargs) -> untyped
+    end
+
+    module PMeanParameters
+      attr_accessor p: Numeric
+      attr_accessor stable: bool
+      def initialize: (?p: Numeric, ?stable: bool) -> void
+    end
+
+    class AggregMin < AggregationOperator
+      def call: (untyped xs, ?dim: dim, ?keepdim: bool, ?mask: untyped) -> untyped
+    end
+
+    class AggregMean < AggregationOperator
+      def call: (untyped xs, ?dim: dim, ?keepdim: bool, ?mask: untyped) -> untyped
+    end
+
+    class AggregPMean < AggregationOperator
+      include PMeanParameters
+      def call: (untyped xs, ?dim: dim, ?keepdim: bool, ?mask: untyped, ?p: Numeric?, ?stable: bool?) -> untyped
+    end
+
+    class AggregPMeanError < AggregationOperator
+      include PMeanParameters
+      def call: (untyped xs, ?dim: dim, ?keepdim: bool, ?mask: untyped, ?p: Numeric?, ?stable: bool?) -> untyped
+    end
+
+    class SatAgg
+      attr_reader agg_op: AggregationOperator
+
+      def initialize: (?AggregationOperator agg_op) -> void
+      def call: (*untyped closed_formulas) -> untyped
+    end
+  end
+
+  class Constant < LTNObject
+    def initialize: (untyped value, ?trainable: bool) -> void
+  end
+
+  class Variable < LTNObject
+    attr_reader latent_var: String
+
+    def initialize: (String var_label, untyped individuals, ?add_batch_dim: bool) -> void
+  end
+
+  def self.process_ltn_objects: (Array[LTNObject] objects) -> [Array[LTNObject], Array[String], Array[Integer]]
+  def self.diag: (*Variable vars) -> Array[Variable]
+  def self.undiag: (*Variable vars) -> Array[Variable]
+
+  class LambdaModel
+    attr_reader func: untyped
+
+    def initialize: (untyped func) -> void
+    def forward: (*untyped inputs, **untyped kwargs) -> untyped
+  end
+
+  module ModelWrapper
+    attr_reader model: untyped
+
+    def initialize: (?untyped model, ?func: untyped) ?{ (*untyped) -> untyped } -> void
+  end
+
+  class Predicate
+    include ModelWrapper
+
+    def forward: (*LTNObject inputs, **untyped kwargs) -> LTNObject
+    def call: (*LTNObject inputs, **untyped kwargs) -> LTNObject
+  end
+
+  class Function
+    include ModelWrapper
+
+    def forward: (*LTNObject inputs, **untyped kwargs) -> LTNObject
+    def call: (*LTNObject inputs, **untyped kwargs) -> LTNObject
+  end
+
+  class Connective
+    attr_reader connective_op: FuzzyOps::ConnectiveOperator
+
+    def initialize: (FuzzyOps::ConnectiveOperator connective_op) -> void
+    def call: (*LTNObject operands, **untyped kwargs) -> LTNObject
+  end
+
+  class Quantifier
+    QUANTIFIERS: Hash[Symbol | String, Symbol]
+
+    attr_reader agg_op: FuzzyOps::AggregationOperator
+    attr_reader quantifier: Symbol
+
+    def initialize: (FuzzyOps::AggregationOperator agg_op, Symbol | String quantifier) -> void
+    def call: (Variable | Array[Variable] vars, LTNObject formula, ?cond_vars: (Variable | Array[Variable])?,
+               ?cond_fn: untyped, **untyped kwargs) ?{ (*LTNObject) -> untyped } -> LTNObject
+    def self.compute_mask: (LTNObject formula, Array[Variable] cond_vars, untyped cond_fn, Array[String] aggregation_vars) -> [LTNObject, LTNObject]
+    def self.transpose_vars: (LTNObject object, Array[String] new_vars_order) -> LTNObject
+  end
+end

data/tutorials/1_grounding_non_logical_symbols.rb

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch's tutorials/1-grounding_non_logical_symbols.ipynb, copyright 2021-2024 by
+# Tommaso Carraro; see the notebook for the full discussion.
+#
+# Tutorial 1: grounding the non-logical symbols (constants, predicates,
+# functions, variables).
+#
+#   bundle exec ruby tutorials/1_grounding_non_logical_symbols.rb
+#
+# In LTN's Real Logic, a *grounding* maps every term of a first-order
+# language to a tensor of real numbers, and every formula to a truth value in
+# [0, 1]. This tutorial covers the signature: constants, predicates,
+# functions and variables. Tutorial 2 covers connectives and quantifiers.
+
+require "ltn"
+
+Torch.manual_seed(2020)
+
+def show(label, value)
+  puts "#{label.ljust(24)} #{value.inspect}"
+end
+
+puts "== Constants"
+# A constant is an individual of the domain, grounded as a tensor of any
+# rank: here a vector of R^2 and a 2x3 matrix.
+c1 = LTN::Constant.new(Torch.tensor([2.1, 3.0]))
+c2 = LTN::Constant.new(Torch.tensor([[4.2, 3.0, 2.5], [4.0, -1.3, 1.8]]))
+# A trainable constant is an embedding: its tensor requires grad, and is
+# learned with the rest of the knowledge base (see example 7).
+c3 = LTN::Constant.new(Torch.tensor([0.0, 0.0]), trainable: true)
+show("c1.value", c1.value)
+show("c2.shape", c2.shape)
+show("c3.value", c3.value)
+# Constants are LTNObjects: a value, and the labels of the free variables
+# appearing in it (none, for a constant).
+show("c1.free_vars", c1.free_vars)
+
+puts "\n== Predicates"
+# A predicate maps individuals to truth values in [0, 1]. It is grounded
+# either by a function (or block), for fixed predicates without trainable
+# weights, or by a Torch::NN::Module, for learnable ones.
+mu = LTN::Constant.new(Torch.tensor([2.0, 3.0]))
+p1 = LTN::Predicate.new { |x| Torch.exp(Torch.neg(Torch.norm(x - mu.value, 2, dim: 1))) }
+
+class ModelP2 < Torch::NN::Module
+  def initialize
+    super
+    @elu = Torch::NN::ELU.new
+    @sigmoid = Torch::NN::Sigmoid.new
+    @dense1 = Torch::NN::Linear.new(2, 5)
+    @dense2 = Torch::NN::Linear.new(5, 1) # one value in [0, 1]
+  end
+
+  def forward(x)
+    @sigmoid.call(@dense2.call(@elu.call(@dense1.call(x))))
+  end
+end
+p2 = LTN::Predicate.new(ModelP2.new)
+
+# Predicates take LTN objects, and return an LTNObject whose value holds the
+# truth values.
+show("P1(c1)", p1.call(c1).value)
+show("P1(LTN::Constant [4.5, 0.8])", p1.call(LTN::Constant.new(Torch.tensor([4.5, 0.8]))).value)
+show("P2(LTN::Constant [3, 4.8])", p2.call(LTN::Constant.new(Torch.tensor([3.0, 4.8]))).value)
+show("P1(c1) as an LTNObject", p1.call(c1))
+
+# LTN adds a batch dimension in front of the inputs it gives to the model, so
+# models work on dim 1, the features. A binary predicate gets two tensors.
+class ModelP4 < Torch::NN::Module
+  def initialize
+    super
+    @elu = Torch::NN::ELU.new
+    @sigmoid = Torch::NN::Sigmoid.new
+    @dense1 = Torch::NN::Linear.new(4, 5)
+    @dense2 = Torch::NN::Linear.new(5, 1)
+  end
+
+  def forward(x, y)
+    x = Torch.cat([x, y], dim: 1)
+    @sigmoid.call(@dense2.call(@elu.call(@dense1.call(x))))
+  end
+end
+p4 = LTN::Predicate.new(ModelP4.new)
+c4 = LTN::Constant.new(Torch.tensor([4.5, 0.8]))
+show("P4(c1, c4)", p4.call(c1, c4).value)
+
+puts "\n== Functions"
+# A function maps individuals to an individual (a tensor of any shape), and
+# is grounded like a predicate: by a function or by a module.
+f1 = LTN::Function.new { |x, y| x - y }
+
+class MyModel < Torch::NN::Module
+  def initialize
+    super
+    @dense1 = Torch::NN::Linear.new(2, 10)
+    @dense2 = Torch::NN::Linear.new(10, 5)
+    @relu = Torch::NN::ReLU.new
+  end
+
+  def forward(x)
+    @dense2.call(@relu.call(@dense1.call(x)))
+  end
+end
+f2 = LTN::Function.new(MyModel.new)
+show("f1(c1, c4)", f1.call(c1, c4).value)
+show("f2(c1)", f2.call(c1).value)
+
+puts "\n== Variables"
+# A variable is a labeled sequence of individuals (not a set: an individual
+# may occur twice). Its free_vars are its label.
+x = LTN::Variable.new("x", Torch.randn(10, 2))
+y = LTN::Variable.new("y", Torch.randn(5, 2))
+show("x.free_vars", x.free_vars)
+
+# Evaluating a symbol on variables evaluates it on every combination of
+# their individuals: one axis per variable, in the order in which they
+# appear, and free_vars tells which axis is which.
+res1 = p4.call(x, y)
+show("P4(x, y).shape", res1.shape)
+show("P4(x, y).free_vars", res1.free_vars)
+show("P4(x_3, y_1)", res1.value[2, 0])
+
+# A function's outputs keep their own dimensions after the variables' axes:
+# f1 maps to R^2, so f1(x, y) is 10 x 5 x 2.
+res2 = f1.call(x, y)
+show("f1(x, y).shape", res2.shape)
+show("f1(x, y).free_vars", res2.free_vars)
+
+# Constants add no axis.
+res3 = p4.call(c1, y)
+show("P4(c1, y).shape", res3.shape)
+show("P4(c1, y).free_vars", res3.free_vars)
+
+puts "\n== Variables made of trainable constants"
+# A variable can be built from the values of trainable constants, so that
+# gradients flow back to them through any formula using the variable.
+c1 = LTN::Constant.new(Torch.tensor([2.1, 3.0]), trainable: true)
+c2 = LTN::Constant.new(Torch.tensor([4.5, 0.8]), trainable: true)
+x = LTN::Variable.new("x", Torch.stack([c1.value, c2.value]))
+p2.call(x).value.sum.backward
+show("gradient of c1", c1.value.grad)
+show("gradient of c2", c2.value.grad)

data/tutorials/2_grounding_connectives.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch's tutorials/2-grounding_connectives.ipynb, copyright 2021-2024 by Tommaso Carraro;
+# see the notebook for the full discussion.
+#
+# Tutorial 2: grounding connectives and quantifiers, including diagonal and
+# guarded quantification.
+#
+#   bundle exec ruby tutorials/2_grounding_connectives.rb
+
+require "ltn"
+
+Torch.manual_seed(2020)
+
+def show(label, value)
+  puts "#{label.ljust(36)} #{value.inspect}"
+end
+
+puts "== Connectives"
+# Connectives are grounded with fuzzy semantics (LTN::FuzzyOps). The
+# recommended ones are the standard negation 1 - u, the product t-norm u v,
+# the probabilistic sum u + v - u v, and the Reichenbach implication
+# 1 - u + u v (see tutorial 2b for why).
+not_ = LTN::Connective.new(LTN::FuzzyOps::NotStandard.new)
+and_ = LTN::Connective.new(LTN::FuzzyOps::AndProd.new)
+or_ = LTN::Connective.new(LTN::FuzzyOps::OrProbSum.new)
+implies = LTN::Connective.new(LTN::FuzzyOps::ImpliesReichenbach.new)
+
+x = LTN::Variable.new("x", Torch.randn(10, 2))
+y = LTN::Variable.new("y", Torch.randn(5, 2))
+c1 = LTN::Constant.new(Torch.tensor([0.5, 0.0]))
+c2 = LTN::Constant.new(Torch.tensor([4.0, 2.0]))
+# A predicate measuring the similarity of two points.
+eq = LTN::Predicate.new { |a, b| Torch.exp(Torch.neg(Torch.norm(a - b, 2, dim: 1))) }
+
+show("Eq(c1, c2)", eq.call(c1, c2).value)
+show("not Eq(c1, c2)", not_.call(eq.call(c1, c2)).value)
+show("Eq(c1, c2) -> Eq(c2, c1)", implies.call(eq.call(c1, c2), eq.call(c2, c1)).value)
+# LTN::Connective broadcasts its operands: a formula has one axis per
+# variable appearing in any of its sub-formulas.
+show("(Eq(x, c1) and Eq(x, c2)).shape", and_.call(eq.call(x, c1), eq.call(x, c2)).shape)
+show("(Eq(x, c1) or Eq(x, y)).shape", or_.call(eq.call(x, c1), eq.call(x, y)).shape)
+
+puts "\n== Quantifiers"
+# Quantifiers are grounded by aggregation operators. The recommended ones
+# are the generalized mean pMean for exists, a soft maximum, and the
+# generalized mean of the errors pMeanError for forall, a soft minimum.
+forall = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMeanError.new(p: 2), :forall)
+exists = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMean.new(p: 2), :exists)
+
+# Quantifying a variable aggregates its axis away; give several variables as
+# an array.
+show("Eq(x, y).shape", eq.call(x, y).shape)
+show("(forall x: Eq(x, y)).shape", forall.call(x, eq.call(x, y)).shape)
+show("forall x, y: Eq(x, y)", forall.call([x, y], eq.call(x, y)).value)
+show("exists x, y: Eq(x, y)", exists.call([x, y], eq.call(x, y)).value)
+show("forall x: exists y: Eq(x, y)", forall.call(x, exists.call(y, eq.call(x, y))).value)
+
+# p sets how strict the aggregation is: as p grows, pMeanError tends to the
+# minimum (forall), and pMean to the maximum (exists). It can be given per
+# call.
+show("forall x: Eq(x, c1), p = 2", forall.call(x, eq.call(x, c1), p: 2).value)
+show("forall x: Eq(x, c1), p = 10", forall.call(x, eq.call(x, c1), p: 10).value)
+show("exists x: Eq(x, c1), p = 2", exists.call(x, eq.call(x, c1), p: 2).value)
+show("exists x: Eq(x, c1), p = 10", exists.call(x, eq.call(x, c1), p: 10).value)
+
+puts "\n== Diagonal quantification"
+# Sometimes a formula should only be evaluated on the i-th individuals of
+# several variables together (e.g. samples and their labels), not on every
+# combination of them. LTN.diag marks variables (with the same number of
+# individuals) to be paired this way.
+samples = Torch.randn(100, 2, 2) # 100 values in R^{2x2}
+labels = Torch.randint(0, 3, [100], dtype: :int64) # one of 3 classes each
+x = LTN::Variable.new("x", samples)
+l = LTN::Variable.new("l", Torch.eye(3)[labels]) # one-hot labels
+
+class ModelC < Torch::NN::Module
+  def initialize
+    super
+    @elu = Torch::NN::ELU.new
+    @softmax = Torch::NN::Softmax.new(dim: 1)
+    @dense1 = Torch::NN::Linear.new(4, 5)
+    @dense2 = Torch::NN::Linear.new(5, 3)
+  end
+
+  def forward(x, l)
+    x = Torch.flatten(x, start_dim: 1)
+    x = @softmax.call(@dense2.call(@elu.call(@dense1.call(x))))
+    Torch.sum(x * l, dim: 1)
+  end
+end
+c = LTN::Predicate.new(ModelC.new)
+
+show("C(x, l).shape", c.call(x, l).shape) # all 100 x 100 combinations
+LTN.diag(x, l)
+show("C(x, l).shape after diag", c.call(x, l).shape) # the 100 pairs only
+show("x.free_vars, l.free_vars", [x.free_vars, l.free_vars])
+LTN.undiag(x, l)
+show("C(x, l).shape after undiag", c.call(x, l).shape)
+
+# In practice, use LTN.diag inside a quantifier: the quantifier resets the
+# variables (LTN.undiag) afterwards. Call it before building the formula, as
+# below, since it changes the variables' labels.
+show("forall diag(x, l): C(x, l)", forall.call(LTN.diag(x, l), c.call(x, l)).value)
+show("x.free_vars, l.free_vars", [x.free_vars, l.free_vars])
+
+puts "\n== Guarded quantification"
+# A guard restricts a quantifier to the individuals satisfying a boolean
+# condition, which may involve other variables too: "there is a distance d
+# such that all pairs of points closer than d are similar".
+points = Torch.rand(50, 2)
+x = LTN::Variable.new("x", points)
+y = LTN::Variable.new("y", points)
+d = LTN::Variable.new("d", Torch.tensor([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]))
+dist = ->(a, b) { Torch.norm(a.value - b.value, 2, dim: 1).unsqueeze(1) }
+
+result = exists.call(d,
+  forall.call([x, y], eq.call(x, y), cond_vars: [x, y, d]) { |a, b, dd| dist.call(a, b).lt(dd.value) })
+show("exists d: forall x, y with dist < d: Eq(x, y)", result.value)
+# The guard is a function (or block) of the condition variables, returning a
+# boolean tensor; it receives LTN objects, so it reads their values. Since
+# only the pairs satisfying it are aggregated, gradients also flow only
+# through them.

data/tutorials/2b_operators_and_gradients.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch's tutorials/2b-operators-and-gradients.ipynb, copyright 2021-2024 by Tommaso Carraro;
+# see the notebook, and the LTN paper (https://arxiv.org/abs/2012.13635), for the full discussion.
+#
+# Tutorial 2b: choosing fuzzy operators, and why their gradients matter.
+#
+#   bundle exec ruby tutorials/2b_operators_and_gradients.rb
+#
+# LTN learns by gradient descent on the truth values of formulas, so the
+# choice of fuzzy semantics is not only about logic: it decides which
+# truth values receive gradients, and how large they are.
+
+require "ltn"
+
+def show(label, value)
+  puts "#{label.ljust(44)} #{value.inspect}"
+end
+
+puts "== Operators"
+# Operators work directly on tensors of truth values.
+x1 = Torch.tensor(0.4)
+x2 = Torch.tensor(0.7)
+and_prod = LTN::FuzzyOps::AndProd.new(stable: false) # `stable` is explained below
+and_luk = LTN::FuzzyOps::AndLuk.new
+show("product: 0.4 and 0.7", and_prod.call(x1, x2))
+show("Lukasiewicz: 0.4 and 0.7", and_luk.call(x1, x2))
+
+xs = Torch.tensor([1.0, 1.0, 1.0, 0.5, 0.3, 0.2, 0.2, 0.1])
+forall_min = LTN::FuzzyOps::AggregMin.new
+forall_pme = LTN::FuzzyOps::AggregPMeanError.new(p: 4, stable: false)
+show("min", forall_min.call(xs, dim: 0))
+show("pMeanError, p = 4", forall_pme.call(xs, dim: 0))
+
+puts "\n== Gradients"
+# Lukasiewicz's conjunction has zero gradient whenever x1 + x2 <= 1: no
+# learning signal at all for such operands.
+x1 = Torch.tensor(0.3).requires_grad!(true)
+x2 = Torch.tensor(0.5).requires_grad!(true)
+y = and_luk.call(x1, x2)
+y.backward
+show("Lukasiewicz: 0.3 and 0.5, gradients", [y.item, x1.grad.item, x2.grad.item])
+
+# The minimum only passes gradients to the smallest value: one example per
+# step gets a learning signal.
+xs = Torch.tensor([1.0, 1.0, 1.0, 0.5, 0.3, 0.2, 0.2, 0.1]).requires_grad!(true)
+y = forall_min.call(xs, dim: 0)
+y.backward
+show("min, gradients", [y.item, xs.grad.to_a])
+
+# pMeanError passes gradients to every value, more to the ones further from
+# the truth. But with all values at 1, its gradient is 0/0: NaN.
+xs = Torch.tensor([1.0, 1.0, 1.0]).requires_grad!(true)
+y = forall_pme.call(xs, dim: 0, p: 4)
+y.backward
+show("pMeanError of 1s, gradients", [y.item, xs.grad.to_a])
+
+puts "\n== Stable operators"
+# The stable variants (the default) first project the truth values slightly
+# into (0, 1] or [0, 1) (LTN::FuzzyOps.pi_0 and pi_1, with epsilon 1e-4),
+# keeping their results and gradients finite.
+xs = Torch.tensor([1.0, 1.0, 1.0]).requires_grad!(true)
+y = forall_pme.call(xs, dim: 0, p: 4, stable: true)
+y.backward
+show("stable pMeanError of 1s, gradients", [y.item, xs.grad.to_a])
+
+# p trades off between a mean (p = 1, every value counts equally) and the
+# minimum (large p, the worst values dominate): larger p focuses the
+# gradients on the outliers.
+[4, 20].each do |p|
+  xs = Torch.tensor([1.0, 1.0, 1.0, 0.5, 0.3, 0.2, 0.2, 0.1]).requires_grad!(true)
+  y = forall_pme.call(xs, dim: 0, p: p)
+  y.backward
+  show("pMeanError, p = #{p}, gradients", [y.item.round(4), xs.grad.to_a.map { |g| g.round(4) }])
+end

data/tutorials/3_knowledgebase_and_learning.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch's tutorials/3-knowledgebase-and-learning.ipynb, copyright 2021-2024 by Tommaso Carraro;
+# see the notebook for the full discussion.
+#
+# Tutorial 3: learning from a knowledge base.
+#
+#   bundle exec ruby tutorials/3_knowledgebase_and_learning.rb
+#
+# The learnable parameters of LTN are those of the groundings of its
+# symbols. Training maximizes the satisfaction of the knowledge base, i.e.
+# the aggregated truth value of its axioms (here with SatAgg), by gradient
+# descent on the loss 1 - satisfaction.
+#
+# The task: two classes A and B of points in [0, 4]^2, of which only one
+# example each is known, a and b. The knowledge base states that a is an A,
+# b is a B, and that similar points belong to the same classes:
+#
+#   C(a, l_a)
+#   C(b, l_b)
+#   forall x1, x2, l: Sim(x1, x2) -> (C(x1, l) <-> C(x2, l))
+
+require "ltn"
+
+EPOCHS = Integer(ENV.fetch("EPOCHS", 2000))
+BATCH_EPOCHS = Integer(ENV.fetch("BATCH_EPOCHS", 100))
+
+Torch.manual_seed(2020)
+
+# C(x, l): the probability, from a softmax over the two classes, that point x
+# has class l (one-hot).
+class ModelC < Torch::NN::Module
+  def initialize
+    super
+    @elu = Torch::NN::ELU.new
+    @softmax = Torch::NN::Softmax.new(dim: 1)
+    @dense1 = Torch::NN::Linear.new(2, 5)
+    @dense2 = Torch::NN::Linear.new(5, 5)
+    @dense3 = Torch::NN::Linear.new(5, 2)
+  end
+
+  def forward(x, l)
+    x = @elu.call(@dense1.call(x))
+    x = @elu.call(@dense2.call(x))
+    Torch.sum(@softmax.call(@dense3.call(x)) * l, dim: 1)
+  end
+end
+
+points = Torch.tensor([[0.4, 0.3], [1.2, 0.3], [2.2, 1.3], [1.7, 1.0], [0.5, 0.5], [0.3, 1.5], [1.3, 1.1],
+  [0.9, 1.7], [3.4, 3.3], [3.2, 3.3], [3.2, 2.3], [2.7, 2.0], [3.5, 3.5], [3.3, 2.5], [3.3, 1.1], [1.9, 3.7],
+  [1.3, 3.5], [3.3, 1.1], [3.9, 3.7]])
+
+c = LTN::Predicate.new(ModelC.new)
+# Sim(u, v) = exp(-||u - v||): a similarity, not learned.
+sim = LTN::Predicate.new { |u, v| Torch.exp(Torch.neg(Torch.sqrt(Torch.sum(Torch.square(u - v), dim: 1)))) }
+
+x1 = LTN::Variable.new("x1", points)
+x2 = LTN::Variable.new("x2", points)
+a = LTN::Constant.new(Torch.tensor([3.3, 2.5]))
+b = LTN::Constant.new(Torch.tensor([1.3, 1.1]))
+l_a = LTN::Constant.new(Torch.tensor([1, 0]))
+l_b = LTN::Constant.new(Torch.tensor([0, 1]))
+l = LTN::Variable.new("l", Torch.tensor([[1, 0], [0, 1]]))
+
+implies = LTN::Connective.new(LTN::FuzzyOps::ImpliesReichenbach.new)
+equiv = LTN::Connective.new(LTN::FuzzyOps::Equiv.new(LTN::FuzzyOps::AndProd.new, LTN::FuzzyOps::ImpliesReichenbach.new))
+forall = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMeanError.new(p: 2), :forall)
+sat_agg = LTN::FuzzyOps::SatAgg.new # pMeanError by default
+
+puts "== Learning"
+optimizer = Torch::Optim::Adam.new(c.parameters, lr: 0.001)
+loss = nil
+EPOCHS.times do |epoch|
+  optimizer.zero_grad
+  loss = 1.0 - sat_agg.call(
+    c.call(a, l_a),
+    c.call(b, l_b),
+    forall.call([x1, x2, l], implies.call(sim.call(x1, x2), equiv.call(c.call(x1, l), c.call(x2, l))))
+  )
+  loss.backward
+  optimizer.step
+  puts format("Epoch %d: Sat Level %.3f", epoch, 1 - loss.item) if (epoch % 200).zero?
+end
+puts format("Training finished with Sat Level %.3f", 1 - loss.item)
+
+puts "\nC(x, l_a) for each point (a = [3.3, 2.5], b = [1.3, 1.1]):"
+Torch.no_grad do
+  c.call(x1, l_a).value.to_a.each_with_index do |truth, i|
+    puts format("  [%.1f, %.1f]  %.2f", *points[i].to_a, truth)
+  end
+end
+
+puts "\n== Learning in mini-batches"
+# With many individuals, a variable can be grounded with a mini-batch of
+# them at each step, like any other training data. Here: 10,000 points of
+# [0, 4]^2, with a = [3, 3] and b = [1, 1] among them.
+points = Torch.rand(10_000, 2) * 4
+points[-1] = Torch.tensor([3.0, 3.0])
+points[-2] = Torch.tensor([1.0, 1.0])
+a = LTN::Constant.new(Torch.tensor([3.0, 3.0]))
+b = LTN::Constant.new(Torch.tensor([1.0, 1.0]))
+
+c = LTN::Predicate.new(ModelC.new) # a new, untrained C
+optimizer = Torch::Optim::Adam.new(c.parameters, lr: 0.001)
+BATCH_EPOCHS.times do |epoch|
+  Torch.randperm(points.shape[0]).split(512).each do |indices|
+    batch = points[indices]
+    x1 = LTN::Variable.new("x1", batch)
+    x2 = LTN::Variable.new("x2", batch)
+    optimizer.zero_grad
+    loss = 1.0 - sat_agg.call(
+      c.call(a, l_a),
+      c.call(b, l_b),
+      forall.call([x1, x2, l], implies.call(sim.call(x1, x2), equiv.call(c.call(x1, l), c.call(x2, l))))
+    )
+    loss.backward
+    optimizer.step
+  end
+  puts format("Epoch %d: Sat Level %.3f", epoch, 1 - loss.item) if (epoch % 10).zero?
+end
+puts format("Training finished with Sat Level %.3f", 1 - loss.item)