hensel_code 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ade0ad51689f11d1f36d2ac3e62c40a6ec61fef5142f11371e5403e195ad70a
+  data.tar.gz: 0f7288540b1000124be29836ef664ea31d2670a9f0390c24b075e90febba6e42
+SHA512:
+  metadata.gz: 457aef94ccb7bf0d107e54e85731d26c8463d24f6a176f5769f55737adb602af753441e7964ea8c5b1ccd53e16357a54eada4221ba62e14b696204f72f76942c
+  data.tar.gz: 4604cc97de514dbb23cecf574a727e83510947158b6565909c6f556d621fab36b972cd2bbe128b89c693e715fc19d2123dcd44681b1bfe860b016eb93b7091eb

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-03-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in hensel_code.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "rubocop-minitest", "~> 0.17.2"
+
+gem "rubocop-rake", "~> 0.6"
+
+gem "minitest-reporters", "~> 1.5"
+
+gem "prime", "~> 0.1.2"
+
+gem "codecov", require: false, group: :test

data/Gemfile.lock

@@ -0,0 +1,73 @@
+PATH
+  remote: .
+  specs:
+    hensel_code (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.5.0)
+    ast (2.4.2)
+    builder (3.2.4)
+    codecov (0.6.0)
+      simplecov (>= 0.15, < 0.22)
+    docile (1.4.0)
+    forwardable (1.3.2)
+    minitest (5.15.0)
+    minitest-reporters (1.5.0)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    parallel (1.21.0)
+    parser (3.1.1.0)
+      ast (~> 2.4.1)
+    prime (0.1.2)
+      forwardable
+      singleton
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.2.1)
+    rexml (3.2.5)
+    rubocop (1.25.1)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    rubocop-minitest (0.17.2)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    singleton (0.1.1)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  ruby
+  x86_64-darwin-19
+
+DEPENDENCIES
+  codecov
+  hensel_code!
+  minitest (~> 5.0)
+  minitest-reporters (~> 1.5)
+  prime (~> 0.1.2)
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  rubocop-minitest (~> 0.17.2)
+  rubocop-rake (~> 0.6)
+
+BUNDLED WITH
+   2.3.8

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 David William Silva
+
+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,191 @@
+# HenselCode
+
+![example workflow](https://github.com/davidwilliam/hensel_code/actions/workflows/main.yml/badge.svg) [![codecov](https://codecov.io/gh/davidwilliam/hensel_code/branch/main/graph/badge.svg?token=XJ0C0U7P2M)](https://codecov.io/gh/davidwilliam/hensel_code) [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop) ![GitHub](https://img.shields.io/github/license/davidwilliam/hensel_code)
+
+Hensel Code allows you to homomorphically encode rational numbers as integers using the finite-segment p-adic arithmetic, also known as Hensel codes. 
+
+## Mathematical Background
+
+In our Wiki, you can find a brief [introduction to the mathematical background on Hensel codes](https://github.com/davidwilliam/hensel_code/wiki/Mathematical-Background). We will continue to update that area as we update the gem.
+
+## Applications
+
+You can also find information about [possible applications with Hensel codes](https://github.com/davidwilliam/hensel_code/wiki/Applications).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hensel_code'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hensel_code
+
+## Usage
+
+Let `p=257` and `r=3`. Given two rational numbers `rat1 = Rational(3,5)` and `rat2 = Rational(4,3)`, we encode `rat1` and `rat2` as follows:
+
+```ruby
+h1 = HenselCode::TruncatedFinitePadicExpansion.new(p, r, rat1)
+# => [HenselCode: 13579675, prime: 257, exponent: 3, modulus: 16974593]
+h2 = HenselCode::TruncatedFinitePadicExpansion.new(p, r, rat1)
+# => [HenselCode: 5658199, prime: 257, exponent: 3, modulus: 16974593]
+h1.class
+# => HenselCode::TruncatedFinitePadicExpansion
+h2.class
+# => HenselCode::TruncatedFinitePadicExpansion
+puts h1
+# => 13579675
+puts h2
+# => 5658199
+```
+
+Now we can carry arithmetic computations on the `h1` and `h2` objects as if we were computing over `rat1` and `rat2`:
+
+```ruby
+h1_plus_h2 = h1 + h2
+h1_minus_h2 = h1 - h2
+h1_times_h2 = h1 * h2
+h1_div_h2 = h1 / h2
+```
+
+All the computations are reduced modulo `p^r`.
+
+At any moment, we can check the rational representation of the results we produced:
+
+```ruby
+h1_plus_h2.to_r
+# => (29/15)
+h1_minus_h2.to_r
+# => (-11/15)
+h1_times_h2.to_r
+# => (4/5)
+h1_div_h2.to_r
+# => (9/20)
+```
+
+And we can verify that
+
+```ruby
+rat1 + rat2
+# => (29/15)
+rat1 - rat2
+# => (-11/15)
+rat1 * rat2
+# => (4/5)
+```
+
+### Constraints
+
+In order to operate on two or more Hensel codes, they all must be of the same object type and have the same prime and exponent, otherwise HenselCode will raise an exception. Again, let `rat1 = Rational(3,5)` and `rat2 = Rational(4,3)`, and `p1 = 241`, `p2 = 251`, `r1 = 3`, and `r2 = 4`:
+
+```ruby
+h1 = HenselCode::TruncatedFinitePadicExpansion.new(p1, r1, rat1)
+# => [HenselCode: 5599009, prime: 241, exponent: 3, modulus: 13997521]
+h2 = HenselCode::TruncatedFinitePadicExpansion.new(p1, r2, rat1)
+# => [HenselCode: 1349361025, prime: 241, exponent: 4, modulus: 3373402561]
+h3 = HenselCode::TruncatedFinitePadicExpansion.new(p2, r1, rat1)
+# => [HenselCode: 6325301, prime: 251, exponent: 3, modulus: 15813251]
+h4 = HenselCode::TruncatedFinitePadicExpansion.new(p2, r2, rat1)
+=> [HenselCode: 1587650401, prime: 251, exponent: 4, modulus: 3969126001]
+```
+
+The following operations will raise exceptions:
+
+```ruby
+h1 + h2
+# => 5599009 has exponent 3 while 1349361025 has exponent 4 (HenselCode::HenselCodesWithDifferentExponents)
+h1 + h3
+# => 5599009 has prime 241 while 6325301 has prime 251 (HenselCode::HenselCodesWithDifferentPrimes)
+h1 + h4
+# => 5599009 has prime 241 and exponent 3 while 1587650401 has prime 251 and exponent 4 (HenselCode::HenselCodesWithDifferentPrimesAndExponents)
+num = 5
+h1 + num
+# => 5599009 is a HenselCode::TruncatedFinitePadicExpansion while 5 is a Integer (HenselCode::IncompatibleOperandTypes)
+```
+
+### Manipulating Hensel Code Objects
+
+Let `p = 541`, `r = 3`, `rat = Rational(11,5)`. We create a Hensel code as before:
+
+```ruby
+h = HenselCode::TruncatedFinitePadicExpansion.new p, r, rat
+# => [HenselCode: 126672339, prime: 541, exponent: 3, modulus: 158340421]
+```
+
+We can change the prime and the exponent:
+
+```ruby
+p = 1223
+r = 4
+h.replace_prime(p)
+# => [HenselCode: 731710629, prime: 1223, exponent: 3, modulus: 1829276567]
+h.replace_exponent(r)
+# => [HenselCode: 1789764193155, prime: 1223, exponent: 4, modulus: 2237205241441]
+```
+
+Any change in the prime and/or the exponent of a Hensel code object will change the Hensel code value and the modulus as well, however, the Hensel code object continues to refer to represent the same rational number:
+
+```ruby
+h.to_r
+# => (11/5)
+```
+
+We can also change the rational number:
+
+```ruby
+rat = Rational(13,7)
+h.replace_rational(rat)
+# => [HenselCode: 1278402995111, prime: 1223, exponent: 4, modulus: 2237205241441]
+h.to_r
+# => (13/7)
+```
+
+We can initiate a Hensel code object with its Hensel code value, instead of a rational number:
+
+```ruby
+h = HenselCode::TruncatedFinitePadicExpansion.new p, r, 53673296543
+```
+
+and then we can check what is the rational number represented by the resulting object:
+
+```ruby
+h.to_r
+# => (706147/633690)
+```
+
+We can update the Hensel code value of an existing Hensel code object:
+
+```ruby
+h.replace_hensel_code(38769823656)
+# => (-685859/94809)
+```
+
+### Class Alias
+
+Since `HenselCode::TruncatedFinitePadicExpansion` is a bit long, the alias `HenselCode::TFPE` can be used instead.
+
+## Coming Soon
+
+There are many types of Hensel codes. We are currently implementing only one. Very soon we will add more types of Hensel codes to the library, which will further expand what we can do with it.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/davidwilliam/hensel_code.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/hensel_code/tfpe_verifier.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module HenselCode
+  # verifications pre-evaluation of hensel codes
+  module TFPEVerifier
+    def valid?(other)
+      incompatible_operand_type?(other)
+      different_prime_and_same_exponent?(other)
+      different_prime_and_different_exponent?(other)
+      same_prime_and_different_exponent?(other)
+    end
+
+    def incompatible_operand_type?(other)
+      message = "#{self} is a #{self.class} while #{other} is a #{other.class}"
+      raise IncompatibleOperandTypes, message unless instance_of?(other.class)
+    end
+
+    def different_prime_and_same_exponent?(other)
+      message = "#{self} has prime #{prime} while #{other} has prime #{other.prime}"
+      raise HenselCodesWithDifferentPrimes, message if prime != other.prime && exponent == other.exponent
+    end
+
+    def different_prime_and_different_exponent?(other)
+      message = <<~MSG
+        "#{self} has prime #{prime} and exponent #{exponent}
+        while #{other} has prime #{other.prime} and exponent #{other.exponent}
+      MSG
+      raise HenselCodesWithDifferentPrimesAndExponents, message if prime != other.prime && exponent != other.exponent
+    end
+
+    def same_prime_and_different_exponent?(other)
+      message = "#{self} has exponent #{exponent} while #{other} has exponent #{other.exponent}"
+      raise HenselCodesWithDifferentExponents, message if prime == other.prime && exponent != other.exponent
+    end
+  end
+end

data/lib/hensel_code/tools.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module HenselCode
+  # Required basics of number generation and modular
+  module Tools
+    def random_integer(bits)
+      OpenSSL::BN.rand(bits).to_i
+    end
+
+    def random_rational(bits)
+      numbers = [random_integer(bits)]
+      while numbers.size < 2
+        num = random_integer(bits)
+        numbers << num if numbers.last.gcd(num) == 1
+      end
+      Rational(*numbers)
+    end
+
+    def random_prime(bits)
+      # The OpenSSL library only generates random primes from 16 bits on
+      # The 3513 is the first 16-bit number
+      # which means there are 3512 primes under 16 bits in length
+      # Therefore for allowing values for the parameter 'bits' between 2 and 15,
+      # we generate all primes from 2 to 15 bits using Ruby's Prime library
+      # and select only those with bit length equal to the value of 'bits'
+      # so we sample one element
+      # We only do this if the value of 'bits' is less than 16, otherwise we
+      # use OpenSSL to generate the prime
+      if bits >= 2 && bits < 16
+        primes = Prime.first(3512)
+        primes.select { |p| p.bit_length == bits }.sample
+      elsif bits >= 16
+        OpenSSL::BN.generate_prime(bits).to_i
+      else
+        raise BadBitRangeForRandomPrime, "The bit length must be greater than or equal to 2"
+      end
+    end
+
+    def random_distinct_primes(quantity, bits)
+      primes = [random_prime(bits)]
+      while primes.size < quantity
+        prime = random_prime(bits)
+        primes << prime if prime != primes.last
+      end
+      primes
+    end
+
+    def eea_core(num1, num2, bound = 0)
+      setup = bound.zero? ? [1, 0] : [0, 1]
+      x0, x1, y0, y1 = [num1, num2] + setup
+      i = 1
+      while x1 > bound
+        q = x0 / x1
+        x0, x1 = x1, x0 - (q * x1)
+        y0, y1 = y1, y0 - (q * y1)
+        i += 1
+      end
+      [x0, y0, i, x1, y1]
+    end
+
+    def extended_gcd(num1, num2)
+      if num1.negative?
+        x, y = extended_gcd(-num1, num2)
+        [x, -y]
+      elsif num2.negative?
+        x, y = extended_gcd(num1, -num2)
+        [x, y]
+      else
+        x, y = eea_core(num1, num2)
+        [x, y]
+      end
+    end
+
+    def mod_inverse(num, mod)
+      x, y, = extended_gcd(num, mod)
+      raise ZeroDivisionError, "#{num} has no inverse modulo #{mod}" unless x == 1
+
+      y % mod
+    end
+  end
+end

data/lib/hensel_code/truncated_finite_padic_expansion.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module HenselCode
+  # truncated finite p-adic expansion hensel code class
+  class TruncatedFinitePadicExpansion
+    include Tools
+    include TFPEVerifier
+
+    attr_accessor :prime, :exponent, :rational, :hensel_code, :n
+    private :prime=, :exponent=, :rational=, :hensel_code=
+
+    def initialize(prime, exponent, number)
+      @prime = prime
+      @exponent = exponent
+      @n = Integer.sqrt((modulus - 1) / 2)
+
+      valid_number?(number)
+      encode
+    end
+
+    def modulus
+      prime**exponent
+    end
+
+    def numerator
+      rational.numerator
+    end
+
+    def denominator
+      rational.denominator
+    end
+
+    def to_r
+      decode
+      rational
+    end
+
+    def to_i
+      hensel_code
+    end
+
+    def to_s
+      hensel_code.to_s
+    end
+
+    def replace_prime(new_prime)
+      self.prime = new_prime
+      encode
+      decode
+      self
+    end
+
+    def replace_exponent(new_exponent)
+      self.exponent = new_exponent
+      encode
+      decode
+      self
+    end
+
+    def replace_rational(new_rational)
+      self.rational = new_rational
+      encode
+      decode
+      self
+    end
+
+    def replace_hensel_code(new_hensel_code)
+      self.hensel_code = new_hensel_code
+      decode
+      encode
+      self
+    end
+
+    def +(other)
+      valid?(other)
+      self.class.new prime, exponent, (hensel_code + other.hensel_code) % modulus
+    end
+
+    def -(other)
+      valid?(other)
+      self.class.new prime, exponent, (hensel_code - other.hensel_code) % modulus
+    end
+
+    def *(other)
+      valid?(other)
+      self.class.new prime, exponent, (hensel_code * other.hensel_code) % modulus
+    end
+
+    def /(other)
+      valid?(other)
+      h2_hensel_code_inverse = mod_inverse(other.hensel_code, modulus)
+      self.class.new prime, exponent, (hensel_code * h2_hensel_code_inverse) % modulus
+    end
+
+    def inspect
+      "[HenselCode: #{hensel_code}, prime: #{prime}, exponent: #{exponent}, modulus: #{modulus}]"
+    end
+
+    private
+
+    def valid_number?(number)
+      case number
+      when Rational
+        @rational = number
+      when Integer
+        @hensel_code = number
+        decode
+      else
+        raise WrongHenselCodeInputType, "number must be a Rational or an\
+                                        Integer object and it was a #{number.class}"
+      end
+    end
+
+    def encode
+      denominator_inverse = mod_inverse(denominator, modulus)
+      @hensel_code = (numerator * denominator_inverse) % modulus
+    end
+
+    def decode
+      eea_vars = eea_core(modulus, hensel_code, n)
+      i, x, y = eea_vars[2..4]
+      @rational = Rational(*[x, y].map { |e| ((-1)**(i + 1)) * e })
+    end
+  end
+end

data/lib/hensel_code/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HenselCode
+  VERSION = "0.1.0"
+end

data/lib/hensel_code.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "hensel_code/version"
+require "prime"
+require "openssl"
+
+# Main classes definitions and loadings
+module HenselCode
+  class Error < StandardError; end
+  class BadBitRangeForRandomPrime < StandardError; end
+  class WrongHenselCodeInputType < StandardError; end
+  class HenselCodesWithDifferentPrimes < StandardError; end
+  class HenselCodesWithDifferentPrimesAndExponents < StandardError; end
+  class HenselCodesWithDifferentExponents < StandardError; end
+  class IncompatibleOperandTypes < StandardError; end
+
+  autoload  :Tools,                           "hensel_code/tools"
+  autoload  :TFPEVerifier,                    "hensel_code/tfpe_verifier"
+  autoload  :TruncatedFinitePadicExpansion,   "hensel_code/truncated_finite_padic_expansion"
+
+  # aliases for classes with long names
+  TFPE = TruncatedFinitePadicExpansion
+  HCWDPAE = HenselCodesWithDifferentPrimesAndExponents
+end

data/sig/hensel_code.rbs

@@ -0,0 +1,4 @@
+module HenselCode
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: hensel_code
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David William Silva
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-03-03 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby library for homomorphically representing rational numbers as integers.
+email:
+- contact@davidwsilva.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- codecov
+- lib/hensel_code.rb
+- lib/hensel_code/tfpe_verifier.rb
+- lib/hensel_code/tools.rb
+- lib/hensel_code/truncated_finite_padic_expansion.rb
+- lib/hensel_code/version.rb
+- sig/hensel_code.rbs
+homepage: https://github.com/davidwilliam/hensel_code
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/davidwilliam/hensel_code
+  source_code_uri: https://github.com/davidwilliam/hensel_code
+  changelog_uri: https://github.com/davidwilliam/hensel_code/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Homomorphic encoding of rational numbers.
+test_files: []