Math-Tool یک کتابخانهی جامع و ماژولار برای پایتون است که مجموعهای از ابزارهای پرکاربرد ریاضی، آماری، ماتریسی، رسم نمودار و رگرسیون خطی را در قالبی ساده، تمیز و یکپارچه فراهم میکند.
این پروژه با هدف فراهمسازی یک جعبهابزار سبک و در عین حال کامل برای دانشجویان، مهندسان و علاقهمندان به علم داده طراحی شده است.
- ✨ ویژگیهای کلیدی
- 📋 پیشنیازها
- 📦 نصب و راهاندازی
- 🚀 شروع سریع
- 📚 مستندات API
- 🧪 اجرای تستها
- 📁 ساختار پروژه
- 🤝 مشارکت
- 📄 لایسنس
- 📬 ارتباط با من
- 🧩 تختسازی و نرمالسازی ورودی — پذیرش هر ساختار تو در تو (لیست، تاپل، جنریتور، آرایهی NumPy،
Seriesپانداس و…) و تبدیل خودکار به آرایهی یکبعدی - ∂ مشتقگیری نمادین — محاسبهی مشتق معمولی و جزئی با پشتیبانی از SymPy
- ∑ سیگمای جامع — پشتیبانی از بازه، لیست، ترکیب دو لیست، دو تابع و عملگر دلخواه (
+،-،*،/،**،%) - 📊 ابزارهای آماری — میانگین، واریانس، انحراف معیار، نرمالسازی و نامساوی چبیشف
- 🔢 تشخیص نوع ماتریس — شناسایی خودکار ماتریسهای همانی، قطری، اسکالر، مربعی، سطری، ستونی و تهی
- 📐 معیارهای خطا — محاسبهی MSE و RMSE با پشتیبانی از ورودیهای نامنظم
- 📉 رگرسیون خطی ساده — ساخت مدل روی دیتافریم، پیشبینی و محاسبهی خطای مدل
- 🗂️ مدیریت داده — ساخت دیتاست نمونه و خواندن/ساخت خودکار فایلهای CSV
- 📈 رسم نمودار — نمودار خطی، پراکندگی و مقایسهی دو تابع
- 🧪 تست کامل — پوشش تست واحد برای تمامی کلاسها و توابع
قبل از استفاده، مطمئن شوید که نسخهی Python 3.8 یا بالاتر روی سیستم شما نصب است.
python --versionمیتوانید این کتابخانه را با دستور زیر نصب کنید:
python -m pip install YFZ
سپس در کد پایتون خود از ماژول math_tool استفاده کنید:
import math_tool
git clone https://github.com/kiarashsardari/Math-Tool.git
cd Math-Toolدر مسیر فایل های پروژه این دستور را اجرا کنید:
pip install -r requirements.txtفایل math_tool.py را در کنار پروژهی خود قرار دهید یا از طریق زیر ایمپورت کنید:
from math_tool import (
Settings, Stats, Matrix, Metrics,
LinearRegression, DataHandler, Plots,
derivative, sigma,
)یک نمونهی کامل از کاربرد کتابخانه:
import numpy as np
import pandas as pd
import sympy as sp
from math_tool import (
Settings, Stats, Matrix, Metrics,
LinearRegression, DataHandler, Plots,
derivative, sigma,
)
# --- ۱. تختسازی ورودی ---
data = [1, 2, [3, (4, 5)], np.array([[6, 7], [8, 9]])]
flat = Settings(data).x
print(flat) # [1 2 3 4 5 6 7 8 9]
# --- ۲. مشتقگیری نمادین ---
x = sp.Symbol('x')
f = 2 * x**3 + 3 * x - 6
print(derivative(f, x)) # 6*x**2 + 3
# --- ۳. سیگمای بازهای ---
total = sigma(0, 10, lambda i: 2 * i)
print(total) # 110
# --- ۴. محاسبات آماری ---
s = Stats([1, 2, 3, 4, 5])
print(s.loc()) # 3.0
print(s.variance()) # 2.0
print(s.scale()) # 1.4142...
print(s.norm()) # [-1.414 -0.707 0. 0.707 1.414]
print(s.chebyshev(2)) # (-1.414, 7.414)
# --- ۵. تشخیص نوع ماتریس ---
print(Matrix([[1, 0], [0, 1]]).detect_matrix()) # ('identity', (2, 2))
# --- ۶. معیار خطا ---
print(Metrics.mse([3, -0.5, 2, 7], [2.5, 0.0, 2, 8])) # 0.375
# --- ۷. رگرسیون خطی ---
df = pd.DataFrame({
'x': [1, 2, 3, 4, 5],
'y': [7, 4, 1, -2, -5],
})
model = LinearRegression(df, 'x', 'y')
print(model.t0, model.t1) # 10.0 -3.0
print(model.predict(10)) # -20.0
# --- ۸. مدیریت داده ---
df_sample = DataHandler.make_sample_dataset(50)
print(df_sample.head())
# --- ۹. رسم نمودار ---
Plots.show_plot([1, 2, 3, 4], [1, 4, 9, 16])مدیریت و تختسازی ورودیهای پیچیده. دیکشنری و مجموعه پذیرفته نمیشوند.
Settings([1, 2, [3, (4, 5)], np.array([[6, 7]])]).x
# خروجی: np.array([1, 2, 3, 4, 5, 6, 7], dtype=object)بررسی خالی بودن ورودی (همهی اعضا None یا آرایهی خالی).
Settings([None]).is_empty() # True
Settings([None, 1]).is_empty() # Falseتختسازی کامل و بازگرداندن آرایهی NumPy یکبعدی.
بررسی iterable بودن، با استثنای str، dict و set.
Settings.is_iter([1, 2]) # True
Settings.is_iter(12) # False
Settings.is_iter("hello") # Falseمحاسبهی مشتق معمولی یا مشتق جزئی با استفاده از SymPy.
import sympy as sp
from math_tool import derivative
x = sp.Symbol('x')
derivative(2*x**3 + 3*x - 6, x) # 6*x**2 + 3
# مشتق جزئی
a, b = sp.symbols('a b')
f = 2*a**3 + 3*b**2
derivative(f, a, b) # [6*a**2, 6*b]💡 اگر فقط یک نماد بدهید، نتیجه یک عبارت تکی خواهد بود؛ در غیر این صورت لیستی از مشتقها برمیگردد.
سیگمای جامع با پشتیبانی از بازه، لیست، دو لیست، دو تابع و عملگر دلخواه.
حالت ۱: بازه با یک تابع
sigma(0, 10, lambda i: 2*i) # 110حالت ۲: لیست با یک تابع
sigma([1, 2, 3, 4], f=lambda x: 2*x) # 20
sigma(n=[1, 2, 3, 4], g=lambda x: 2*x) # 20حالت ۳: دو لیست با عملگر و یک تابع
i = [1, 2, 3, 4, 5]
n = [6, 7, 8, 9, 10]
sigma(i, n, f=lambda x: 2*x, operator='-') # -50حالت ۴: دو لیست با دو تابع و عملگر
sigma(
[1, 2, 3, 4, 5],
[6, 7, 8, 9, 10],
f=lambda x: 2*x,
g=lambda x: x - 1,
operator='-',
) # -5عملگرهای پشتیبانیشده: +، -، *، /، **، %
ابزارهای آماری پایه روی هر ورودی قابلتختسازی.
from math_tool import Stats
s = Stats([[1, 2], (3, 4), [5]])| متد | فرمول | توضیح |
|---|---|---|
loc() |
μ = Σ(xᵢ)/n | میانگین |
variance() |
σ² = Σ(xᵢ−μ)²/n | واریانس (جامعه) |
scale() |
σ = √variance | انحراف معیار |
norm() |
(xᵢ−μ)/σ | نرمالسازی |
chebyshev(k) |
μ ± k·σ | بازهی نامساوی چبیشف |
s = Stats([1, 2, 3, 4, 5])
s.loc() # 3.0
s.variance() # 2.0
s.scale() # 1.4142...
s.norm() # [-1.414, -0.707, 0, 0.707, 1.414]
s.chebyshev(2) # (-1.414, 7.414)
⚠️ مقادیرNoneیا آرایهی خالی خطا میدهند. مقادیر غیرعددی نیز خطایValueErrorیاTypeErrorمیدهند.
تشخیص نوع ماتریس و بررسی تساوی.
خروجی: تاپل (نوع، shape)
| نوع | توضیح |
|---|---|
null |
همهی اعضا صفر |
rectangular |
مستطیلی |
row |
سطری (۱×n) |
column |
ستونی (n×۱) |
square |
مربعی |
diagonal |
قطری |
scalar |
مضربی از همانی |
identity |
همانی |
Matrix([[1, 0], [0, 1]]).detect_matrix() # ('identity', (2, 2))
Matrix([[3, 0], [0, 3]]).detect_matrix() # ('scalar', (2, 2))
Matrix([[0, 0], [0, 0]]).detect_matrix() # ('null', (2, 2))بررسی تساوی دو ماتریس (بههمراه shape).
Matrix([[1, 2], [3, 4]]).matrix_equal([[1, 2], [3, 4]]) # Trueمعیارهای خطا.
from math_tool import Metrics
Metrics.mse([3, -0.5, 2, 7], [2.5, 0.0, 2, 8]) # 0.375Metrics.rmse(0.375) # 0.6123...💡 اگر اندازهی دو ورودی برابر نباشد، خروجی
Noneاست.
رسم نمودارهای آماده با Matplotlib.
Plots.show_plot([1, 2, 3, 4], [1, 4, 9, 16])Plots.show_scatter([1, 2, 3], [4, 5, 6])مقایسهی دو تابع روی بازهی [۱، ۱۰].
Plots.comparison_plot(
f_true=lambda x: 2*x,
f_pred=lambda x: 3*x + 3,
)رگرسیون خطی ساده با فرمول بسته روی دیتافریم.
مدل بهفرم y = θ₀ + θ₁·x:
θ₁ = Σ(xᵢ−x̄)(yᵢ−ȳ) / Σ(xᵢ−x̄)²
θ₀ = ȳ − θ₁·x̄
import pandas as pd
from math_tool import LinearRegression
df = pd.DataFrame({
'x': [1, 2, 3, 4, 5],
'y': [7, 4, 1, -2, -5],
})
model = LinearRegression(df, 'x', 'y')
print(model.t0, model.t1) # 10.0 -3.0
print(model.predict(10)) # -20.0
print(model.model_mse(df['x'], df['y'])) # 0.0ساخت دیتاست نمونه و مدیریت فایلهای CSV.
ساخت دیتاست نمونه از سن و قد با نویز مصنوعی و ذخیره در sample_dataset.csv.
df = DataHandler.make_sample_dataset(100)
print(df.head())اگر فایل CSV موجود باشد میخواند، در غیر این صورت با تابع دادهشده آن را میسازد.
df = DataHandler.read_or_make_csv(
"data.csv",
DataHandler.make_sample_dataset,
100,
)کتابخانه دارای مجموعهی کامل تست واحد با unittest است.
برای اجرای تستها دستور زیر را اجرا کنید:
python -m unittest test_math_tool.py -v
در صورت موفقیتآمیز بودن تمام تستها، پیام OK در خروجی نمایش داده میشود.
تعداد تستها ممکن است با توسعه و بهروزرسانی پروژه تغییر کند.
Math-Tool/
├── .github/
│ └── workflows/
│ └── publish.yml
├── math_tool.py
├── test_math_tool.py
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md```
---
<a id="contributing"></a>
## 🤝 مشارکت
از هرگونه مشارکت، پیشنهاد و گزارش باگ استقبال میشود! 🙌
1. مخزن را **Fork** کنید
2. یک شاخهی جدید بسازید:
```bash
git checkout -b feature/amazing-feature
- تغییرات خود را Commit کنید:
git commit -m "Add some amazing feature" - شاخه را Push کنید:
git push origin feature/amazing-feature
- یک Pull Request باز کنید
- رعایت PEP 8
- افزودن تست برای هر قابلیت جدید
- استفاده از docstring برای توابع عمومی
- حفظ سازگاری با ورژنهای قبلی
این پروژه تحت مجوز MIT منتشر شده است.
استفاده، کپی، تغییر، توزیع و استفادهی تجاری از این نرمافزار مجاز است، مشروط بر اینکه اطلاعیهی حق نشر و متن مجوز در نسخهها یا بخشهای قابلتوجه نرمافزار حفظ شوند.
برای جزئیات بیشتر، فایل LICENSE را مطالعه کنید.
Kiarash Sardari
- 🐙 GitHub: @kiarashsardari
- 📦 مخزن پروژه: Math-Tool
- 📧 ایمیل: kiarash123sardari@gmail.com