{"id":13484539,"url":"https://github.com/jzakiya/primes-utils","last_synced_at":"2025-03-27T16:30:56.926Z","repository":{"id":29730484,"uuid":"33273743","full_name":"jzakiya/primes-utils","owner":"jzakiya","description":"primes-utils rubygem","archived":false,"fork":false,"pushed_at":"2016-01-05T20:03:15.000Z","size":36,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-30T18:42:43.361Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jzakiya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-01T21:22:54.000Z","updated_at":"2022-06-19T17:12:16.000Z","dependencies_parsed_at":"2022-07-24T16:32:01.857Z","dependency_job_id":null,"html_url":"https://github.com/jzakiya/primes-utils","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzakiya%2Fprimes-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzakiya%2Fprimes-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzakiya%2Fprimes-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzakiya%2Fprimes-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jzakiya","download_url":"https://codeload.github.com/jzakiya/primes-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245882302,"owners_count":20687862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:25.822Z","updated_at":"2025-03-27T16:30:56.614Z","avatar_url":"https://github.com/jzakiya.png","language":"Ruby","funding_links":[],"categories":["Scientific"],"sub_categories":[],"readme":"# primes-utils\n\n## Introduction\n\n`primes-utils` is a Rubygem which provides a suite of extremely fast utility methods for testing and generating primes.\n\nFor details on the Math and Code used to implement them see:\n\n`PRIMES-UTILS HANDBOOK`\n\nNow available and `FREE` to view and download at:\n\nhttps://www.scribd.com/doc/266461408/Primes-Utils-Handbook\n\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```\ngem 'primes-utils'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install primes-utils\n\nThen require as:\n\n    require 'primes/utils'\n\n## Methods\n\n**prime?**\n\nDetermine if the absolute value of an integer is prime.  Return 'true' or 'false'.\nThis replaces the `prime?` method  in the `prime.rb` standard library.\n\n```\n101.prime? =\u003e true\n100.prime? =\u003e false\n-71.prime? =\u003e true\n0.prime? =\u003e false\n1.prime? =\u003e false\n```\n\n**primemr?(k=20)**\n\nUsing Miller-Rabin primality test for integers, return 'true' or 'false'.\nMiller-Rabin [6] is super fast, but probabilistic (not deterministic), primality test.\nThe reliability can be increased by increasing the default input parameter of k=20.\n\n```\n1111111111111111111.primemr? =\u003e true\n1111111111111111111.primemr? 50  =\u003e true\n1111111111111111111.primemr?(50) =\u003e true\n11111111111111111111.primemr? =\u003e false\n-3333333333333333333.primemr? =\u003e false\nn=10**1700; (n+469).primemr? =\u003e true\n0.primemr? =\u003e false\n1.primemr? =\u003e false\n```\n\n**factors(p=13) or prime_division(p=13)**\n\nDetermine the prime factorization of the absolute value of an integer.\nThis replaces the `prime_division` method in the `prime.rb` standard library.\nOutput is array of arrays of factors and exponents: [[p1,e1],[p2,e2]..[pn,en]].\nDefault Strictly Prime (SP) Prime Generator (PG) used here is P13.\nCan change SP PG used on input. Acceptable primes range: [3 - 19].\n\n```\n1111111111111111111.prime_division =\u003e [[1111111111111111111, 1]]\n11111111111111111111.prime_division  =\u003e [[11, 1], [41, 1], [101, 1], [271, 1], [3541, 1], [9091, 1], [27961, 1]]\n123456789.factors =\u003e [[3, 2], [3607, 1], [3803, 1]]\n123456789.factors 17 =\u003e [[3, 2], [3607, 1], [3803, 1]]\n123456789.factors(17) =\u003e [[3, 2], [3607, 1], [3803, 1]]\n-12345678.factors =\u003e [[2, 1], [3, 2], [47, 1], [14593, 1]]\n0.factors =\u003e []\n1.factors =\u003e []\n```\n\n**primes(start=0), primesf(start=0), primesmr(start=0)**\n\nReturn an array of primes within the absolute value range `(|start| - |end|)`.\nThe order of the range doesn't matter if both given: `start.primes end  \u003c=\u003e end.prime start`.\nIf only one parameter used, then all the primes up to that number will be returned.\nSee `PRIMES-UTILS HANDBOOK` for details on best use practices.\nAlso see `Error Handling`.\n\n```\n50.primes =\u003e [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47]\n50.primesf 125 =\u003e [53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113]\n300.primes 250 =\u003e [251, 257, 263, 269, 271, 277, 281, 283, 293]\nn=10**100; (n-250).primesmr(n+250) =\u003e []\n541.primes.size =\u003e 100\n1000.primes(5000).size =\u003e 501\n(prms = 1000000.primes(1000100)).size =\u003e 6\nprms.size =\u003e 6\nprms =\u003e [1000003, 1000033, 1000037, 1000039, 1000081, 1000099]\n-10.primes -50  =\u003e [11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47]\nn=10**20; n.primes n+n  -\u003e ERROR1: range size too big for available memory. =\u003e nil\nn=10**20; n.primes 100  -\u003e ERROR2: end_num too big for available memory. =\u003e nil\nn=10**8;  (25*n).primes -\u003e ERROR3: not enough memory to store all primes in output array. =\u003e nil\n0.primesf  =\u003e []\n1.primesmr =\u003e []\n```\n\n**primescnt(start=0), primescntf(start=0), primescntmr(start=0)**\n\nProvide count of primes within the absolute value range `(|start| - |end|)`.\nThe order of the range doesn't matter if both given: `start.primes end  \u003c=\u003e end.prime start`.\nIf only one parameter used, the count of all the primes up to that number will be returned.\nSee `PRIMES-UTILS HANDBOOK` for details on best use practices.\nAlso see `Error Handling`.\n\n```\n100001.primescnt =\u003e 9592\n100002.primescnt =\u003e 9592\n100003.primescnt =\u003e 9593\n100000.primescntf 100500 =\u003e 40\nn=10**400; (n-500).primescntmr(n+500) =\u003e 1\n-10.primescnt -50  =\u003e 11\nn=10**20; n.primescnt n+n -\u003e ERROR1: range size too big for available memory. =\u003e nil\nn=10**20; n.primescnt 100 -\u003e ERROR2: end_num too big for available memory. =\u003e nil\nn=10**8; (25*n).primescnt =\u003e 121443371\n0.primescntf  =\u003e 0\n1.primescntmr =\u003e 0\n```\n\n**primenth(p=7) or nthprime(p=7)**\n\nReturn the value of the (absolute value of) nth prime.\nDefault Strictly Prime (SP) Prime Generator (PG) is adaptively selected.\nCan change SP PG used on input. Acceptable primes range: [3 - 13].\nIndexed nth primes now upto 2.01 billionth.\nAlso see `Error Handling`.\n\n```\n1000000.primenth =\u003e 15485863\n1500000.nthprime =\u003e 23879519\n2000000.nthprime 11 =\u003e 32452843\n-500000.nthprime =\u003e 7368787\n1122951705.nthprime =\u003e 25741879847\nn = 10**11; n.primenth -\u003e ERROR1: range size too big for available memory. =\u003e nil\n0.nthprime =\u003e 0\n1.primenth =\u003e 2\n```\n\n**primes_utils**\n\nDisplays a list of all the `primes-utils` methods available for your system.\nUse as `n.primes_utils` where n is any `class Integer` value.\n\n```\n0.primes_utils =\u003e \"prime? primemr? primes primesf primesmr primescnt primescntf primescntmr primenth|nthprime factors|prime_division primes_utils\"\n```\n\n## Error Handling\nStarting with 2.2.0, error handling has been implemented to gracefully fail when array creation requires more memory than available.\nThis occurs when the range size, or end_num, need arrays greater than the amount of avalable memory. The first case shows the message\n`ERROR1: range size too big for available memory.` and the second case `ERROR2: end_num too big for available memory.`\nThe affected methods are `primes`, `primescnt`, and `nthprime|primenth`.\n`nthprime|primenth` also displays the error message `\u003cpcnt\u003e not enough primes, approx nth too small.`\n(`\u003cpcnt\u003e` is computed count of primes) when the computed approx_nth value is \u003c nth value (though this should never happen by design).\nWith 2.4.0 error handling was added to `primes` that catches the error and displays message `ERROR3: not enough memory to store all primes in output array.`.\nFor all errors, the return value for each method is `nil`.\n\nThere is also the rare possibility you could get a `NoMemoryError: failed to allocate memory` for the methods \n`primesf` and `primesmr` if their list of numerated primes is bigger than the amount of available system memory needed to store them. \nIf those methods are used as designed these errors won't occur, so the extra code isn't justified for them.\nIf they occur you will know why now.\n\nThis behavior is referenced to MRI Ruby.\n\n## Coding Implementations\nThe methods `primemr?`, `nthprime|primenth`, `primes`, `primescnt`, `primesmr`, and `primescnt` are coded in pure ruby.\nThe methods `prime?` and `prime_division|factors` have two implementations.\nEach has a pure ruby implementation, and a hybrid implementation using the Unix cli command `factor` if its available on the host OS. \nThe methods `primesf` and `primescntf` use the `factor` version of `prime?` and are created if it exits.\n`factor` [5] is an extremely fast C coded factoring algorithm, part of the GNU Core Utilities package [4].\n\nUpon loading, the gem tests if the command `factor` exists on the host OS.\nIf so, it performs a system call to it within `prime?` and `prime_division|factors`, which uses its output.\nIf not, each method uses a fast pure ruby implementation based on the Sieve of Zakiya (SoZ)[1][2][3].\nNew in 2.2.0, upon loading with Ruby 1.8 `require 'rubygems'` is invoked to enable installing gems.\n\nAll the `primes-utils` methods are `instance_methods` for `class Integer`.\n\n## History\n```\n2.7.0 – more tweaking adaptive pg selection ranges in select_pg; coded using between? instead of cover?\n2.6.0 – much, much better adaptive pg selection algorithm used in select_pg\n2.5.1 – corrected minor error in select_pg\n2.5.0 – 9 more index primes under the 110-millionth in nths; fixed Ruby 1.8 incompatibility in primes;\n        better|simpler technique for select_pg, significant speed increases for large ranges; used now\n        in all sozcore2 client methods primes, primescnt and primenth|nthprime; more code cleanups\n2.4.0 – fixed error in algorithm when ks resgroup ≤ sqrt(end_num) resgroup; algorithm now split\n        arrays when start_num \u003e sqrt(end_num) in sozcore2, whose code also signficantly optimized,\n        with API change adding pcs2start value to output parameters to use in primenth, which changed\n        to use it; ruby idiom code opt for set_start_value; consolidated pcs_to_num | pcs_to_start_num\n        functions into one new pcs_to_num, with associated changes in sozcore1|2; primes|cnt also\n        significantly faster resulting from sozcore2 changes; massive code cleanups all-arround; added\n        private methods select_pg (to adaptively select the pg used in primes), and array_check (used in\n        sozcore2 to catch array creation out-of-memory errors)\n2.3.0 – primescnt now finds primes upto some integer much faster, and for much larger integers\n        increased index nth primes to over 2 billionth; used in nthprime|primenth and primescnt\n2.2.0 – for sozcore2: refactored to include more common code; changed output api; added memory\n        error messages when prms and prms_range arrays creation fails; for primenth: used new\n        function to compute parameter b and removed ceiling for it; increased number of index primes\n        in nths; primes, primescnt, and primenth|nthprime also refactored, will use all available mem\n2.1.0 – changed default PG in primes and primescnt from P13 to P5, significantly faster\n2.0.0 – new methods primesf, primesmr, primescnt, primescntf, primescntmr, primes_utils\n        also improved mem efficiency/speed and extended range for primes and primenth\n        changed default PG in nthprime|primenth from P11 to P7, major refactoring of all methods\n1.1.1 – more efficient/faster code to count up to nth prime in primenth\n1.1.0 – new nth prime approximation method in primenth\n1.0.6 – fixed n=1 check error for prime?\n1.0.5 – minor bug fix\n1.0.4 – fixed n=0 case for primenth; fixed subtle bug in primes, refactored to generalize code\n1.0.3 – minor bug fix\n1.0.2 – directly test for cli command factor on installed platform at start\n1.0.1 – check if using Ruby 1.8 at start, if so, require 'rational' library for gcd method\n1.0.0 – initial release April 1, 2015 with methods prime?, primemr?, primes, prime_division|factors, primenth|nthprime\n```\n\n## Author\nJabari Zakiya\n\n## References\n[1]https://www.scribd.com/doc/150217723/Improved-Primality-Testing-and-Factorization-in-Ruby-revised\n[2]https://www.scribd.com/doc/228155369/The-Segmented-Sieve-of-Zakiya-SSoZ\n[3]https://www.scribd.com/doc/73385696/The-Sieve-of-Zakiya\n[4]https://en.wikipedia.org/wiki/GNU_Core_Utilities\n[5]https://en.wikipedia.org/wiki/Factor_(Unix)\n[6]https://en.wikipedia.org/wiki/Miller-Rabin_primality_test\n\n## License\nGPLv2+\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzakiya%2Fprimes-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjzakiya%2Fprimes-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzakiya%2Fprimes-utils/lists"}