{"id":16661391,"url":"https://github.com/bodigrim/mod","last_synced_at":"2025-04-08T04:17:17.237Z","repository":{"id":35799545,"uuid":"219241872","full_name":"Bodigrim/mod","owner":"Bodigrim","description":"Modular arithmetic, promoting moduli to the type level","archived":false,"fork":false,"pushed_at":"2025-01-18T10:55:52.000Z","size":85,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T09:21:26.799Z","etag":null,"topics":["exponentiation","finite-numbers","inversion","modular-arithmetic","modular-exponentiation","modular-inversions","moduli","number-theory"],"latest_commit_sha":null,"homepage":"http://hackage.haskell.org/package/mod","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bodigrim.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-03T02:37:51.000Z","updated_at":"2025-01-18T10:55:54.000Z","dependencies_parsed_at":"2024-04-28T20:50:28.988Z","dependency_job_id":null,"html_url":"https://github.com/Bodigrim/mod","commit_stats":{"total_commits":89,"total_committers":3,"mean_commits":"29.666666666666668","dds":0.0786516853932584,"last_synced_commit":"a1853c2692357642023d355092a8939345e23d55"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bodigrim%2Fmod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bodigrim%2Fmod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bodigrim%2Fmod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bodigrim%2Fmod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bodigrim","download_url":"https://codeload.github.com/Bodigrim/mod/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773721,"owners_count":20993639,"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":["exponentiation","finite-numbers","inversion","modular-arithmetic","modular-exponentiation","modular-inversions","moduli","number-theory"],"created_at":"2024-10-12T10:34:49.064Z","updated_at":"2025-04-08T04:17:17.196Z","avatar_url":"https://github.com/Bodigrim.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mod [![Hackage](https://img.shields.io/hackage/v/mod.svg)](https://hackage.haskell.org/package/mod) [![Stackage LTS](https://www.stackage.org/package/mod/badge/lts)](https://www.stackage.org/lts/package/mod) [![Stackage Nightly](https://www.stackage.org/package/mod/badge/nightly)](https://www.stackage.org/nightly/package/mod)\n\n[Modular arithmetic](https://en.wikipedia.org/wiki/Modular_arithmetic),\npromoting moduli to the type level, with an emphasis on performance.\nOriginally a part of the [arithmoi](https://hackage.haskell.org/package/arithmoi) package.\n\n```haskell\n\u003e :set -XDataKinds\n\u003e 4 + 5 :: Mod 7\n2\n\u003e 4 - 5 :: Mod 7\n6\n\u003e 4 * 5 :: Mod 7\n6\n\u003e 4 / 5 :: Mod 7\n5\n\u003e 4 ^ 5 :: Mod 7\n2\n```\n\n## Competitors\n\nThere are other Haskell packages, employing the very same idea of moduli on the type level,\nnamely `modular`, `modular-arithmetic` and `finite-field`. One can also use `finite-typelits`,\nwhich covers some elementary modular arithmetic as well.\nUnfortunately, all of them fall behind\nin terms of performance. Here is a brief comparison:\n\n| Discipline  | `mod`  | `modular` | `modular-arithmetic` | `finite-typelits` | `finite-field`\n| :---------- | :----: | :-------: | :------------------: | :---------------: | :------------:\n| Addition    | Fast   | Slow      | Slow                 | Slow              | Slow\n| Small `(*)` | Fast   | Slow      | Slow                 | Slow              | Slow\n| Inversion   | Fast   | N/A       | Slow                 | N/A               | Slow\n| Power       | Fast   | Slow      | Slow                 | Slow              | Slow\n| Overflows   | Safe   | Safe      | Unsafe               | Safe              | Safe\n\n* __Addition.__\n  All competing implementations of\n  the modular addition involve divisions, while `mod` completely avoids\n  this costly operation. This makes a difference even for small numbers;\n  e. g., `sum [1..10^7]` becomes 5x faster. For larger integers the speed up\n  is even more significant, because the computational complexity of division is not linear.\n\n* __Small `(*)`.__\n  When a modulus fits in a machine word (which is quite a common case on 64-bit architectures),\n  `mod` implements the modular multiplication as a couple of CPU instructions\n  and neither allocates intermediate arbitrary-precision values,\n  nor calls `libgmp` at all. For computations like `product [1..10^7]`\n  this gives a 3x boost to performance\n  in comparison to other libraries.\n\n* __Inversion.__\n  This package relies on `libgmp` for modular inversions.\n  Even for small arguments it is about 5x faster than\n  the native implementation of modular inversion\n  in `modular-arithmetic`.\n\n* __Power.__\n  This package relies on `libgmp` for modular exponentiation.\n  Even for small arguments it is about 2x faster than competitors.\n\n* __Overflows.__\n  At first glance `modular-arithmetic` is more flexible than `mod`,\n  because it allows to specify the underlying representation of a modular residue,\n  e. g., `Mod Integer 100`, `Mod Int 100`, `Mod Word8 100`. We argue that this is\n  a dangerous freedom, vulnerable to overflows.\n  For instance, `20 ^ 2 :: Mod Word8 100` returns `44` instead of the expected `0`.\n  Even less expected is that `50 :: Mod Word8 300` appears to be `6`\n  (remember that type-level numbers are always `Natural`).\n\n### What is the difference between `mod` and `finite-typelits`?\n\n`mod` is specifically designed to represent modular residues\nfor mathematical applications (__wrapping-around__ finite numbers) and\nprovides modular inversion and exponentiation.\n\nThe main focus of `finite-typelits` is on __non-wrapping-around__ finite numbers,\nlike indices of arrays in `vector-sized`.\nIt features a `Num` instance only for the sake of overloading numeric literals.\nThere is no lawful way to define `Num` except modular arithmetic,\nbut from `finite-typelits`' viewpoint this is a by-product.\n\n## Citius, altius, fortius!\n\nIf you are looking for an ultimate performance\nand your moduli fit into `Word`,\ntry `Data.Mod.Word`,\nwhich is a drop-in replacement of `Data.Mod`,\noffering better performance and much less allocations.\n\n## Benchmarks\n\nHere are some relative benchmarks (less is better),\nwhich can be reproduced by running `cabal bench`.\n\n| Discipline  | `Data.Mod.Word`  | `Data.Mod`  | `modular` | `modular-arithmetic` | `finite-typelits` | `finite-field`\n| :---------- | :--------------: | :---------: | :-------: | :------------------: | :---------------: | :------------:\n| Sum         |   0.44x          |    1x       |  16.6x    |      8.9x            |  14.7x            | 14.2x\n| Product     |   0.95x          |    1x       |  7.8x     |      4.5x            |  7.0x             | 7.0x\n| Inversion   |   0.54x          |    1x       |  N/A      |      3.2x            |  N/A              | 1.8x\n| Power       |   0.29x          |    1x       |  2.0x     |      1.2x            |  1.4x             | 1.5x\n\n## What's next?\n\nThis package was cut out of [`arithmoi`](https://hackage.haskell.org/package/arithmoi)\nto provide modular arithmetic\nwith a light dependency footprint. This goal certainly limits the scope of the API\nto the bare minimum. If you need more advanced tools\n(the Chinese remainder theorem, cyclic groups, modular equations, etc.)\nplease refer to the [Math.NumberTheory.Moduli](https://hackage.haskell.org/package/arithmoi/docs/Math-NumberTheory-Moduli.html) module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbodigrim%2Fmod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbodigrim%2Fmod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbodigrim%2Fmod/lists"}