commit bd6037cc52bd57b655b322d56688896f6eabe1b6
parent 46c9665659397bd423f66ff1eb22a0c6c40ff1cc
Author: Amit Dutta <amitdutta4255@gmail.com>
Date: Sun, 17 Aug 2025 19:57:20 +0530
Update README.md
Diffstat:
| M | README.md | | | 253 | +++++++++++++++++++++++++++++++++++-------------------------------------------- |
1 file changed, 113 insertions(+), 140 deletions(-)
diff --git a/README.md b/README.md
@@ -1,12 +1,14 @@
-# Advanced Math Utilities
+# Advanced Math Utilities (adpkg)
-A comprehensive Python package for various mathematical and financial calculations. This package includes modules for:
-- **Finance**: Compound interest
-- **Number Theory**: Prime checking, factorial, permutation, combination
-- **String Manipulation**: String reversal
-- **Matrix Operations**: Addition, multiplication, transpose, determinant
+Welcome! 👋 This package gives you a bunch of handy tools for math, finance, and geometry in Python. You don’t need to be a math expert—just import and use!
+
+It includes modules for:
+- **Finance**: Calculate compound interest easily
+- **Number Theory**: Check primes, factorials, permutations, combinations
+- **Strings**: Reverse words or phrases
+- **Matrices**: Add, multiply, transpose, and find determinants
- **Statistics**: Mean, median, mode
-- **Geometry**: Area of triangle
+- **Geometry**: Triangle area with Heron’s formula
[](https://pypi.org/project/adpkg/)
[](https://pypi.org/project/adpkg/)
@@ -14,217 +16,188 @@ A comprehensive Python package for various mathematical and financial calculatio
---
+## 📑 Table of Contents
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [💰 Finance Module](#-finance-module)
+ - [interest](#interestprime_amount-time_duration_str-n-rate)
+- [🔢 AdCustom Module](#-adcustom-module)
+ - [Number Theory](#number-theory)
+ - [check_prime](#check_primen)
+ - [factorial](#factorialn)
+ - [permutation](#permutationn-r)
+ - [combination](#combinationn-r)
+ - [Strings](#strings)
+ - [string_reverse](#string_reverses)
+ - [Matrices](#matrices)
+ - [matrix_addition](#matrix_additiona-b)
+ - [matrix_multiplication](#matrix_multiplicationa-b)
+ - [matrix_transpose](#matrix_transposea)
+ - [determinant_value](#determinant_valuea)
+ - [Statistics](#statistics)
+ - [mean](#meandata)
+ - [median](#mediandata)
+ - [mode](#modedata)
+- [🔺 Triangle Module](#-triangle-module)
+ - [areaoftriangle](#areaoftrianglea-b-c-unit)
+- [🧪 Running Tests](#-running-tests)
+- [🛠️ Contributing](#-contributing)
+- [🗺️ Roadmap](#-roadmap)
+- [📜 License](#-license)
+
+---
+
## 📦 Installation
-Install from PyPI:
+Install from PyPI (make sure you have Python installed):
```bash
pip install adpkg
```
-Verify installation:
+Check if it worked:
```bash
python -m pip show adpkg
```
---
-## 🚀 Usage
+## 🚀 Quick Start
-Here is the **detailed documentation** for each module and function, with examples, expected results, and edge cases.
+Here are simple examples to get you started. More detailed examples are below.
----
+```python
+from adpkg import finance, adcustom, triangle
-### 💰 Finance Module (`finance.py`)
+# Calculate compound interest
+print(finance.interest(1000, "1y", 12, 5))
-#### Function: `interest(prime_amount, time_duration_str, number_of_times_interest_will_compound_per_year, rate_of_interest)`
+# Factorial
+print(adcustom.factorial(5))
-Calculates compound interest.
+# Reverse a string
+print(adcustom.string_reverse("hello"))
-**Examples:**
-```python
-from adpkg import finance
+# Area of a triangle
+print(triangle.areaoftriangle(3, 4, 5))
+```
+
+---
-# 1 year, monthly compounding
-i1 = finance.interest(1000, "1y", 12, 5)
-print(i1) # 51.161
+## 💰 Finance Module
-# 5 years, quarterly compounding
-i2 = finance.interest(2000, "5y", 4, 7)
-print(i2) # 816.622
+### `interest(prime_amount, time_duration_str, n, rate)`
+- Calculates compound interest based on years/months.
+- Duration formats: `"2y"`, `"6m"`, or `"1y6m"`.
-# 2 years 6 months, daily compounding
-i3 = finance.interest(500, "2y6m", 365, 4.5)
-print(i3) # 61.446
+```python
+from adpkg import finance
+print(finance.interest(1000, "1y", 12, 5)) # 51.161
+print(finance.interest(2000, "5y", 4, 7)) # 816.622
-# Edge cases
-print(finance.interest(-1000, "1y", 12, 5)) # None (negative principal)
-print(finance.interest(1000, "abc", 12, 5)) # None (invalid time format)
-print(finance.interest(1000, "1y", 0, 5)) # None (zero compounding)
+# Edge case: invalid input
+print(finance.interest(1000, "abc", 12, 5)) # None
```
---
-### 🔢 AdCustom Module (`adcustom.py`)
+## 🔢 AdCustom Module
-#### Number Theory
+### Number Theory
-##### `check_prime(inp)`
+#### `check_prime(n)` → 1 if prime, 0 if not, None if invalid.
```python
-from adpkg import adcustom
-print(adcustom.check_prime(17)) # 1
-print(adcustom.check_prime(10)) # 0
-print(adcustom.check_prime(-5)) # None
-print(adcustom.check_prime("a")) # None
+print(adcustom.check_prime(17)) # 1
+print(adcustom.check_prime(10)) # 0
```
-##### `factorial(inp)`
+#### `factorial(n)`
```python
print(adcustom.factorial(5)) # 120
-print(adcustom.factorial(0)) # 1
print(adcustom.factorial(-2)) # None
-print(adcustom.factorial("x"))# None
```
-##### `permutation(total_item, chosen_item)`
+#### `permutation(n, r)`
```python
-print(adcustom.permutation(5, 2)) # 20
-print(adcustom.permutation(6, 3)) # 120
-print(adcustom.permutation(4, -1)) # None
-print(adcustom.permutation("a", 2))# None
+print(adcustom.permutation(5, 2)) # 20
```
-##### `combination(total_item, chosen_item)`
+#### `combination(n, r)`
```python
-print(adcustom.combination(5, 2)) # 10
-print(adcustom.combination(6, 3)) # 20
-print(adcustom.combination(4, -1)) # None
-print(adcustom.combination("a", 3)) # None
+print(adcustom.combination(5, 2)) # 10
```
----
-
-#### String Manipulation
+### Strings
-##### `string_reverse(string)`
+#### `string_reverse(s)`
```python
-print(adcustom.string_reverse("hello")) # 'olleh'
-print(adcustom.string_reverse("adpkg")) # 'gkpda'
-print(adcustom.string_reverse("")) # ''
-print(adcustom.string_reverse(123)) # None (invalid input)
+print(adcustom.string_reverse("hello")) # "olleh"
```
----
-
-#### Matrix Operations
+### Matrices
-##### `matrix_addition(matrix1, matrix2)`
+#### `matrix_addition(a, b)`
```python
-mat1 = [[1, 2], [3, 4]]
-mat2 = [[5, 6], [7, 8]]
-print(adcustom.matrix_addition(mat1, mat2)) # [[6, 8], [10, 12]]
-
-# Edge case: mismatched dimensions
-mat3 = [[1, 2, 3], [4, 5, 6]]
-print(adcustom.matrix_addition(mat1, mat3)) # None
+print(adcustom.matrix_addition([[1,2],[3,4]], [[5,6],[7,8]]))
+# [[6,8],[10,12]]
```
-##### `matrix_multiplication(matrix1, matrix2)`
+#### `matrix_multiplication(a, b)`
```python
-print(adcustom.matrix_multiplication(mat1, mat2)) # [[19, 22], [43, 50]]
-
-# Edge case: incompatible dimensions
-mat_bad = [[1, 2, 3]]
-print(adcustom.matrix_multiplication(mat1, mat_bad)) # None
+print(adcustom.matrix_multiplication([[1,2],[3,4]], [[5,6],[7,8]]))
+# [[19,22],[43,50]]
```
-##### `matrix_transpose(matrix)`
+#### `matrix_transpose(a)`
```python
-mat = [[1, 2, 3], [4, 5, 6]]
-print(adcustom.matrix_transpose(mat)) # [[1, 4], [2, 5], [3, 6]]
-
-# Edge case: empty matrix
-print(adcustom.matrix_transpose([])) # None
+print(adcustom.matrix_transpose([[1,2,3],[4,5,6]]))
+# [[1,4],[2,5],[3,6]]
```
-##### `determinant_value(matrix)`
+#### `determinant_value(a)`
```python
-print(adcustom.determinant_value([[1, 2], [3, 4]])) # -2
-print(adcustom.determinant_value([[1, 2, 3], [0, 1, 4], [5, 6, 0]])) # 1
-
-# Edge case: >3x3 matrix
-big_mat = [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]
-print(adcustom.determinant_value(big_mat)) # None
+print(adcustom.determinant_value([[1,2],[3,4]])) # -2
```
----
-
-#### Statistics
+### Statistics
-##### `mean(inp_set)`
+#### `mean(data)`
```python
-data = [1, 2, 3, 4, 5]
-print(adcustom.mean(data)) # 3.0
-print(adcustom.mean([])) # None
-print(adcustom.mean("x")) # None
+print(adcustom.mean([1,2,3,4,5])) # 3.0
```
-##### `median(inp_set)`
+#### `median(data)`
```python
-data = [1, 3, 2, 5, 4]
-print(adcustom.median(data)) # 3
-
-data_even = [1, 2, 3, 4]
-print(adcustom.median(data_even)) # 2.5
-
-# Edge case: invalid input
-print(adcustom.median("abc")) # None
+print(adcustom.median([1,3,2,5,4])) # 3
```
-##### `mode(inp_set)`
+#### `mode(data)`
```python
-data = [1, 2, 2, 3, 4, 4, 4, 5]
-print(adcustom.mode(data)) # ([4], 3)
-
-single_mode = [10, 10, 20, 30]
-print(adcustom.mode(single_mode)) # ([10], 2)
-
-multi_mode = [1, 1, 2, 2, 3]
-print(adcustom.mode(multi_mode)) # ([1, 2], 2)
-
-# Edge case: empty list
-print(adcustom.mode([])) # None
+print(adcustom.mode([1,2,2,3,4,4,4,5])) # ([4], 3)
```
---
-### 🔺 Triangle Module (`triangle.py`)
+## 🔺 Triangle Module
-#### `areaoftriangle(len_a, len_b, len_c, unit='')`
+### `areaoftriangle(a, b, c, unit='')`
+- Uses Heron’s formula.
```python
-from adpkg import triangle
-
-print(triangle.areaoftriangle(3, 4, 5)) # 6.0
-print(triangle.areaoftriangle(3, 4, 5, "sq cm")) # '6.0 sq cm'
-print(triangle.areaoftriangle(7, 8, 9, "m^2")) # '26.833 m^2'
-
-# Edge cases
-print(triangle.areaoftriangle(1, 2, 3)) # None (degenerate triangle)
-print(triangle.areaoftriangle(-3, 4, 5)) # None (negative side)
-print(triangle.areaoftriangle("a", 4, 5)) # None (invalid input)
+print(triangle.areaoftriangle(3, 4, 5)) # 6.0
+print(triangle.areaoftriangle(3, 4, 5, "sq cm")) # "6.0 sq cm"
```
---
## 🧪 Running Tests
-Tests available: `test1.py` – `test5.py`
+We included some test files (`test1.py` – `test5.py`).
Run one test:
```bash
python test1.py
```
-Run all:
+Run all tests at once:
```bash
python -m unittest discover -s . -p "test*.py"
```
@@ -233,17 +206,17 @@ python -m unittest discover -s . -p "test*.py"
## 🛠️ Contributing
-If you’d like to contribute to this project, here’s how you can help:
+Want to help? Awesome! Here’s how:
+1. **Fork this repo** → Make your own copy on GitHub.
+2. **Create a branch** → Work on your changes in a separate branch.
+3. **Add your code and tests** → Make sure it works!
+4. **Open a Pull Request** → Propose your changes.
-- **Fork the repository** → Make your own copy of this project on GitHub.
-- **Create a new branch** → Work on a separate branch for your changes (e.g., `feature/new-function`).
-- **Add your feature or bug fix with tests** → Write the code and include tests to ensure it works correctly.
-- **Open a Pull Request (PR)** → Submit your changes so they can be reviewed and merged into the main project.
---
## 🗺️ Roadmap
-- ✅ Implemented: Finance, number theory, strings, matrices, stats, triangles
-- 🔜 Coming: Probability, calculus, polynomials, advanced linear algebra
+- ✅ Current: Finance, number theory, strings, matrices, stats, triangles
+- 🔜 Next: Probability, calculus, polynomials, advanced linear algebra
- 📊 Future: Machine learning helpers, symbolic algebra, optimization
---
