Metadata-Version: 2.4
Name: dolphinmath
Version: 0.0.3
Summary: Simple math helper library made by a student
Author-email: Peddakotla Karthikeya <karthikeyapeddakotla@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/dolphinmath/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# DolphinMath

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests Passed](https://img.shields.io/badge/tests-passed-brightgreen.svg)]()

`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](#installation)
2. [Quick Start](#quick-start)
3. [Module Reference & Examples](#module-reference--examples)
   - [Numbers Module (`dolphinmath.numbers`)](#numbers-module-dolphinmathnumbers)
   - [Primes Module (`dolphinmath.prime`)](#primes-module-dolphinmathprime)
   - [Sequences Module (`dolphinmath.sequences`)](#sequences-module-dolphinmathsequences)
   - [Series Module (`dolphinmath.series`)](#series-module-dolphinmathseries)
   - [Statistics Module (`dolphinmath.stats`)](#statistics-module-dolphinmathstats)
4. [Development & Testing](#development--testing)
5. [License](#license)

---

## Installation

To install `DolphinMath` run:

```bash
pip install dolphinmath
```
Upgrade to the latest version:
```bash
pip install --upgrade dolphinmath
```

---

## Quick Start

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

```python
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` |

```python
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)]` |

```python
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]` |

```python
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` |

```python
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)` |

```python
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:
   ```bash
   python -m tests.test_numbers
   python -m tests.test_prime
   ```
2. Or use pytest if installed:
   ```bash
   python -m pytest
   ```

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
