ModularInverse
A fast and efficient Elixir library for calculating modular multiplicative inverses.
The modular multiplicative inverse of an integer a
modulo m
is an integer x
such that (a * x) mod m = 1
. This library provides a robust implementation using the Extended Euclidean Algorithm.
Installation
The package can be installed
by adding modular_inverse
to your list of dependencies in mix.exs
:
def deps do
[
{:modular_inverse, "~> 1.0"}
]
end
Usage
Basic Usage
# Calculate the modular inverse of 3 modulo 11
iex> ModularInverse.of(3, 11)
4
# Verify the result: (3 * 4) mod 11 = 12 mod 11 = 1
iex> rem(3 * 4, 11)
1
# Another example
iex> ModularInverse.of(7, 13)
2
iex> rem(7 * 2, 13)
1
Error Handling
When the modular inverse does not exist (i.e., when a
and m
are not coprime), the function raises a RuntimeError
:
iex> ModularInverse.of(4, 8)
** (RuntimeError) The inverse of the given arguments does not exist, since they are not mutually prime.
Mathematical Background
What is a Modular Multiplicative Inverse?
Given integers a
and m
, the modular multiplicative inverse of a
modulo m
is an integer x
such that:
(a * x) mod m = 1
When Does It Exist?
The modular multiplicative inverse exists if and only if a
and m
are coprime (i.e., their greatest common divisor is 1).
Examples
- For
a = 3
andm = 11
: The inverse is4
because(3 * 4) mod 11 = 12 mod 11 = 1
- For
a = 7
andm = 13
: The inverse is2
because(7 * 2) mod 13 = 14 mod 13 = 1
- For
a = 4
andm = 8
: No inverse exists becausegcd(4, 8) = 4 ≠ 1
Algorithm
This library uses the Extended Euclidean Algorithm to efficiently compute modular inverses. The algorithm:
- Computes the greatest common divisor (GCD) of
a
andm
- If the GCD is 1, calculates the Bézout coefficients
- Uses the coefficients to construct the modular inverse
- Normalizes the result to the smallest non-negative representative
Performance
- Time Complexity: O(log min(a, m))
- Space Complexity: O(1)
This makes it efficient even for very large numbers.
API Reference
ModularInverse.of(a, m)
Calculates the modular multiplicative inverse of a
modulo m
.
Parameters
a
- The integer for which to find the modular inversem
- The modulus (must be positive)
Returns
non_neg_integer()
- The modular multiplicative inverse ofa
modulom
Raises
RuntimeError
- When the modular inverse does not exist (whena
andm
are not coprime)
Examples
iex> ModularInverse.of(3, 11)
4
iex> ModularInverse.of(7, 13)
2
iex> ModularInverse.of(1, 5)
1
Applications
Modular multiplicative inverses are fundamental in many areas of mathematics and computer science:
- Cryptography: RSA encryption, elliptic curve cryptography
- Number Theory: Solving linear congruences
- Computer Science: Hash functions, checksums
- Algebra: Working in finite fields
Testing
The library includes comprehensive randomized testing to ensure correctness across a wide range of inputs. The test suite validates the mathematical property that (a * inverse) mod m = 1
for all valid inputs.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
Copyright (c) 2025 University of Kitakyushu
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/modular_inverse.