sperm 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2ef71a04bbb2e84a9baa9d94c78c7d2f0a2d3ac3
+  data.tar.gz: 343595cd65a161078b48c082bdca8bf0f44c17e9
+SHA512:
+  metadata.gz: b674a6080bf35a001cbc34064b0de3de3ac9181d2e52c6039560e03c3678d7c6b5ee2ae05f72946ac76c76d62d05d84c94f34ae66bc0396b1bf19b7d451281aa
+  data.tar.gz: 568b52e9c823c7ca2578133cd733813075e32951e2c0785b9e13b99a46f70e6e7a07e8cebe95b07448773fd4090ab092170b0ec7f82125d7e17d004c64fd0df3

data/.editorconfig

@@ -0,0 +1,12 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,5 @@
+AllCops:
+  Excludes:
+    - vendor/**
+LineLength:
+  Max: 119

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Arthur Khashaev
+
+MIT License
+
+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,53 @@
+# Stupendous Permutations
+**Sperm** is a random permutations generator based on the ideas of group
+theory that allows you to generate very large permutations without extra
+memory consumption.
+
+[![Gem Version](https://badge.fury.io/rb/sperm.png)](https://badge.fury.io/rb/sperm)
+[![Build Status](https://travis-ci.org/Invizory/sperm.png)](https://travis-ci.org/Invizory/sperm)
+[![Code Climate](https://codeclimate.com/github/Invizory/sperm.png)](https://codeclimate.com/github/Invizory/sperm)
+[![Coverage Status](https://coveralls.io/repos/Invizory/sperm/badge.png)](https://coveralls.io/r/Invizory/sperm)
+
+## Installation
+Add this line to your application's Gemfile:
+```ruby
+gem 'sperm'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install sperm
+```
+
+## Usage
+```ruby
+Sperm.rand(5).each { |element| puts element }
+```
+
+This is a shorthand for:
+```ruby
+Sperm::RandomPermutations.new(5).rand.each { |element| puts element }
+```
+
+You can also use your own source of randomness:
+```ruby
+Sperm::RandomPermutations.new(5, Random.new(42))
+Sperm::RandomPermutations.new(10**8, SecureRandom)
+```
+
+## How it works
+### Computational complexity
+Operation                  | Time complexity    | Space complexity
+---------------------------|--------------------|------------------
+Initialization             | O(n/ϕ(n) · log(n)) | O(1)
+Generation of next element | O(1)               | O(1)
+
+## Copyright
+Copyright © 2014 [Arthur Khashaev]. See [LICENSE.txt](LICENSE.txt) for details.
+
+[Arthur Khashaev]: http://khashaev.ru/

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
+
+Rubocop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/sperm

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+require 'sperm'
+require 'optparse'
+
+optparse = OptionParser.new do |opts|
+  opts.banner = "Usage: #{$PROGRAM_NAME} [options] order"
+
+  opts.on_tail '-p', '--permutation ORDER', Integer,
+               'Generate permutation of specified order' do |order|
+    Sperm.rand(order).each { |element| puts element }
+    exit
+  end
+
+  opts.on_tail '-h', '--help', 'Just display this help' do
+    puts opts
+    exit
+  end
+
+  opts.on_tail '-v', '--version', 'Just print the version infomation' do
+    puts "Sperm #{Sperm::VERSION}"
+    exit
+  end
+end
+
+optparse.parse!

data/data/groups.yml

@@ -0,0 +1,55 @@
+-
+  prime: 17
+  generator: 3
+  order_phi: 8
+  order_factors: [2, 2, 2, 2]
+-
+  prime: 107
+  generator: 2
+  order_phi: 52
+  order_factors: [2, 53]
+-
+  prime: 1019
+  generator: 2
+  order_phi: 508
+  order_factors: [2, 509]
+-
+  prime: 10007
+  generator: 5
+  order_phi: 5038
+  order_factors: [2, 5003]
+-
+  prime: 100043
+  generator: 2
+  order_phi: 50020
+  order_factors: [2, 50021]
+-
+  prime: 1000667
+  generator: 2
+  order_phi: 500332
+  order_factors: [2, 500333]
+-
+  prime: 10000223
+  generator: 5
+  order_phi: 5000110
+  order_factors: [2, 5000111]
+-
+  prime: 100000127
+  generator: 5
+  order_phi: 50000062
+  order_factors: [2, 50000063]
+-
+  prime: 1000000007
+  generator: 5
+  order_phi: 500000002
+  order_factors: [2, 500000003]
+-
+  prime: 1000099403
+  generator: 2
+  order_phi: 500049700
+  order_factors: [2, 500049701]
+-
+  prime: 4100000027
+  generator: 2
+  order_phi: 2050000012
+  order_factors: [2, 2050000013]

data/lib/sperm.rb

@@ -0,0 +1,11 @@
+require 'sperm/version'
+require 'sperm/exceptions'
+require 'sperm/random_permutations'
+
+# Sperm is an efficient random permutations generator.
+#
+module Sperm
+  def self.rand(order)
+    RandomPermutations.new(order).rand
+  end
+end

data/lib/sperm/exceptions.rb

@@ -0,0 +1,16 @@
+module Sperm
+  # This runtime error appears when requested permutation order is bigger
+  # than maximum group order in known set of cyclic groups.
+  #
+  class NoSuitableGroup < RuntimeError
+    attr_reader :order
+
+    def initialize(order)
+      @order = order
+    end
+
+    def to_s
+      "no suitable group for permutation of order #{order} found"
+    end
+  end
+end

data/lib/sperm/groups.rb

@@ -0,0 +1,6 @@
+require 'sperm/groups/additive'
+require 'sperm/groups/multiplicative'
+require 'sperm/groups/isomorphism'
+require 'sperm/groups/multiplicative_shuffler'
+require 'sperm/groups/intmod'
+require 'sperm/groups/collection'

data/lib/sperm/groups/additive.rb

@@ -0,0 +1,28 @@
+require 'sperm/groups/intmod'
+
+module Sperm::Groups
+  # Represents (Z/nZ, +) - an additive cyclic group of integers modulo n.
+  #
+  class ZnAdd
+    include Zn
+
+    attr_reader :modulo
+    alias_method :order, :modulo
+
+    def initialize(modulo_factors)
+      @modulo_factors = modulo_factors.uniq
+      @modulo = modulo_factors.inject(1, &:*)
+    end
+
+    def generator?(number)
+      fail ArgumentError, 'not an element' unless include?(number)
+      @modulo_factors.all? { |prime| coprime_with_prime?(number, prime) }
+    end
+
+    private
+
+    def coprime_with_prime?(number, prime)
+      number % prime != 0
+    end
+  end
+end

data/lib/sperm/groups/collection.rb

@@ -0,0 +1,34 @@
+require 'sperm/groups/additive'
+require 'sperm/groups/multiplicative'
+require 'sperm/groups/isomorphism'
+
+require 'ostruct'
+require 'yaml'
+
+module Sperm::Groups
+  # Represents collection of known cyclic groups that can be used
+  # for generating random permutations.
+  #
+  class GroupsCollection
+    def initialize(isomorphisms)
+      @isomorphisms = isomorphisms.sort_by { |isomorphism| isomorphism.order }
+    end
+
+    def find_suitable_isomorphism(order)
+      @isomorphisms.bsearch { |isomorphism| isomorphism.order >= order }
+    end
+
+    def self.load_file(path)
+      array = YAML.load_file(path)
+      isomorphisms = array.map { |hash| OpenStruct.new(hash) }.map do |group|
+        add_group = ZnAdd.new(group.order_factors)
+        mul_group = ZpMul.new(group.prime, group.generator)
+        Isomorphism.new(add_group, mul_group)
+      end
+      new(isomorphisms)
+    end
+
+    DEFAULT_FILE = File.expand_path('../../../../data/groups.yml', __FILE__)
+    DEFAULT = load_file(DEFAULT_FILE)
+  end
+end

data/lib/sperm/groups/intmod.rb

@@ -0,0 +1,9 @@
+module Sperm::Groups
+  # Represents Z/nZ group.
+  #
+  module Zn
+    def include?(element)
+      (0...modulo).include?(element)
+    end
+  end
+end

data/lib/sperm/groups/isomorphism.rb

@@ -0,0 +1,24 @@
+require 'forwardable'
+require 'openssl'
+
+module Sperm::Groups
+  # Provides isomorphism from (Z/(p-1)Z, +) to (Z/pZ \ {0}, *).
+  #
+  class Isomorphism
+    extend Forwardable
+
+    attr_reader :add_group, :mul_group
+    def_delegator :add_group, :order
+
+    def initialize(add_group, mul_group)
+      fail ArgumentError, 'unequal orders' unless add_group.order == mul_group.order
+      @add_group = add_group
+      @mul_group = mul_group
+    end
+
+    def map(number)
+      fail ArgumentError, 'not an element' unless add_group.include?(number)
+      mul_group.generator.to_bn.mod_exp(number, mul_group.modulo).to_i
+    end
+  end
+end

data/lib/sperm/groups/multiplicative.rb

@@ -0,0 +1,34 @@
+require 'sperm/groups/intmod'
+
+module Sperm::Groups
+  # Represents (Z/pZ \ {0}, *) - a multiplicative cyclic group of integers
+  # modulo p.
+  #
+  class ZpMul
+    include Zn
+
+    attr_reader :prime, :generator
+    alias_method :modulo, :prime
+
+    def initialize(prime, generator)
+      @prime = prime
+      @generator = generator
+    end
+
+    def order
+      modulo - 1
+    end
+
+    def produce_cycle(first, multiplier)
+      fail ArgumentError, 'not an element' unless include?(first) && include?(multiplier)
+      Enumerator.new do |yielder|
+        current = first
+        loop do
+          yielder.yield current
+          current = (current * multiplier) % modulo
+          break if current == first
+        end
+      end
+    end
+  end
+end

data/lib/sperm/groups/multiplicative_shuffler.rb

@@ -0,0 +1,35 @@
+module Sperm::Groups
+  # Generates random cyclic representations of (Z/pZ \ {0}, *).
+  #
+  class ZpMulShuffler
+    def initialize(isomorphism, rand_source)
+      @isomorphism, @rand_source = isomorphism, rand_source
+    end
+
+    def rand
+      first = 1 + @rand_source.rand(mul_group.modulo - 1)
+      mul_group.produce_cycle(first, rand_mul_generator).lazy
+    end
+
+    private
+
+    def rand_mul_generator
+      add_gen = rand_add_generator
+      @isomorphism.map(add_gen)
+    end
+
+    def rand_add_generator
+      gen = @rand_source.rand(add_group.modulo)
+      gen = (gen + 1) % add_group.modulo until add_group.generator?(gen)
+      gen
+    end
+
+    def add_group
+      @isomorphism.add_group
+    end
+
+    def mul_group
+      @isomorphism.mul_group
+    end
+  end
+end

data/lib/sperm/random_permutations.rb

@@ -0,0 +1,23 @@
+require 'sperm/groups'
+require 'sperm/exceptions'
+require 'sperm/random_source'
+
+module Sperm
+  # Generates random permutations of given order.
+  #
+  class RandomPermutations
+    attr_reader :order
+
+    def initialize(order, random = Random.new, groups = Groups::GroupsCollection::DEFAULT)
+      isomorphism = groups.find_suitable_isomorphism(order)
+      fail NoSuitableGroup, order unless isomorphism
+      random_source = RandomSource.new(random)
+      @order = order
+      @shuffler = Groups::ZpMulShuffler.new(isomorphism, random_source)
+    end
+
+    def rand
+      @shuffler.rand.select { |element| element.between?(1, order) }.map { |element| element - 1 }
+    end
+  end
+end

data/lib/sperm/random_source.rb

@@ -0,0 +1,19 @@
+module Sperm
+  # Internal wrapper for Random instances and RandomSecure.
+  #
+  class RandomSource
+    include Forwardable
+
+    def initialize(adaptee)
+      @adaptee = adaptee
+
+      %i(rand random_number).each do |method|
+        next unless @adaptee.respond_to? method
+        def_delegator :@adaptee, method, :rand
+        return
+      end
+
+      fail ArgumentError, 'unsupported source of randomness'
+    end
+  end
+end

data/lib/sperm/version.rb

@@ -0,0 +1,5 @@
+# Sperm is an efficient random permutations generator.
+#
+module Sperm
+  VERSION = '0.1.1'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+if ENV['COVERAGE'] || ENV['TRAVIS']
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+    SimpleCov::Formatter::HTMLFormatter,
+    Coveralls::SimpleCov::Formatter
+  ]
+  SimpleCov.start do
+    add_filter '/vendor/'
+    add_filter '/spec/'
+  end
+end
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'sperm'
+
+# Some helpers for Enumerable.
+#
+module Enumerable
+  def permutation?
+    sort.to_a == (0...count).to_a
+  end
+
+  def empty?
+    count == 0
+  end
+end

data/spec/sperm/random_permutations_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+describe Sperm::RandomPermutations do
+  subject { Sperm::RandomPermutations.new(order) }
+
+  describe '#rand' do
+    context 'when order is zero' do
+      let(:order) { 0 }
+      it 'generates an empty permutation' do
+        expect(subject.rand).to be_empty
+      end
+    end
+
+    context 'when order is small' do
+      let(:order) { 42 }
+      it 'generates a permutation' do
+        expect(subject.rand).to be_a_permutation
+      end
+    end
+
+    context 'when order is large' do
+      let(:order) { 10**8 }
+      it 'generates at least first element of permutation' do
+        expect(subject.rand.first).to be_between(0, order - 1)
+      end
+    end
+
+    context 'when order is too large' do
+      let(:order) { 10**100 }
+      it 'raises an error' do
+        expect { subject }.to raise_error Sperm::NoSuitableGroup
+      end
+    end
+  end
+end

data/spec/sperm_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Sperm do
+  it 'has a version number' do
+    expect(Sperm::VERSION).not_to be_nil
+  end
+end

data/sperm.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'sperm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'sperm'
+  spec.version       = Sperm::VERSION
+
+  spec.author        = 'Arthur Khashaev'
+  spec.email         = 'arthur@khashaev.ru'
+
+  spec.summary       = 'Sperm is an efficient random permutations generator'
+  spec.description   = 'Sperm is a random permutations generator ' \
+                       'based on the ideas of group theory ' \
+                       'that allows you to generate stupendous permutations ' \
+                       'without extra memory consumption.'
+
+  spec.homepage      = 'https://github.com/Invizory/sperm'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', "~> 1.5"
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'coveralls'
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: sperm
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Arthur Khashaev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Sperm is a random permutations generator based on the ideas of group
+  theory that allows you to generate stupendous permutations without extra memory
+  consumption.
+email: arthur@khashaev.ru
+executables:
+- sperm
+extensions: []
+extra_rdoc_files: []
+files:
+- .editorconfig
+- .gitignore
+- .rspec
+- .rubocop.yml
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/sperm
+- data/groups.yml
+- lib/sperm.rb
+- lib/sperm/exceptions.rb
+- lib/sperm/groups.rb
+- lib/sperm/groups/additive.rb
+- lib/sperm/groups/collection.rb
+- lib/sperm/groups/intmod.rb
+- lib/sperm/groups/isomorphism.rb
+- lib/sperm/groups/multiplicative.rb
+- lib/sperm/groups/multiplicative_shuffler.rb
+- lib/sperm/random_permutations.rb
+- lib/sperm/random_source.rb
+- lib/sperm/version.rb
+- spec/spec_helper.rb
+- spec/sperm/random_permutations_spec.rb
+- spec/sperm_spec.rb
+- sperm.gemspec
+homepage: https://github.com/Invizory/sperm
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.7
+signing_key: 
+specification_version: 4
+summary: Sperm is an efficient random permutations generator
+test_files:
+- spec/spec_helper.rb
+- spec/sperm/random_permutations_spec.rb
+- spec/sperm_spec.rb