ltntorch 0.1.0

data/lib/ltn/process_ltn_objects.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch, copyright 2021-2024 by Tommaso Carraro.
+
+module LTN
+  # Makes the groundings of LTN objects compatible for an element-wise
+  # predicate, function or connective (LTN broadcasting).
+  #
+  # Every object is expanded to the union of the free variables of all the
+  # objects, in the order in which they first appear, by repeating its values
+  # along the variables it lacks. The variable axes are then flattened into a
+  # single leading batch axis, so that the i-th row of every processed object
+  # refers to the same combination of individuals.
+  #
+  # Unlike LTNtorch, this never modifies the given objects: LTNtorch rebinds
+  # the value and free variables of intermediate results (objects whose value
+  # has a grad_fn), so reusing such a formula afterwards sees the broadcast
+  # grounding. The processed values are the same.
+  #
+  # @parameter objects [Array(LTNObject)] the objects to process.
+  # @returns [Array] a triple: the processed objects, the labels of all the
+  #   free variables, and the number of individuals of each of them.
+  # @raises [TypeError] if `objects` is not an array of LTN objects.
+  def self.process_ltn_objects(objects)
+    unless objects.is_a?(Array) && objects.all?(LTNObject)
+      raise TypeError, "The objects should be an Array of LTNObject"
+    end
+
+    vars_to_n = {}
+    objects.each do |object|
+      object.free_vars.each_with_index { |var, index| vars_to_n[var] = object.shape[index] }
+    end
+    vars = vars_to_n.keys
+    n_individuals_per_var = vars_to_n.values
+
+    processed = objects.map do |object|
+      value = object.value
+      vars_in_object = object.free_vars.dup
+
+      (vars - vars_in_object).each do |new_var|
+        new_var_index = vars_in_object.size
+        value = value.unsqueeze(new_var_index)
+        value = Torch.repeat_interleave(value, vars_to_n[new_var], dim: new_var_index)
+        vars_in_object << new_var
+      end
+
+      permutation = vars.map { |var| vars_in_object.index(var) } + (vars_in_object.size...value.dim).to_a
+      value = value.permute(permutation)
+      value = value.reshape([-1] + value.shape[vars_in_object.size..])
+
+      LTNObject.new(value, vars.dup)
+    end
+
+    [processed, vars, n_individuals_per_var]
+  end
+end

data/lib/ltn/quantifier.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch, copyright 2021-2024 by Tommaso Carraro.
+
+module LTN
+  # An LTN quantifier: aggregates the truth values of a formula along the axes
+  # of the quantified variables, with an aggregation operator (see
+  # LTN::FuzzyOps).
+  #
+  #   forall = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMeanError.new(p: 2), :forall)
+  #   exists = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMean.new(p: 2), :exists)
+  #   forall.call(x, exists.call(y, p.call(x, y)))
+  #
+  # Guarded quantification restricts the aggregation to the individuals that
+  # satisfy a condition:
+  #
+  #   forall.call(x, p.call(x), cond_vars: [x]) { |x| x.value.sum(1).gt(0.5) }
+  class Quantifier
+    QUANTIFIERS = {:forall => :forall, :exists => :exists, "f" => :forall, "e" => :exists}.freeze
+
+    # @attribute [FuzzyOps::AggregationOperator] the aggregation operator.
+    attr_reader :agg_op
+
+    # @attribute [Symbol] :forall or :exists.
+    attr_reader :quantifier
+
+    # @parameter agg_op [FuzzyOps::AggregationOperator] the aggregation operator.
+    # @parameter quantifier [Symbol, String] :forall or :exists (LTNtorch's "f" and "e" work too).
+    #   It determines the truth value of a guarded quantification over no individuals:
+    #   1 for :forall, 0 for :exists.
+    # @raises [TypeError] if `agg_op` is not an aggregation operator.
+    # @raises [ArgumentError] if `quantifier` is not one of the above.
+    def initialize(agg_op, quantifier)
+      unless agg_op.is_a?(FuzzyOps::AggregationOperator)
+        raise TypeError, "Quantifier.new: argument 'agg_op' (position 1) must be a " \
+          "LTN::FuzzyOps::AggregationOperator, not #{agg_op.class}"
+      end
+      unless QUANTIFIERS.key?(quantifier)
+        raise ArgumentError, "Expected parameter 'quantifier' to be :exists (or 'e') for the existential " \
+          "quantifier, or :forall (or 'f') for the universal one, but got #{quantifier.inspect}"
+      end
+
+      @agg_op = agg_op
+      @quantifier = QUANTIFIERS.fetch(quantifier)
+    end
+
+    # Quantifies `formula` over `vars`, then resets any diagonal
+    # quantification on them (see LTN.diag).
+    #
+    # @parameter vars [Variable, Array(Variable)] the quantified variables.
+    # @parameter formula [LTNObject] the formula.
+    # @parameter cond_vars [Variable, Array(Variable), nil] the variables of
+    #   the guard, for guarded quantification.
+    # @parameter cond_fn [#call, nil] the guard: given the (broadcast) LTN
+    #   objects of `cond_vars`, returns a boolean tensor with one value per
+    #   combination of their individuals. It can be given as a block instead.
+    # @parameter kwargs [Hash] passed to the aggregation operator, e.g. `p: 4`.
+    # @returns [LTNObject] the result, whose free variables are those of the
+    #   formula minus the quantified ones. Guarded quantification returns
+    #   float64 values, as in LTNtorch.
+    # @raises [ArgumentError] if only one of `cond_vars` and `cond_fn` is
+    #   given, a quantified variable does not appear in the formula, or the
+    #   formula's values are not in [0, 1].
+    # @raises [TypeError] if an argument has the wrong type.
+    def call(vars, formula, cond_vars: nil, cond_fn: nil, **kwargs, &block)
+      if cond_fn && block
+        raise ArgumentError, "Expected the guard as either 'cond_fn' or a block, but got both."
+      end
+      cond_fn ||= block
+      if cond_fn && cond_vars.nil?
+        raise ArgumentError, "Since 'cond_fn' has been set, 'cond_vars' must be set as well, but got nil."
+      end
+      if cond_vars && cond_fn.nil?
+        raise ArgumentError, "Since 'cond_vars' has been set, 'cond_fn' must be set as well, but got nil."
+      end
+      vars = variables(vars, "vars")
+      unless formula.is_a?(LTNObject)
+        raise TypeError, "Expected parameter 'formula' to be an LTNObject, but got #{formula.class}"
+      end
+
+      FuzzyOps.check_values(formula.value)
+
+      aggregation_vars = vars.map { |var| var.free_vars.first }.uniq
+      if cond_fn
+        cond_vars = variables(cond_vars, "cond_vars")
+        unless cond_fn.respond_to?(:call)
+          raise TypeError, "Expected parameter 'cond_fn' to be a function, but got #{cond_fn.class}"
+        end
+
+        formula, mask = self.class.compute_mask(formula, cond_vars, cond_fn, aggregation_vars)
+        output = agg_op.call(formula.value, dim: aggregation_dims(formula, aggregation_vars), mask: mask.value, **kwargs)
+        # The aggregation is undefined (NaN) where the guard leaves no
+        # individuals: forall is then vacuously true, exists false.
+        output = FuzzyOps.where(Torch.isnan(output), (quantifier == :forall) ? 1.0 : 0.0, output.double)
+      else
+        output = agg_op.call(formula.value, dim: aggregation_dims(formula, aggregation_vars), **kwargs)
+      end
+
+      LTN.undiag(*vars)
+      LTNObject.new(output, formula.free_vars - aggregation_vars)
+    end
+
+    # Prepares a guarded quantification: broadcasts `formula` over the
+    # condition variables it lacks, and computes the mask of `cond_fn`. Both
+    # are transposed so that their leading axes are the condition variables
+    # that are not quantified, then the quantified ones.
+    #
+    # Unlike LTNtorch, this does not modify `formula`.
+    #
+    # @parameter formula [LTNObject] the formula.
+    # @parameter cond_vars [Array(Variable)] the variables of the guard.
+    # @parameter cond_fn [#call] the guard.
+    # @parameter aggregation_vars [Array(String)] labels of the quantified variables.
+    # @returns [Array(LTNObject)] the formula and the mask, with the same shape and free variables.
+    def self.compute_mask(formula, cond_vars, cond_fn, aggregation_vars)
+      cond_vars_not_in_formula = cond_vars.reject { |var| formula.free_vars.include?(var.free_vars.first) }
+      unless cond_vars_not_in_formula.empty?
+        processed, _, n_individuals = LTN.process_ltn_objects([formula] + cond_vars_not_in_formula)
+        formula = LTNObject.new(processed.first.value.view(n_individuals), processed.first.free_vars)
+      end
+
+      cond_labels = cond_vars.map { |var| var.free_vars.first }
+      cond_not_aggregated = cond_labels.reject { |var| aggregation_vars.include?(var) }
+      cond_aggregated = cond_labels.select { |var| aggregation_vars.include?(var) }
+      not_in_cond = formula.free_vars.reject { |var| cond_labels.include?(var) }
+      formula = transpose_vars(formula, (cond_not_aggregated + cond_aggregated + not_in_cond).uniq)
+
+      processed_cond_vars, cond_vars_order, n_individuals_per_var = LTN.process_ltn_objects(cond_vars)
+      mask = cond_fn.call(*processed_cond_vars)
+      mask = LTNObject.new(mask.reshape(n_individuals_per_var), cond_vars_order)
+      mask = transpose_vars(mask, (cond_not_aggregated + cond_aggregated).uniq)
+
+      if formula.shape != mask.shape
+        (formula, mask), _, n_individuals_per_var = LTN.process_ltn_objects([formula, mask])
+        mask = LTNObject.new(mask.value.view(n_individuals_per_var), mask.free_vars)
+        formula = LTNObject.new(formula.value.view(n_individuals_per_var), formula.free_vars)
+      end
+
+      [formula, mask]
+    end
+
+    # @parameter object [LTNObject] the object to transpose.
+    # @parameter new_vars_order [Array(String)] its free variables, in the new order.
+    # @returns [LTNObject] a new object with the axes of the free variables permuted.
+    #   (LTNtorch modifies and returns `object`.)
+    def self.transpose_vars(object, new_vars_order)
+      permutation = new_vars_order.map { |var| object.free_vars.index(var) }
+      LTNObject.new(object.value.permute(permutation), new_vars_order)
+    end
+
+    def inspect
+      "Quantifier(agg_op=#{agg_op.inspect}, quantifier=#{quantifier.inspect})"
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    def variables(vars, name)
+      return [vars] if vars.is_a?(Variable)
+      return vars if vars.is_a?(Array) && vars.all?(Variable)
+
+      types = vars.is_a?(Array) ? vars.map(&:class).inspect : vars.class
+      raise TypeError, "Expected parameter '#{name}' to be a Variable or an Array of Variable, but got #{types}"
+    end
+
+    def aggregation_dims(formula, aggregation_vars)
+      aggregation_vars.map do |var|
+        formula.free_vars.index(var) ||
+          raise(ArgumentError, "Variable #{var.inspect} does not appear in the formula (free variables: " \
+            "#{formula.free_vars.inspect})")
+      end
+    end
+  end
+end

data/lib/ltn/variable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch, copyright 2021-2024 by Tommaso Carraro.
+
+module LTN
+  # An LTN variable: a sequence of individuals of the domain, grounded as a
+  # tensor whose first dimension indexes the individuals.
+  class Variable < LTNObject
+    # @attribute [String] the label given to the variable, which #free_vars
+    #   replaces temporarily during diagonal quantification (see LTN.diag).
+    attr_reader :latent_var
+
+    # @parameter var_label [String] the label of the variable. Labels starting
+    #   with `diag_` are reserved for diagonal quantification.
+    # @parameter individuals [Torch::Tensor] the individuals, one per row.
+    #   float64 values are converted to float32.
+    # @parameter add_batch_dim [Boolean] whether to turn a 1-D tensor of n
+    #   individuals into a n x 1 tensor, so that each individual is a vector.
+    # @raises [TypeError] if the label is not a String or the individuals are not a tensor.
+    # @raises [ArgumentError] if the label starts with `diag_`.
+    def initialize(var_label, individuals, add_batch_dim: true)
+      unless var_label.is_a?(String)
+        raise TypeError, "Variable.new: argument 'var_label' (position 1) must be a String, not #{var_label.class}"
+      end
+      if var_label.start_with?("diag_")
+        raise ArgumentError, "Labels starting with 'diag_' are reserved for diagonal quantification."
+      end
+      unless individuals.is_a?(Torch::Tensor)
+        raise TypeError, "Variable.new: argument 'individuals' (position 2) must be a Torch::Tensor, not #{individuals.class}"
+      end
+
+      super(individuals, [var_label])
+
+      # Avoids dtype mismatches with float32 models. (LTNtorch converts CPU
+      # float64 tensors only; here any float64 tensor is converted.)
+      @value = @value.float if @value.dtype == :float64
+      @value = @value.view(@value.shape[0], 1) if @value.dim == 1 && add_batch_dim
+      @value = @value.to(LTN.device)
+      @latent_var = var_label
+    end
+
+    def inspect
+      "Variable(value=#{value.inspect}, free_vars=#{free_vars.inspect})"
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/ltn/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+
+module LTN
+  VERSION = "0.1.0"
+end

data/lib/ltn.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Mauro Tortonesi.
+# Ported from LTNtorch, copyright 2021-2024 by Tommaso Carraro.
+
+require "torch"
+
+require_relative "ltn/version"
+require_relative "ltn/ltn_object"
+require_relative "ltn/fuzzy_ops"
+require_relative "ltn/constant"
+require_relative "ltn/variable"
+require_relative "ltn/process_ltn_objects"
+require_relative "ltn/lambda_model"
+require_relative "ltn/model_wrapper"
+require_relative "ltn/predicate"
+require_relative "ltn/function"
+require_relative "ltn/diag"
+require_relative "ltn/connective"
+require_relative "ltn/quantifier"
+
+# Logic Tensor Networks (LTN) on top of torch.rb: a Ruby port of LTNtorch
+# (https://github.com/tommasocarraro/LTNtorch).
+module LTN
+  class Error < StandardError; end
+
+  class << self
+    # The device on which LTN places the groundings of its variables.
+    #
+    # LTNtorch picks CUDA at import time when available. Here the default is
+    # chosen lazily, on first access, and can be overridden at any time, e.g.
+    # `LTN.device = Torch.device("cpu")` to force CPU in tests.
+    #
+    # @returns [Torch::Device]
+    def device
+      @device ||= Torch.device(Torch::CUDA.available? ? "cuda" : "cpu")
+    end
+
+    # @parameter device [Torch::Device, String] e.g. `"cpu"` or `"cuda:0"`.
+    def device=(device)
+      @device = device.is_a?(Torch::Device) ? device : Torch.device(device)
+    end
+  end
+end

data/license.md

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright, 2026, by Mauro Tortonesi.  
+Copyright, 2021-2024, by Tommaso Carraro (LTNtorch, from which this library is ported).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,166 @@
+# LTNtorch-rb
+
+An implementation of [Logic Tensor Networks](https://arxiv.org/abs/2012.13635)
+(LTN) on top of [torch.rb](https://github.com/ankane/torch.rb), ported from
+[LTNtorch](https://github.com/tommasocarraro/LTNtorch), the PyTorch
+implementation by Tommaso Carraro. It is developed at the [Big Data and
+Compute Continuum Research Lab](https://bdcc.unife.it) of the University of
+Ferrara, Italy, as a companion to the
+[reinforce](https://github.com/DSG-UniFE/reinforce) Reinforcement Learning
+library.
+
+LTN is a neuro-symbolic framework: predicates, functions and constants of a
+first-order logic language are grounded as (possibly learnable) tensors and
+neural networks, and the axioms of a knowledge base are evaluated with
+differentiable fuzzy logic semantics. Maximizing the satisfaction of the
+axioms becomes the training objective.
+
+**Status:** under active development. The core of LTN (groundings,
+predicates, functions, connectives, quantifiers, guarded and diagonal
+quantification, and the fuzzy operators) is ported, and checked against
+LTNtorch's results; see `changelog.md` for progress and for the
+differences from LTNtorch.
+
+## Prerequisites
+
+LTNtorch-rb requires the [torch.rb](https://rubygems.org/gems/torch-rb) gem,
+which provides Ruby bindings for LibTorch (the C++ core of PyTorch). torch.rb
+compiles against exactly one LibTorch version (0.27.x needs LibTorch 2.15.x).
+
+On macOS you can install LibTorch with Homebrew:
+
+    $ brew install pytorch
+
+Otherwise, download LibTorch from [the PyTorch Web site](https://pytorch.org/),
+extract it, and point Bundler at it:
+
+    $ bundle config build.torch-rb --with-torch-dir=/path/to/libtorch
+
+For more info, see [torch.rb's readme](https://github.com/ankane/torch.rb).
+
+## Installation
+
+Add the gem to your application's gems.rb (or Gemfile):
+
+    $ bundle add ltntorch
+
+or install it directly:
+
+    $ gem install ltntorch
+
+Then:
+
+```ruby
+require "ltn"
+```
+
+## Usage
+
+Learn a predicate `A` from a knowledge base saying that it holds for one
+cluster of points and not for another:
+
+```ruby
+require "ltn"
+
+positives = Torch.randn(50, 2) * 0.5 + 1.0
+negatives = Torch.randn(50, 2) * 0.5 - 1.0
+
+# A learnable predicate: any Torch::NN::Module returning truth values in [0, 1].
+a = LTN::Predicate.new(
+  Torch::NN::Sequential.new(
+    Torch::NN::Linear.new(2, 8), Torch::NN::ELU.new,
+    Torch::NN::Linear.new(8, 1), Torch::NN::Sigmoid.new
+  )
+)
+
+not_ = LTN::Connective.new(LTN::FuzzyOps::NotStandard.new)
+forall = LTN::Quantifier.new(LTN::FuzzyOps::AggregPMeanError.new(p: 2), :forall)
+sat_agg = LTN::FuzzyOps::SatAgg.new
+
+x_pos = LTN::Variable.new("x_pos", positives)
+x_neg = LTN::Variable.new("x_neg", negatives)
+optimizer = Torch::Optim::Adam.new(a.parameters, lr: 0.01)
+
+200.times do
+  optimizer.zero_grad
+  # forall x_pos: A(x_pos), and forall x_neg: not A(x_neg)
+  sat = sat_agg.call(
+    forall.call(x_pos, a.call(x_pos)),
+    forall.call(x_neg, not_.call(a.call(x_neg)))
+  )
+  (1.0 - sat).backward
+  optimizer.step
+end
+```
+
+Predicates and functions can also be grounded by a block, e.g.
+`LTN::Predicate.new { |x| Torch.sigmoid(x.sum(1)) }`, and quantifiers can be
+guarded by a condition on the individuals:
+
+```ruby
+forall.call(x, a.call(x), cond_vars: [x]) { |x| x.value.sum(1).gt(0.0) }
+```
+
+## Examples and tutorials
+
+`examples/` contains Ruby ports of LTNtorch's seven examples, and
+`tutorials/` of its four tutorials, as scripts:
+
+| Script | What it shows |
+|---|---|
+| `tutorials/1_grounding_non_logical_symbols.rb` | Constants, predicates, functions and variables |
+| `tutorials/2_grounding_connectives.rb` | Connectives, quantifiers, diagonal and guarded quantification |
+| `tutorials/2b_operators_and_gradients.rb` | Choosing fuzzy operators, and their gradients |
+| `tutorials/3_knowledgebase_and_learning.rb` | Learning from a knowledge base, in mini-batches too |
+| `examples/1_binary_classification.rb` | A predicate learned from positive and negative examples |
+| `examples/2_multi_class_single_label_classification.rb` | Iris, with a softmax classifier as predicate |
+| `examples/3_multi_class_multi_label_classification.rb` | Crabs, with mutually exclusive labels, and queries |
+| `examples/4_semi_supervised_pattern_recognition.rb` | MNIST digits learned from their sums only (downloads MNIST; `--default-init` for the LTN paper's accuracy) |
+| `examples/5_regression.rb` | Real estate prices, with a smooth equality and diagonal quantification |
+| `examples/6_clustering.rb` | Clustering without labels, with guarded quantification |
+| `examples/7_learning_embeddings_with_ltn.rb` | Smokers, friends and cancer: learned embeddings of individuals |
+
+Run them with, e.g., `bundle exec ruby examples/6_clustering.rb`; set
+`EPOCHS` to train for fewer epochs. Their results are close to those of
+LTNtorch's notebooks, and `bundle exec sus benchmark/examples.rb` checks
+that they keep learning.
+
+The API follows LTNtorch's, so its
+[documentation](https://tommasocarraro.github.io/LTNtorch/) and
+[tutorials](https://github.com/tommasocarraro/LTNtorch/tree/main/tutorials)
+apply, with Ruby conventions: optional arguments are keywords, symbols are
+called with `#call`, and quantifiers take `:forall`/`:exists`.
+
+## Contributing
+
+See `CONTRIBUTING.md` for setup, tests, linting and coverage.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+## Credits and citation
+
+LTNtorch-rb is a port of LTNtorch; if you use it in your work, please also
+cite the original software and the LTN paper:
+
+- T. Carraro, *LTNtorch: PyTorch implementation of Logic Tensor Networks*,
+  [doi:10.5281/zenodo.6394282](https://doi.org/10.5281/zenodo.6394282).
+- S. Badreddine, A. d'Avila Garcez, L. Serafini, M. Spranger, *Logic Tensor
+  Networks*, Artificial Intelligence 303, 2022,
+  [arXiv:2012.13635](https://arxiv.org/abs/2012.13635).
+
+## License
+
+This software is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT); see `license.md`.
+
+### Developer Certificate of Origin
+
+This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+
+### Contributor Covenant
+
+This project is governed by [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.