dolphinmath 0.0.3

Simple math helper library made by a student

DolphinMath

DolphinMath is a lightweight, high-performance, and comprehensive Python helper library designed for mathematical and statistical operations. It provides convenient functions for number theory, sequences, progressions, prime number computations, and statistical summaries.

---

Table of Contents

1. Installation
2. Quick Start
3. Module Reference & Examples
   • Numbers Module (dolphinmath.numbers)
   • Primes Module (dolphinmath.prime)
   • Sequences Module (dolphinmath.sequences)
   • Series Module (dolphinmath.series)
   • Statistics Module (dolphinmath.stats)
4. Development & Testing
5. License

---

Installation

To install DolphinMath run:

pip install dolphinmath

Upgrade to the latest version:

pip install --upgrade dolphinmath

---

Quick Start

All functions are exposed at the package root level for easy import:

import dolphinmath as dm

# Basic calculations
print(dm.gcd(24, 36))          # Output: 12
print(dm.is_prime(97))         # Output: True
print(dm.fibonacci(8))         # Output: [0, 1, 1, 2, 3, 5, 8, 13]
print(dm.quartiles([1, 2, 3, 4, 5, 6, 7, 8])) # Output: (2.75, 4.5, 6.25)

---

Module Reference & Examples

Numbers Module (dolphinmath.numbers)

Provides basic number theory operations and properties of integers.

Function	Description	Example
gcd(a, b)	Great Common Divisor of $a$ and $b$.	dm.gcd(12, 18) $\rightarrow$ 6
hcf(a, b)	Highest Common Factor (alias of gcd).	dm.hcf(12, 18) $\rightarrow$ 6
lcm(a, b)	Least Common Multiple of $a$ and $b$.	dm.lcm(12, 18) $\rightarrow$ 36
prime_factors(n)	Prime factors of $n \ge 2$ with duplicates.	dm.prime_factors(12) $\rightarrow$ [2, 2, 3]
factors(n)	All positive factors of $n$ ($O(\sqrt{n})$ speed).	dm.factors(12) $\rightarrow$ [1, 2, 3, 4, 6, 12]
is_perfect(n)	Returns True if $n$ is equal to sum of proper factors.	dm.is_perfect(28) $\rightarrow$ True
is_armstrong(n)	Returns True if sum of digits to power length is $n$.	dm.is_armstrong(153) $\rightarrow$ True
is_even(n)	Returns True if $n$ is even.	dm.is_even(14) $\rightarrow$ True
is_odd(n)	Returns True if $n$ is odd.	dm.is_odd(15) $\rightarrow$ True
reverse_number(n)	Reverses digits of $n$, preserving signs.	dm.reverse_number(-123) $\rightarrow$ -321
sum_of_digits(n)	Returns sum of digits of the absolute value of $n$.	dm.sum_of_digits(-405) $\rightarrow$ 9
palindrome_number(n)	Returns True if $n$ is palindromic.	dm.palindrome_number(121) $\rightarrow$ True

import dolphinmath as dm

# Checking number properties
print(dm.is_even(42))            # True
print(dm.is_odd(42))             # False
print(dm.reverse_number(-809))   # -908
print(dm.sum_of_digits(-405))    # 9
print(dm.palindrome_number(12321))# True

---

Primes Module (dolphinmath.prime)

Optimized utilities for identifying, counting, and generating prime numbers.

Function	Description	Example
is_prime(n)	Check primality of $n$ using $6k \pm 1$ test.	dm.is_prime(97) $\rightarrow$ True
prime_sieve(limit)	Generate primes up to limit (Sieve of Eratosthenes).	dm.prime_sieve(20) $\rightarrow$ [2, 3, 5, 7, 11, 13, 17, 19]
list_primes(a, b)	Find all primes in range $[a, b]$ (inclusive).	dm.list_primes(10, 20) $\rightarrow$ [11, 13, 17, 19]
primes(a, b)	Print all primes in range $[a, b]$ one per line.	dm.primes(1, 5) $\rightarrow$ prints 2, 3, 5
count_primes(a, b)	Count the number of primes in range $[a, b]$.	dm.count_primes(10, 20) $\rightarrow$ 4
prime_count_upto(lim)	Count primes up to a limit using sieve.	dm.prime_count_upto(100) $\rightarrow$ 25
nth_prime(n)	Find the $n$-th prime (optimized PNT bound search).	dm.nth_prime(1000) $\rightarrow$ 7919
next_prime(n)	Find the first prime strictly greater than $n$.	dm.next_prime(5) $\rightarrow$ 7
twin_primes(a, b)	Find all twin prime pairs $(p, p+2)$ in $[a, b]$.	dm.twin_primes(3, 15) $\rightarrow$ [(3, 5), (5, 7), (11, 13)]

import dolphinmath as dm

# Efficient prime generation and checks
print(dm.prime_sieve(30))             # [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
print(dm.twin_primes(1, 20))          # [(3, 5), (5, 7), (11, 13), (17, 19)]
print(dm.nth_prime(500))              # 3571
print(dm.next_prime(14))              # 17

---

Sequences Module (dolphinmath.sequences)

Functions for generating popular mathematical sequences.

Function	Description	Example
factorial(n)	Compute factorial of $n \ge 0$ ($n!$).	dm.factorial(5) $\rightarrow$ 120
fibonacci(n)	Generate first $n$ Fibonacci numbers.	dm.fibonacci(5) $\rightarrow$ [0, 1, 1, 2, 3]
lucas_sequence(n)	Generate first $n$ Lucas numbers ($2, 1, 3, 4, ...$).	dm.lucas_sequence(5) $\rightarrow$ [2, 1, 3, 4, 7]
tribonacci(n)	Generate first $n$ Tribonacci numbers ($0, 0, 1, ...$).	dm.tribonacci(6) $\rightarrow$ [0, 0, 1, 1, 2, 4]

import dolphinmath as dm

# Sequences
print(dm.factorial(6))                # 720
print(dm.fibonacci(8))                # [0, 1, 1, 2, 3, 5, 8, 13]
print(dm.lucas_sequence(6))           # [2, 1, 3, 4, 7, 11]
print(dm.tribonacci(8))               # [0, 0, 1, 1, 2, 4, 7, 13]

---

Series Module (dolphinmath.series)

Progression series calculators and generalized means.

Function	Description	Example
ap_nth(a, d, n)	Calculate the $n$-th term of Arithmetic Progression.	dm.ap_nth(2, 3, 5) $\rightarrow$ 14
ap_sum(a, d, n)	Calculate sum of first $n$ terms of AP.	dm.ap_sum(2, 3, 5) $\rightarrow$ 40.0
gp_nth(a, r, n)	Calculate the $n$-th term of Geometric Progression.	dm.gp_nth(2, 3, 4) $\rightarrow$ 54
gp_sum(a, r, n)	Calculate sum of first $n$ terms of GP.	dm.gp_sum(2, 3, 4) $\rightarrow$ 80.0
harmonic_sum(n)	Sum of first $n$ terms of Harmonic series.	dm.harmonic_sum(3) $\rightarrow$ 1.8333...
arithmetic_mean(ns)	Calculate arithmetic mean of a list of numbers.	dm.arithmetic_mean([1, 2, 3]) $\rightarrow$ 2.0
geometric_mean(ns)	Calculate geometric mean of positive numbers.	dm.geometric_mean([2, 8]) $\rightarrow$ 4.0

import dolphinmath as dm

# Series and means
print(dm.ap_sum(1, 2, 10))            # Sum: 1 + 3 + ... + 19 = 100.0
print(dm.gp_nth(3, 2, 5))             # 5th term of 3, 6, 12, 24, 48 = 48
print(dm.harmonic_sum(4))             # 1 + 1/2 + 1/3 + 1/4 = 2.083333333333333
print(dm.geometric_mean([1, 10, 100]))# 10.0

---

Statistics Module (dolphinmath.stats)

Statistical functions for descriptive data analysis.

Function	Description	Example
mean(nums)	Calculate the arithmetic mean of a list.	dm.mean([1, 2, 3, 4, 5]) $\rightarrow$ 3.0
median(nums)	Calculate the median of a list.	dm.median([1, 2, 3, 4]) $\rightarrow$ 2.5
mode(nums)	Returns a list of modes (highest frequency).	dm.mode([1, 2, 2, 3]) $\rightarrow$ [2]
variance(nums, sample)	Calculate sample or population variance.	dm.variance([1, 2, 3, 4]) $\rightarrow$ 1.6666...
standard_deviation(...)	Calculate sample or population standard deviation.	dm.standard_deviation([1, 2, 3, 4]) $\rightarrow$ 1.2909...
range_value(nums)	Difference between max and min in a list.	dm.range_value([1, 2, 9, 4]) $\rightarrow$ 8
quartiles(nums)	Returns a tuple (Q1, Q2, Q3) using interpolation.	dm.quartiles([1, 2, 3, 4, 5, 6, 7, 8]) $\rightarrow$ (2.75, 4.5, 6.25)

import dolphinmath as dm

data = [10, 20, 20, 30, 40, 50, 60, 70]

print(dm.mean(data))                  # 37.5
print(dm.median(data))                # 35.0
print(dm.mode(data))                  # [20]
print(dm.variance(data, sample=True)) # 450.0
print(dm.standard_deviation(data))    # 21.213203435596427
print(dm.range_value(data))           # 60
print(dm.quartiles(data))             # (20.0, 35.0, 52.5)

---

Development & Testing

We use standard unit tests. To run tests:

1. Run testing modules directly:

   python -m tests.test_numbers
   python -m tests.test_prime
   

2. Or use pytest if installed:

   python -m pytest
   

---

License

This project is licensed under the MIT License - see the LICENSE file for details.